Multi-Cloud Storage Client

This library provides a unified interface for interacting with different cloud storage providers, such as Google Cloud Storage (GCS) and Amazon S3.

OpenTelemetry Tracing

This library is instrumented with OpenTelemetry. If the application using this library has an active OpenTelemetry SDK configured, a trace span will be created automatically when a GCSStorageProvider is instantiated.

You can also add custom attributes to this span by passing a tracingAttributes object to the factory function.

Usage

createStorageProvider(type, options, tracingAttributes)

The createStorageProvider factory function is the primary way to create a storage provider instance.

• type: The type of storage provider to create. Use the StorageProviderType enum (GCS or S3).
• options: The configuration options for the specific provider. These are passed directly to the underlying SDK.
• tracingAttributes (optional): A map of key-value pairs to be added as attributes to the client constructor trace span.

IStorageProvider

All storage providers implement the IStorageProvider interface, which defines the following methods:

• get(bucket: string, path: string): Promise<Buffer>
• getStream(bucket: string, path: string): Readable
• put(bucket: string, path: string, content: Buffer | string): Promise<void>
• putStream(bucket: string, path: string): Writable
• delete(bucket: string, path: string): Promise<void>
• list(bucket: string, prefix?: string): Promise<string[]>

Example

Google Cloud Storage (GCS) with Tracing Attributes

import {
    createStorageProvider,
    StorageProviderType,
    StorageOptions,
} from '@ionq/storage-client';

const gcsOptions: StorageOptions = {
    projectId: 'your-gcp-project-id',
    keyFilename: '/path/to/your/keyfile.json',
};

// Add custom attributes to the constructor's trace span.
const tracingAttributes = {
    'region': 'ionq-us-east1',
    'app.service.name': 'my-data-processor',
};

const gcsProvider = createStorageProvider(
    StorageProviderType.GCS,
    gcsOptions,
    tracingAttributes,
);

async function runGCSExample() {
    const bucket = 'my-gcs-bucket';
    const path = 'my-file.txt';
    const content = 'Hello, GCS!';

    await gcsProvider.put(bucket, path, content);
    console.log('File uploaded to GCS.');

    const fileContent = await gcsProvider.get(bucket, path);
    console.log('File content from GCS:', fileContent.toString());
}

runGCSExample();

Amazon S3

import {
    createStorageProvider,
    StorageProviderType,
    S3ClientConfig,
} from '@ionq/storage-client';

const s3Options: S3ClientConfig = {
    region: 'us-east-1',
    credentials: {
        accessKeyId: 'YOUR_AWS_ACCESS_KEY_ID',
        secretAccessKey: 'YOUR_AWS_SECRET_ACCESS_KEY',
    },
};

const s3Provider = createStorageProvider(StorageProviderType.S3, s3Options);

async function runS3Example() {
    const bucket = 'my-s3-bucket';
    const path = 'my-file.txt';
    const content = 'Hello, S3!';

    await s3Provider.put(bucket, path, content);
    console.log('File uploaded to S3.');

    const fileContent = await s3Provider.get(bucket, path);
    console.log('File content from S3:', fileContent.toString());
}

runS3Example();