Registry / aws / oss-client

oss-client

JSON →
library0.1.5jsnpmunverified

The `oss-client` package provides a robust Node.js client for Alibaba Cloud's Object Storage Service (OSS), functionally similar to Amazon S3. The current stable version is 2.5.1, released in August 2025. This library maintains an active release cadence, with minor feature updates every few months and bug fixes as needed. It leverages modern JavaScript features, exclusively using `async/await` for all operations, making asynchronous programming straightforward. A key differentiator is its strong TypeScript support and ESM-first approach since version 2.0.0, catering to contemporary Node.js development practices. It is specifically designed for Aliyun OSS, offering comprehensive object manipulation capabilities including put, get, delete, stream handling, URL generation, and ACL management, along with support for bucket and object tagging.

npm install oss-client
INSTALL
IMPORT
SIG · OSS-CLIENT
O
oss-client
awsjavascriptv0.1.5
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OSSObject
import { OSSObject } from 'oss-client';
const { OSSObject } = require('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.

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();
Debug
Known issues
breakingVersion 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`.
affects: >=2.0.0
breakingWith 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.
affects: >=2.0.0
breakingThe `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.
affects: >=2.4.0
gotchaThe `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)`.
affects: >=2.0.1
gotchaWhen 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.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM: require() of ES Module ... oss-client/index.js from ... not supported.
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
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
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.
Upgrade
Version history
0.1.5latest on npm
Audit
Dependencies
urllibrequiredHTTP client for network requests to OSS. Version 4.x is required since oss-client v2.4.0.
Agent activity
14 hits · last 30 days
node
12
Resources
oss-client — npm install oss-client · libregistry