Registry / aws / object-storage-client

object-storage-client

JSON →
library0.0.37jsnpmunverified

The `object-storage-client` package provides a TypeScript and JavaScript client library for programmatic interaction with the Metorial Object Storage Service. It offers a comprehensive, promise-based API for managing buckets and objects, including creation, listing, uploading, downloading, and deletion. The current stable version, 0.2.5, indicates it is in early development and pre-1.0 stability, meaning minor versions might introduce breaking changes. Its key differentiators include strong TypeScript support, a direct interface to the Metorial Object Storage backend (which itself supports multiple storage backends like local filesystem, AWS S3, Google Cloud Storage, and Azure Blob Storage), and a straightforward API for asynchronous operations. This client is specifically designed for the Metorial ecosystem, which aims to connect AI agents to various tools and services.

npm install object-storage-client
INSTALL
IMPORT
SIG · OBJECT-STORAGE-CLI
O
object-storage-client
awsjavascriptv0.0.37
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.

ObjectStorageClient
import { ObjectStorageClient } from 'object-storage-client';
const ObjectStorageClient = require('object-storage-client').ObjectStorageClient;
The library is written in TypeScript and primarily targets ESM environments; use named imports. Direct CommonJS require() may lead to incorrect resolution or require default property access.
ObjectStorageError
import { ObjectStorageError } from 'object-storage-client';
import ObjectStorageError from 'object-storage-client';
This is a named export for the custom error class used for API-specific errors, allowing detailed error handling based on status codes. Do not use a default import.

This quickstart demonstrates the full lifecycle of object storage operations: creating a bucket, uploading a text file, downloading it, listing objects, and finally deleting both the object and the bucket. It also includes basic error handling for API-specific and generic errors.

import { ObjectStorageClient, ObjectStorageError } from 'object-storage-client'; const client = new ObjectStorageClient('http://localhost:8080'); async function runObjectStorageDemo() { try { // Create a bucket const bucketName = 'my-unique-test-bucket-' + Date.now(); console.log(`Attempting to create bucket: ${bucketName}`); const bucket = await client.createBucket(bucketName); console.log(`Created bucket: ${bucket.name}`); // Upload an object const data = Buffer.from('Hello, Object Storage World!'); const objectKey = 'hello.txt'; console.log(`Uploading object '${objectKey}' to '${bucketName}'`); const obj = await client.putObject( bucketName, objectKey, data, 'text/plain', { author: 'AI-Agent' } ); console.log(`Uploaded object: ${obj.key} (ETag: ${obj.etag})`); // Download an object console.log(`Downloading object '${objectKey}' from '${bucketName}'`); const objData = await client.getObject(bucketName, objectKey); console.log(`Downloaded ${objData.data.length} bytes. Content: ${objData.data.toString()}`); // List objects console.log(`Listing objects in '${bucketName}'`); const objects = await client.listObjects(bucketName); for (const item of objects) { console.log(`- ${item.key}: ${item.size} bytes`); } // Delete object console.log(`Deleting object '${objectKey}' from '${bucketName}'`); await client.deleteObject(bucketName, objectKey); console.log('Object deleted.'); // Delete bucket console.log(`Deleting bucket: ${bucketName}`); await client.deleteBucket(bucketName); console.log('Bucket deleted.'); } catch (error) { if (error instanceof ObjectStorageError) { console.error(`Object Storage API Error: Status ${error.statusCode}, Message: ${error.message}`); } else if (error instanceof Error) { console.error(`Generic Error: ${error.message}`); } else { console.error('An unknown error occurred:', error); } } } runObjectStorageDemo();
Debug
Known issues
breakingAs of version 0.2.5, this library is in pre-1.0 development. Breaking changes may be introduced in minor or even patch releases without strict adherence to semantic versioning until a stable 1.0.0 release is made. Users should pin exact versions and review changelogs carefully.
fix
Pin the exact version (e.g., `"object-storage-client": "0.2.5"`) in your `package.json` and manually review the project's GitHub releases for breaking changes before upgrading. Consider using a tool like `npm-check-updates` with a conservative update policy.
affects: <1.0.0
gotchaThis client is specifically designed for the Metorial Object Storage Service. While the service itself supports multiple backends (S3, GCS, Azure), this client does not offer a generic S3-compatible interface that works with *any* S3-compatible service directly. It communicates with the Metorial API, not a generic S3 endpoint.
fix
Ensure your application is configured to interact with a Metorial Object Storage Service instance. If you need a client for a generic S3-compatible service, consider alternatives like `@aws-sdk/client-s3` or `minio`'s client library.
affects: >=0.1.0
gotchaConnection errors (e.g., server offline, wrong URL, network issues) will typically throw standard Node.js or browser `Error` objects (e.g., `ECONNREFUSED`, `FetchError`) rather than `ObjectStorageError`. The `ObjectStorageError` is reserved for successful HTTP requests that return an API-specific error from the Metorial service.
fix
Implement robust `try...catch` blocks that handle both `ObjectStorageError` for API responses and generic `Error` instances for underlying network or connection failures, as demonstrated in the quickstart example.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: (0 , object_storage_client_1.ObjectStorageClient) is not a constructor
Attempting to use CommonJS `require()` or an incorrect import style in an ESM context or a bundler misconfiguration.
fix
Ensure you are using `import { ObjectStorageClient } from 'object-storage-client';` in your TypeScript/ESM files. If using CommonJS, consider transpiling your code to ESM or configuring your bundler (e.g., Webpack, Rollup) to correctly handle ESM module resolution for `object-storage-client`.
Object Storage API Error: Status 404, Message: Bucket not found
Attempting to perform an operation (like `getObject`, `deleteObject`) on a bucket that does not exist or has been deleted.
fix
Verify that the bucket name is correct and that the bucket exists before attempting object-level operations. If the bucket should exist, check the server-side logs for unexpected deletion or naming issues.
Error: connect ECONNREFUSED 127.0.0.1:8080
The Metorial Object Storage Service is not running or is not accessible at the specified endpoint (e.g., `http://localhost:8080`).
fix
Ensure the Metorial Object Storage Service is running and accessible from where your client code is executing. Double-check the URL and port provided to the `ObjectStorageClient` constructor. If running in Docker, ensure port mappings are correct.
Upgrade
Version history
0.0.37latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
object-storage-client — npm install object-storage-client · libregistry