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

package/dist/connection/index.js

@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Connection management utilities for East Node IO.
+ *
+ * Provides opaque handle-based connection management for databases,
+ * storage services, and file transfer protocols.
+ *
+ * @packageDocumentation
+ */
+import { randomUUID } from 'node:crypto';
+import { EastError } from "@elaraai/east/internal";
+/**
+ * Internal connection handle storage.
+ * Maps handle UUIDs to connection objects and their cleanup functions.
+ *
+ * @internal
+ */
+const connectionHandles = new Map();
+/**
+ * Creates an opaque handle for a connection object.
+ *
+ * Generates a UUID handle and stores the connection in internal storage.
+ * The handle can be used to retrieve the connection later.
+ *
+ * @param connection - The connection object to store
+ * @param cleanup - Optional cleanup function to call when closing all handles
+ * @returns Opaque handle (UUID string) for the connection
+ *
+ * @example
+ * ```ts
+ * const pool = new pg.Pool(config);
+ * const handle = createHandle(pool, async () => await pool.end());
+ * ```
+ */
+export function createHandle(connection, cleanup) {
+    const handle = randomUUID();
+    const entry = { connection };
+    if (cleanup) {
+        entry.cleanup = cleanup;
+    }
+    connectionHandles.set(handle, entry);
+    return handle;
+}
+/**
+ * Retrieves a connection object by its handle.
+ *
+ * Looks up the connection associated with the given handle.
+ * Throws an error if the handle is invalid or not found.
+ *
+ * @typeParam T - The expected type of the connection object
+ * @param handle - The opaque handle for the connection
+ * @returns The connection object cast to type T
+ *
+ * @throws {EastError} When handle is invalid or not found (location: "connection_handle")
+ *
+ * @example
+ * ```ts
+ * const pool = getConnection<pg.Pool>(handle);
+ * const result = await pool.query(sql, params);
+ * ```
+ */
+export function getConnection(handle) {
+    const entry = connectionHandles.get(handle);
+    if (!entry) {
+        throw new EastError(`Invalid connection handle: ${handle}`, {
+            location: { filename: "connection_handle", line: 0n, column: 0n }
+        });
+    }
+    return entry.connection;
+}
+/**
+ * Closes and removes a connection handle.
+ *
+ * Removes the connection from internal storage. The connection object
+ * itself should be closed by the caller before calling this function.
+ *
+ * @param handle - The opaque handle to close
+ *
+ * @throws {EastError} When handle is invalid or not found (location: "connection_close")
+ *
+ * @example
+ * ```ts
+ * const pool = getConnection<pg.Pool>(handle);
+ * await pool.end();
+ * closeHandle(handle);
+ * ```
+ */
+export function closeHandle(handle) {
+    const entry = connectionHandles.get(handle);
+    if (!entry) {
+        throw new EastError(`Cannot close invalid handle: ${handle}`, {
+            location: { filename: "connection_close", line: 0n, column: 0n }
+        });
+    }
+    connectionHandles.delete(handle);
+}
+/**
+ * Gets the current number of active connection handles.
+ *
+ * Useful for debugging and testing to ensure connections are properly cleaned up.
+ *
+ * @returns Number of active connection handles
+ *
+ * @internal
+ */
+export function getHandleCount() {
+    return connectionHandles.size;
+}
+/**
+ * Closes all active connection handles.
+ *
+ * Useful for test cleanup to ensure all connections are closed even if tests fail.
+ * Calls each connection's registered cleanup function, then clears all handles.
+ *
+ * @internal
+ */
+export async function closeAllHandles() {
+    for (const [handle, entry] of connectionHandles.entries()) {
+        try {
+            if (entry.cleanup) {
+                await entry.cleanup();
+            }
+        }
+        catch (err) {
+            // Ignore errors during cleanup
+            console.error(`Error closing handle ${handle}:`, err);
+        }
+    }
+    connectionHandles.clear();
+}
+//# sourceMappingURL=index.js.map

package/dist/connection/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connection/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA8D,CAAC;AAEhG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,UAAe,EAAE,OAA6B;IACvE,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAuD,EAAE,UAAU,EAAE,CAAC;IACjF,IAAI,OAAO,EAAE,CAAC;QACV,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC;IAC5B,CAAC;IACD,iBAAiB,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAI,MAAc;IAC3C,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,MAAM,IAAI,SAAS,CAAC,8BAA8B,MAAM,EAAE,EAAE;YACxD,QAAQ,EAAE,EAAE,QAAQ,EAAE,mBAAmB,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;SACpE,CAAC,CAAC;IACP,CAAC;IACD,OAAO,KAAK,CAAC,UAAe,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACtC,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,MAAM,IAAI,SAAS,CAAC,gCAAgC,MAAM,EAAE,EAAE;YAC1D,QAAQ,EAAE,EAAE,QAAQ,EAAE,kBAAkB,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;SACnE,CAAC,CAAC;IACP,CAAC;IACD,iBAAiB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc;IAC1B,OAAO,iBAAiB,CAAC,IAAI,CAAC;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACjC,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,iBAAiB,CAAC,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,CAAC;YACD,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;gBAChB,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YAC1B,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,+BAA+B;YAC/B,OAAO,CAAC,KAAK,CAAC,wBAAwB,MAAM,GAAG,EAAE,GAAG,CAAC,CAAC;QAC1D,CAAC;IACL,CAAC;IACD,iBAAiB,CAAC,KAAK,EAAE,CAAC;AAC9B,CAAC"}

package/dist/format/csv.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { BlobType, ArrayType, DictType, StringType, OptionType, BooleanType, StructType, VariantType, NullType } from "@elaraai/east";
+import type { PlatformFunction } from "@elaraai/east/internal";
+export declare const CsvColumnType: VariantType<{
+    Null: NullType;
+    Boolean: NullType;
+    Integer: NullType;
+    Float: NullType;
+    String: NullType;
+    DateTime: NullType;
+    Blob: NullType;
+}>;
+export declare const CsvParseConfig: StructType<{
+    columns: OptionType<DictType<StringType, VariantType<{
+        Null: NullType;
+        Boolean: NullType;
+        Integer: NullType;
+        Float: NullType;
+        String: NullType;
+        DateTime: NullType;
+        Blob: NullType;
+    }>>>;
+    delimiter: OptionType<StringType>;
+    quoteChar: OptionType<StringType>;
+    escapeChar: OptionType<StringType>;
+    newline: OptionType<StringType>;
+    hasHeader: BooleanType;
+    nullString: OptionType<StringType>;
+    skipEmptyLines: BooleanType;
+    trimFields: BooleanType;
+}>;
+export declare const CsvSerializeConfig: StructType<{
+    delimiter: StringType;
+    quoteChar: StringType;
+    escapeChar: StringType;
+    newline: StringType;
+    includeHeader: BooleanType;
+    nullString: StringType;
+    alwaysQuote: BooleanType;
+}>;
+/** Represents a single CSV row as a dictionary mapping column names to optional string values. */
+export declare const CsvRowType: DictType<StringType, VariantType<{
+    Null: NullType;
+    Boolean: BooleanType;
+    Integer: import("@elaraai/east").IntegerType;
+    Float: import("@elaraai/east").FloatType;
+    String: StringType;
+    DateTime: import("@elaraai/east").DateTimeType;
+    Blob: BlobType;
+}>>;
+/** Represents CSV data as an array of row dictionaries. */
+export declare const CsvDataType: ArrayType<DictType<StringType, VariantType<{
+    Null: NullType;
+    Boolean: BooleanType;
+    Integer: import("@elaraai/east").IntegerType;
+    Float: import("@elaraai/east").FloatType;
+    String: StringType;
+    DateTime: import("@elaraai/east").DateTimeType;
+    Blob: BlobType;
+}>>>;
+/**
+ * Parses CSV data from a binary blob into structured row data.
+ *
+ * Converts CSV-formatted binary data into an array of row dictionaries,
+ * where each dictionary maps column names to optional string values.
+ * Supports configurable delimiters, quote characters, escape sequences,
+ * and header handling.
+ *
+ * This is a platform function for the East language, enabling CSV parsing
+ * in East programs running on Node.js.
+ *
+ * @param blob - The CSV data as a binary blob (UTF-8 encoded)
+ * @param config - Parsing configuration including delimiter, quote characters, and header options
+ * @returns An array of row dictionaries, each mapping column names to optional string values
+ *
+ * @throws {EastError} When CSV is malformed with specific error messages:
+ * - "Unclosed quote in row N, column M" - Quote not properly closed
+ * - "Too many fields in row N (expected X columns, found at least Y)" - More fields than header
+ * - "Too few fields in row N (expected X columns, got Y)" - Fewer fields than header
+ * - "Invalid escape sequence in row N, column M" - Invalid escape character usage
+ * - "Expected delimiter or newline after closing quote in row N, column M" - Invalid data after quote
+ * - "quoteChar must have length 1" - Invalid configuration
+ * - "escapeChar must have length 1" - Invalid configuration
+ * - "delimiter must not be empty" - Invalid configuration
+ *
+ * @example
+ * ```ts
+ * const parseCSV = East.function([BlobType], CsvDataType, ($, csvBlob) => {
+ *     const config = $.const(East.value({
+ *         delimiter: variant('some', ','),
+ *         quoteChar: variant('some', '"'),
+ *         escapeChar: variant('some', '"'),
+ *         newline: variant('none', null),
+ *         hasHeader: true,
+ *         nullString: variant('some', ''),
+ *         skipEmptyLines: true,
+ *         trimFields: false,
+ *     }, CsvParseConfig));
+ *
+ *     return csv_parse(csvBlob, config);
+ *     // Returns: [{"name": some("Alice"), "age": some("30")}, ...]
+ * });
+ * ```
+ *
+ * @remarks
+ * - Handles quoted fields with embedded delimiters and newlines
+ * - Supports both quote-as-escape ("") and backslash-escape (\") modes
+ * - Auto-detects newline format (CRLF, LF, or CR) when newline option is none
+ * - Validates column counts when hasHeader is true
+ * - Skips UTF-8 BOM (0xEF 0xBB 0xBF) if present at start
+ * - When hasHeader is false, generates column names as "column_0", "column_1", etc.
+ */
+export declare const csv_parse: import("@elaraai/east").PlatformDefinition<[BlobType, StructType<{
+    columns: OptionType<DictType<StringType, VariantType<{
+        Null: NullType;
+        Boolean: NullType;
+        Integer: NullType;
+        Float: NullType;
+        String: NullType;
+        DateTime: NullType;
+        Blob: NullType;
+    }>>>;
+    delimiter: OptionType<StringType>;
+    quoteChar: OptionType<StringType>;
+    escapeChar: OptionType<StringType>;
+    newline: OptionType<StringType>;
+    hasHeader: BooleanType;
+    nullString: OptionType<StringType>;
+    skipEmptyLines: BooleanType;
+    trimFields: BooleanType;
+}>], ArrayType<DictType<StringType, VariantType<{
+    Null: NullType;
+    Boolean: BooleanType;
+    Integer: import("@elaraai/east").IntegerType;
+    Float: import("@elaraai/east").FloatType;
+    String: StringType;
+    DateTime: import("@elaraai/east").DateTimeType;
+    Blob: BlobType;
+}>>>>;
+/**
+ * Serializes structured row data into CSV-formatted binary data.
+ *
+ * Converts an array of row dictionaries into CSV-formatted binary data.
+ * Supports configurable delimiters, quote characters, escape sequences,
+ * and formatting options.
+ *
+ * This is a platform function for the East language, enabling CSV serialization
+ * in East programs running on Node.js.
+ *
+ * @param data - An array of row dictionaries to serialize
+ * @param config - Serialization configuration including delimiter, quote characters, and formatting options
+ * @returns A binary blob containing the CSV-formatted data (UTF-8 encoded)
+ *
+ * @throws {EastError} When configuration is invalid:
+ * - "quoteChar must have length 1" - Invalid configuration
+ * - "escapeChar must have length 1" - Invalid configuration
+ * - "delimiter must not be empty" - Invalid configuration
+ *
+ * @example
+ * ```ts
+ * const serializeCSV = East.function([CsvDataType], BlobType, ($, data) => {
+ *     const config = $.const(East.value({
+ *         delimiter: ',',
+ *         quoteChar: '"',
+ *         escapeChar: '"',
+ *         newline: '\n',
+ *         includeHeader: true,
+ *         nullString: '',
+ *         alwaysQuote: false,
+ *     }, CsvSerializeConfig));
+ *
+ *     return csv_serialize(data, config);
+ *     // Returns blob that decodes to: "name,age\nAlice,30\nBob,25"
+ * });
+ * ```
+ *
+ * @remarks
+ * - Automatically quotes fields containing delimiter, quote char, newline, or null string
+ * - Escapes quote characters within quoted fields using escapeChar
+ * - Column order is determined by the first row's dictionary keys
+ * - Null values are serialized as nullString
+ * - Use alwaysQuote: true to force quoting of all fields
+ */
+export declare const csv_serialize: import("@elaraai/east").PlatformDefinition<[ArrayType<DictType<StringType, VariantType<{
+    Null: NullType;
+    Boolean: BooleanType;
+    Integer: import("@elaraai/east").IntegerType;
+    Float: import("@elaraai/east").FloatType;
+    String: StringType;
+    DateTime: import("@elaraai/east").DateTimeType;
+    Blob: BlobType;
+}>>>, StructType<{
+    delimiter: StringType;
+    quoteChar: StringType;
+    escapeChar: StringType;
+    newline: StringType;
+    includeHeader: BooleanType;
+    nullString: StringType;
+    alwaysQuote: BooleanType;
+}>], BlobType>;
+/**
+ * Node.js implementation of CSV platform functions.
+ *
+ * Pass this array to {@link East.compile} to enable CSV operations.
+ */
+export declare const CsvImpl: PlatformFunction[];
+//# sourceMappingURL=csv.d.ts.map

package/dist/format/csv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../../src/format/csv.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAQ,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAA6B,WAAW,EAAE,QAAQ,EAAS,MAAM,eAAe,CAAC;AAC9K,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAI/D,eAAO,MAAM,aAAa;;;;;;;;EAQxB,CAAA;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;EAUzB,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;EAQ7B,CAAC;AAIH,kGAAkG;AAClG,eAAO,MAAM,UAAU;;;;;;;;GAAyC,CAAC;AAEjE,2DAA2D;AAC3D,eAAO,MAAM,WAAW;;;;;;;;IAAwB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;KAAsE,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;cAA8E,CAAC;AAEzG;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAwBrC,CAAC"}