@elaraai/east-node-io 0.0.1-beta.0 → 0.0.1-beta.2

package/dist/storage/types.js

@@ -0,0 +1,94 @@
+/**
+ * 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 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 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 const S3ListResultType = StructType({
+    /**
+     * Array of object metadata for objects matching the prefix.
+     */
+    objects: ArrayType(S3ObjectMetadataType),
+    /**
+     * 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.js.map

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","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,GACf,MAAM,eAAe,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,UAAU;IAElB;;OAEG;IACH,MAAM,EAAE,UAAU;IAElB;;;OAGG;IACH,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC;IAEnC;;;OAGG;IACH,eAAe,EAAE,UAAU,CAAC,UAAU,CAAC;IAEvC;;;OAGG;IACH,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC;CACnC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;IAC3C;;OAEG;IACH,GAAG,EAAE,UAAU;IAEf;;OAEG;IACH,IAAI,EAAE,WAAW;IAEjB;;OAEG;IACH,YAAY,EAAE,YAAY;IAE1B;;;OAGG;IACH,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC;IAEnC;;;OAGG;IACH,IAAI,EAAE,UAAU,CAAC,UAAU,CAAC;CAC/B,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,UAAU,CAAC;IACvC;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC,oBAAoB,CAAC;IAExC;;OAEG;IACH,WAAW,EAAE,WAAW;IAExB;;;OAGG;IACH,iBAAiB,EAAE,UAAU,CAAC,UAAU,CAAC;CAC5C,CAAC,CAAC"}

package/dist/transfer/ftp.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * FTP platform functions for East Node IO.
+ *
+ * Provides FTP and FTPS file transfer operations for East programs,
+ * including upload, download, list, and delete operations.
+ *
+ * @packageDocumentation
+ */
+import { BlobType, ArrayType, NullType } from "@elaraai/east";
+import type { PlatformFunction } from "@elaraai/east/internal";
+import { StringType } from "./types.js";
+/**
+ * Connects to an FTP server.
+ *
+ * Creates a connection to an FTP or FTPS server and returns an opaque handle
+ * for use in file transfer operations.
+ *
+ * This is a platform function for the East language, enabling FTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param config - FTP connection configuration
+ * @returns Connection handle (opaque string)
+ *
+ * @throws {EastError} When connection fails due to:
+ * - Invalid hostname or port (location: "ftp_connect")
+ * - Authentication failure (location: "ftp_connect")
+ * - Network errors (location: "ftp_connect")
+ * - SSL/TLS errors for FTPS (location: "ftp_connect")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, BlobType } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const uploadToFtp = East.function([StringType, BlobType], NullType, ($, filename, data) => {
+ *     const config = $.let({
+ *         host: "ftp.example.com",
+ *         port: 21n,
+ *         user: "username",
+ *         password: "password",
+ *         secure: false,
+ *     });
+ *
+ *     const conn = $.let(Transfer.FTP.connect(config));
+ *     $(Transfer.FTP.put(conn, filename, data));
+ *     $(Transfer.FTP.close(conn));
+ * });
+ *
+ * const compiled = East.compileAsync(uploadToFtp.toIR(), Transfer.FTP.Implementation);
+ * await compiled("file.txt", fileData);
+ * ```
+ *
+ * @remarks
+ * - Supports both FTP and FTPS (FTP over SSL/TLS)
+ * - Connection is maintained until explicitly closed
+ * - All operations are asynchronous (use East.compileAsync)
+ */
+export declare const ftp_connect: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
+    host: StringType;
+    port: import("@elaraai/east").IntegerType;
+    user: StringType;
+    password: StringType;
+    secure: import("@elaraai/east").BooleanType;
+}>], StringType>;
+/**
+ * Uploads a file to an FTP server.
+ *
+ * Uploads binary data to the FTP server at the specified remote path.
+ * Overwrites existing files with the same path.
+ *
+ * This is a platform function for the East language, enabling FTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param handle - Connection handle from ftp_connect()
+ * @param remotePath - Remote file path on the FTP server
+ * @param data - Binary data to upload
+ * @returns Null on success
+ *
+ * @throws {EastError} When upload fails due to:
+ * - Invalid connection handle (location: "ftp_put")
+ * - Permission denied (location: "ftp_put")
+ * - Invalid remote path (location: "ftp_put")
+ * - Network errors (location: "ftp_put")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, BlobType, NullType } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const uploadFile = East.function([StringType, BlobType], NullType, ($, filename, data) => {
+ *     const config = $.let({
+ *         host: "ftp.example.com",
+ *         port: 21n,
+ *         user: "username",
+ *         password: "password",
+ *         secure: false,
+ *     });
+ *     const conn = $.let(Transfer.FTP.connect(config));
+ *     $(Transfer.FTP.put(conn, `/uploads/${filename}`, data));
+ *     $(Transfer.FTP.close(conn));
+ *     return $.return(null);
+ * });
+ *
+ * const compiled = East.compileAsync(uploadFile.toIR(), Transfer.FTP.Implementation);
+ * await compiled("file.txt", fileData);
+ * ```
+ *
+ * @remarks
+ * - Creates parent directories if they don't exist
+ * - Overwrites existing files
+ * - Binary mode transfer
+ */
+export declare const ftp_put: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType, BlobType], NullType>;
+/**
+ * Downloads a file from an FTP server.
+ *
+ * Retrieves binary data from the FTP server at the specified remote path.
+ * Returns the file data as a Blob (Uint8Array).
+ *
+ * This is a platform function for the East language, enabling FTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param handle - Connection handle from ftp_connect()
+ * @param remotePath - Remote file path on the FTP server
+ * @returns Binary data as Blob
+ *
+ * @throws {EastError} When download fails due to:
+ * - Invalid connection handle (location: "ftp_get")
+ * - File not found (location: "ftp_get")
+ * - Permission denied (location: "ftp_get")
+ * - Network errors (location: "ftp_get")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, BlobType } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const downloadFile = East.function([StringType], BlobType, ($, filename) => {
+ *     const config = $.let({
+ *         host: "ftp.example.com",
+ *         port: 21n,
+ *         user: "username",
+ *         password: "password",
+ *         secure: false,
+ *     });
+ *     const conn = $.let(Transfer.FTP.connect(config));
+ *     const data = $.let(Transfer.FTP.get(conn, `/downloads/${filename}`));
+ *     $(Transfer.FTP.close(conn));
+ *     return $.return(data);
+ * });
+ *
+ * const compiled = East.compileAsync(downloadFile.toIR(), Transfer.FTP.Implementation);
+ * const fileData = await compiled("file.txt");  // Returns Uint8Array
+ * ```
+ *
+ * @remarks
+ * - Binary mode transfer
+ * - Entire file is loaded into memory
+ */
+export declare const ftp_get: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType], BlobType>;
+/**
+ * Lists files in an FTP directory.
+ *
+ * Retrieves a list of files and directories at the specified remote path.
+ * Returns metadata for each file including name, size, and modification time.
+ *
+ * This is a platform function for the East language, enabling FTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param handle - Connection handle from ftp_connect()
+ * @param remotePath - Remote directory path on the FTP server
+ * @returns Array of file information metadata
+ *
+ * @throws {EastError} When listing fails due to:
+ * - Invalid connection handle (location: "ftp_list")
+ * - Directory not found (location: "ftp_list")
+ * - Permission denied (location: "ftp_list")
+ * - Network errors (location: "ftp_list")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, ArrayType } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const listFiles = East.function([StringType], ArrayType(Transfer.FTP.Types.FileInfo), ($, remotePath) => {
+ *     const config = $.let({
+ *         host: "ftp.example.com",
+ *         port: 21n,
+ *         user: "username",
+ *         password: "password",
+ *         secure: false,
+ *     });
+ *     const conn = $.let(Transfer.FTP.connect(config));
+ *     const files = $.let(Transfer.FTP.list(conn, remotePath));
+ *     $(Transfer.FTP.close(conn));
+ *     return $.return(files);
+ * });
+ *
+ * const compiled = East.compileAsync(listFiles.toIR(), Transfer.FTP.Implementation);
+ * const uploads = await compiled("/uploads");  // [{name: "file.txt", size: 1024n, ...}, ...]
+ * ```
+ *
+ * @remarks
+ * - Returns both files and directories
+ * - Use isDirectory field to distinguish between files and directories
+ */
+export declare const ftp_list: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType], ArrayType<import("@elaraai/east").StructType<{
+    name: StringType;
+    path: StringType;
+    size: import("@elaraai/east").IntegerType;
+    isDirectory: import("@elaraai/east").BooleanType;
+    modifiedTime: StringType;
+}>>>;
+/**
+ * Deletes a file from an FTP server.
+ *
+ * Removes a file from the FTP server at the specified remote path.
+ * Does not delete directories.
+ *
+ * This is a platform function for the East language, enabling FTP file transfer
+ * operations in East programs running on Node.js.
+ *
+ * @param handle - Connection handle from ftp_connect()
+ * @param remotePath - Remote file path to delete
+ * @returns Null on success
+ *
+ * @throws {EastError} When deletion fails due to:
+ * - Invalid connection handle (location: "ftp_delete")
+ * - File not found (location: "ftp_delete")
+ * - Permission denied (location: "ftp_delete")
+ * - Network errors (location: "ftp_delete")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, NullType } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const deleteFile = East.function([StringType], NullType, ($, filename) => {
+ *     const config = $.let({
+ *         host: "ftp.example.com",
+ *         port: 21n,
+ *         user: "username",
+ *         password: "password",
+ *         secure: false,
+ *     });
+ *     const conn = $.let(Transfer.FTP.connect(config));
+ *     $(Transfer.FTP.delete(conn, `/uploads/${filename}`));
+ *     $(Transfer.FTP.close(conn));
+ *     return $.return(null);
+ * });
+ *
+ * const compiled = East.compileAsync(deleteFile.toIR(), Transfer.FTP.Implementation);
+ * await compiled("old-file.txt");
+ * ```
+ *
+ * @remarks
+ * - Only deletes files, not directories
+ * - Throws error if file doesn't exist
+ */
+export declare const ftp_delete: import("@elaraai/east").AsyncPlatformDefinition<[StringType, StringType], NullType>;
+/**
+ * Closes an FTP connection.
+ *
+ * Closes the FTP connection and releases all resources.
+ * The handle becomes invalid after this operation.
+ *
+ * @param handle - Connection handle from ftp_connect()
+ * @returns Null on success
+ *
+ * @throws {EastError} When handle is invalid (location: "ftp_close")
+ *
+ * @example
+ * ```ts
+ * import { East, NullType } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const cleanup = East.function([], NullType, $ => {
+ *     const config = $.let({
+ *         host: "ftp.example.com",
+ *         port: 21n,
+ *         user: "username",
+ *         password: "password",
+ *         secure: false,
+ *     });
+ *     const conn = $.let(Transfer.FTP.connect(config));
+ *     // ... do work ...
+ *     $(Transfer.FTP.close(conn));
+ *     return $.return(null);
+ * });
+ *
+ * const compiled = East.compileAsync(cleanup.toIR(), Transfer.FTP.Implementation);
+ * await compiled();
+ * ```
+ */
+export declare const ftp_close: import("@elaraai/east").PlatformDefinition<[StringType], NullType>;
+/**
+ * Closes all FTP connections.
+ *
+ * Closes all active FTP connections and releases all resources.
+ * Useful for test cleanup to ensure all connections are closed.
+ *
+ * @returns Null on success
+ *
+ * @example
+ * ```ts
+ * import { East, NullType } from "@elaraai/east";
+ * import { Transfer } from "@elaraai/east-node-io";
+ *
+ * const cleanupAll = East.function([], NullType, $ => {
+ *     // ... test code that may have left connections open ...
+ *     $(Transfer.FTP.closeAll());
+ *     return $.return(null);
+ * });
+ *
+ * const compiled = East.compileAsync(cleanupAll.toIR(), Transfer.FTP.Implementation);
+ * await compiled();
+ * ```
+ *
+ * @internal
+ */
+export declare const ftp_close_all: import("@elaraai/east").AsyncPlatformDefinition<[], NullType>;
+/**
+ * Node.js implementation of FTP platform functions.
+ *
+ * Provides the runtime implementations for FTP operations using basic-ftp.
+ * Pass this to East.compileAsync() to enable FTP functionality.
+ */
+export declare const FtpImpl: PlatformFunction[];
+//# sourceMappingURL=ftp.d.ts.map

package/dist/transfer/ftp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ftp.d.ts","sourceRoot":"","sources":["../../src/transfer/ftp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAQ,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK/D,OAAO,EAAuC,UAAU,EAAgB,MAAM,YAAY,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,WAAW;;;;;;gBAA2E,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,OAAO,+FAAwF,CAAC;AAE7G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,OAAO,qFAA8E,CAAC;AAEnG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,QAAQ;;;;;;IAA8F,CAAC;AAEpH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,UAAU,qFAAiF,CAAC;AAEzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,SAAS,oEAA+D,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,aAAa,+DAAoD,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAuIrC,CAAC"}