@elaraai/e3 0.0.1-beta.0

package/dist/src/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * e3: TypeScript SDK for authoring e3 packages.
+ *
+ * This package provides a fluent API for defining e3 packages in TypeScript:
+ * - `e3.input()` - Define input datasets
+ * - `e3.task()` - Define tasks that transform datasets
+ * - `e3.package()` - Bundle definitions into a package
+ * - `e3.export()` - Export package to a .zip bundle
+ *
+ * Terminology:
+ * - **Dataset**: A location holding a value (leaf node in the data tree)
+ * - **Tree**: A location containing datasets or nested trees (branch node)
+ * - **Structure**: The shape of the data tree
+ * - **Task**: A transformation that reads input datasets and produces an output dataset
+ * - **Path**: An address pointing to a dataset or tree
+ *
+ * @example
+ * ```ts
+ * import { StringType } from '@elaraai/east';
+ * import e3 from '@elaraai/e3';
+ *
+ * const input_name = e3.input('name', StringType, 'World');
+ *
+ * const say_hello = e3.task(
+ *   'say_hello',
+ *   [input_name],
+ *   ($, name) => str`Hello, ${name}!`
+ * );
+ *
+ * // Only need to pass the final task - dependencies are collected automatically
+ * const pkg = e3.package('hello_world', '1.0.0', say_hello);
+ *
+ * // Discoverable access to package contents
+ * pkg.datasets.inputs.name;       // input dataset
+ * pkg.datasets.outputs.say_hello; // output dataset
+ * pkg.tasks.say_hello;            // task definition
+ *
+ * await e3.export(pkg, 'package.zip');
+ * ```
+ */
+import type { DatasetDef, DataTreeDef, DatasetsOf, MergeDatasets, PackageDef, PackageItem, TaskDef } from './types.js';
+import { input } from './input.js';
+import { task, customTask } from './task.js';
+import { package_ } from './package.js';
+import { export_ } from './export.js';
+export type { DataTreeDef, DatasetDef, DatasetsOf, TaskDef, PackageDef, PackageItem, MergeDatasets, };
+/**
+ * The e3 SDK namespace.
+ *
+ * Provides functions for authoring e3 packages in TypeScript.
+ */
+declare const e3: {
+    input: typeof input;
+    task: typeof task;
+    customTask: typeof customTask;
+    package: typeof package_;
+    export: typeof export_;
+};
+export default e3;
+export { input, task, customTask, package_ as package, export_ as export };
+export { inputsTree } from './input.js';
+export { tasksTree } from './task.js';
+export { sha256File, sha256Bytes, hashToPath } from './sha256.js';
+export { addObject } from './export.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,aAAa,EACb,UAAU,EACV,WAAW,EACX,OAAO,EACR,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC,YAAY,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,OAAO,EACP,UAAU,EACV,WAAW,EACX,aAAa,GACd,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,EAAE;;;;;;CAMP,CAAC;AAEF,eAAe,EAAE,CAAC;AAGlB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,IAAI,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC;AAG3E,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGtC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { input } from './input.js';
+import { task, customTask } from './task.js';
+import { package_ } from './package.js';
+import { export_ } from './export.js';
+/**
+ * The e3 SDK namespace.
+ *
+ * Provides functions for authoring e3 packages in TypeScript.
+ */
+const e3 = {
+    input,
+    task,
+    customTask,
+    package: package_,
+    export: export_,
+};
+export default e3;
+// Also export individual functions for tree-shaking
+export { input, task, customTask, package_ as package, export_ as export };
+// Singleton tree definitions
+export { inputsTree } from './input.js';
+export { tasksTree } from './task.js';
+// Utility exports
+export { sha256File, sha256Bytes, hashToPath } from './sha256.js';
+export { addObject } from './export.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoDH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAYtC;;;;GAIG;AACH,MAAM,EAAE,GAAG;IACT,KAAK;IACL,IAAI;IACJ,UAAU;IACV,OAAO,EAAE,QAAQ;IACjB,MAAM,EAAE,OAAO;CAChB,CAAC;AAEF,eAAe,EAAE,CAAC;AAElB,oDAAoD;AACpD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,IAAI,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,CAAC;AAE3E,6BAA6B;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,kBAAkB;AAClB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/input.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Input dataset definitions for e3 packages.
+ */
+import type { EastType, ValueTypeOf } from '@elaraai/east';
+import { variant } from '@elaraai/east';
+import type { DatasetDef, DataTreeDef } from './types.js';
+/**
+ * Singleton datatree definition for `.inputs`.
+ *
+ * All input datasets are children of this datatree.
+ */
+export declare const inputsTree: DataTreeDef;
+/**
+ * Defines an input dataset.
+ *
+ * Creates a dataset at `.inputs.${name}` in the workspace.
+ *
+ * @typeParam T - The East type of the input value
+ * @param name - Dataset name (used as path segment in the tree)
+ * @param type - East type of the input value
+ * @param defaultValue - Optional default value
+ * @returns A DatasetDef that can be used in dataflows and packages
+ *
+ * @example
+ * ```ts
+ * import { StringType, IntegerType } from '@elaraai/east';
+ *
+ * // Input with default
+ * const name = input('name', StringType, 'World');
+ *
+ * // Input without default
+ * const count = input('count', IntegerType);
+ * ```
+ */
+export declare function input<Name extends string, T extends EastType>(name: Name, type: T, defaultValue?: ValueTypeOf<T>): DatasetDef<T, [variant<"field", "inputs">, variant<"field", Name>]>;
+//# sourceMappingURL=input.d.ts.map

package/dist/src/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/input.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,WAKxB,CAAC;AAGF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,CAAC,SAAS,QAAQ,EAC3D,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,CAAC,EACP,YAAY,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAC5B,UAAU,CAAC,CAAC,EAAE,CAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAE,CAAC,CASvE"}

package/dist/src/input.js

@@ -0,0 +1,49 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { variant } from '@elaraai/east';
+/**
+ * Singleton datatree definition for `.inputs`.
+ *
+ * All input datasets are children of this datatree.
+ */
+export const inputsTree = {
+    kind: 'datatree',
+    name: 'inputs',
+    path: [variant('field', 'inputs')],
+    deps: new Set(),
+};
+/**
+ * Defines an input dataset.
+ *
+ * Creates a dataset at `.inputs.${name}` in the workspace.
+ *
+ * @typeParam T - The East type of the input value
+ * @param name - Dataset name (used as path segment in the tree)
+ * @param type - East type of the input value
+ * @param defaultValue - Optional default value
+ * @returns A DatasetDef that can be used in dataflows and packages
+ *
+ * @example
+ * ```ts
+ * import { StringType, IntegerType } from '@elaraai/east';
+ *
+ * // Input with default
+ * const name = input('name', StringType, 'World');
+ *
+ * // Input without default
+ * const count = input('count', IntegerType);
+ * ```
+ */
+export function input(name, type, defaultValue) {
+    return {
+        kind: 'dataset',
+        name,
+        path: [variant('field', 'inputs'), variant('field', name)],
+        type,
+        default: defaultValue,
+        deps: new Set([...inputsTree.deps, inputsTree]),
+    };
+}
+//# sourceMappingURL=input.js.map

package/dist/src/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../src/input.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGxC;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAgB;IACrC,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAClC,IAAI,EAAE,IAAI,GAAG,EAAE;CAChB,CAAC;AAGF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,KAAK,CACnB,IAAU,EACV,IAAO,EACP,YAA6B;IAE7B,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI;QACJ,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC1D,IAAI;QACJ,OAAO,EAAE,YAAY;QACrB,IAAI,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;KAChD,CAAC;AACJ,CAAC"}

package/dist/src/package.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Package definitions for e3.
+ */
+import type { MergeDatasets, PackageDef, PackageItem } from './types.js';
+/**
+ * Creates a package definition from items.
+ *
+ * Automatically collects all dependencies from the provided items.
+ * You only need to pass the "top-level" items - all inputs, intermediate
+ * tasks, and datasets they depend on are included automatically.
+ *
+ * Organizes items into a discoverable structure:
+ * - `pkg.datasets.inputs.*` - Input datasets
+ * - `pkg.datasets.outputs.*` - Output datasets
+ * - `pkg.tasks.*` - Tasks
+ *
+ * @param name - Package name
+ * @param version - Package version
+ * @param items - Items to include (datasets, tasks)
+ * @returns A PackageDef with typed access to contents
+ *
+ * @example
+ * ```ts
+ * const input_name = e3.input('name', StringType, 'World');
+ * const say_hello = e3.task('say_hello', [input_name], ...);
+ *
+ * // Only need to pass the final task - input_name is included automatically
+ * const pkg = e3.package('hello_world', '1.0.0', say_hello);
+ *
+ * // Typed access to contents
+ * const nameInput = pkg.datasets.inputs.name;
+ * const helloOutput = pkg.datasets.outputs.say_hello;
+ * const helloTask = pkg.tasks.say_hello;
+ * ```
+ */
+export declare function package_<TItems extends (PackageItem | PackageDef<any>)[]>(name: string, version: string, ...items: TItems): PackageDef<MergeDatasets<TItems>>;
+//# sourceMappingURL=package.d.ts.map

package/dist/src/package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,WAAW,EAEZ,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAS,CAAC,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,EACvE,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,GAAG,KAAK,EAAE,MAAM,GACf,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CA6EnC"}

package/dist/src/package.js

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Creates a package definition from items.
+ *
+ * Automatically collects all dependencies from the provided items.
+ * You only need to pass the "top-level" items - all inputs, intermediate
+ * tasks, and datasets they depend on are included automatically.
+ *
+ * Organizes items into a discoverable structure:
+ * - `pkg.datasets.inputs.*` - Input datasets
+ * - `pkg.datasets.outputs.*` - Output datasets
+ * - `pkg.tasks.*` - Tasks
+ *
+ * @param name - Package name
+ * @param version - Package version
+ * @param items - Items to include (datasets, tasks)
+ * @returns A PackageDef with typed access to contents
+ *
+ * @example
+ * ```ts
+ * const input_name = e3.input('name', StringType, 'World');
+ * const say_hello = e3.task('say_hello', [input_name], ...);
+ *
+ * // Only need to pass the final task - input_name is included automatically
+ * const pkg = e3.package('hello_world', '1.0.0', say_hello);
+ *
+ * // Typed access to contents
+ * const nameInput = pkg.datasets.inputs.name;
+ * const helloOutput = pkg.datasets.outputs.say_hello;
+ * const helloTask = pkg.tasks.say_hello;
+ * ```
+ */
+export function package_(name, version, ...items) {
+    // Recursively collect all items and their transitive dependencies
+    const all_items = new Set();
+    const visited = new Set();
+    function collect(item) {
+        if (visited.has(item))
+            return;
+        visited.add(item);
+        // First collect all dependencies recursively
+        for (const dep of item.deps) {
+            collect(dep);
+        }
+        // Then add this item (ensures topological order)
+        all_items.add(item);
+    }
+    for (const item of items) {
+        if (item.kind === "package") {
+            for (const dep of item.contents) {
+                all_items.add(dep);
+            }
+        }
+        else {
+            collect(item);
+        }
+    }
+    const datasets = {};
+    const tasks = {};
+    // all_items is in topological order by construction
+    for (const item of all_items) {
+        if (item.kind === 'datatree') {
+            let current = datasets;
+            for (let i = 0; i < item.path.length - 1; i++) { // TODO should this path be the parent path?
+                const segment = item.path[i];
+                if (segment.type === 'field') {
+                    current = current[segment.value];
+                    if (current === undefined) {
+                        throw new Error(`Parent tree not found in package(): ${segment.value}`);
+                    }
+                }
+                else {
+                    throw new Error(`Unsupported path segment type in package(): ${segment.type}`);
+                }
+            }
+            // the only tree type is struct for now
+            current[item.name] = {};
+        }
+        else if (item.kind === 'dataset') {
+            let current = datasets;
+            for (let i = 0; i < item.path.length - 1; i++) { // TODO should this path be the parent path?
+                const segment = item.path[i];
+                if (segment.type === 'field') {
+                    current = current[segment.value];
+                    if (current === undefined) {
+                        throw new Error(`Parent tree not found in package(): ${segment.value}`);
+                    }
+                }
+                else {
+                    throw new Error(`Unsupported path segment type in package(): ${segment.type}`);
+                }
+            }
+            current[item.name] = item;
+        }
+        else if (item.kind === 'task') {
+            // TODO - check task inputs and output exist with correct types?
+            tasks[item.name] = item;
+        }
+    }
+    return {
+        kind: 'package',
+        name,
+        version,
+        datasets: datasets,
+        contents: [...all_items],
+    };
+}
+//# sourceMappingURL=package.js.map

package/dist/src/package.js.map

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

package/dist/src/sha256.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Computes the SHA256 hash of a file.
+ *
+ * Reads the file in streaming mode to handle large files efficiently
+ * without loading the entire contents into memory.
+ *
+ * @param path - Absolute or relative path to the file
+ * @returns The SHA256 hash as a 64-character lowercase hex string
+ *
+ * @throws {Error} When the file does not exist or cannot be read
+ *
+ * @remarks
+ * - Uses Node.js crypto module for hashing
+ * - Streams file contents to avoid memory pressure on large files
+ * - Returns lowercase hex encoding (64 characters for SHA256)
+ *
+ * @example
+ * ```ts
+ * import { sha256File } from '@elaraai/e3';
+ *
+ * const hash = await sha256File('./myfile.txt');
+ * // hash: "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+ * ```
+ */
+export declare function sha256File(path: string): Promise<string>;
+/**
+ * Computes the SHA256 hash of a byte array.
+ *
+ * @param data - The bytes to hash
+ * @returns The SHA256 hash as a 64-character lowercase hex string
+ *
+ * @example
+ * ```ts
+ * import { sha256Bytes } from '@elaraai/e3';
+ *
+ * const data = new TextEncoder().encode('hello world');
+ * const hash = sha256Bytes(data);
+ * // hash: "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+ * ```
+ */
+export declare function sha256Bytes(data: Uint8Array): string;
+/**
+ * Converts a SHA256 hex string to an object store path.
+ *
+ * The path uses the first 2 characters as a directory prefix for sharding,
+ * followed by the remaining 62 characters as the filename.
+ *
+ * @param hash - A 64-character lowercase hex SHA256 hash
+ * @returns Path of the form "objects/ab/cdef1234..."
+ *
+ * @throws {Error} When the hash is not a valid 64-character hex string
+ *
+ * @example
+ * ```ts
+ * import { hashToPath } from '@elaraai/e3';
+ *
+ * const path = hashToPath('b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9');
+ * // path: "objects/b9/4d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+ * ```
+ */
+export declare function hashToPath(hash: string): string;
+//# sourceMappingURL=sha256.d.ts.map

package/dist/src/sha256.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256.d.ts","sourceRoot":"","sources":["../../src/sha256.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA8B9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK/C"}

package/dist/src/sha256.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.
+ */
+/**
+ * SHA256 hashing utilities for e3.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+/**
+ * Computes the SHA256 hash of a file.
+ *
+ * Reads the file in streaming mode to handle large files efficiently
+ * without loading the entire contents into memory.
+ *
+ * @param path - Absolute or relative path to the file
+ * @returns The SHA256 hash as a 64-character lowercase hex string
+ *
+ * @throws {Error} When the file does not exist or cannot be read
+ *
+ * @remarks
+ * - Uses Node.js crypto module for hashing
+ * - Streams file contents to avoid memory pressure on large files
+ * - Returns lowercase hex encoding (64 characters for SHA256)
+ *
+ * @example
+ * ```ts
+ * import { sha256File } from '@elaraai/e3';
+ *
+ * const hash = await sha256File('./myfile.txt');
+ * // hash: "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+ * ```
+ */
+export async function sha256File(path) {
+    // Check file exists first for a clearer error message
+    try {
+        const stats = await stat(path);
+        if (!stats.isFile()) {
+            throw new Error(`Not a file: ${path}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            throw new Error(`File not found: ${path}`);
+        }
+        throw err;
+    }
+    return new Promise((resolve, reject) => {
+        const hash = createHash('sha256');
+        const stream = createReadStream(path);
+        stream.on('data', (chunk) => {
+            hash.update(chunk);
+        });
+        stream.on('end', () => {
+            resolve(hash.digest('hex'));
+        });
+        stream.on('error', (err) => {
+            reject(err);
+        });
+    });
+}
+/**
+ * Computes the SHA256 hash of a byte array.
+ *
+ * @param data - The bytes to hash
+ * @returns The SHA256 hash as a 64-character lowercase hex string
+ *
+ * @example
+ * ```ts
+ * import { sha256Bytes } from '@elaraai/e3';
+ *
+ * const data = new TextEncoder().encode('hello world');
+ * const hash = sha256Bytes(data);
+ * // hash: "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+ * ```
+ */
+export function sha256Bytes(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/**
+ * Converts a SHA256 hex string to an object store path.
+ *
+ * The path uses the first 2 characters as a directory prefix for sharding,
+ * followed by the remaining 62 characters as the filename.
+ *
+ * @param hash - A 64-character lowercase hex SHA256 hash
+ * @returns Path of the form "objects/ab/cdef1234..."
+ *
+ * @throws {Error} When the hash is not a valid 64-character hex string
+ *
+ * @example
+ * ```ts
+ * import { hashToPath } from '@elaraai/e3';
+ *
+ * const path = hashToPath('b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9');
+ * // path: "objects/b9/4d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+ * ```
+ */
+export function hashToPath(hash) {
+    if (!/^[0-9a-f]{64}$/.test(hash)) {
+        throw new Error(`Invalid SHA256 hash: expected 64 lowercase hex characters, got "${hash}"`);
+    }
+    return `objects/${hash.slice(0, 2)}/${hash.slice(2)}`;
+}
+//# sourceMappingURL=sha256.js.map

package/dist/src/sha256.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256.js","sourceRoot":"","sources":["../../src/sha256.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,sDAAsD;IACtD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,KAAK,IAAI,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACnE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QAClC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAEtC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;YACpB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACzB,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,mEAAmE,IAAI,GAAG,CAAC,CAAC;IAC9F,CAAC;IACD,OAAO,WAAW,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACxD,CAAC"}

package/dist/src/sha256.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=sha256.spec.d.ts.map

package/dist/src/sha256.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256.spec.d.ts","sourceRoot":"","sources":["../../src/sha256.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}