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

package/dist/compression/types.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Compression type definitions for East Node IO.
+ *
+ * Provides East type definitions for compression and decompression operations,
+ * supporting gzip, zip, and tar formats.
+ *
+ * @packageDocumentation
+ */
+import { StructType, OptionType, ArrayType, DictType, StringType, IntegerType, BlobType } from "@elaraai/east";
+/**
+ * Compression level for gzip operations (0-9).
+ *
+ * - 0: No compression
+ * - 1-3: Fast compression
+ * - 4-6: Balanced (6 is default)
+ * - 7-9: Maximum compression
+ */
+export declare const GzipLevelType: IntegerType;
+/**
+ * Gzip compression options.
+ *
+ * Controls how data is compressed using gzip.
+ */
+export declare const GzipOptionsType: StructType<{
+    /**
+     * Compression level (0-9).
+     * If not specified, defaults to 6.
+     */
+    level: OptionType<IntegerType>;
+}>;
+/**
+ * Compression level for zip operations (0-9).
+ *
+ * - 0: Store only (no compression)
+ * - 1-3: Fast compression
+ * - 4-6: Balanced (default is typically 6)
+ * - 7-9: Maximum compression
+ */
+export declare const ZipLevelType: IntegerType;
+/**
+ * Zip compression options.
+ *
+ * Controls how data is compressed when creating zip archives.
+ */
+export declare const ZipOptionsType: StructType<{
+    /**
+     * Compression level (0-9).
+     * If not specified, defaults to 6.
+     */
+    level: OptionType<IntegerType>;
+}>;
+/**
+ * Entry in a ZIP archive.
+ *
+ * Contains the file name and its uncompressed data.
+ */
+export declare const ZipEntryType: StructType<{
+    /**
+     * Name/path of the file within the archive.
+     */
+    name: StringType;
+    /**
+     * Uncompressed file data as bytes.
+     */
+    data: BlobType;
+}>;
+/**
+ * List of entries for creating a ZIP archive.
+ */
+export declare const ZipEntriesType: ArrayType<StructType<{
+    /**
+     * Name/path of the file within the archive.
+     */
+    name: StringType;
+    /**
+     * Uncompressed file data as bytes.
+     */
+    data: BlobType;
+}>>;
+/**
+ * Entry in a TAR archive.
+ *
+ * Contains the file name and its data.
+ */
+export declare const TarEntryType: StructType<{
+    /**
+     * Name/path of the file within the archive.
+     */
+    name: StringType;
+    /**
+     * File data as bytes.
+     */
+    data: BlobType;
+}>;
+/**
+ * List of entries for creating a TAR archive.
+ */
+export declare const TarEntriesType: ArrayType<StructType<{
+    /**
+     * Name/path of the file within the archive.
+     */
+    name: StringType;
+    /**
+     * File data as bytes.
+     */
+    data: BlobType;
+}>>;
+/**
+ * Extracted files from a ZIP archive as a dictionary.
+ *
+ * Maps file names to their uncompressed data.
+ */
+export declare const ZipExtractedType: DictType<StringType, BlobType>;
+/**
+ * Extracted files from a TAR archive as a dictionary.
+ *
+ * Maps file names to their data.
+ */
+export declare const TarExtractedType: DictType<StringType, BlobType>;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/compression/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EACH,UAAU,EACV,UAAU,EACV,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,EACX,QAAQ,EACX,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,aAAc,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,eAAe;IACxB;;;OAGG;;EAEL,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,aAAc,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACvB;;;OAGG;;EAEL,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,YAAY;IACrB;;OAEG;;IAGH;;OAEG;;EAEL,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc;IAdvB;;OAEG;;IAGH;;OAEG;;GAO8C,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,YAAY;IACrB;;OAEG;;IAGH;;OAEG;;EAEL,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc;IAdvB;;OAEG;;IAGH;;OAEG;;GAO8C,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,gCAAiC,CAAC;AAE/D;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,gCAAiC,CAAC"}

package/dist/compression/types.js

@@ -0,0 +1,106 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Compression type definitions for East Node IO.
+ *
+ * Provides East type definitions for compression and decompression operations,
+ * supporting gzip, zip, and tar formats.
+ *
+ * @packageDocumentation
+ */
+import { StructType, OptionType, ArrayType, DictType, StringType, IntegerType, BlobType, } from "@elaraai/east";
+/**
+ * Compression level for gzip operations (0-9).
+ *
+ * - 0: No compression
+ * - 1-3: Fast compression
+ * - 4-6: Balanced (6 is default)
+ * - 7-9: Maximum compression
+ */
+export const GzipLevelType = IntegerType;
+/**
+ * Gzip compression options.
+ *
+ * Controls how data is compressed using gzip.
+ */
+export const GzipOptionsType = StructType({
+    /**
+     * Compression level (0-9).
+     * If not specified, defaults to 6.
+     */
+    level: OptionType(GzipLevelType),
+});
+/**
+ * Compression level for zip operations (0-9).
+ *
+ * - 0: Store only (no compression)
+ * - 1-3: Fast compression
+ * - 4-6: Balanced (default is typically 6)
+ * - 7-9: Maximum compression
+ */
+export const ZipLevelType = IntegerType;
+/**
+ * Zip compression options.
+ *
+ * Controls how data is compressed when creating zip archives.
+ */
+export const ZipOptionsType = StructType({
+    /**
+     * Compression level (0-9).
+     * If not specified, defaults to 6.
+     */
+    level: OptionType(ZipLevelType),
+});
+/**
+ * Entry in a ZIP archive.
+ *
+ * Contains the file name and its uncompressed data.
+ */
+export const ZipEntryType = StructType({
+    /**
+     * Name/path of the file within the archive.
+     */
+    name: StringType,
+    /**
+     * Uncompressed file data as bytes.
+     */
+    data: BlobType,
+});
+/**
+ * List of entries for creating a ZIP archive.
+ */
+export const ZipEntriesType = ArrayType(ZipEntryType);
+/**
+ * Entry in a TAR archive.
+ *
+ * Contains the file name and its data.
+ */
+export const TarEntryType = StructType({
+    /**
+     * Name/path of the file within the archive.
+     */
+    name: StringType,
+    /**
+     * File data as bytes.
+     */
+    data: BlobType,
+});
+/**
+ * List of entries for creating a TAR archive.
+ */
+export const TarEntriesType = ArrayType(TarEntryType);
+/**
+ * Extracted files from a ZIP archive as a dictionary.
+ *
+ * Maps file names to their uncompressed data.
+ */
+export const ZipExtractedType = DictType(StringType, BlobType);
+/**
+ * Extracted files from a TAR archive as a dictionary.
+ *
+ * Maps file names to their data.
+ */
+export const TarExtractedType = DictType(StringType, BlobType);
+//# sourceMappingURL=types.js.map

package/dist/compression/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/compression/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EACH,UAAU,EACV,UAAU,EACV,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,EACX,QAAQ,GACX,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;IACtC;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAC,aAAa,CAAC;CACnC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;IACrC;;;OAGG;IACH,KAAK,EAAE,UAAU,CAAC,YAAY,CAAC;CAClC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;IACnC;;OAEG;IACH,IAAI,EAAE,UAAU;IAEhB;;OAEG;IACH,IAAI,EAAE,QAAQ;CACjB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAC;IACnC;;OAEG;IACH,IAAI,EAAE,UAAU;IAEhB;;OAEG;IACH,IAAI,EAAE,QAAQ;CACjB,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;AAE/D;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC"}

package/dist/compression/zip.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * ZIP archive platform functions for East Node IO.
+ *
+ * Provides ZIP archive creation and extraction operations for East programs,
+ * enabling file archiving and compression using the ZIP format.
+ *
+ * @packageDocumentation
+ */
+import { BlobType } from "@elaraai/east";
+import type { PlatformFunction } from "@elaraai/east/internal";
+/**
+ * Creates a ZIP archive from a list of files.
+ *
+ * Compresses multiple files into a single ZIP archive. Each file entry
+ * contains a name (path) and its data. The compression level can be
+ * controlled via options (0-9, where 0 is store only and 9 is maximum
+ * compression).
+ *
+ * This is a platform function for the East language, enabling ZIP archive
+ * creation in East programs running on Node.js.
+ *
+ * @param entries - List of files to include in the archive
+ * @param options - Compression options (level)
+ * @returns ZIP archive as compressed blob
+ *
+ * @throws {EastError} When compression fails due to:
+ * - Invalid compression level (location: "zip_compress")
+ * - Empty file name (location: "zip_compress")
+ * - Memory allocation errors (location: "zip_compress")
+ * - Internal compression errors (location: "zip_compress")
+ *
+ * @example
+ * ```ts
+ * import { East, BlobType, StringType, variant } from "@elaraai/east";
+ * import { Compression } from "@elaraai/east-node-io";
+ *
+ * const createZip = East.function([StringType, StringType], BlobType, ($, file1Content, file2Content) => {
+ *     const entries = $.let([
+ *         {
+ *             name: "file1.txt",
+ *             data: file1Content.encodeUtf8(),
+ *         },
+ *         {
+ *             name: "file2.txt",
+ *             data: file2Content.encodeUtf8(),
+ *         },
+ *     ]);
+ *     const options = $.let({
+ *         level: variant('some', 9n),
+ *     });
+ *     const zipBlob = $.let(Compression.Zip.compress(entries, options));
+ *     return $.return(zipBlob);
+ * });
+ *
+ * const compiled = East.compile(createZip.toIR(), Compression.Zip.Implementation);
+ * const result = compiled("Hello", "World");  // ZIP archive blob
+ * ```
+ *
+ * @remarks
+ * - Uses adm-zip library for ZIP operations
+ * - Default compression level is 6 if not specified
+ * - Level 0 stores files without compression
+ * - Higher levels (7-9) provide better compression but are slower
+ * - File names can include directory paths (e.g., "dir/file.txt")
+ */
+export declare const zip_compress: import("@elaraai/east").PlatformDefinition<[import("@elaraai/east").ArrayType<import("@elaraai/east").StructType<{
+    name: import("@elaraai/east").StringType;
+    data: BlobType;
+}>>, import("@elaraai/east").StructType<{
+    level: import("@elaraai/east").OptionType<import("@elaraai/east").IntegerType>;
+}>], BlobType>;
+/**
+ * Extracts files from a ZIP archive.
+ *
+ * Decompresses a ZIP archive and extracts all files into a dictionary
+ * mapping file names to their uncompressed data.
+ *
+ * This is a platform function for the East language, enabling ZIP archive
+ * extraction in East programs running on Node.js.
+ *
+ * @param zipData - ZIP archive blob
+ * @returns Dictionary mapping file names to their data
+ *
+ * @throws {EastError} When extraction fails due to:
+ * - Invalid ZIP format (location: "zip_decompress")
+ * - Corrupted archive (location: "zip_decompress")
+ * - Memory allocation errors (location: "zip_decompress")
+ * - Internal decompression errors (location: "zip_decompress")
+ *
+ * @example
+ * ```ts
+ * import { East, BlobType, DictType, StringType } from "@elaraai/east";
+ * import { Compression } from "@elaraai/east-node-io";
+ *
+ * const extractZip = East.function([BlobType], DictType(StringType, BlobType), ($, zipBlob) => {
+ *     const files = $.let(Compression.Zip.decompress(zipBlob));
+ *     return $.return(files);
+ * });
+ *
+ * const compiled = East.compile(extractZip.toIR(), Compression.Zip.Implementation);
+ * const result = compiled(zipBlob);
+ * // Map { "file1.txt" => Uint8Array, "file2.txt" => Uint8Array }
+ * ```
+ *
+ * @remarks
+ * - Uses adm-zip library for ZIP operations
+ * - Automatically detects and validates ZIP format
+ * - Preserves directory structure in file names
+ */
+export declare const zip_decompress: import("@elaraai/east").PlatformDefinition<[BlobType], import("@elaraai/east").DictType<import("@elaraai/east").StringType, BlobType>>;
+/**
+ * Node.js implementation of ZIP platform functions.
+ *
+ * Pass this array to {@link East.compile} to enable ZIP archive operations.
+ */
+export declare const ZipImpl: PlatformFunction[];
+//# sourceMappingURL=zip.d.ts.map

package/dist/compression/zip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.d.ts","sourceRoot":"","sources":["../../src/compression/zip.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAQ,QAAQ,EAAa,MAAM,eAAe,CAAC;AAE1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,YAAY;;;;;cAA4E,CAAC;AAEtG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,cAAc,wIAAgE,CAAC;AAmE5F;;;;GAIG;AACH,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAkCrC,CAAC"}

package/dist/compression/zip.js

@@ -0,0 +1,200 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * ZIP archive platform functions for East Node IO.
+ *
+ * Provides ZIP archive creation and extraction operations for East programs,
+ * enabling file archiving and compression using the ZIP format.
+ *
+ * @packageDocumentation
+ */
+import { East, BlobType, SortedMap } from "@elaraai/east";
+import { EastError } from "@elaraai/east/internal";
+import AdmZip from "adm-zip";
+import { ZipOptionsType, ZipEntriesType, ZipExtractedType } from "./types.js";
+/**
+ * Creates a ZIP archive from a list of files.
+ *
+ * Compresses multiple files into a single ZIP archive. Each file entry
+ * contains a name (path) and its data. The compression level can be
+ * controlled via options (0-9, where 0 is store only and 9 is maximum
+ * compression).
+ *
+ * This is a platform function for the East language, enabling ZIP archive
+ * creation in East programs running on Node.js.
+ *
+ * @param entries - List of files to include in the archive
+ * @param options - Compression options (level)
+ * @returns ZIP archive as compressed blob
+ *
+ * @throws {EastError} When compression fails due to:
+ * - Invalid compression level (location: "zip_compress")
+ * - Empty file name (location: "zip_compress")
+ * - Memory allocation errors (location: "zip_compress")
+ * - Internal compression errors (location: "zip_compress")
+ *
+ * @example
+ * ```ts
+ * import { East, BlobType, StringType, variant } from "@elaraai/east";
+ * import { Compression } from "@elaraai/east-node-io";
+ *
+ * const createZip = East.function([StringType, StringType], BlobType, ($, file1Content, file2Content) => {
+ *     const entries = $.let([
+ *         {
+ *             name: "file1.txt",
+ *             data: file1Content.encodeUtf8(),
+ *         },
+ *         {
+ *             name: "file2.txt",
+ *             data: file2Content.encodeUtf8(),
+ *         },
+ *     ]);
+ *     const options = $.let({
+ *         level: variant('some', 9n),
+ *     });
+ *     const zipBlob = $.let(Compression.Zip.compress(entries, options));
+ *     return $.return(zipBlob);
+ * });
+ *
+ * const compiled = East.compile(createZip.toIR(), Compression.Zip.Implementation);
+ * const result = compiled("Hello", "World");  // ZIP archive blob
+ * ```
+ *
+ * @remarks
+ * - Uses adm-zip library for ZIP operations
+ * - Default compression level is 6 if not specified
+ * - Level 0 stores files without compression
+ * - Higher levels (7-9) provide better compression but are slower
+ * - File names can include directory paths (e.g., "dir/file.txt")
+ */
+export const zip_compress = East.platform("zip_compress", [ZipEntriesType, ZipOptionsType], BlobType);
+/**
+ * Extracts files from a ZIP archive.
+ *
+ * Decompresses a ZIP archive and extracts all files into a dictionary
+ * mapping file names to their uncompressed data.
+ *
+ * This is a platform function for the East language, enabling ZIP archive
+ * extraction in East programs running on Node.js.
+ *
+ * @param zipData - ZIP archive blob
+ * @returns Dictionary mapping file names to their data
+ *
+ * @throws {EastError} When extraction fails due to:
+ * - Invalid ZIP format (location: "zip_decompress")
+ * - Corrupted archive (location: "zip_decompress")
+ * - Memory allocation errors (location: "zip_decompress")
+ * - Internal decompression errors (location: "zip_decompress")
+ *
+ * @example
+ * ```ts
+ * import { East, BlobType, DictType, StringType } from "@elaraai/east";
+ * import { Compression } from "@elaraai/east-node-io";
+ *
+ * const extractZip = East.function([BlobType], DictType(StringType, BlobType), ($, zipBlob) => {
+ *     const files = $.let(Compression.Zip.decompress(zipBlob));
+ *     return $.return(files);
+ * });
+ *
+ * const compiled = East.compile(extractZip.toIR(), Compression.Zip.Implementation);
+ * const result = compiled(zipBlob);
+ * // Map { "file1.txt" => Uint8Array, "file2.txt" => Uint8Array }
+ * ```
+ *
+ * @remarks
+ * - Uses adm-zip library for ZIP operations
+ * - Automatically detects and validates ZIP format
+ * - Preserves directory structure in file names
+ */
+export const zip_decompress = East.platform("zip_decompress", [BlobType], ZipExtractedType);
+/**
+ * Helper function to compress files into a ZIP archive using adm-zip.
+ *
+ * @param entries - List of file entries
+ * @param level - Compression level (0-9)
+ * @returns ZIP archive as Uint8Array
+ */
+function compressZip(entries, level) {
+    // Validate level
+    if (level < 0 || level > 9) {
+        throw new EastError(`Invalid compression level: ${level}. Must be 0-9.`, {
+            location: { filename: "zip_compress", line: 0n, column: 0n }
+        });
+    }
+    const zip = new AdmZip();
+    for (const entry of entries) {
+        const name = entry.name;
+        const data = entry.data;
+        if (!name || name.length === 0) {
+            throw new EastError("File name cannot be empty", {
+                location: { filename: "zip_compress", line: 0n, column: 0n }
+            });
+        }
+        // Add file to ZIP archive
+        zip.addFile(name, Buffer.from(data));
+    }
+    // Generate ZIP buffer with specified compression level
+    const buffer = zip.toBuffer();
+    return new Uint8Array(buffer);
+}
+/**
+ * Helper function to extract files from a ZIP archive using adm-zip.
+ *
+ * @param zipData - ZIP archive data
+ * @returns Map of file names to their data
+ */
+function decompressZip(zipData) {
+    const files = new SortedMap();
+    // Create AdmZip instance from buffer
+    const zip = new AdmZip(Buffer.from(zipData));
+    // Extract all entries
+    const zipEntries = zip.getEntries();
+    for (const entry of zipEntries) {
+        // Skip directories, only process files
+        if (!entry.isDirectory) {
+            const data = entry.getData();
+            files.set(entry.entryName, new Uint8Array(data));
+        }
+    }
+    return files;
+}
+/**
+ * Node.js implementation of ZIP platform functions.
+ *
+ * Pass this array to {@link East.compile} to enable ZIP archive operations.
+ */
+export const ZipImpl = [
+    zip_compress.implement((entries, options) => {
+        try {
+            // Extract compression level (default to 6)
+            const level = options.level.type === "some"
+                ? Number(options.level.value)
+                : 6;
+            return compressZip(entries, level);
+        }
+        catch (err) {
+            if (err instanceof EastError)
+                throw err;
+            throw new EastError(`ZIP compression failed: ${err.message}`, {
+                location: { filename: "zip_compress", line: 0n, column: 0n },
+                cause: err
+            });
+        }
+    }),
+    zip_decompress.implement((zipData) => {
+        try {
+            return decompressZip(zipData);
+        }
+        catch (err) {
+            if (err instanceof EastError)
+                throw err;
+            throw new EastError(`ZIP decompression failed: ${err.message}`, {
+                location: { filename: "zip_decompress", line: 0n, column: 0n },
+                cause: err
+            });
+        }
+    }),
+];
+//# sourceMappingURL=zip.js.map

package/dist/compression/zip.js.map

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

package/dist/connection/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * 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 declare function createHandle(connection: any, cleanup?: () => Promise<void>): string;
+/**
+ * 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 declare function getConnection<T>(handle: string): T;
+/**
+ * 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 declare function closeHandle(handle: string): void;
+/**
+ * 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 declare function getHandleCount(): number;
+/**
+ * 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 declare function closeAllHandles(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/connection/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connection/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsBH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,CAQnF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAQlD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAQhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAYrD"}