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

package/dist/storage/s3.d.ts

@@ -0,0 +1,373 @@
+/**
+ * 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 { BlobType, StringType, IntegerType, NullType } from "@elaraai/east";
+import type { PlatformFunction } from "@elaraai/east/internal";
+/**
+ * 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 declare const s3_put_object: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
+    region: StringType;
+    bucket: StringType;
+    accessKeyId: import("@elaraai/east").OptionType<StringType>;
+    secretAccessKey: import("@elaraai/east").OptionType<StringType>;
+    endpoint: import("@elaraai/east").OptionType<StringType>;
+}>, 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 declare const s3_get_object: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
+    region: StringType;
+    bucket: StringType;
+    accessKeyId: import("@elaraai/east").OptionType<StringType>;
+    secretAccessKey: import("@elaraai/east").OptionType<StringType>;
+    endpoint: import("@elaraai/east").OptionType<StringType>;
+}>, 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 declare const s3_head_object: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
+    region: StringType;
+    bucket: StringType;
+    accessKeyId: import("@elaraai/east").OptionType<StringType>;
+    secretAccessKey: import("@elaraai/east").OptionType<StringType>;
+    endpoint: import("@elaraai/east").OptionType<StringType>;
+}>, StringType], import("@elaraai/east").StructType<{
+    key: StringType;
+    size: IntegerType;
+    lastModified: import("@elaraai/east").DateTimeType;
+    contentType: import("@elaraai/east").OptionType<StringType>;
+    etag: import("@elaraai/east").OptionType<StringType>;
+}>>;
+/**
+ * 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 declare const s3_delete_object: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
+    region: StringType;
+    bucket: StringType;
+    accessKeyId: import("@elaraai/east").OptionType<StringType>;
+    secretAccessKey: import("@elaraai/east").OptionType<StringType>;
+    endpoint: import("@elaraai/east").OptionType<StringType>;
+}>, 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 declare const s3_list_objects: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
+    region: StringType;
+    bucket: StringType;
+    accessKeyId: import("@elaraai/east").OptionType<StringType>;
+    secretAccessKey: import("@elaraai/east").OptionType<StringType>;
+    endpoint: import("@elaraai/east").OptionType<StringType>;
+}>, StringType, IntegerType], import("@elaraai/east").StructType<{
+    objects: import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+        key: StringType;
+        size: IntegerType;
+        lastModified: import("@elaraai/east").DateTimeType;
+        contentType: import("@elaraai/east").OptionType<StringType>;
+        etag: import("@elaraai/east").OptionType<StringType>;
+    }>>;
+    isTruncated: import("@elaraai/east").BooleanType;
+    continuationToken: import("@elaraai/east").OptionType<StringType>;
+}>>;
+/**
+ * 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 declare const s3_presign_url: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
+    region: StringType;
+    bucket: StringType;
+    accessKeyId: import("@elaraai/east").OptionType<StringType>;
+    secretAccessKey: import("@elaraai/east").OptionType<StringType>;
+    endpoint: import("@elaraai/east").OptionType<StringType>;
+}>, 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 declare const S3Impl: PlatformFunction[];
+//# sourceMappingURL=s3.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/storage/s3.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAQ,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAW,MAAM,eAAe,CAAC;AAE3F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AA8C/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,aAAa;;;;;;oCAAsF,CAAC;AAEjH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,aAAa;;;;;;0BAA4E,CAAC;AACvG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;GAAyF,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,gBAAgB;;;;;;0BAA+E,CAAC;AAE7G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;GAAmG,CAAC;AAEhI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,eAAO,MAAM,cAAc;;;;;;yCAA4F,CAAC;AAExH;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,gBAAgB,EA0LpC,CAAC"}