@forklaunch/infrastructure-s3 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 forklaunch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/eject/infrastructure/index.ts

@@ -0,0 +1,230 @@
+import {
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  DeleteObjectsCommandInput,
+  GetObjectCommand,
+  PutObjectCommand,
+  PutObjectCommandInput,
+  S3Client
+} from '@aws-sdk/client-s3';
+import {
+  MetricsDefinition,
+  OpenTelemetryCollector,
+  TelemetryOptions
+} from '@forklaunch/core/http';
+import { ObjectStore } from '@forklaunch/core/objectstore';
+import { Readable } from 'stream';
+
+/**
+ * Options for configuring the S3ObjectStore.
+ *
+ * @example
+ * const options: S3ObjectStoreOptions = {
+ *   bucket: 'my-bucket',
+ *   clientConfig: { region: 'us-west-2' }
+ * };
+ */
+interface S3ObjectStoreOptions {
+  /** The S3 bucket name. */
+  bucket: string;
+  /** Optional existing S3 client instance. */
+  client?: S3Client;
+  /** Optional configuration for creating a new S3 client. */
+  clientConfig?: ConstructorParameters<typeof S3Client>[0];
+}
+
+/**
+ * S3-backed implementation of the ObjectStore interface.
+ * Provides methods for storing, retrieving, streaming, and deleting objects in S3.
+ *
+ * @example
+ * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);
+ * await store.putObject({ key: 'user-1', name: 'Alice' });
+ * const user = await store.readObject<{ name: string }>('user-1');
+ */
+export class S3ObjectStore implements ObjectStore<S3Client> {
+  private s3: S3Client;
+  private bucket: string;
+
+  /**
+   * Creates a new S3ObjectStore instance.
+   * @param openTelemetryCollector - Collector for OpenTelemetry metrics.
+   * @param options - S3 configuration options.
+   * @param telemetryOptions - Telemetry configuration options.
+   *
+   * @example
+   * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);
+   */
+  constructor(
+    private openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>,
+    options: S3ObjectStoreOptions,
+    private telemetryOptions: TelemetryOptions
+  ) {
+    this.s3 = options.client || new S3Client(options.clientConfig || {});
+    this.bucket = options.bucket;
+  }
+
+  /**
+   * Stores an object in the S3 bucket.
+   * @template T - The type of the object being stored.
+   * @param object - The object to store. Must include a `key` property.
+   *
+   * @example
+   * await store.putObject({ key: 'user-1', name: 'Alice' });
+   */
+  async putObject<T>(object: T & { key: string }): Promise<void> {
+    const { key, ...rest } = object;
+    const params: PutObjectCommandInput = {
+      Bucket: this.bucket,
+      Key: key,
+      Body: JSON.stringify(rest),
+      ContentType: 'application/json'
+    };
+    await this.s3.send(new PutObjectCommand(params));
+  }
+
+  /**
+   * Stores multiple objects in the S3 bucket.
+   * @template T - The type of the objects being stored.
+   * @param objects - The objects to store. Each must include a `key` property.
+   *
+   * @example
+   * await store.putBatchObjects([
+   *   { key: 'user-1', name: 'Alice' },
+   *   { key: 'user-2', name: 'Bob' }
+   * ]);
+   */
+  async putBatchObjects<T>(objects: (T & { key: string })[]): Promise<void> {
+    await Promise.all(objects.map((obj) => this.putObject(obj)));
+  }
+
+  /**
+   * Streams an object upload to the S3 bucket.
+   * For compatibility; uses putObject internally.
+   * @template T - The type of the object being stored.
+   * @param object - The object to stream-upload. Must include a `key` property.
+   */
+  async streamUploadObject<T>(object: T & { key: string }): Promise<void> {
+    await this.putObject(object);
+  }
+
+  /**
+   * Streams multiple object uploads to the S3 bucket.
+   * For compatibility; uses putBatchObjects internally.
+   * @template T - The type of the objects being stored.
+   * @param objects - The objects to stream-upload. Each must include a `key` property.
+   */
+  async streamUploadBatchObjects<T>(
+    objects: (T & { key: string })[]
+  ): Promise<void> {
+    await this.putBatchObjects(objects);
+  }
+
+  /**
+   * Deletes an object from the S3 bucket.
+   * @param objectKey - The key of the object to delete.
+   *
+   * @example
+   * await store.deleteObject('user-1');
+   */
+  async deleteObject(objectKey: string): Promise<void> {
+    await this.s3.send(
+      new DeleteObjectCommand({ Bucket: this.bucket, Key: objectKey })
+    );
+  }
+
+  /**
+   * Deletes multiple objects from the S3 bucket.
+   * @param objectKeys - The keys of the objects to delete.
+   *
+   * @example
+   * await store.deleteBatchObjects(['user-1', 'user-2']);
+   */
+  async deleteBatchObjects(objectKeys: string[]): Promise<void> {
+    const params: DeleteObjectsCommandInput = {
+      Bucket: this.bucket,
+      Delete: {
+        Objects: objectKeys.map((Key) => ({ Key }))
+      }
+    };
+    await this.s3.send(new DeleteObjectsCommand(params));
+  }
+
+  /**
+   * Reads an object from the S3 bucket.
+   * @template T - The expected type of the object.
+   * @param objectKey - The key of the object to read.
+   * @returns The parsed object.
+   *
+   * @example
+   * const user = await store.readObject<{ name: string }>('user-1');
+   */
+  async readObject<T>(objectKey: string): Promise<T> {
+    const resp = await this.s3.send(
+      new GetObjectCommand({ Bucket: this.bucket, Key: objectKey })
+    );
+    const body = resp.Body as Readable;
+    const chunks: Buffer[] = [];
+    for await (const chunk of body) {
+      chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString()) as T;
+  }
+
+  /**
+   * Reads multiple objects from the S3 bucket.
+   * @template T - The expected type of the objects.
+   * @param objectKeys - The keys of the objects to read.
+   * @returns An array of parsed objects.
+   *
+   * @example
+   * const users = await store.readBatchObjects<{ name: string }>(['user-1', 'user-2']);
+   */
+  async readBatchObjects<T>(objectKeys: string[]): Promise<T[]> {
+    return Promise.all(objectKeys.map((key) => this.readObject<T>(key)));
+  }
+
+  /**
+   * Streams an object download from the S3 bucket.
+   * @param objectKey - The key of the object to download.
+   * @returns A readable stream of the object's contents.
+   * @throws If the S3 response does not include a readable stream.
+   *
+   * @example
+   * const stream = await store.streamDownloadObject('user-1');
+   * stream.pipe(fs.createWriteStream('user-1.json'));
+   */
+  async streamDownloadObject(objectKey: string): Promise<Readable> {
+    const resp = await this.s3.send(
+      new GetObjectCommand({ Bucket: this.bucket, Key: objectKey })
+    );
+    if (!resp.Body || !(resp.Body instanceof Readable)) {
+      throw new Error('S3 did not return a stream');
+    }
+    return resp.Body;
+  }
+
+  /**
+   * Streams multiple object downloads from the S3 bucket.
+   * @param objectKeys - The keys of the objects to download.
+   * @returns An array of readable streams.
+   *
+   * @example
+   * const streams = await store.streamDownloadBatchObjects(['user-1', 'user-2']);
+   * streams[0].pipe(fs.createWriteStream('user-1.json'));
+   */
+  async streamDownloadBatchObjects(objectKeys: string[]): Promise<Readable[]> {
+    return Promise.all(objectKeys.map((key) => this.streamDownloadObject(key)));
+  }
+
+  /**
+   * Gets the underlying S3 client instance.
+   * @returns The S3Client instance used by this store.
+   *
+   * @example
+   * const s3Client = store.getClient();
+   */
+  getClient(): S3Client {
+    return this.s3;
+  }
+}

package/lib/index.d.mts

@@ -0,0 +1,157 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import { OpenTelemetryCollector, MetricsDefinition, TelemetryOptions } from '@forklaunch/core/http';
+import { ObjectStore } from '@forklaunch/core/objectstore';
+import { Readable } from 'stream';
+
+/**
+ * Options for configuring the S3ObjectStore.
+ *
+ * @example
+ * const options: S3ObjectStoreOptions = {
+ *   bucket: 'my-bucket',
+ *   clientConfig: { region: 'us-west-2' }
+ * };
+ */
+interface S3ObjectStoreOptions {
+    /** The S3 bucket name. */
+    bucket: string;
+    /** Optional existing S3 client instance. */
+    client?: S3Client;
+    /** Optional configuration for creating a new S3 client. */
+    clientConfig?: ConstructorParameters<typeof S3Client>[0];
+}
+/**
+ * S3-backed implementation of the ObjectStore interface.
+ * Provides methods for storing, retrieving, streaming, and deleting objects in S3.
+ *
+ * @example
+ * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);
+ * await store.putObject({ key: 'user-1', name: 'Alice' });
+ * const user = await store.readObject<{ name: string }>('user-1');
+ */
+declare class S3ObjectStore implements ObjectStore<S3Client> {
+    private openTelemetryCollector;
+    private telemetryOptions;
+    private s3;
+    private bucket;
+    /**
+     * Creates a new S3ObjectStore instance.
+     * @param openTelemetryCollector - Collector for OpenTelemetry metrics.
+     * @param options - S3 configuration options.
+     * @param telemetryOptions - Telemetry configuration options.
+     *
+     * @example
+     * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);
+     */
+    constructor(openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>, options: S3ObjectStoreOptions, telemetryOptions: TelemetryOptions);
+    /**
+     * Stores an object in the S3 bucket.
+     * @template T - The type of the object being stored.
+     * @param object - The object to store. Must include a `key` property.
+     *
+     * @example
+     * await store.putObject({ key: 'user-1', name: 'Alice' });
+     */
+    putObject<T>(object: T & {
+        key: string;
+    }): Promise<void>;
+    /**
+     * Stores multiple objects in the S3 bucket.
+     * @template T - The type of the objects being stored.
+     * @param objects - The objects to store. Each must include a `key` property.
+     *
+     * @example
+     * await store.putBatchObjects([
+     *   { key: 'user-1', name: 'Alice' },
+     *   { key: 'user-2', name: 'Bob' }
+     * ]);
+     */
+    putBatchObjects<T>(objects: (T & {
+        key: string;
+    })[]): Promise<void>;
+    /**
+     * Streams an object upload to the S3 bucket.
+     * For compatibility; uses putObject internally.
+     * @template T - The type of the object being stored.
+     * @param object - The object to stream-upload. Must include a `key` property.
+     */
+    streamUploadObject<T>(object: T & {
+        key: string;
+    }): Promise<void>;
+    /**
+     * Streams multiple object uploads to the S3 bucket.
+     * For compatibility; uses putBatchObjects internally.
+     * @template T - The type of the objects being stored.
+     * @param objects - The objects to stream-upload. Each must include a `key` property.
+     */
+    streamUploadBatchObjects<T>(objects: (T & {
+        key: string;
+    })[]): Promise<void>;
+    /**
+     * Deletes an object from the S3 bucket.
+     * @param objectKey - The key of the object to delete.
+     *
+     * @example
+     * await store.deleteObject('user-1');
+     */
+    deleteObject(objectKey: string): Promise<void>;
+    /**
+     * Deletes multiple objects from the S3 bucket.
+     * @param objectKeys - The keys of the objects to delete.
+     *
+     * @example
+     * await store.deleteBatchObjects(['user-1', 'user-2']);
+     */
+    deleteBatchObjects(objectKeys: string[]): Promise<void>;
+    /**
+     * Reads an object from the S3 bucket.
+     * @template T - The expected type of the object.
+     * @param objectKey - The key of the object to read.
+     * @returns The parsed object.
+     *
+     * @example
+     * const user = await store.readObject<{ name: string }>('user-1');
+     */
+    readObject<T>(objectKey: string): Promise<T>;
+    /**
+     * Reads multiple objects from the S3 bucket.
+     * @template T - The expected type of the objects.
+     * @param objectKeys - The keys of the objects to read.
+     * @returns An array of parsed objects.
+     *
+     * @example
+     * const users = await store.readBatchObjects<{ name: string }>(['user-1', 'user-2']);
+     */
+    readBatchObjects<T>(objectKeys: string[]): Promise<T[]>;
+    /**
+     * Streams an object download from the S3 bucket.
+     * @param objectKey - The key of the object to download.
+     * @returns A readable stream of the object's contents.
+     * @throws If the S3 response does not include a readable stream.
+     *
+     * @example
+     * const stream = await store.streamDownloadObject('user-1');
+     * stream.pipe(fs.createWriteStream('user-1.json'));
+     */
+    streamDownloadObject(objectKey: string): Promise<Readable>;
+    /**
+     * Streams multiple object downloads from the S3 bucket.
+     * @param objectKeys - The keys of the objects to download.
+     * @returns An array of readable streams.
+     *
+     * @example
+     * const streams = await store.streamDownloadBatchObjects(['user-1', 'user-2']);
+     * streams[0].pipe(fs.createWriteStream('user-1.json'));
+     */
+    streamDownloadBatchObjects(objectKeys: string[]): Promise<Readable[]>;
+    /**
+     * Gets the underlying S3 client instance.
+     * @returns The S3Client instance used by this store.
+     *
+     * @example
+     * const s3Client = store.getClient();
+     */
+    getClient(): S3Client;
+}
+
+export { S3ObjectStore };

package/lib/index.d.ts

@@ -0,0 +1,157 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import { OpenTelemetryCollector, MetricsDefinition, TelemetryOptions } from '@forklaunch/core/http';
+import { ObjectStore } from '@forklaunch/core/objectstore';
+import { Readable } from 'stream';
+
+/**
+ * Options for configuring the S3ObjectStore.
+ *
+ * @example
+ * const options: S3ObjectStoreOptions = {
+ *   bucket: 'my-bucket',
+ *   clientConfig: { region: 'us-west-2' }
+ * };
+ */
+interface S3ObjectStoreOptions {
+    /** The S3 bucket name. */
+    bucket: string;
+    /** Optional existing S3 client instance. */
+    client?: S3Client;
+    /** Optional configuration for creating a new S3 client. */
+    clientConfig?: ConstructorParameters<typeof S3Client>[0];
+}
+/**
+ * S3-backed implementation of the ObjectStore interface.
+ * Provides methods for storing, retrieving, streaming, and deleting objects in S3.
+ *
+ * @example
+ * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);
+ * await store.putObject({ key: 'user-1', name: 'Alice' });
+ * const user = await store.readObject<{ name: string }>('user-1');
+ */
+declare class S3ObjectStore implements ObjectStore<S3Client> {
+    private openTelemetryCollector;
+    private telemetryOptions;
+    private s3;
+    private bucket;
+    /**
+     * Creates a new S3ObjectStore instance.
+     * @param openTelemetryCollector - Collector for OpenTelemetry metrics.
+     * @param options - S3 configuration options.
+     * @param telemetryOptions - Telemetry configuration options.
+     *
+     * @example
+     * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);
+     */
+    constructor(openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>, options: S3ObjectStoreOptions, telemetryOptions: TelemetryOptions);
+    /**
+     * Stores an object in the S3 bucket.
+     * @template T - The type of the object being stored.
+     * @param object - The object to store. Must include a `key` property.
+     *
+     * @example
+     * await store.putObject({ key: 'user-1', name: 'Alice' });
+     */
+    putObject<T>(object: T & {
+        key: string;
+    }): Promise<void>;
+    /**
+     * Stores multiple objects in the S3 bucket.
+     * @template T - The type of the objects being stored.
+     * @param objects - The objects to store. Each must include a `key` property.
+     *
+     * @example
+     * await store.putBatchObjects([
+     *   { key: 'user-1', name: 'Alice' },
+     *   { key: 'user-2', name: 'Bob' }
+     * ]);
+     */
+    putBatchObjects<T>(objects: (T & {
+        key: string;
+    })[]): Promise<void>;
+    /**
+     * Streams an object upload to the S3 bucket.
+     * For compatibility; uses putObject internally.
+     * @template T - The type of the object being stored.
+     * @param object - The object to stream-upload. Must include a `key` property.
+     */
+    streamUploadObject<T>(object: T & {
+        key: string;
+    }): Promise<void>;
+    /**
+     * Streams multiple object uploads to the S3 bucket.
+     * For compatibility; uses putBatchObjects internally.
+     * @template T - The type of the objects being stored.
+     * @param objects - The objects to stream-upload. Each must include a `key` property.
+     */
+    streamUploadBatchObjects<T>(objects: (T & {
+        key: string;
+    })[]): Promise<void>;
+    /**
+     * Deletes an object from the S3 bucket.
+     * @param objectKey - The key of the object to delete.
+     *
+     * @example
+     * await store.deleteObject('user-1');
+     */
+    deleteObject(objectKey: string): Promise<void>;
+    /**
+     * Deletes multiple objects from the S3 bucket.
+     * @param objectKeys - The keys of the objects to delete.
+     *
+     * @example
+     * await store.deleteBatchObjects(['user-1', 'user-2']);
+     */
+    deleteBatchObjects(objectKeys: string[]): Promise<void>;
+    /**
+     * Reads an object from the S3 bucket.
+     * @template T - The expected type of the object.
+     * @param objectKey - The key of the object to read.
+     * @returns The parsed object.
+     *
+     * @example
+     * const user = await store.readObject<{ name: string }>('user-1');
+     */
+    readObject<T>(objectKey: string): Promise<T>;
+    /**
+     * Reads multiple objects from the S3 bucket.
+     * @template T - The expected type of the objects.
+     * @param objectKeys - The keys of the objects to read.
+     * @returns An array of parsed objects.
+     *
+     * @example
+     * const users = await store.readBatchObjects<{ name: string }>(['user-1', 'user-2']);
+     */
+    readBatchObjects<T>(objectKeys: string[]): Promise<T[]>;
+    /**
+     * Streams an object download from the S3 bucket.
+     * @param objectKey - The key of the object to download.
+     * @returns A readable stream of the object's contents.
+     * @throws If the S3 response does not include a readable stream.
+     *
+     * @example
+     * const stream = await store.streamDownloadObject('user-1');
+     * stream.pipe(fs.createWriteStream('user-1.json'));
+     */
+    streamDownloadObject(objectKey: string): Promise<Readable>;
+    /**
+     * Streams multiple object downloads from the S3 bucket.
+     * @param objectKeys - The keys of the objects to download.
+     * @returns An array of readable streams.
+     *
+     * @example
+     * const streams = await store.streamDownloadBatchObjects(['user-1', 'user-2']);
+     * streams[0].pipe(fs.createWriteStream('user-1.json'));
+     */
+    streamDownloadBatchObjects(objectKeys: string[]): Promise<Readable[]>;
+    /**
+     * Gets the underlying S3 client instance.
+     * @returns The S3Client instance used by this store.
+     *
+     * @example
+     * const s3Client = store.getClient();
+     */
+    getClient(): S3Client;
+}
+
+export { S3ObjectStore };

package/lib/index.js

@@ -0,0 +1,202 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  S3ObjectStore: () => S3ObjectStore
+});
+module.exports = __toCommonJS(index_exports);
+var import_client_s3 = require("@aws-sdk/client-s3");
+var import_stream = require("stream");
+var S3ObjectStore = class {
+  /**
+   * Creates a new S3ObjectStore instance.
+   * @param openTelemetryCollector - Collector for OpenTelemetry metrics.
+   * @param options - S3 configuration options.
+   * @param telemetryOptions - Telemetry configuration options.
+   *
+   * @example
+   * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);
+   */
+  constructor(openTelemetryCollector, options, telemetryOptions) {
+    this.openTelemetryCollector = openTelemetryCollector;
+    this.telemetryOptions = telemetryOptions;
+    this.s3 = options.client || new import_client_s3.S3Client(options.clientConfig || {});
+    this.bucket = options.bucket;
+  }
+  s3;
+  bucket;
+  /**
+   * Stores an object in the S3 bucket.
+   * @template T - The type of the object being stored.
+   * @param object - The object to store. Must include a `key` property.
+   *
+   * @example
+   * await store.putObject({ key: 'user-1', name: 'Alice' });
+   */
+  async putObject(object) {
+    const { key, ...rest } = object;
+    const params = {
+      Bucket: this.bucket,
+      Key: key,
+      Body: JSON.stringify(rest),
+      ContentType: "application/json"
+    };
+    await this.s3.send(new import_client_s3.PutObjectCommand(params));
+  }
+  /**
+   * Stores multiple objects in the S3 bucket.
+   * @template T - The type of the objects being stored.
+   * @param objects - The objects to store. Each must include a `key` property.
+   *
+   * @example
+   * await store.putBatchObjects([
+   *   { key: 'user-1', name: 'Alice' },
+   *   { key: 'user-2', name: 'Bob' }
+   * ]);
+   */
+  async putBatchObjects(objects) {
+    await Promise.all(objects.map((obj) => this.putObject(obj)));
+  }
+  /**
+   * Streams an object upload to the S3 bucket.
+   * For compatibility; uses putObject internally.
+   * @template T - The type of the object being stored.
+   * @param object - The object to stream-upload. Must include a `key` property.
+   */
+  async streamUploadObject(object) {
+    await this.putObject(object);
+  }
+  /**
+   * Streams multiple object uploads to the S3 bucket.
+   * For compatibility; uses putBatchObjects internally.
+   * @template T - The type of the objects being stored.
+   * @param objects - The objects to stream-upload. Each must include a `key` property.
+   */
+  async streamUploadBatchObjects(objects) {
+    await this.putBatchObjects(objects);
+  }
+  /**
+   * Deletes an object from the S3 bucket.
+   * @param objectKey - The key of the object to delete.
+   *
+   * @example
+   * await store.deleteObject('user-1');
+   */
+  async deleteObject(objectKey) {
+    await this.s3.send(
+      new import_client_s3.DeleteObjectCommand({ Bucket: this.bucket, Key: objectKey })
+    );
+  }
+  /**
+   * Deletes multiple objects from the S3 bucket.
+   * @param objectKeys - The keys of the objects to delete.
+   *
+   * @example
+   * await store.deleteBatchObjects(['user-1', 'user-2']);
+   */
+  async deleteBatchObjects(objectKeys) {
+    const params = {
+      Bucket: this.bucket,
+      Delete: {
+        Objects: objectKeys.map((Key) => ({ Key }))
+      }
+    };
+    await this.s3.send(new import_client_s3.DeleteObjectsCommand(params));
+  }
+  /**
+   * Reads an object from the S3 bucket.
+   * @template T - The expected type of the object.
+   * @param objectKey - The key of the object to read.
+   * @returns The parsed object.
+   *
+   * @example
+   * const user = await store.readObject<{ name: string }>('user-1');
+   */
+  async readObject(objectKey) {
+    const resp = await this.s3.send(
+      new import_client_s3.GetObjectCommand({ Bucket: this.bucket, Key: objectKey })
+    );
+    const body = resp.Body;
+    const chunks = [];
+    for await (const chunk of body) {
+      chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString());
+  }
+  /**
+   * Reads multiple objects from the S3 bucket.
+   * @template T - The expected type of the objects.
+   * @param objectKeys - The keys of the objects to read.
+   * @returns An array of parsed objects.
+   *
+   * @example
+   * const users = await store.readBatchObjects<{ name: string }>(['user-1', 'user-2']);
+   */
+  async readBatchObjects(objectKeys) {
+    return Promise.all(objectKeys.map((key) => this.readObject(key)));
+  }
+  /**
+   * Streams an object download from the S3 bucket.
+   * @param objectKey - The key of the object to download.
+   * @returns A readable stream of the object's contents.
+   * @throws If the S3 response does not include a readable stream.
+   *
+   * @example
+   * const stream = await store.streamDownloadObject('user-1');
+   * stream.pipe(fs.createWriteStream('user-1.json'));
+   */
+  async streamDownloadObject(objectKey) {
+    const resp = await this.s3.send(
+      new import_client_s3.GetObjectCommand({ Bucket: this.bucket, Key: objectKey })
+    );
+    if (!resp.Body || !(resp.Body instanceof import_stream.Readable)) {
+      throw new Error("S3 did not return a stream");
+    }
+    return resp.Body;
+  }
+  /**
+   * Streams multiple object downloads from the S3 bucket.
+   * @param objectKeys - The keys of the objects to download.
+   * @returns An array of readable streams.
+   *
+   * @example
+   * const streams = await store.streamDownloadBatchObjects(['user-1', 'user-2']);
+   * streams[0].pipe(fs.createWriteStream('user-1.json'));
+   */
+  async streamDownloadBatchObjects(objectKeys) {
+    return Promise.all(objectKeys.map((key) => this.streamDownloadObject(key)));
+  }
+  /**
+   * Gets the underlying S3 client instance.
+   * @returns The S3Client instance used by this store.
+   *
+   * @example
+   * const s3Client = store.getClient();
+   */
+  getClient() {
+    return this.s3;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  S3ObjectStore
+});
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.ts"],"sourcesContent":["import {\n  DeleteObjectCommand,\n  DeleteObjectsCommand,\n  DeleteObjectsCommandInput,\n  GetObjectCommand,\n  PutObjectCommand,\n  PutObjectCommandInput,\n  S3Client\n} from '@aws-sdk/client-s3';\nimport {\n  MetricsDefinition,\n  OpenTelemetryCollector,\n  TelemetryOptions\n} from '@forklaunch/core/http';\nimport { ObjectStore } from '@forklaunch/core/objectstore';\nimport { Readable } from 'stream';\n\n/**\n * Options for configuring the S3ObjectStore.\n *\n * @example\n * const options: S3ObjectStoreOptions = {\n *   bucket: 'my-bucket',\n *   clientConfig: { region: 'us-west-2' }\n * };\n */\ninterface S3ObjectStoreOptions {\n  /** The S3 bucket name. */\n  bucket: string;\n  /** Optional existing S3 client instance. */\n  client?: S3Client;\n  /** Optional configuration for creating a new S3 client. */\n  clientConfig?: ConstructorParameters<typeof S3Client>[0];\n}\n\n/**\n * S3-backed implementation of the ObjectStore interface.\n * Provides methods for storing, retrieving, streaming, and deleting objects in S3.\n *\n * @example\n * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);\n * await store.putObject({ key: 'user-1', name: 'Alice' });\n * const user = await store.readObject<{ name: string }>('user-1');\n */\nexport class S3ObjectStore implements ObjectStore<S3Client> {\n  private s3: S3Client;\n  private bucket: string;\n\n  /**\n   * Creates a new S3ObjectStore instance.\n   * @param openTelemetryCollector - Collector for OpenTelemetry metrics.\n   * @param options - S3 configuration options.\n   * @param telemetryOptions - Telemetry configuration options.\n   *\n   * @example\n   * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);\n   */\n  constructor(\n    private openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>,\n    options: S3ObjectStoreOptions,\n    private telemetryOptions: TelemetryOptions\n  ) {\n    this.s3 = options.client || new S3Client(options.clientConfig || {});\n    this.bucket = options.bucket;\n  }\n\n  /**\n   * Stores an object in the S3 bucket.\n   * @template T - The type of the object being stored.\n   * @param object - The object to store. Must include a `key` property.\n   *\n   * @example\n   * await store.putObject({ key: 'user-1', name: 'Alice' });\n   */\n  async putObject<T>(object: T & { key: string }): Promise<void> {\n    const { key, ...rest } = object;\n    const params: PutObjectCommandInput = {\n      Bucket: this.bucket,\n      Key: key,\n      Body: JSON.stringify(rest),\n      ContentType: 'application/json'\n    };\n    await this.s3.send(new PutObjectCommand(params));\n  }\n\n  /**\n   * Stores multiple objects in the S3 bucket.\n   * @template T - The type of the objects being stored.\n   * @param objects - The objects to store. Each must include a `key` property.\n   *\n   * @example\n   * await store.putBatchObjects([\n   *   { key: 'user-1', name: 'Alice' },\n   *   { key: 'user-2', name: 'Bob' }\n   * ]);\n   */\n  async putBatchObjects<T>(objects: (T & { key: string })[]): Promise<void> {\n    await Promise.all(objects.map((obj) => this.putObject(obj)));\n  }\n\n  /**\n   * Streams an object upload to the S3 bucket.\n   * For compatibility; uses putObject internally.\n   * @template T - The type of the object being stored.\n   * @param object - The object to stream-upload. Must include a `key` property.\n   */\n  async streamUploadObject<T>(object: T & { key: string }): Promise<void> {\n    await this.putObject(object);\n  }\n\n  /**\n   * Streams multiple object uploads to the S3 bucket.\n   * For compatibility; uses putBatchObjects internally.\n   * @template T - The type of the objects being stored.\n   * @param objects - The objects to stream-upload. Each must include a `key` property.\n   */\n  async streamUploadBatchObjects<T>(\n    objects: (T & { key: string })[]\n  ): Promise<void> {\n    await this.putBatchObjects(objects);\n  }\n\n  /**\n   * Deletes an object from the S3 bucket.\n   * @param objectKey - The key of the object to delete.\n   *\n   * @example\n   * await store.deleteObject('user-1');\n   */\n  async deleteObject(objectKey: string): Promise<void> {\n    await this.s3.send(\n      new DeleteObjectCommand({ Bucket: this.bucket, Key: objectKey })\n    );\n  }\n\n  /**\n   * Deletes multiple objects from the S3 bucket.\n   * @param objectKeys - The keys of the objects to delete.\n   *\n   * @example\n   * await store.deleteBatchObjects(['user-1', 'user-2']);\n   */\n  async deleteBatchObjects(objectKeys: string[]): Promise<void> {\n    const params: DeleteObjectsCommandInput = {\n      Bucket: this.bucket,\n      Delete: {\n        Objects: objectKeys.map((Key) => ({ Key }))\n      }\n    };\n    await this.s3.send(new DeleteObjectsCommand(params));\n  }\n\n  /**\n   * Reads an object from the S3 bucket.\n   * @template T - The expected type of the object.\n   * @param objectKey - The key of the object to read.\n   * @returns The parsed object.\n   *\n   * @example\n   * const user = await store.readObject<{ name: string }>('user-1');\n   */\n  async readObject<T>(objectKey: string): Promise<T> {\n    const resp = await this.s3.send(\n      new GetObjectCommand({ Bucket: this.bucket, Key: objectKey })\n    );\n    const body = resp.Body as Readable;\n    const chunks: Buffer[] = [];\n    for await (const chunk of body) {\n      chunks.push(chunk);\n    }\n    return JSON.parse(Buffer.concat(chunks).toString()) as T;\n  }\n\n  /**\n   * Reads multiple objects from the S3 bucket.\n   * @template T - The expected type of the objects.\n   * @param objectKeys - The keys of the objects to read.\n   * @returns An array of parsed objects.\n   *\n   * @example\n   * const users = await store.readBatchObjects<{ name: string }>(['user-1', 'user-2']);\n   */\n  async readBatchObjects<T>(objectKeys: string[]): Promise<T[]> {\n    return Promise.all(objectKeys.map((key) => this.readObject<T>(key)));\n  }\n\n  /**\n   * Streams an object download from the S3 bucket.\n   * @param objectKey - The key of the object to download.\n   * @returns A readable stream of the object's contents.\n   * @throws If the S3 response does not include a readable stream.\n   *\n   * @example\n   * const stream = await store.streamDownloadObject('user-1');\n   * stream.pipe(fs.createWriteStream('user-1.json'));\n   */\n  async streamDownloadObject(objectKey: string): Promise<Readable> {\n    const resp = await this.s3.send(\n      new GetObjectCommand({ Bucket: this.bucket, Key: objectKey })\n    );\n    if (!resp.Body || !(resp.Body instanceof Readable)) {\n      throw new Error('S3 did not return a stream');\n    }\n    return resp.Body;\n  }\n\n  /**\n   * Streams multiple object downloads from the S3 bucket.\n   * @param objectKeys - The keys of the objects to download.\n   * @returns An array of readable streams.\n   *\n   * @example\n   * const streams = await store.streamDownloadBatchObjects(['user-1', 'user-2']);\n   * streams[0].pipe(fs.createWriteStream('user-1.json'));\n   */\n  async streamDownloadBatchObjects(objectKeys: string[]): Promise<Readable[]> {\n    return Promise.all(objectKeys.map((key) => this.streamDownloadObject(key)));\n  }\n\n  /**\n   * Gets the underlying S3 client instance.\n   * @returns The S3Client instance used by this store.\n   *\n   * @example\n   * const s3Client = store.getClient();\n   */\n  getClient(): S3Client {\n    return this.s3;\n  }\n}\n"],"mappings":"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","names":[]}

package/lib/index.mjs

@@ -0,0 +1,183 @@
+// index.ts
+import {
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  GetObjectCommand,
+  PutObjectCommand,
+  S3Client
+} from "@aws-sdk/client-s3";
+import { Readable } from "stream";
+var S3ObjectStore = class {
+  /**
+   * Creates a new S3ObjectStore instance.
+   * @param openTelemetryCollector - Collector for OpenTelemetry metrics.
+   * @param options - S3 configuration options.
+   * @param telemetryOptions - Telemetry configuration options.
+   *
+   * @example
+   * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);
+   */
+  constructor(openTelemetryCollector, options, telemetryOptions) {
+    this.openTelemetryCollector = openTelemetryCollector;
+    this.telemetryOptions = telemetryOptions;
+    this.s3 = options.client || new S3Client(options.clientConfig || {});
+    this.bucket = options.bucket;
+  }
+  s3;
+  bucket;
+  /**
+   * Stores an object in the S3 bucket.
+   * @template T - The type of the object being stored.
+   * @param object - The object to store. Must include a `key` property.
+   *
+   * @example
+   * await store.putObject({ key: 'user-1', name: 'Alice' });
+   */
+  async putObject(object) {
+    const { key, ...rest } = object;
+    const params = {
+      Bucket: this.bucket,
+      Key: key,
+      Body: JSON.stringify(rest),
+      ContentType: "application/json"
+    };
+    await this.s3.send(new PutObjectCommand(params));
+  }
+  /**
+   * Stores multiple objects in the S3 bucket.
+   * @template T - The type of the objects being stored.
+   * @param objects - The objects to store. Each must include a `key` property.
+   *
+   * @example
+   * await store.putBatchObjects([
+   *   { key: 'user-1', name: 'Alice' },
+   *   { key: 'user-2', name: 'Bob' }
+   * ]);
+   */
+  async putBatchObjects(objects) {
+    await Promise.all(objects.map((obj) => this.putObject(obj)));
+  }
+  /**
+   * Streams an object upload to the S3 bucket.
+   * For compatibility; uses putObject internally.
+   * @template T - The type of the object being stored.
+   * @param object - The object to stream-upload. Must include a `key` property.
+   */
+  async streamUploadObject(object) {
+    await this.putObject(object);
+  }
+  /**
+   * Streams multiple object uploads to the S3 bucket.
+   * For compatibility; uses putBatchObjects internally.
+   * @template T - The type of the objects being stored.
+   * @param objects - The objects to stream-upload. Each must include a `key` property.
+   */
+  async streamUploadBatchObjects(objects) {
+    await this.putBatchObjects(objects);
+  }
+  /**
+   * Deletes an object from the S3 bucket.
+   * @param objectKey - The key of the object to delete.
+   *
+   * @example
+   * await store.deleteObject('user-1');
+   */
+  async deleteObject(objectKey) {
+    await this.s3.send(
+      new DeleteObjectCommand({ Bucket: this.bucket, Key: objectKey })
+    );
+  }
+  /**
+   * Deletes multiple objects from the S3 bucket.
+   * @param objectKeys - The keys of the objects to delete.
+   *
+   * @example
+   * await store.deleteBatchObjects(['user-1', 'user-2']);
+   */
+  async deleteBatchObjects(objectKeys) {
+    const params = {
+      Bucket: this.bucket,
+      Delete: {
+        Objects: objectKeys.map((Key) => ({ Key }))
+      }
+    };
+    await this.s3.send(new DeleteObjectsCommand(params));
+  }
+  /**
+   * Reads an object from the S3 bucket.
+   * @template T - The expected type of the object.
+   * @param objectKey - The key of the object to read.
+   * @returns The parsed object.
+   *
+   * @example
+   * const user = await store.readObject<{ name: string }>('user-1');
+   */
+  async readObject(objectKey) {
+    const resp = await this.s3.send(
+      new GetObjectCommand({ Bucket: this.bucket, Key: objectKey })
+    );
+    const body = resp.Body;
+    const chunks = [];
+    for await (const chunk of body) {
+      chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString());
+  }
+  /**
+   * Reads multiple objects from the S3 bucket.
+   * @template T - The expected type of the objects.
+   * @param objectKeys - The keys of the objects to read.
+   * @returns An array of parsed objects.
+   *
+   * @example
+   * const users = await store.readBatchObjects<{ name: string }>(['user-1', 'user-2']);
+   */
+  async readBatchObjects(objectKeys) {
+    return Promise.all(objectKeys.map((key) => this.readObject(key)));
+  }
+  /**
+   * Streams an object download from the S3 bucket.
+   * @param objectKey - The key of the object to download.
+   * @returns A readable stream of the object's contents.
+   * @throws If the S3 response does not include a readable stream.
+   *
+   * @example
+   * const stream = await store.streamDownloadObject('user-1');
+   * stream.pipe(fs.createWriteStream('user-1.json'));
+   */
+  async streamDownloadObject(objectKey) {
+    const resp = await this.s3.send(
+      new GetObjectCommand({ Bucket: this.bucket, Key: objectKey })
+    );
+    if (!resp.Body || !(resp.Body instanceof Readable)) {
+      throw new Error("S3 did not return a stream");
+    }
+    return resp.Body;
+  }
+  /**
+   * Streams multiple object downloads from the S3 bucket.
+   * @param objectKeys - The keys of the objects to download.
+   * @returns An array of readable streams.
+   *
+   * @example
+   * const streams = await store.streamDownloadBatchObjects(['user-1', 'user-2']);
+   * streams[0].pipe(fs.createWriteStream('user-1.json'));
+   */
+  async streamDownloadBatchObjects(objectKeys) {
+    return Promise.all(objectKeys.map((key) => this.streamDownloadObject(key)));
+  }
+  /**
+   * Gets the underlying S3 client instance.
+   * @returns The S3Client instance used by this store.
+   *
+   * @example
+   * const s3Client = store.getClient();
+   */
+  getClient() {
+    return this.s3;
+  }
+};
+export {
+  S3ObjectStore
+};
+//# sourceMappingURL=index.mjs.map

package/lib/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../index.ts"],"sourcesContent":["import {\n  DeleteObjectCommand,\n  DeleteObjectsCommand,\n  DeleteObjectsCommandInput,\n  GetObjectCommand,\n  PutObjectCommand,\n  PutObjectCommandInput,\n  S3Client\n} from '@aws-sdk/client-s3';\nimport {\n  MetricsDefinition,\n  OpenTelemetryCollector,\n  TelemetryOptions\n} from '@forklaunch/core/http';\nimport { ObjectStore } from '@forklaunch/core/objectstore';\nimport { Readable } from 'stream';\n\n/**\n * Options for configuring the S3ObjectStore.\n *\n * @example\n * const options: S3ObjectStoreOptions = {\n *   bucket: 'my-bucket',\n *   clientConfig: { region: 'us-west-2' }\n * };\n */\ninterface S3ObjectStoreOptions {\n  /** The S3 bucket name. */\n  bucket: string;\n  /** Optional existing S3 client instance. */\n  client?: S3Client;\n  /** Optional configuration for creating a new S3 client. */\n  clientConfig?: ConstructorParameters<typeof S3Client>[0];\n}\n\n/**\n * S3-backed implementation of the ObjectStore interface.\n * Provides methods for storing, retrieving, streaming, and deleting objects in S3.\n *\n * @example\n * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);\n * await store.putObject({ key: 'user-1', name: 'Alice' });\n * const user = await store.readObject<{ name: string }>('user-1');\n */\nexport class S3ObjectStore implements ObjectStore<S3Client> {\n  private s3: S3Client;\n  private bucket: string;\n\n  /**\n   * Creates a new S3ObjectStore instance.\n   * @param openTelemetryCollector - Collector for OpenTelemetry metrics.\n   * @param options - S3 configuration options.\n   * @param telemetryOptions - Telemetry configuration options.\n   *\n   * @example\n   * const store = new S3ObjectStore(otelCollector, { bucket: 'my-bucket' }, telemetryOptions);\n   */\n  constructor(\n    private openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>,\n    options: S3ObjectStoreOptions,\n    private telemetryOptions: TelemetryOptions\n  ) {\n    this.s3 = options.client || new S3Client(options.clientConfig || {});\n    this.bucket = options.bucket;\n  }\n\n  /**\n   * Stores an object in the S3 bucket.\n   * @template T - The type of the object being stored.\n   * @param object - The object to store. Must include a `key` property.\n   *\n   * @example\n   * await store.putObject({ key: 'user-1', name: 'Alice' });\n   */\n  async putObject<T>(object: T & { key: string }): Promise<void> {\n    const { key, ...rest } = object;\n    const params: PutObjectCommandInput = {\n      Bucket: this.bucket,\n      Key: key,\n      Body: JSON.stringify(rest),\n      ContentType: 'application/json'\n    };\n    await this.s3.send(new PutObjectCommand(params));\n  }\n\n  /**\n   * Stores multiple objects in the S3 bucket.\n   * @template T - The type of the objects being stored.\n   * @param objects - The objects to store. Each must include a `key` property.\n   *\n   * @example\n   * await store.putBatchObjects([\n   *   { key: 'user-1', name: 'Alice' },\n   *   { key: 'user-2', name: 'Bob' }\n   * ]);\n   */\n  async putBatchObjects<T>(objects: (T & { key: string })[]): Promise<void> {\n    await Promise.all(objects.map((obj) => this.putObject(obj)));\n  }\n\n  /**\n   * Streams an object upload to the S3 bucket.\n   * For compatibility; uses putObject internally.\n   * @template T - The type of the object being stored.\n   * @param object - The object to stream-upload. Must include a `key` property.\n   */\n  async streamUploadObject<T>(object: T & { key: string }): Promise<void> {\n    await this.putObject(object);\n  }\n\n  /**\n   * Streams multiple object uploads to the S3 bucket.\n   * For compatibility; uses putBatchObjects internally.\n   * @template T - The type of the objects being stored.\n   * @param objects - The objects to stream-upload. Each must include a `key` property.\n   */\n  async streamUploadBatchObjects<T>(\n    objects: (T & { key: string })[]\n  ): Promise<void> {\n    await this.putBatchObjects(objects);\n  }\n\n  /**\n   * Deletes an object from the S3 bucket.\n   * @param objectKey - The key of the object to delete.\n   *\n   * @example\n   * await store.deleteObject('user-1');\n   */\n  async deleteObject(objectKey: string): Promise<void> {\n    await this.s3.send(\n      new DeleteObjectCommand({ Bucket: this.bucket, Key: objectKey })\n    );\n  }\n\n  /**\n   * Deletes multiple objects from the S3 bucket.\n   * @param objectKeys - The keys of the objects to delete.\n   *\n   * @example\n   * await store.deleteBatchObjects(['user-1', 'user-2']);\n   */\n  async deleteBatchObjects(objectKeys: string[]): Promise<void> {\n    const params: DeleteObjectsCommandInput = {\n      Bucket: this.bucket,\n      Delete: {\n        Objects: objectKeys.map((Key) => ({ Key }))\n      }\n    };\n    await this.s3.send(new DeleteObjectsCommand(params));\n  }\n\n  /**\n   * Reads an object from the S3 bucket.\n   * @template T - The expected type of the object.\n   * @param objectKey - The key of the object to read.\n   * @returns The parsed object.\n   *\n   * @example\n   * const user = await store.readObject<{ name: string }>('user-1');\n   */\n  async readObject<T>(objectKey: string): Promise<T> {\n    const resp = await this.s3.send(\n      new GetObjectCommand({ Bucket: this.bucket, Key: objectKey })\n    );\n    const body = resp.Body as Readable;\n    const chunks: Buffer[] = [];\n    for await (const chunk of body) {\n      chunks.push(chunk);\n    }\n    return JSON.parse(Buffer.concat(chunks).toString()) as T;\n  }\n\n  /**\n   * Reads multiple objects from the S3 bucket.\n   * @template T - The expected type of the objects.\n   * @param objectKeys - The keys of the objects to read.\n   * @returns An array of parsed objects.\n   *\n   * @example\n   * const users = await store.readBatchObjects<{ name: string }>(['user-1', 'user-2']);\n   */\n  async readBatchObjects<T>(objectKeys: string[]): Promise<T[]> {\n    return Promise.all(objectKeys.map((key) => this.readObject<T>(key)));\n  }\n\n  /**\n   * Streams an object download from the S3 bucket.\n   * @param objectKey - The key of the object to download.\n   * @returns A readable stream of the object's contents.\n   * @throws If the S3 response does not include a readable stream.\n   *\n   * @example\n   * const stream = await store.streamDownloadObject('user-1');\n   * stream.pipe(fs.createWriteStream('user-1.json'));\n   */\n  async streamDownloadObject(objectKey: string): Promise<Readable> {\n    const resp = await this.s3.send(\n      new GetObjectCommand({ Bucket: this.bucket, Key: objectKey })\n    );\n    if (!resp.Body || !(resp.Body instanceof Readable)) {\n      throw new Error('S3 did not return a stream');\n    }\n    return resp.Body;\n  }\n\n  /**\n   * Streams multiple object downloads from the S3 bucket.\n   * @param objectKeys - The keys of the objects to download.\n   * @returns An array of readable streams.\n   *\n   * @example\n   * const streams = await store.streamDownloadBatchObjects(['user-1', 'user-2']);\n   * streams[0].pipe(fs.createWriteStream('user-1.json'));\n   */\n  async streamDownloadBatchObjects(objectKeys: string[]): Promise<Readable[]> {\n    return Promise.all(objectKeys.map((key) => this.streamDownloadObject(key)));\n  }\n\n  /**\n   * Gets the underlying S3 client instance.\n   * @returns The S3Client instance used by this store.\n   *\n   * @example\n   * const s3Client = store.getClient();\n   */\n  getClient(): S3Client {\n    return this.s3;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@forklaunch/infrastructure-s3",
+  "version": "0.0.1",
+  "description": "S3 infrastructure for ForkLaunch components.",
+  "homepage": "https://github.com/forklaunch/forklaunch-js#readme",
+  "bugs": {
+    "url": "https://github.com/forklaunch/forklaunch-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forklaunch/forklaunch-js.git"
+  },
+  "license": "MIT",
+  "author": "Rohin Bhargava",
+  "exports": {
+    ".": {
+      "types": "./lib/src/index.d.ts",
+      "import": "./lib/src/index.mjs",
+      "require": "./lib/src/index.js",
+      "default": "./lib/src/index.js"
+    }
+  },
+  "types": "lib/index.d.ts",
+  "directories": {
+    "test": "__test__"
+  },
+  "files": [
+    "lib/**"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.821.0",
+    "@forklaunch/core": "0.8.3",
+    "@forklaunch/common": "0.3.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.27.0",
+    "@types/jest": "^29.5.14",
+    "globals": "^16.2.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.3",
+    "ts-jest": "^29.3.4",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.0",
+    "typedoc": "^0.28.5",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.33.0"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && tsup ./index.ts --format cjs,esm --no-splitting --dts --tsconfig tsconfig.json --out-dir lib --clean --sourcemap && if [ -f eject-infrastructure-package.bash ]; then pnpm package:eject; fi",
+    "clean": "rm -rf lib pnpm.lock.yaml node_modules",
+    "docs": "typedoc --out docs *",
+    "format": "prettier --ignore-path=.prettierignore --config .prettierrc '**/*.{ts,tsx,json}' --write",
+    "lint": "eslint . -c eslint.config.mjs",
+    "lint:fix": "eslint . -c eslint.config.mjs --fix",
+    "package:eject": "./eject-infrastructure-package.bash s3",
+    "publish:package": "./publish-package.bash",
+    "test": "vitest --passWithNoTests"
+  }
+}