@elaraai/east-node-io 0.0.1-beta.1 → 0.0.1-beta.11

package/dist/storage/s3.js

@@ -0,0 +1,502 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * S3 platform functions for East Node IO.
+ *
+ * Provides S3 and S3-compatible object storage operations for East programs,
+ * including upload, download, delete, list, and presigned URL generation.
+ *
+ * @packageDocumentation
+ */
+import { East, BlobType, StringType, IntegerType, NullType, variant } from "@elaraai/east";
+import { EastError } from "@elaraai/east/internal";
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, ListObjectsV2Command, HeadObjectCommand, } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { S3ConfigType, S3ListResultType, S3ObjectMetadataType } from "./types.js";
+/**
+ * Creates an S3 client from configuration.
+ *
+ * @param config - S3 configuration
+ * @returns Configured S3Client instance
+ * @internal
+ */
+function createS3Client(config) {
+    const credentials = config.accessKeyId?.type === 'some' && config.secretAccessKey?.type === 'some'
+        ? {
+            accessKeyId: config.accessKeyId.value,
+            secretAccessKey: config.secretAccessKey.value,
+        }
+        : undefined;
+    const endpoint = config.endpoint?.type === 'some' ? config.endpoint.value : undefined;
+    // Build S3 client config conditionally to satisfy exactOptionalPropertyTypes
+    const clientConfig = {
+        region: config.region,
+        credentials,
+    };
+    if (endpoint !== undefined) {
+        clientConfig.endpoint = endpoint;
+        clientConfig.forcePathStyle = true; // Use path-style for S3-compatible services
+    }
+    return new S3Client(clientConfig);
+}
+/**
+ * Uploads an object to S3.
+ *
+ * Uploads binary data to an S3 bucket with the specified key (path).
+ * Overwrites existing objects with the same key.
+ *
+ * This is a platform function for the East language, enabling S3 object storage
+ * operations in East programs running on Node.js.
+ *
+ * @param config - S3 configuration
+ * @param key - Object key (path) in the bucket
+ * @param data - Binary data to upload
+ * @returns Null on success
+ *
+ * @throws {EastError} When upload fails due to:
+ * - Invalid bucket name (location: "s3_put_object")
+ * - Authentication failure (location: "s3_put_object")
+ * - Network errors (location: "s3_put_object")
+ * - Permission denied (location: "s3_put_object")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, BlobType } from "@elaraai/east";
+ * import { Storage } from "@elaraai/east-node-io";
+ *
+ * const uploadFile = East.function([StringType, BlobType], StringType, ($, filename, data) => {
+ *     const config = $.let({
+ *         region: "us-east-1",
+ *         bucket: "my-bucket",
+ *         accessKeyId: East.some("AKIAIOSFODNN7EXAMPLE"),
+ *         secretAccessKey: East.some("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"),
+ *         endpoint: East.none(),
+ *     });
+ *
+ *     // Upload the file
+ *     $(Storage.S3.putObject(config, filename, data));
+ *
+ *     // Generate presigned URL for sharing
+ *     return Storage.S3.presignUrl(config, filename, 3600n);
+ * });
+ *
+ * const compiled = East.compileAsync(uploadFile.toIR(), Storage.S3.Implementation);
+ * const url = await compiled("report.pdf", pdfBlob);
+ * ```
+ *
+ * @remarks
+ * - Supports S3 and S3-compatible services (MinIO, DigitalOcean Spaces, etc.)
+ * - Uses AWS SDK v3 for S3 operations
+ * - All operations are asynchronous (use East.compileAsync)
+ */
+export const s3_put_object = East.asyncPlatform("s3_put_object", [S3ConfigType, StringType, BlobType], NullType);
+/**
+ * Downloads an object from S3.
+ *
+ * Retrieves binary data from an S3 bucket by key (path).
+ * Returns the object data as a Blob (Uint8Array).
+ *
+ * This is a platform function for the East language, enabling S3 object storage
+ * operations in East programs running on Node.js.
+ *
+ * @param config - S3 configuration
+ * @param key - Object key (path) in the bucket
+ * @returns Binary data as Blob
+ *
+ * @throws {EastError} When download fails due to:
+ * - Object not found (location: "s3_get_object")
+ * - Invalid bucket name (location: "s3_get_object")
+ * - Authentication failure (location: "s3_get_object")
+ * - Network errors (location: "s3_get_object")
+ * - Permission denied (location: "s3_get_object")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, BlobType } from "@elaraai/east";
+ * import { Storage } from "@elaraai/east-node-io";
+ *
+ * const downloadFile = East.function([StringType], BlobType, ($, filename) => {
+ *     const config = $.let({
+ *         region: "us-east-1",
+ *         bucket: "my-bucket",
+ *         accessKeyId: East.none(),
+ *         secretAccessKey: East.none(),
+ *         endpoint: East.none(),
+ *     });
+ *
+ *     return Storage.S3.getObject(config, filename);
+ * });
+ *
+ * const compiled = East.compileAsync(downloadFile.toIR(), Storage.S3.Implementation);
+ * const pdfData = await compiled("report.pdf");  // Returns Uint8Array
+ * ```
+ *
+ * @remarks
+ * - Returns Uint8Array (BlobType) containing raw binary data
+ * - Use decodeUtf8() to convert text files to strings
+ * - Streams large objects automatically
+ */
+export const s3_get_object = East.asyncPlatform("s3_get_object", [S3ConfigType, StringType], BlobType);
+/**
+ * Retrieves object metadata from S3 without downloading the file.
+ *
+ * Gets metadata for an S3 object including size, ETag (hash), last modified time,
+ * and content type. This is useful for checking if a file has changed without
+ * downloading it by comparing ETags.
+ *
+ * This is a platform function for the East language, enabling S3 object storage
+ * operations in East programs running on Node.js.
+ *
+ * @param config - S3 configuration
+ * @param key - Object key (path) in the bucket
+ * @returns Object metadata including ETag, size, and timestamps
+ *
+ * @throws {EastError} When metadata retrieval fails due to:
+ * - Object not found (location: "s3_head_object")
+ * - Invalid bucket name (location: "s3_head_object")
+ * - Authentication failure (location: "s3_head_object")
+ * - Network errors (location: "s3_head_object")
+ * - Permission denied (location: "s3_head_object")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType } from "@elaraai/east";
+ * import { Storage } from "@elaraai/east-node-io";
+ *
+ * const checkFileChanged = East.function([StringType, StringType], BooleanType, ($, filename, localEtag) => {
+ *     const config = $.let({
+ *         region: "us-east-1",
+ *         bucket: "my-bucket",
+ *         accessKeyId: East.none(),
+ *         secretAccessKey: East.none(),
+ *         endpoint: East.none(),
+ *     });
+ *
+ *     const metadata = $.let(Storage.S3.headObject(config, filename));
+ *
+ *     return $.match(metadata.etag, {
+ *         some: ($, remoteEtag) => remoteEtag.notEqual(localEtag),
+ *         none: ($) => East.value(true), // File changed if no ETag available
+ *     });
+ * });
+ *
+ * const compiled = East.compileAsync(checkFileChanged.toIR(), Storage.S3.Implementation);
+ * const changed = await compiled("report.pdf", '"abc123def456"');  // ETags include quotes
+ * if (changed) {
+ *     // Download the file since it changed
+ * }
+ * ```
+ *
+ * @remarks
+ * - ETag is typically an MD5 hash (for simple uploads) or composite hash (for multipart uploads)
+ * - ETags include surrounding quotes (e.g., '"abc123"')
+ * - Much faster than downloading the entire file
+ * - Use this to implement efficient sync/caching logic
+ */
+export const s3_head_object = East.asyncPlatform("s3_head_object", [S3ConfigType, StringType], S3ObjectMetadataType);
+/**
+ * Deletes an object from S3.
+ *
+ * Removes an object from an S3 bucket by key (path).
+ * Succeeds even if the object doesn't exist (idempotent).
+ *
+ * This is a platform function for the East language, enabling S3 object storage
+ * operations in East programs running on Node.js.
+ *
+ * @param config - S3 configuration
+ * @param key - Object key (path) to delete
+ * @returns Null on success
+ *
+ * @throws {EastError} When deletion fails due to:
+ * - Invalid bucket name (location: "s3_delete_object")
+ * - Authentication failure (location: "s3_delete_object")
+ * - Network errors (location: "s3_delete_object")
+ * - Permission denied (location: "s3_delete_object")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, NullType } from "@elaraai/east";
+ * import { Storage } from "@elaraai/east-node-io";
+ *
+ * const deleteFile = East.function([StringType], NullType, ($, filename) => {
+ *     const config = $.let({
+ *         region: "us-east-1",
+ *         bucket: "my-bucket",
+ *         accessKeyId: East.none(),
+ *         secretAccessKey: East.none(),
+ *         endpoint: East.none(),
+ *     });
+ *
+ *     return Storage.S3.deleteObject(config, filename);
+ * });
+ *
+ * const compiled = East.compileAsync(deleteFile.toIR(), Storage.S3.Implementation);
+ * await compiled("old-report.pdf");
+ * ```
+ *
+ * @remarks
+ * - Idempotent: succeeds even if object doesn't exist
+ * - Does not delete versioned objects (only current version)
+ */
+export const s3_delete_object = East.asyncPlatform("s3_delete_object", [S3ConfigType, StringType], NullType);
+/**
+ * Lists objects in an S3 bucket with a prefix.
+ *
+ * Retrieves metadata for objects matching a prefix, with pagination support.
+ * Returns up to `maxKeys` objects per request.
+ *
+ * This is a platform function for the East language, enabling S3 object storage
+ * operations in East programs running on Node.js.
+ *
+ * @param config - S3 configuration
+ * @param prefix - Prefix to filter objects (empty string for all objects)
+ * @param maxKeys - Maximum number of objects to return (1-1000)
+ * @returns List result with objects and pagination info
+ *
+ * @throws {EastError} When listing fails due to:
+ * - Invalid bucket name (location: "s3_list_objects")
+ * - Authentication failure (location: "s3_list_objects")
+ * - Network errors (location: "s3_list_objects")
+ * - Permission denied (location: "s3_list_objects")
+ * - Invalid maxKeys value (location: "s3_list_objects")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, ArrayType } from "@elaraai/east";
+ * import { Storage, S3ObjectMetadataType } from "@elaraai/east-node-io";
+ *
+ * const listReports = East.function([], ArrayType(S3ObjectMetadataType), ($) => {
+ *     const config = $.let({
+ *         region: "us-east-1",
+ *         bucket: "my-bucket",
+ *         accessKeyId: East.none(),
+ *         secretAccessKey: East.none(),
+ *         endpoint: East.none(),
+ *     });
+ *
+ *     const result = $.let(Storage.S3.listObjects(config, "reports/", 100n));
+ *     return result.objects;
+ * });
+ *
+ * const compiled = East.compileAsync(listReports.toIR(), Storage.S3.Implementation);
+ * const reports = await compiled();
+ * ```
+ *
+ * @remarks
+ * - Returns objects sorted by key (lexicographically)
+ * - Use continuationToken from result to fetch next page
+ * - maxKeys is clamped to 1-1000 range
+ */
+export const s3_list_objects = East.asyncPlatform("s3_list_objects", [S3ConfigType, StringType, IntegerType], S3ListResultType);
+/**
+ * Generates a presigned URL for temporary access to an S3 object.
+ *
+ * Creates a signed URL that grants temporary access to an object without
+ * requiring AWS credentials. Useful for sharing files or client-side uploads.
+ *
+ * This is a platform function for the East language, enabling S3 object storage
+ * operations in East programs running on Node.js.
+ *
+ * @param config - S3 configuration
+ * @param key - Object key (path) in the bucket
+ * @param expiresIn - URL expiration time in seconds (1-604800)
+ * @returns Presigned URL as string
+ *
+ * @throws {EastError} When URL generation fails due to:
+ * - Invalid bucket name (location: "s3_presign_url")
+ * - Invalid expiration time (location: "s3_presign_url")
+ * - Missing credentials (location: "s3_presign_url")
+ * - Network errors (location: "s3_presign_url")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType } from "@elaraai/east";
+ * import { Storage } from "@elaraai/east-node-io";
+ *
+ * const shareFile = East.function([StringType], StringType, ($, filename) => {
+ *     const config = $.let({
+ *         region: "us-east-1",
+ *         bucket: "my-bucket",
+ *         accessKeyId: East.some("AKIAIOSFODNN7EXAMPLE"),
+ *         secretAccessKey: East.some("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"),
+ *         endpoint: East.none(),
+ *     });
+ *
+ *     // Generate URL valid for 1 hour
+ *     return Storage.S3.presignUrl(config, filename, 3600n);
+ * });
+ *
+ * const compiled = East.compileAsync(shareFile.toIR(), Storage.S3.Implementation);
+ * const url = await compiled("report.pdf");
+ * console.log(`Share this link: ${url}`);
+ * ```
+ *
+ * @remarks
+ * - URL expires after `expiresIn` seconds
+ * - Requires credentials (cannot use default AWS credential chain)
+ * - Works with S3-compatible services
+ * - Maximum expiration: 7 days (604800 seconds)
+ */
+export const s3_presign_url = East.asyncPlatform("s3_presign_url", [S3ConfigType, StringType, IntegerType], StringType);
+/**
+ * Node.js implementation of S3 platform functions.
+ *
+ * Provides the runtime implementations for S3 operations using AWS SDK v3.
+ * Pass this to East.compileAsync() to enable S3 functionality.
+ */
+export const S3Impl = [
+    s3_put_object.implement(async (config, key, data) => {
+        try {
+            const client = createS3Client(config);
+            const command = new PutObjectCommand({
+                Bucket: config.bucket,
+                Key: key,
+                Body: data,
+            });
+            await client.send(command);
+            return null;
+        }
+        catch (err) {
+            throw new EastError(`S3 putObject failed: ${err.message}`, {
+                location: { filename: "s3_put_object", line: 0n, column: 0n },
+                cause: err
+            });
+        }
+    }),
+    s3_get_object.implement(async (config, key) => {
+        try {
+            const client = createS3Client(config);
+            const command = new GetObjectCommand({
+                Bucket: config.bucket,
+                Key: key,
+            });
+            const response = await client.send(command);
+            if (!response.Body) {
+                throw new Error('Response body is empty');
+            }
+            // Convert stream to Uint8Array
+            const chunks = [];
+            for await (const chunk of response.Body) {
+                chunks.push(chunk);
+            }
+            // Concatenate all chunks
+            const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+            const result = new Uint8Array(totalLength);
+            let offset = 0;
+            for (const chunk of chunks) {
+                result.set(chunk, offset);
+                offset += chunk.length;
+            }
+            return result;
+        }
+        catch (err) {
+            throw new EastError(`S3 getObject failed: ${err.message}`, {
+                location: { filename: "s3_get_object", line: 0n, column: 0n },
+                cause: err
+            });
+        }
+    }),
+    s3_head_object.implement(async (config, key) => {
+        try {
+            const client = createS3Client(config);
+            const command = new HeadObjectCommand({
+                Bucket: config.bucket,
+                Key: key,
+            });
+            const response = await client.send(command);
+            return {
+                key,
+                size: BigInt(response.ContentLength || 0),
+                lastModified: response.LastModified || new Date(),
+                contentType: response.ContentType ? variant('some', response.ContentType) : variant('none', null),
+                etag: response.ETag ? variant('some', response.ETag) : variant('none', null),
+            };
+        }
+        catch (err) {
+            throw new EastError(`S3 headObject failed: ${err.message}`, {
+                location: { filename: "s3_head_object", line: 0n, column: 0n },
+                cause: err
+            });
+        }
+    }),
+    s3_delete_object.implement(async (config, key) => {
+        try {
+            const client = createS3Client(config);
+            const command = new DeleteObjectCommand({
+                Bucket: config.bucket,
+                Key: key,
+            });
+            await client.send(command);
+            return null;
+        }
+        catch (err) {
+            throw new EastError(`S3 deleteObject failed: ${err.message}`, {
+                location: { filename: "s3_delete_object", line: 0n, column: 0n },
+                cause: err
+            });
+        }
+    }),
+    s3_list_objects.implement(async (config, prefix, maxKeys) => {
+        try {
+            const client = createS3Client(config);
+            // Clamp maxKeys to valid range (1-1000)
+            const maxKeysNum = Number(maxKeys);
+            const clampedMaxKeys = Math.max(1, Math.min(1000, maxKeysNum));
+            const command = new ListObjectsV2Command({
+                Bucket: config.bucket,
+                Prefix: prefix,
+                MaxKeys: clampedMaxKeys,
+            });
+            const response = await client.send(command);
+            // Convert S3 objects to East metadata format
+            // Note: ContentType is not part of _Object in ListObjectsV2, only in HeadObject/GetObject
+            const objects = (response.Contents || []).map((obj) => ({
+                key: obj.Key || '',
+                size: BigInt(obj.Size || 0),
+                lastModified: obj.LastModified || new Date(),
+                contentType: variant('none', null), // ListObjectsV2 doesn't include ContentType
+                etag: obj.ETag
+                    ? variant('some', obj.ETag)
+                    : variant('none', null),
+            }));
+            return {
+                objects,
+                isTruncated: response.IsTruncated || false,
+                continuationToken: response.NextContinuationToken
+                    ? variant('some', response.NextContinuationToken)
+                    : variant('none', null),
+            };
+        }
+        catch (err) {
+            throw new EastError(`S3 listObjects failed: ${err.message}`, {
+                location: { filename: "s3_list_objects", line: 0n, column: 0n },
+                cause: err
+            });
+        }
+    }),
+    s3_presign_url.implement(async (config, key, expiresIn) => {
+        try {
+            const client = createS3Client(config);
+            // Clamp expiresIn to valid range (1 second to 7 days)
+            const expiresInNum = Number(expiresIn);
+            const clampedExpiresIn = Math.max(1, Math.min(604800, expiresInNum));
+            const command = new GetObjectCommand({
+                Bucket: config.bucket,
+                Key: key,
+            });
+            const url = await getSignedUrl(client, command, {
+                expiresIn: clampedExpiresIn,
+            });
+            return url;
+        }
+        catch (err) {
+            throw new EastError(`S3 presignUrl failed: ${err.message}`, {
+                location: { filename: "s3_presign_url", line: 0n, column: 0n },
+                cause: err
+            });
+        }
+    }),
+];
+//# sourceMappingURL=s3.js.map

package/dist/storage/s3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.js","sourceRoot":"","sources":["../../src/storage/s3.ts"],"names":[],"mappings":"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"}

package/dist/storage/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Shared storage type definitions for East Node IO.
+ *
+ * Provides East type definitions for S3 and S3-compatible object storage
+ * operations including configurations, metadata, and result types.
+ *
+ * @packageDocumentation
+ */
+import { StructType, OptionType, ArrayType, StringType, IntegerType, BooleanType, DateTimeType } from "@elaraai/east";
+/**
+ * S3 storage configuration.
+ *
+ * Configures connection to S3 or S3-compatible object storage services
+ * (MinIO, DigitalOcean Spaces, etc.).
+ */
+export declare const S3ConfigType: StructType<{
+    /**
+     * AWS region (e.g., "us-east-1", "eu-west-1").
+     */
+    region: StringType;
+    /**
+     * S3 bucket name.
+     */
+    bucket: StringType;
+    /**
+     * AWS access key ID for authentication.
+     * Optional, defaults to AWS credential chain.
+     */
+    accessKeyId: OptionType<StringType>;
+    /**
+     * AWS secret access key for authentication.
+     * Optional, defaults to AWS credential chain.
+     */
+    secretAccessKey: OptionType<StringType>;
+    /**
+     * Custom endpoint for S3-compatible services (e.g., "http://localhost:9000" for MinIO).
+     * Optional, defaults to AWS S3 endpoint.
+     */
+    endpoint: OptionType<StringType>;
+}>;
+/**
+ * S3 object metadata.
+ *
+ * Represents metadata about an object stored in S3.
+ */
+export declare const S3ObjectMetadataType: StructType<{
+    /**
+     * Object key (path) in the bucket.
+     */
+    key: StringType;
+    /**
+     * Object size in bytes.
+     */
+    size: IntegerType;
+    /**
+     * Last modified timestamp as a Date object.
+     */
+    lastModified: DateTimeType;
+    /**
+     * Content type of the object (MIME type).
+     * Optional, may be None if not set.
+     */
+    contentType: OptionType<StringType>;
+    /**
+     * ETag of the object (entity tag for versioning/caching).
+     * Optional, may be None if not available.
+     */
+    etag: OptionType<StringType>;
+}>;
+/**
+ * S3 list objects result.
+ *
+ * Contains the result of listing objects in an S3 bucket with pagination support.
+ */
+export declare const S3ListResultType: StructType<{
+    /**
+     * Array of object metadata for objects matching the prefix.
+     */
+    objects: ArrayType<StructType<{
+        /**
+         * Object key (path) in the bucket.
+         */
+        key: StringType;
+        /**
+         * Object size in bytes.
+         */
+        size: IntegerType;
+        /**
+         * Last modified timestamp as a Date object.
+         */
+        lastModified: DateTimeType;
+        /**
+         * Content type of the object (MIME type).
+         * Optional, may be None if not set.
+         */
+        contentType: OptionType<StringType>;
+        /**
+         * ETag of the object (entity tag for versioning/caching).
+         * Optional, may be None if not available.
+         */
+        etag: OptionType<StringType>;
+    }>>;
+    /**
+     * Whether the result list is truncated (more results available).
+     */
+    isTruncated: BooleanType;
+    /**
+     * Continuation token for fetching next page of results.
+     * Optional, None if no more results available.
+     */
+    continuationToken: OptionType<StringType>;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/dist/storage/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EACH,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACf,MAAM,eAAe,CAAC;AAEvB;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACrB;;OAEG;;IAGH;;OAEG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;EAEL,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;IAC7B;;OAEG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;;OAGG;;IAGH;;;OAGG;;EAEL,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;IACzB;;OAEG;;QApCH;;WAEG;;QAGH;;WAEG;;QAGH;;WAEG;;QAGH;;;WAGG;;QAGH;;;WAGG;;;IAeH;;OAEG;;IAGH;;;OAGG;;EAEL,CAAC"}