Aliyun OSS Node.js Client

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... oss-client/index.js from ... not supported.

  cause Attempting to use `require()` to import `oss-client` in a CommonJS context when the package is primarily designed for ESM in v2.x.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and use `import { OSSObject } from 'oss-client';`. Alternatively, for older Node.js or strict CommonJS environments, consider `oss-client` v1.x.

• TypeError: ossObject.put is not a function

  cause Incorrectly instantiating the `OSSObject` client or trying to call a method that doesn't exist or is not exposed.
  fix Verify that `new OSSObject({...})` is correctly called and that `OSSObject` is properly imported. Check the method signature and available methods against the documentation for your `oss-client` version.

• Error: signature is invalid

  cause Authentication failure due to incorrect `accessKeyId`, `accessKeySecret`, or an expired `stsToken` (if using v1.x or a custom STS solution). This can also happen if the region or bucket name is wrong.
  fix Double-check your `accessKeyId`, `accessKeySecret`, `region`, and `bucket` configurations for typos. Ensure the keys have the necessary permissions for the operations being performed. If using temporary credentials, verify their validity.

Warnings

• breaking Version 2.0.0 introduced significant breaking changes, dropping support for Node.js versions below 16.0.0. Projects on older Node.js versions must either upgrade Node.js or remain on `oss-client` v1.x.
  Fix: Upgrade Node.js to version 16.0.0 or higher, or pin `oss-client` to version `1.x`.
• breaking With v2.0.0, support for `stsToken`, `headerEncoding`, and dedicated `Bucket` and `Image Client` APIs was removed. These functionalities require alternative implementations or SDKs.
  Fix: Refactor code to remove usage of `stsToken`, `headerEncoding`, and `Bucket`/`Image Client` specific APIs. Consult Aliyun OSS documentation for alternative approaches for STS or image processing.
• breaking The `urllib` dependency was upgraded to version 4.x in `oss-client` v2.4.0. This might introduce breaking changes in `urllib` itself if your project directly or indirectly relied on older `urllib` versions.
  Fix: Ensure `urllib` is compatible with your project's ecosystem. Review `urllib` v4.x release notes for any breaking changes that might affect your direct `urllib` usage, if any.
• gotcha The `getObjectUrl` method was deprecated in favor of `generateObjectUrl` in v2.0.1. While `getObjectUrl` still exists as an alias, using the new method is recommended for future compatibility.
  Fix: Replace all calls to `client.getObjectUrl(name)` with `client.generateObjectUrl(name)`.
• gotcha When using `putStream`, ensure the stream is correctly handled and closed. Improper stream management can lead to resource leaks or incomplete uploads, especially with large files.
  Fix: Always handle stream errors and ensure streams are properly piped or consumed and closed. Consider using `pipeline` from `node:stream/promises` for robust stream handling.

Install

• npm install oss-client npm
• yarn add oss-client yarn
• pnpm add oss-client pnpm

Imports

• OSSObject
  wrong:

  const { OSSObject } = require('oss-client');

  correct:

  import { OSSObject } from 'oss-client';

  Since v2.0.0, oss-client is primarily ESM-first. While CommonJS `require` might work with transpilation, direct ESM import is recommended. For Node.js < 16, use v1.x.
• ClientOptions

  import type { ClientOptions } from 'oss-client';

  Importing types like `ClientOptions` is crucial for TypeScript projects to leverage static analysis and auto-completion for client configuration.
• PutObjectOptions

  import type { PutObjectOptions } from 'oss-client';

  Importing specific operation options types, such as `PutObjectOptions`, helps ensure correct parameter usage for methods like `put` and `putStream` in TypeScript.

Quickstart

Demonstrates initializing the OSS client, uploading a file, retrieving its content, and then deleting the object using async/await.

import { OSSObject } from 'oss-client';
import { readFileSync } from 'node:fs';
import { join } from 'node:path';

const ossObject = new OSSObject({
  region: process.env.OSS_REGION ?? 'oss-cn-hangzhou',
  endpoint: process.env.OSS_ENDPOINT ?? 'https://oss-cn-hangzhou.aliyuncs.com',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID ?? 'YOUR_ACCESS_KEY_ID',
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET ?? 'YOUR_ACCESS_KEY_SECRET',
  bucket: process.env.OSS_BUCKET_NAME ?? 'your-bucket-name',
});

async function uploadFile() {
  const localFilePath = join(__dirname, 'test-file.txt');
  // For demonstration, create a dummy file if it doesn't exist
  try {
    readFileSync(localFilePath);
  } catch (error) {
    require('node:fs').writeFileSync(localFilePath, 'Hello, Aliyun OSS!');
  }

  const remoteObjectName = 'my-test-object.txt';
  try {
    const result = await ossObject.put(remoteObjectName, localFilePath);
    console.log(`Successfully uploaded: ${result.name} to ${result.url}`);

    const downloadResult = await ossObject.get(remoteObjectName);
    console.log(`Downloaded content: ${downloadResult.content?.toString()}`);

    await ossObject.delete(remoteObjectName);
    console.log(`Successfully deleted: ${remoteObjectName}`);
  } catch (error) {
    console.error('OSS operation failed:', error);
  }
}

uploadFile();