Metorial Object Storage Client

Common errors

• TypeError: (0 , object_storage_client_1.ObjectStorageClient) is not a constructor

  cause 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

  cause 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

  cause 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.

Warnings

• breaking As 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.
• gotcha This 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.
• gotcha Connection 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.

Install

• npm install object-storage-client npm
• yarn add object-storage-client yarn
• pnpm add object-storage-client pnpm

Imports

• ObjectStorageClient
  wrong:

  const ObjectStorageClient = require('object-storage-client').ObjectStorageClient;

  correct:

  import { ObjectStorageClient } from 'object-storage-client';

  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
  wrong:

  import ObjectStorageError from 'object-storage-client';

  correct:

  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.

Quickstart

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();