@elaraai/e3-cloud-files 0.0.0-stage → 1.0.92

package/dist/src/sync/memory.js

@@ -0,0 +1,155 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { FilesUnreadableError, NO_LEDGER } from './engine.js';
+/** Items as an async iterable, as a store's paged listing gives them. */
+function iterate(items) {
+    return {
+        [Symbol.asyncIterator]() {
+            let at = 0;
+            return {
+                next: () => Promise.resolve(at < items.length ? { value: items[at++], done: false } : { value: undefined, done: true }),
+            };
+        },
+    };
+}
+/** A bucket in memory: files by key, each with its time and an ETag that changes with its bytes. */
+export class MemoryBucket {
+    #files = new Map();
+    /** Why each file a reader may not read is refused, by key */
+    #refused = new Map();
+    #version = 0;
+    /** How many times a file's bytes were read, for tests that hold a sync to reading only what changed */
+    reads = 0;
+    /** How many listings were asked for, for tests that hold a sync to listing a prefix once */
+    listings = 0;
+    /**
+     * Writes a file, as an upload would.
+     *
+     * @param key - Its key, from the bucket's root
+     * @param bytes - Its bytes, or text as UTF-8
+     * @param modified - When it was written
+     */
+    put(key, bytes, modified = new Date()) {
+        const data = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes;
+        this.#version += 1;
+        this.#files.set(key, { bytes: data, modified, etag: `"${this.#version}-${data.length}"` });
+    }
+    /** Deletes a file. */
+    delete(key) {
+        this.#files.delete(key);
+    }
+    /**
+     * Makes a file unreadable, as an archived file, or one encrypted with a key
+     * the reader may not use, is: listed, but refused when read.
+     *
+     * @param key - Its key, from the bucket's root
+     * @param reason - Why, as the reader says it; `null` makes it readable again
+     */
+    refuse(key, reason) {
+        if (reason === null)
+            this.#refused.delete(key);
+        else
+            this.#refused.set(key, reason);
+    }
+    /**
+     * A reader of the files under a prefix, as a binding to `s3://bucket/<prefix>` reads them.
+     * A file put after the reader is made is listed by it, as a bucket would list it.
+     *
+     * @param prefix - The binding's prefix: `''`, or ending with `/`
+     * @returns The reader, whose keys are relative to the prefix
+     */
+    reader(prefix = '') {
+        const files = this.#files;
+        const refused = this.#refused;
+        const counted = () => { this.reads += 1; };
+        const listedOnce = () => { this.listings += 1; };
+        const listed = (key, file) => ({ key: key.slice(prefix.length), size: file.bytes.length, modified: file.modified, etag: file.etag });
+        return {
+            list(under, options = {}) {
+                listedOnce();
+                const keys = [...files.keys()]
+                    .filter((key) => key.startsWith(prefix + under) && (options.topFolderOnly !== true || !key.slice((prefix + under).length).includes('/')))
+                    .sort();
+                return iterate(keys.map((key) => listed(key, files.get(key))));
+            },
+            stat(key) {
+                const file = files.get(prefix + key);
+                return Promise.resolve(file === undefined ? null : listed(prefix + key, file));
+            },
+            read(object) {
+                const file = files.get(prefix + object.key);
+                if (file === undefined)
+                    return Promise.reject(new FilesUnreadableError(object.key, 'went while the sync read it'));
+                if (file.etag !== object.etag)
+                    return Promise.reject(new FilesUnreadableError(object.key, 'changed since it was listed: the next sync takes it'));
+                const reason = refused.get(prefix + object.key);
+                if (reason !== undefined)
+                    return Promise.reject(new FilesUnreadableError(object.key, reason));
+                counted();
+                return Promise.resolve(file.bytes);
+            },
+        };
+    }
+}
+/** A workspace's inputs in memory: what a sync wrote to each, and a hash of each value. */
+export class MemoryWorkspace {
+    /** Each `file` or `latest` input's bytes */
+    files = new Map();
+    /** Each `folder` input's entries */
+    folders = new Map();
+    /** Each `listing` input's rows */
+    listings = new Map();
+    /** How many times each input was written */
+    writes = new Map();
+    #values = new Map();
+    #version = 0;
+    /** Records a write, and answers the value's hash: a new one each time. */
+    #wrote(input) {
+        this.writes.set(input, (this.writes.get(input) ?? 0) + 1);
+        this.#version += 1;
+        const value = `value-${this.#version}`;
+        this.#values.set(input, value);
+        return value;
+    }
+    /** Empties an input, as a deploy that resets the workspace's inputs does. */
+    reset(input) {
+        this.files.delete(input);
+        this.folders.delete(input);
+        this.listings.delete(input);
+        this.#values.delete(input);
+    }
+    current(input) {
+        return Promise.resolve(this.#values.get(input) ?? null);
+    }
+    setFile(input, bytes) {
+        this.files.set(input, bytes);
+        return Promise.resolve(this.#wrote(input));
+    }
+    updateFolder(input, changes) {
+        const folder = changes.fresh ? new Map() : new Map(this.folders.get(input) ?? []);
+        for (const path of changes.remove)
+            folder.delete(path);
+        for (const [path, bytes] of changes.set)
+            folder.set(path, bytes);
+        this.folders.set(input, new Map([...folder].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))));
+        return Promise.resolve(this.#wrote(input));
+    }
+    setListing(input, rows) {
+        this.listings.set(input, new Map(rows));
+        return Promise.resolve(this.#wrote(input));
+    }
+}
+/** A ledger in memory. */
+export class MemoryLedger {
+    #states = new Map();
+    read(input) {
+        return Promise.resolve(this.#states.get(input) ?? NO_LEDGER);
+    }
+    write(input, state) {
+        this.#states.set(input, { entries: new Map(state.entries), value: state.value, under: state.under });
+        return Promise.resolve();
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/src/sync/memory.js.map

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

package/dist/test/decode.examples.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Decoding what Files fills, one example each. Each `fn` is the East
+ * function a task runs over an input a source's files fill: a `file` or
+ * `latest` input is the file's bytes, a `Blob`; a `folder` input every file's
+ * bytes by its path under the prefix, a `Dict<String, Blob>`; a `listing`
+ * input each file's size, time and ETag by its path. Nothing decodes a file
+ * for you: the task does, here as East's JSON, as CSV, or as lines of text.
+ * The declarations themselves (`Files.source`, `file`, `latest`, `folder`,
+ * `listing`, `Files.manifest`) are the index's hand-written entries, and the
+ * skill's.
+ */
+import { BlobType, DateTimeType, IntegerType, StringType, StructType } from '@elaraai/east';
+export declare const fileAsJson: import("@elaraai/east").ExampleDef<[BlobType], any>;
+export declare const fileAsCsv: import("@elaraai/east").ExampleDef<[BlobType], any>;
+export declare const fileAsLines: import("@elaraai/east").ExampleDef<[BlobType], any>;
+export declare const folderAsOneArray: import("@elaraai/east").ExampleDef<[import("@elaraai/east").DictType<StringType, BlobType>], any>;
+export declare const folderRowsWithTheirFile: import("@elaraai/east").ExampleDef<[import("@elaraai/east").DictType<StringType, BlobType>], any>;
+export declare const folderUnderASubfolder: import("@elaraai/east").ExampleDef<[import("@elaraai/east").DictType<StringType, BlobType>, StringType], any>;
+export declare const listingChangedSince: import("@elaraai/east").ExampleDef<[import("@elaraai/east").DictType<StringType, StructType<{
+    readonly size: IntegerType;
+    readonly modified: DateTimeType;
+    readonly etag: StringType;
+}>>, DateTimeType], any>;
+export declare const listingTotals: import("@elaraai/east").ExampleDef<[import("@elaraai/east").DictType<StringType, StructType<{
+    readonly size: IntegerType;
+    readonly modified: DateTimeType;
+    readonly etag: StringType;
+}>>], any>;
+//# sourceMappingURL=decode.examples.d.ts.map

package/dist/test/decode.examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.examples.d.ts","sourceRoot":"","sources":["../../test/decode.examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAmB,QAAQ,EAAE,YAAY,EAAa,WAAW,EAAE,UAAU,EAAE,UAAU,EAAW,MAAM,eAAe,CAAC;AAcjI,eAAO,MAAM,UAAU,qDAMrB,CAAC;AAEH,eAAO,MAAM,SAAS,qDAMpB,CAAC;AAEH,eAAO,MAAM,WAAW,qDAOtB,CAAC;AAMH,eAAO,MAAM,gBAAgB,mGAU3B,CAAC;AAEH,eAAO,MAAM,uBAAuB,mGAWlC,CAAC;AAEH,eAAO,MAAM,qBAAqB,+GAOhC,CAAC;AAMH,eAAO,MAAM,mBAAmB;;;;wBAa9B,CAAC;AAEH,eAAO,MAAM,aAAa;;;;UAUxB,CAAC"}

package/dist/test/decode.examples.js

@@ -0,0 +1,103 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Decoding what Files fills, one example each. Each `fn` is the East
+ * function a task runs over an input a source's files fill: a `file` or
+ * `latest` input is the file's bytes, a `Blob`; a `folder` input every file's
+ * bytes by its path under the prefix, a `Dict<String, Blob>`; a `listing`
+ * input each file's size, time and ETag by its path. Nothing decodes a file
+ * for you: the task does, here as East's JSON, as CSV, or as lines of text.
+ * The declarations themselves (`Files.source`, `file`, `latest`, `folder`,
+ * `listing`, `Files.manifest`) are the index's hand-written entries, and the
+ * skill's.
+ */
+import { East, ArrayType, BlobType, DateTimeType, FloatType, IntegerType, StringType, StructType, example } from '@elaraai/east';
+import { FilesFolderType, FilesListingType } from '@elaraai/e3-cloud-files';
+const Rate = StructType({ currency: StringType, rate: FloatType });
+const Order = StructType({ id: StringType, sku: StringType, amount: FloatType });
+const Reading = StructType({ tank: StringType, litres: FloatType });
+/** Text as a file's bytes. */
+const utf8 = (text) => new TextEncoder().encode(text);
+// ---
+// A file's bytes: file and latest
+// ---
+export const fileAsJson = example({
+    keywords: ['Files', 'file', 'latest', 'Blob', 'decodeUtf8', 'parseJson', 'JSON', 'decode', 'task'],
+    description: 'A file input\'s bytes decoded as East\'s JSON, in the task that reads it: what upload.file(\'rates\', { key: \'rates.json\' }) or upload.latest(…) fills, a Blob',
+    fn: East.function([BlobType], ArrayType(Rate), (_$, file) => file.decodeUtf8().parseJson(ArrayType(Rate))),
+    inputs: [utf8('[{"currency":"AUD","rate":1.0},{"currency":"USD","rate":0.66}]')],
+    returns: [{ currency: 'AUD', rate: 1.0 }, { currency: 'USD', rate: 0.66 }],
+});
+export const fileAsCsv = example({
+    keywords: ['Files', 'file', 'latest', 'Blob', 'decodeCsv', 'CSV', 'header', 'delimiter', 'columns'],
+    description: 'A file input\'s bytes decoded as CSV with a header row, each row a struct whose fields name the columns',
+    fn: East.function([BlobType], ArrayType(Reading), (_$, file) => file.decodeCsv(Reading, { delimiter: ',' })),
+    inputs: [utf8('tank,litres\nT1,1200.5\nT2,880\n')],
+    returns: [{ tank: 'T1', litres: 1200.5 }, { tank: 'T2', litres: 880 }],
+});
+export const fileAsLines = example({
+    keywords: ['Files', 'file', 'Blob', 'decodeUtf8', 'split', 'lines', 'text', 'trim'],
+    description: 'A text file input\'s lines, trimmed, blank ones left out',
+    fn: East.function([BlobType], ArrayType(StringType), (_$, file) => file.decodeUtf8().split('\n').map((_$, line) => line.trim()).filter((_$, line) => line.notEquals(''))),
+    inputs: [utf8('first\n\n  second  \nthird\n')],
+    returns: ['first', 'second', 'third'],
+});
+// ---
+// A folder's files
+// ---
+export const folderAsOneArray = example({
+    keywords: ['Files', 'folder', 'Dict', 'Blob', 'flattenToArray', 'parseJson', 'every file', 'concatenate'],
+    description: 'Every file of a folder input decoded and joined into one array, in the order of their paths: what upload.folder(\'orders\', { prefix: \'orders/\', include: \'*.json\' }) fills, a Dict<String, Blob> keyed by each file\'s path under the prefix',
+    fn: East.function([FilesFolderType], ArrayType(Order), (_$, files) => files.flattenToArray((_$, file) => file.decodeUtf8().parseJson(ArrayType(Order)))),
+    inputs: [new Map([
+            ['2026-10-01.json', utf8('[{"id":"O-1","sku":"A1","amount":250.0}]')],
+            ['2026-10-02.json', utf8('[{"id":"O-2","sku":"B2","amount":80.0},{"id":"O-3","sku":"A1","amount":120.0}]')],
+        ])],
+    returns: [{ id: 'O-1', sku: 'A1', amount: 250 }, { id: 'O-2', sku: 'B2', amount: 80 }, { id: 'O-3', sku: 'A1', amount: 120 }],
+});
+export const folderRowsWithTheirFile = example({
+    keywords: ['Files', 'folder', 'path', 'key', 'flattenToArray', 'decodeCsv', 'which file', 'provenance'],
+    description: 'Every CSV file of a folder input decoded, each row carrying the path of the file it came from',
+    fn: East.function([FilesFolderType], ArrayType(StructType({ file: StringType, tank: StringType, litres: FloatType })), (_$, files) => files.flattenToArray((_$, file, path) => file.decodeCsv(Reading, { delimiter: ',' }).map((_$, row) => ({ file: path, tank: row.tank, litres: row.litres })))),
+    inputs: [new Map([
+            ['site-a.csv', utf8('tank,litres\nT1,1200.5\n')],
+            ['site-b.csv', utf8('tank,litres\nT9,40\n')],
+        ])],
+    returns: [{ file: 'site-a.csv', tank: 'T1', litres: 1200.5 }, { file: 'site-b.csv', tank: 'T9', litres: 40 }],
+});
+export const folderUnderASubfolder = example({
+    keywords: ['Files', 'folder', 'filter', 'startsWith', 'path', 'subfolder', 'include', '**'],
+    description: 'Only the files of a folder input under one of its subfolders. A folder declared with include \'**/*.csv\', or none, holds its subfolders\' files too, each path naming its subfolder (2026/10/a.csv); \'*.csv\' matches only the top level',
+    fn: East.function([FilesFolderType, StringType], FilesFolderType, (_$, files, under) => files.filter((_$, _file, path) => path.startsWith(under))),
+    inputs: [new Map([['2025/12/a.csv', utf8('a')], ['2026/01/b.csv', utf8('b')], ['2026/02/c.csv', utf8('c')]]), '2026/'],
+    returns: new Map([['2026/01/b.csv', utf8('b')], ['2026/02/c.csv', utf8('c')]]),
+});
+// ---
+// A listing: the files, without their bytes
+// ---
+export const listingChangedSince = example({
+    keywords: ['Files', 'listing', 'modified', 'since', 'DateTime', 'filter', 'keys', 'newest'],
+    description: 'The paths of a listing input\'s files changed since a time, without reading their bytes: what upload.listing(\'order_files\', { prefix: \'orders/\' }) fills, each file\'s size, modified time and ETag by its path',
+    fn: East.function([FilesListingType, DateTimeType], ArrayType(StringType), (_$, rows, since) => rows.filter((_$, row) => row.modified.greaterThan(since)).keys().toArray()),
+    inputs: [
+        new Map([
+            ['2026-10-01.json', { size: 120n, modified: new Date(Date.UTC(2026, 9, 1)), etag: 'a1' }],
+            ['2026-10-02.json', { size: 310n, modified: new Date(Date.UTC(2026, 9, 2)), etag: 'b2' }],
+        ]),
+        new Date(Date.UTC(2026, 9, 1, 12)),
+    ],
+    returns: ['2026-10-02.json'],
+});
+export const listingTotals = example({
+    keywords: ['Files', 'listing', 'size', 'sum', 'count', 'bytes', 'how many'],
+    description: 'How many files a listing input holds, and their bytes in all',
+    fn: East.function([FilesListingType], StructType({ files: IntegerType, bytes: IntegerType }), (_$, rows) => ({ files: rows.size(), bytes: rows.sum((_$, row) => row.size) })),
+    inputs: [new Map([
+            ['a.json', { size: 120n, modified: new Date(Date.UTC(2026, 9, 1)), etag: 'a1' }],
+            ['b.json', { size: 310n, modified: new Date(Date.UTC(2026, 9, 2)), etag: 'b2' }],
+        ])],
+    returns: { files: 2n, bytes: 430n },
+});
+//# sourceMappingURL=decode.examples.js.map

package/dist/test/decode.examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode.examples.js","sourceRoot":"","sources":["../../test/decode.examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACjI,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE5E,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;AACnE,MAAM,KAAK,GAAG,UAAU,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AACjF,MAAM,OAAO,GAAG,UAAU,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AAEpE,8BAA8B;AAC9B,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAE9D,MAAM;AACN,kCAAkC;AAClC,MAAM;AAEN,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC;IAChC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC;IAClG,WAAW,EAAE,kKAAkK;IAC/K,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1G,MAAM,EAAE,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IAChF,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;CAC3E,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC;IAC/B,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,CAAC;IACnG,WAAW,EAAE,yGAAyG;IACtH,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;IAC5G,MAAM,EAAE,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAClD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;CACvE,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;IACjC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC;IACnF,WAAW,EAAE,0DAA0D;IACvE,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAChE,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;IACxG,MAAM,EAAE,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAC9C,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC;CACtC,CAAC,CAAC;AAEH,MAAM;AACN,mBAAmB;AACnB,MAAM;AAEN,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC;IACtC,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,CAAC;IACzG,WAAW,EAAE,mPAAmP;IAChQ,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CACnE,KAAK,CAAC,cAAc,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACpF,MAAM,EAAE,CAAC,IAAI,GAAG,CAAC;YACf,CAAC,iBAAiB,EAAE,IAAI,CAAC,0CAA0C,CAAC,CAAC;YACrE,CAAC,iBAAiB,EAAE,IAAI,CAAC,gFAAgF,CAAC,CAAC;SAC5G,CAAC,CAAC;IACH,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;CAC9H,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;IAC7C,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC;IACvG,WAAW,EAAE,+FAA+F;IAC5G,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CACnI,KAAK,CAAC,cAAc,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CACtC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACxH,MAAM,EAAE,CAAC,IAAI,GAAG,CAAC;YACf,CAAC,YAAY,EAAE,IAAI,CAAC,0BAA0B,CAAC,CAAC;YAChD,CAAC,YAAY,EAAE,IAAI,CAAC,sBAAsB,CAAC,CAAC;SAC7C,CAAC,CAAC;IACH,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;CAC9G,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC;IAC3C,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,CAAC;IAC3F,WAAW,EAAE,4OAA4O;IACzP,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,eAAe,EAAE,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CACrF,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5D,MAAM,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;IACtH,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAC/E,CAAC,CAAC;AAEH,MAAM;AACN,4CAA4C;AAC5C,MAAM;AAEN,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;IACzC,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;IAC3F,WAAW,EAAE,qNAAqN;IAClO,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,gBAAgB,EAAE,YAAY,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAC7F,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC;IAC7E,MAAM,EAAE;QACN,IAAI,GAAG,CAAC;YACN,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YACzF,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;SAC1F,CAAC;QACF,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;KACnC;IACD,OAAO,EAAE,CAAC,iBAAiB,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAC;IACnC,QAAQ,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC;IAC3E,WAAW,EAAE,8DAA8D;IAC3E,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CACzG,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnE,MAAM,EAAE,CAAC,IAAI,GAAG,CAAC;YACf,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAChF,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;SACjF,CAAC,CAAC;IACH,OAAO,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;CACpC,CAAC,CAAC"}

package/dist/test/orders.examples.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * The worked example of the author's guide (README): an orders business whose
+ * partners drop files in a bucket. Every shape appears: one file (`rates`),
+ * the newest of a folder of snapshots (`stock`), every file of a folder
+ * (`orders`), and a folder's listing (`order_files`), each decoded in East by
+ * a task, as a file's bytes arrive as they are.
+ *
+ * `sampleFiles` is what a partner drops, in East's JSON; the examples deploy
+ * uploads them to the bucket the example binds, then syncs and runs.
+ */
+import { ArrayType, BlobType, FloatType, IntegerType, StringType, StructType } from '@elaraai/east';
+import { type FilesManifest } from '../src/index.js';
+/** Where the partners' files are: each workspace binds it to a bucket and prefix. */
+export declare const upload: import("../src/authoring.js").FilesSource;
+/** One file: today's exchange rates. */
+export declare const rates: import("@elaraai/e3").DatasetDef<BlobType, [import("@elaraai/east").variant<"field", "inputs">, import("@elaraai/east").variant<"field", "rates">]>;
+/** The newest stock snapshot: the snapshots are named by their date, so the greatest key is the latest. */
+export declare const stock: import("@elaraai/e3").DatasetDef<BlobType, [import("@elaraai/east").variant<"field", "inputs">, import("@elaraai/east").variant<"field", "stock">]>;
+/** Every order file, keyed by its name. */
+export declare const orders: import("@elaraai/e3").DatasetDef<import("@elaraai/east").DictType<StringType, BlobType>, [import("@elaraai/east").variant<"field", "inputs">, import("@elaraai/east").variant<"field", "orders">]>;
+/** The order files' sizes, times and ETags, without their bytes. */
+export declare const orderFiles: import("@elaraai/e3").DatasetDef<import("@elaraai/east").DictType<StringType, StructType<{
+    readonly size: IntegerType;
+    readonly modified: import("@elaraai/east").DateTimeType;
+    readonly etag: StringType;
+}>>, [import("@elaraai/east").variant<"field", "inputs">, import("@elaraai/east").variant<"field", "order_files">]>;
+/** What `e3-cloud files deploy` deploys. */
+declare const manifest: FilesManifest;
+export default manifest;
+export declare const Rate: StructType<{
+    readonly currency: StringType;
+    readonly rate: FloatType;
+}>;
+export declare const StockLine: StructType<{
+    readonly sku: StringType;
+    readonly units: FloatType;
+}>;
+export declare const Order: StructType<{
+    readonly id: StringType;
+    readonly sku: StringType;
+    readonly currency: StringType;
+    readonly amount: FloatType;
+}>;
+/** A file's bytes as East's JSON. */
+export declare const decodeRates: import("@elaraai/east").CallableFunctionExpr<[BlobType], ArrayType<StructType<{
+    readonly currency: StringType;
+    readonly rate: FloatType;
+}>>>;
+export declare const decodeStock: import("@elaraai/east").CallableFunctionExpr<[BlobType], ArrayType<StructType<{
+    readonly sku: StringType;
+    readonly units: FloatType;
+}>>>;
+/** Every order file's orders, one after another. */
+export declare const decodeOrders: import("@elaraai/east").CallableFunctionExpr<[import("@elaraai/east").DictType<StringType, BlobType>], ArrayType<StructType<{
+    readonly id: StringType;
+    readonly sku: StringType;
+    readonly currency: StringType;
+    readonly amount: FloatType;
+}>>>;
+/** How many order files there are, from the listing alone. */
+export declare const countFiles: import("@elaraai/east").CallableFunctionExpr<[import("@elaraai/east").DictType<StringType, StructType<{
+    readonly size: IntegerType;
+    readonly modified: import("@elaraai/east").DateTimeType;
+    readonly etag: StringType;
+}>>], IntegerType>;
+export declare const rateTable: import("@elaraai/e3").TaskDef<ArrayType<StructType<{
+    readonly currency: StringType;
+    readonly rate: FloatType;
+}>>, [import("@elaraai/east").variant<"field", "tasks">, import("@elaraai/east").variant<"field", "rate_table">, import("@elaraai/east").variant<"field", "output">]>;
+export declare const stockLevels: import("@elaraai/e3").TaskDef<ArrayType<StructType<{
+    readonly sku: StringType;
+    readonly units: FloatType;
+}>>, [import("@elaraai/east").variant<"field", "tasks">, import("@elaraai/east").variant<"field", "stock_levels">, import("@elaraai/east").variant<"field", "output">]>;
+export declare const allOrders: import("@elaraai/e3").TaskDef<ArrayType<StructType<{
+    readonly id: StringType;
+    readonly sku: StringType;
+    readonly currency: StringType;
+    readonly amount: FloatType;
+}>>, [import("@elaraai/east").variant<"field", "tasks">, import("@elaraai/east").variant<"field", "all_orders">, import("@elaraai/east").variant<"field", "output">]>;
+export declare const orderFileCount: import("@elaraai/e3").TaskDef<IntegerType, [import("@elaraai/east").variant<"field", "tasks">, import("@elaraai/east").variant<"field", "order_file_count">, import("@elaraai/east").variant<"field", "output">]>;
+export declare const ordersPackage: import("@elaraai/e3").PackageDef<Record<string, unknown>>;
+/** Sample files, by key under the binding, written with East's JSON encoder. */
+export declare const sampleFiles: ReadonlyMap<string, Uint8Array>;
+//# sourceMappingURL=orders.examples.d.ts.map

package/dist/test/orders.examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orders.examples.d.ts","sourceRoot":"","sources":["../../test/orders.examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AAEH,OAAO,EAAQ,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAiB,MAAM,eAAe,CAAC;AAEzH,OAAO,EAA4C,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAM/F,qFAAqF;AACrF,eAAO,MAAM,MAAM,2CAAyB,CAAC;AAE7C,wCAAwC;AACxC,eAAO,MAAM,KAAK,qJAA8C,CAAC;AACjE,2GAA2G;AAC3G,eAAO,MAAM,KAAK,qJAAkE,CAAC;AACrF,2CAA2C;AAC3C,eAAO,MAAM,MAAM,oMAAoE,CAAC;AACxF,oEAAoE;AACpE,eAAO,MAAM,UAAU;;;;mHAA0E,CAAC;AAElG,4CAA4C;AAC5C,QAAA,MAAM,QAAQ,EAAE,aAAwC,CAAC;AACzD,eAAe,QAAQ,CAAC;AAIxB,eAAO,MAAM,IAAI;;;EAAwD,CAAC;AAC1E,eAAO,MAAM,SAAS;;;EAAoD,CAAC;AAC3E,eAAO,MAAM,KAAK;;;;;EAA2F,CAAC;AAE9G,qCAAqC;AACrC,eAAO,MAAM,WAAW;;;IACuB,CAAC;AAEhD,eAAO,MAAM,WAAW;;;IAC4B,CAAC;AAErD,oDAAoD;AACpD,eAAO,MAAM,YAAY;;;;;IAMvB,CAAC;AAEH,8DAA8D;AAC9D,eAAO,MAAM,UAAU;;;;kBAA4E,CAAC;AAEpG,eAAO,MAAM,SAAS;;;qKAAkE,CAAC;AACzF,eAAO,MAAM,WAAW;;;uKAAoE,CAAC;AAC7F,eAAO,MAAM,SAAS;;;;;qKAAoE,CAAC;AAC3F,eAAO,MAAM,cAAc,mNAA4E,CAAC;AAExG,eAAO,MAAM,aAAa,2DAAmF,CAAC;AAQ9G,gFAAgF;AAChF,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAUtD,CAAC"}

package/dist/test/orders.examples.js

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * The worked example of the author's guide (README): an orders business whose
+ * partners drop files in a bucket. Every shape appears: one file (`rates`),
+ * the newest of a folder of snapshots (`stock`), every file of a folder
+ * (`orders`), and a folder's listing (`order_files`), each decoded in East by
+ * a task, as a file's bytes arrive as they are.
+ *
+ * `sampleFiles` is what a partner drops, in East's JSON; the examples deploy
+ * uploads them to the bucket the example binds, then syncs and runs.
+ */
+import { East, ArrayType, BlobType, FloatType, IntegerType, StringType, StructType, encodeJSONFor } from '@elaraai/east';
+import e3 from '@elaraai/e3';
+import { Files, FilesFolderType, FilesListingType } from '../src/index.js';
+const RUNNER = { runtime: 'east-c', platforms: ['east-c-std'] };
+// ─── src/files.ts: the files, and the inputs they fill ──────────────────────
+/** Where the partners' files are: each workspace binds it to a bucket and prefix. */
+export const upload = Files.source('upload');
+/** One file: today's exchange rates. */
+export const rates = upload.file('rates', { key: 'rates.json' });
+/** The newest stock snapshot: the snapshots are named by their date, so the greatest key is the latest. */
+export const stock = upload.latest('stock', { prefix: 'stock/', include: '*.json' });
+/** Every order file, keyed by its name. */
+export const orders = upload.folder('orders', { prefix: 'orders/', include: '*.json' });
+/** The order files' sizes, times and ETags, without their bytes. */
+export const orderFiles = upload.listing('order_files', { prefix: 'orders/', include: '*.json' });
+/** What `e3-cloud files deploy` deploys. */
+const manifest = Files.manifest([upload]);
+export default manifest;
+// ─── src/package.ts: the files, decoded ─────────────────────────────────────
+export const Rate = StructType({ currency: StringType, rate: FloatType });
+export const StockLine = StructType({ sku: StringType, units: FloatType });
+export const Order = StructType({ id: StringType, sku: StringType, currency: StringType, amount: FloatType });
+/** A file's bytes as East's JSON. */
+export const decodeRates = East.function([BlobType], ArrayType(Rate), (_$, file) => file.decodeUtf8().parseJson(ArrayType(Rate)));
+export const decodeStock = East.function([BlobType], ArrayType(StockLine), (_$, file) => file.decodeUtf8().parseJson(ArrayType(StockLine)));
+/** Every order file's orders, one after another. */
+export const decodeOrders = East.function([FilesFolderType], ArrayType(Order), ($, files) => {
+    const all = $.let([], ArrayType(Order));
+    $.for(files, ($, file) => {
+        $(all.append(file.decodeUtf8().parseJson(ArrayType(Order))));
+    });
+    $.return(all);
+});
+/** How many order files there are, from the listing alone. */
+export const countFiles = East.function([FilesListingType], IntegerType, (_$, rows) => rows.size());
+export const rateTable = e3.task('rate_table', [rates], decodeRates, { runner: RUNNER });
+export const stockLevels = e3.task('stock_levels', [stock], decodeStock, { runner: RUNNER });
+export const allOrders = e3.task('all_orders', [orders], decodeOrders, { runner: RUNNER });
+export const orderFileCount = e3.task('order_file_count', [orderFiles], countFiles, { runner: RUNNER });
+export const ordersPackage = e3.package('orders', '1.0.0', rateTable, stockLevels, allOrders, orderFileCount);
+// ─── What a partner drops ───────────────────────────────────────────────────
+const rateFile = encodeJSONFor(ArrayType(Rate));
+const stockFile = encodeJSONFor(ArrayType(StockLine));
+const orderFile = encodeJSONFor(ArrayType(Order));
+/** Sample files, by key under the binding, written with East's JSON encoder. */
+export const sampleFiles = new Map([
+    ['rates.json', rateFile([{ currency: 'AUD', rate: 1.0 }, { currency: 'USD', rate: 0.66 }])],
+    ['stock/2026-10-01.json', stockFile([{ sku: 'A1', units: 120 }, { sku: 'B2', units: 40 }])],
+    ['stock/2026-10-02.json', stockFile([{ sku: 'A1', units: 95 }, { sku: 'B2', units: 52 }])],
+    ['orders/2026-10-01.json', orderFile([{ id: 'O-1', sku: 'A1', currency: 'AUD', amount: 250 }])],
+    ['orders/2026-10-02.json', orderFile([
+            { id: 'O-2', sku: 'B2', currency: 'USD', amount: 80 },
+            { id: 'O-3', sku: 'A1', currency: 'AUD', amount: 120 },
+        ])],
+    ['orders/README.txt', new TextEncoder().encode('Not an order file: the glob leaves it out.')],
+]);
+//# sourceMappingURL=orders.examples.js.map

package/dist/test/orders.examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orders.examples.js","sourceRoot":"","sources":["../../test/orders.examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AAEH,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACzH,OAAO,EAAmB,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAsB,MAAM,iBAAiB,CAAC;AAE/F,MAAM,MAAM,GAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC;AAExE,+EAA+E;AAE/E,qFAAqF;AACrF,MAAM,CAAC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAE7C,wCAAwC;AACxC,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,CAAC;AACjE,2GAA2G;AAC3G,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;AACrF,2CAA2C;AAC3C,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;AACxF,oEAAoE;AACpE,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;AAElG,4CAA4C;AAC5C,MAAM,QAAQ,GAAkB,KAAK,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AACzD,eAAe,QAAQ,CAAC;AAExB,+EAA+E;AAE/E,MAAM,CAAC,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;AAC1E,MAAM,CAAC,MAAM,SAAS,GAAG,UAAU,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;AAC3E,MAAM,CAAC,MAAM,KAAK,GAAG,UAAU,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AAE9G,qCAAqC;AACrC,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CACjF,IAAI,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEhD,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CACtF,IAAI,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAErD,oDAAoD;AACpD,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE;IAC1F,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACxC,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IACH,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAChB,CAAC,CAAC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;AAEpG,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AACzF,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAC7F,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAC3F,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAExG,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;AAE9G,+EAA+E;AAE/E,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAChD,MAAM,SAAS,GAAG,aAAa,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC;AACtD,MAAM,SAAS,GAAG,aAAa,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AAElD,gFAAgF;AAChF,MAAM,CAAC,MAAM,WAAW,GAAoC,IAAI,GAAG,CAAC;IAClE,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3F,CAAC,uBAAuB,EAAE,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3F,CAAC,uBAAuB,EAAE,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1F,CAAC,wBAAwB,EAAE,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC/F,CAAC,wBAAwB,EAAE,SAAS,CAAC;YACnC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE;YACrD,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE;SACvD,CAAC,CAAC;IACH,CAAC,mBAAmB,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,4CAA4C,CAAC,CAAC;CAC9F,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@elaraai/e3-cloud-files",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.92",
+  "description": "Files for e3 cloud: a solution's inputs that come from files in a bucket, declared in its code and synced on demand, locally and in the cloud",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./check": {
+      "types": "./dist/src/check/index.d.ts",
+      "default": "./dist/src/check/index.js"
+    },
+    "./sync": {
+      "types": "./dist/src/sync/index.d.ts",
+      "default": "./dist/src/sync/index.js"
+    },
+    "./storage": {
+      "types": "./dist/src/storage/index.d.ts",
+      "default": "./dist/src/storage/index.js"
+    },
+    "./s3": {
+      "types": "./dist/src/s3/index.d.ts",
+      "default": "./dist/src/s3/index.js"
+    },
+    "./examples/*": {
+      "types": "./dist/test/*.examples.d.ts",
+      "default": "./dist/test/*.examples.js"
+    }
+  },
+  "files": [
+    "dist/src/**/*",
+    "dist/test/**/*.examples.*",
+    "!dist/**/*.spec.*",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "keywords": [
+    "east",
+    "elara",
+    "e3",
+    "e3-cloud",
+    "files",
+    "s3"
+  ],
+  "author": "Elara AI Pty Ltd",
+  "license": "BUSL-1.1",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@elaraai/e3-types": "1.0.92",
+    "@elaraai/e3-cloud-types": "1.0.92"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.966.0",
+    "@elaraai/e3": "1.0.92",
+    "@elaraai/e3-core": "1.0.92",
+    "@elaraai/east": "1.0.92"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@elaraai/e3": {
+      "optional": true
+    },
+    "@elaraai/e3-core": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }