@decaf-ts/integrations 0.10.8 → 0.12.0

package/lib/cjs/io/spreadsheet/SpreadsheetService.cjs

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpreadsheetService = void 0;
+const db_decorators_1 = require("@decaf-ts/db-decorators");
+const DELIMITERS = {
+    csv: ",",
+    tsv: "\t",
+    json: "",
+};
+function resolveFormat(format, delimiter) {
+    if (format)
+        return format;
+    if (delimiter === "\t")
+        return "tsv";
+    return "csv";
+}
+function parseDelimited(content, delimiter) {
+    const rows = [];
+    let row = [];
+    let field = "";
+    let quoted = false;
+    for (let index = 0; index < content.length; index += 1) {
+        const character = content[index];
+        if (quoted) {
+            if (character === '"') {
+                if (content[index + 1] === '"') {
+                    field += '"';
+                    index += 1;
+                }
+                else {
+                    quoted = false;
+                }
+            }
+            else {
+                field += character;
+            }
+            continue;
+        }
+        if (character === '"' && field.length === 0) {
+            quoted = true;
+            continue;
+        }
+        if (character === delimiter) {
+            row.push(field);
+            field = "";
+            continue;
+        }
+        if (character === "\n") {
+            row.push(field.replace(/\r$/, ""));
+            rows.push(row);
+            row = [];
+            field = "";
+            continue;
+        }
+        field += character;
+    }
+    if (field.length > 0 || row.length > 0) {
+        row.push(field.replace(/\r$/, ""));
+        rows.push(row);
+    }
+    return rows.filter((entry) => entry.length > 1 || (entry[0] ?? "").trim().length > 0);
+}
+function quoteField(value, delimiter) {
+    if (value.includes(delimiter) ||
+        value.includes('"') ||
+        value.includes("\n") ||
+        value.includes("\r")) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
+function cell(value) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value === "object") {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    return String(value);
+}
+/**
+ * @description Dependency-free spreadsheet parsing and serialization service
+ * @summary A stateless (no configuration, no HTTP client) service that
+ * converts between tabular strings and row arrays. `parse` handles CSV and
+ * TSV with a quoted-field parser (double-quote escaping, CRLF stripping,
+ * blank-row filtering) and JSON arrays of rows or records; `serialize`
+ * writes CSV/TSV with RFC 4180-style quoting of fields containing the
+ * delimiter, quotes, or line breaks, or pretty-printed JSON records. Values
+ * are stringified with `null`/`undefined` as empty cells and objects as JSON.
+ * @class SpreadsheetService
+ * @category IO
+ * @example
+ * ```ts
+ * import { SpreadsheetService } from "@decaf-ts/integrations/io/spreadsheet";
+ *
+ * const spreadsheets = new SpreadsheetService();
+ * const parsed = spreadsheets.parse("name,count\nalpha,1\nbeta,2", {
+ *   format: "csv",
+ * });
+ * // parsed.header === ["name", "count"], parsed.rows === [["alpha", "1"], ["beta", "2"]]
+ * ```
+ * @memberOf module:integrations/io/spreadsheet/service
+ */
+class SpreadsheetService {
+    /**
+     * @description Parses spreadsheet text into a header and data rows
+     * @summary Dispatches on the resolved format. `"json"` content must be an
+     * array: either an array of arrays (the first row becomes the header unless
+     * `header: false`) or an array of records (the union of the first record's
+     * keys becomes the header). CSV/TSV content is parsed with a quoted-field
+     * parser honoring `""` escapes and CR/LF line endings, dropping blank rows;
+     * the first row becomes the header unless `header: false`.
+     * @param {string} content - The spreadsheet text content to parse.
+     * @param {SpreadsheetParseOptions} [options] - Format, delimiter, and header options.
+     * @returns {SpreadsheetParseResult} The resolved format, header row, and data rows.
+     * @throws {InternalError} When the content is not a string, the JSON payload is invalid, or the JSON payload is not an array.
+     * @example
+     * ```ts
+     * // TSV with an explicit delimiter and no header row
+     * const tsv = spreadsheets.parse("alpha\t1\nbeta\t2", { delimiter: "\t", header: false });
+     * // JSON records infer the header from the first record's keys
+     * const json = spreadsheets.parse('[{"name":"alpha","count":1}]', { format: "json" });
+     * ```
+     */
+    parse(content, options = {}) {
+        if (typeof content !== "string") {
+            throw new db_decorators_1.InternalError("Spreadsheet parse requires text content");
+        }
+        const format = resolveFormat(options.format, options.delimiter);
+        if (format === "json") {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch (error) {
+                throw new db_decorators_1.InternalError(`Spreadsheet JSON parse failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (!Array.isArray(parsed)) {
+                throw new db_decorators_1.InternalError("Spreadsheet JSON content must be an array of rows or records");
+            }
+            if (parsed.length === 0)
+                return { format, header: [], rows: [] };
+            if (Array.isArray(parsed[0])) {
+                const rows = parsed.map((row) => row.map(cell));
+                const header = options.header === false ? [] : (rows.shift() ?? []);
+                return { format, header: header.map(cell), rows };
+            }
+            const records = parsed;
+            const header = Object.keys(records[0] ?? {});
+            const rows = records.map((record) => header.map((field) => cell(record[field])));
+            return { format, header, rows };
+        }
+        const delimiter = options.delimiter ?? DELIMITERS[format];
+        const rows = parseDelimited(content, delimiter);
+        const header = options.header === false ? [] : (rows.shift() ?? []);
+        return { format, header: header.map(cell), rows };
+    }
+    /**
+     * @description Serializes rows into spreadsheet text
+     * @summary Stringifies each cell (objects become JSON, `null`/`undefined`
+     * become empty cells) and dispatches on the resolved format. For `"json"`,
+     * the optional `header` values (or the first data row) become the record
+     * keys and the output is pretty-printed JSON records. For `"csv"`/`"tsv"`,
+     * fields containing the delimiter, quotes, or line breaks are wrapped in
+     * double quotes with inner quotes escaped, and the optional `header` row is
+     * written first. Non-array rows are treated as single-cell rows.
+     * @param {unknown[][]} rows - The data rows to serialize.
+     * @param {SpreadsheetWriteOptions} [options] - Format, delimiter, and header options.
+     * @returns {string} The serialized spreadsheet content.
+     * @throws {InternalError} When `rows` is not an array.
+     * @example
+     * ```ts
+     * const csv = spreadsheets.serialize(
+     *   [["alpha", 1], ["beta, gamma", 2]],
+     *   { format: "csv", header: ["name", "count"] }
+     * );
+     * // "name,count\nalpha,1\n\"beta, gamma\",2"
+     * ```
+     */
+    serialize(rows, options = {}) {
+        if (!Array.isArray(rows)) {
+            throw new db_decorators_1.InternalError("Spreadsheet write requires rows as an array of arrays");
+        }
+        const format = resolveFormat(options.format, options.delimiter);
+        const header = options.header;
+        const materialized = rows.map((row) => Array.isArray(row) ? row.map(cell) : [cell(row)]);
+        if (format === "json") {
+            const fields = header ?? materialized.shift() ?? [];
+            return JSON.stringify(materialized.map((row) => Object.fromEntries(fields.map((field, index) => [field, row[index] ?? ""]))), null, 2);
+        }
+        const delimiter = options.delimiter ?? DELIMITERS[format];
+        const lines = [
+            ...(header ? [header] : []),
+            ...materialized,
+        ].map((row) => row.map((value) => quoteField(cell(value), delimiter)).join(delimiter));
+        return lines.join("\n");
+    }
+}
+exports.SpreadsheetService = SpreadsheetService;
+//# sourceMappingURL=SpreadsheetService.js.map
+//# sourceMappingURL=SpreadsheetService.cjs.map

package/lib/cjs/io/spreadsheet/SpreadsheetService.cjs.map

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

package/lib/cjs/io/spreadsheet/index.cjs

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @module integrations/io/spreadsheet
+ * @summary Tabular text parse/serialize service (CSV, TSV, JSON lines).
+ * @description Re-exports the offline spreadsheet service and its types; no
+ * network or credentials are involved.
+ */
+__exportStar(require("./SpreadsheetService.cjs"), exports);
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.cjs.map

package/lib/cjs/io/spreadsheet/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io/spreadsheet/index.cjs","sourceRoot":"","sources":["io/spreadsheet/index.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,0DAAwC;AACxC,iCAAiC"}

package/lib/cjs/loader/ObjectLoader.cjs

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObjectLoader = void 0;
 exports.createLoaderHookContext = createLoaderHookContext;
+exports.moduleReference = moduleReference;
 const path_1 = require("path");
 const url_1 = require("url");
 function isPathLikeSource(source) {
@@ -49,12 +50,26 @@ function isPathLikeSource(source) {
  * @description Base loader and concrete family loaders for dynamically
  * resolving Decaf integration objects without forcing callers to duplicate
  * import, selection, or post-load hook logic.
+ *
+ * ## Tree-shaking / build-time references
+ *
+ * Dynamic imports are resolved at runtime, so a bundler cannot see which modules
+ * are actually reachable and may drop them from the output. To keep a module
+ * available, keep a *static* reference to it somewhere in the entry graph (for
+ * example a `loaderManifest` object or a side-effect import) while the runtime
+ * lookup still goes through {@link ObjectLoader.loadModule}. Prefer passing the
+ * specifier as a variable (`import(specifier)`) instead of a string literal:
+ * bundlers leave non-literal dynamic imports untouched, which preserves the
+ * lazy/runtime semantics. See {@link moduleReference} for a small helper that
+ * encodes this pattern.
  */
 class ObjectLoader {
     constructor(options = {}) {
         this.family = options.family ?? "generic";
         this.defaultExportName = options.defaultExportName ?? "default";
         this.hooks = options.hooks ?? [];
+        this.beforeResolveHooks = options.beforeResolveHooks ?? [];
+        this.metadata = options.metadata ?? {};
     }
     normalizeSource(source) {
         if (source instanceof URL) {
@@ -81,9 +96,13 @@ class ObjectLoader {
             if (exportedNames.length === 1) {
                 return module[exportedNames[0]];
             }
+            // Pre-existing raw Error kept for backward compatibility. New code paths
+            // must throw a decaf error hierarchy subclass instead.
             throw new Error(`Module "${source}" does not expose a default export.`);
         }
         if (!(exportName in module)) {
+            // Pre-existing raw Error kept for backward compatibility. New code paths
+            // must throw a decaf error hierarchy subclass instead.
             throw new Error(`Module "${source}" does not export "${exportName}".`);
         }
         return module[exportName];
@@ -98,6 +117,43 @@ class ObjectLoader {
         }
         return current;
     }
+    /**
+     * @summary Build the hook context for a load operation.
+     * @description Concrete loaders call this to build a context that carries the
+     * load phase and any loader-specific metadata into hooks.
+     */
+    createContext(source, exportName, module, phase, metadata = this.metadata) {
+        return {
+            family: this.family,
+            source,
+            exportName,
+            module,
+            loaderName: this.constructor.name,
+            phase,
+            metadata,
+        };
+    }
+    /**
+     * @summary Run the configured export hooks against a value.
+     * @description Exposed to concrete loaders that load content (assets, configs)
+     * instead of importing a module, so they can reuse the same hook pipeline.
+     */
+    async runHooks(value, context, options = {}) {
+        const hooks = [...this.hooks, ...(options.hooks ?? [])];
+        return this.applyHooks(value, context, hooks);
+    }
+    /**
+     * @summary Run the configured pre-resolve hooks against a module namespace.
+     */
+    async runBeforeResolveHooks(module, context, options = {}) {
+        const hooks = [
+            ...this.beforeResolveHooks,
+            ...(options.beforeResolveHooks ?? []),
+        ];
+        if (!hooks.length)
+            return module;
+        return this.applyHooks(module, context, hooks);
+    }
     createInstance(options) {
         const Loader = this.constructor;
         return new Loader(options);
@@ -107,17 +163,12 @@ class ObjectLoader {
     }
     async loadExport(source, exportName = this.defaultExportName, options = {}) {
         const normalizedSource = this.normalizeSource(source);
-        const module = await this.importModule(normalizedSource);
+        const imported = await this.importModule(normalizedSource);
+        const beforeResolveContext = this.createContext(normalizedSource, exportName, imported, "beforeResolve", options.metadata ?? this.metadata);
+        const module = await this.runBeforeResolveHooks(imported, beforeResolveContext, options);
         const resolved = this.resolveExport(module, exportName, normalizedSource);
-        const hookContext = {
-            family: this.family,
-            source: normalizedSource,
-            exportName,
-            module,
-            loaderName: this.constructor.name,
-        };
-        const hooks = [...this.hooks, ...(options.hooks ?? [])];
-        return this.applyHooks(resolved, hookContext, hooks);
+        const afterResolveContext = this.createContext(normalizedSource, exportName, module, "afterResolve", options.metadata ?? this.metadata);
+        return this.runHooks(resolved, afterResolveContext, options);
     }
     async loadDefault(source, options = {}) {
         return this.loadExport(source, this.defaultExportName, options);
@@ -130,6 +181,17 @@ class ObjectLoader {
             family: this.family,
             defaultExportName: this.defaultExportName,
             hooks: [...this.hooks, ...hooks],
+            beforeResolveHooks: [...this.beforeResolveHooks],
+            metadata: this.metadata,
+        });
+    }
+    withBeforeResolveHooks(...hooks) {
+        return this.createInstance({
+            family: this.family,
+            defaultExportName: this.defaultExportName,
+            hooks: [...this.hooks],
+            beforeResolveHooks: [...this.beforeResolveHooks, ...hooks],
+            metadata: this.metadata,
         });
     }
     withOptions(options) {
@@ -137,18 +199,40 @@ class ObjectLoader {
             family: options.family ?? this.family,
             defaultExportName: options.defaultExportName ?? this.defaultExportName,
             hooks: [...this.hooks, ...(options.hooks ?? [])],
+            beforeResolveHooks: [
+                ...this.beforeResolveHooks,
+                ...(options.beforeResolveHooks ?? []),
+            ],
+            metadata: { ...this.metadata, ...(options.metadata ?? {}) },
         });
     }
 }
 exports.ObjectLoader = ObjectLoader;
-function createLoaderHookContext(loader, module, source, exportName) {
+function createLoaderHookContext(loader, module, source, exportName, phase = "afterResolve", metadata = {}) {
     return {
         family: loader.family,
         source,
         exportName,
         module,
         loaderName: loader.constructor.name,
+        phase,
+        metadata,
     };
 }
+/**
+ * @summary Build a lazy module reference that survives bundling.
+ * @description Pass a *variable* specifier to `import()` so bundlers do not
+ * statically inline or drop the target. Pair it with a static reference in your
+ * entry graph when the module must be retained:
+ *
+ * ```ts
+ * export const loaderManifest = { feature: "./feature/index.cjs" } as const;
+ * const reference = moduleReference(loaderManifest.feature);
+ * const module = await reference();
+ * ```
+ */
+function moduleReference(specifier) {
+    return () => Promise.resolve(`${specifier}`).then(s => __importStar(require(s)));
+}
 //# sourceMappingURL=ObjectLoader.js.map
 //# sourceMappingURL=ObjectLoader.cjs.map

package/lib/cjs/loader/ObjectLoader.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"loader/ObjectLoader.cjs","sourceRoot":"","sources":["loader/ObjectLoader.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"loader/ObjectLoader.cjs","sourceRoot":"","sources":["loader/ObjectLoader.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2KA,0DAUC;AAaD,0CAEC;AApMD,+BAA2C;AAC3C,6BAAoC;AACpC,SAAS,gBAAgB,CAAC,MAAM;IAC5B,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC;QAC1B,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC;QACtB,IAAA,iBAAU,EAAC,MAAM,CAAC;QAClB,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AACxC,CAAC;AACD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,YAAY;IACrB,YAAY,OAAO,GAAG,EAAE;QACpB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,SAAS,CAAC;QAC1C,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,SAAS,CAAC;QAChE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,IAAI,EAAE,CAAC;QAC3D,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC3C,CAAC;IACD,eAAe,CAAC,MAAM;QAClB,IAAI,MAAM,YAAY,GAAG,EAAE,CAAC;YACxB,OAAO,MAAM,CAAC,IAAI,CAAC;QACvB,CAAC;QACD,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3D,OAAO,MAAM,CAAC;QAClB,CAAC;QACD,IAAI,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,IAAA,mBAAa,EAAC,IAAA,cAAO,EAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QAC/C,CAAC;QACD,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,KAAK,CAAC,YAAY,CAAC,MAAM;QACrB,MAAM,UAAU,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QAChD,OAAO,CAAC,yBAAa,UAAU,uCAAC,CAAC,CAAC;IACtC,CAAC;IACD,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM;QACpC,MAAM,aAAa,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,YAAY,CAAC,CAAC;QAChF,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;gBACtB,OAAO,MAAM,CAAC,OAAO,CAAC;YAC1B,CAAC;YACD,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC7B,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;YACpC,CAAC;YACD,yEAAyE;YACzE,uDAAuD;YACvD,MAAM,IAAI,KAAK,CAAC,WAAW,MAAM,qCAAqC,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,CAAC,CAAC,UAAU,IAAI,MAAM,CAAC,EAAE,CAAC;YAC1B,yEAAyE;YACzE,uDAAuD;YACvD,MAAM,IAAI,KAAK,CAAC,WAAW,MAAM,sBAAsB,UAAU,IAAI,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IACD,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK;QAClC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACvB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC1C,IAAI,OAAO,IAAI,KAAK,WAAW,EAAE,CAAC;gBAC9B,OAAO,GAAG,IAAI,CAAC;YACnB,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IACD;;;;OAIG;IACH,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC,QAAQ;QACrE,OAAO;YACH,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM;YACN,UAAU;YACV,MAAM;YACN,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI;YACjC,KAAK;YACL,QAAQ;SACX,CAAC;IACN,CAAC;IACD;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE;QACvC,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;IACD;;OAEG;IACH,KAAK,CAAC,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE;QACrD,MAAM,KAAK,GAAG;YACV,GAAG,IAAI,CAAC,kBAAkB;YAC1B,GAAG,CAAC,OAAO,CAAC,kBAAkB,IAAI,EAAE,CAAC;SACxC,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,MAAM;YACb,OAAO,MAAM,CAAC;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IACD,cAAc,CAAC,OAAO;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;QAChC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IACD,KAAK,CAAC,UAAU,CAAC,MAAM;QACnB,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IACD,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC,iBAAiB,EAAE,OAAO,GAAG,EAAE;QACtE,MAAM,gBAAgB,GAAG,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QACtD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,gBAAgB,CAAC,CAAC;QAC3D,MAAM,oBAAoB,GAAG,IAAI,CAAC,aAAa,CAAC,gBAAgB,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC5I,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,qBAAqB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,OAAO,CAAC,CAAC;QACzF,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC;QAC1E,MAAM,mBAAmB,GAAG,IAAI,CAAC,aAAa,CAAC,gBAAgB,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxI,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;IACD,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE;QAClC,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE;QAC3B,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;IACD,SAAS,CAAC,GAAG,KAAK;QACd,OAAO,IAAI,CAAC,cAAc,CAAC;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC;YAChC,kBAAkB,EAAE,CAAC,GAAG,IAAI,CAAC,kBAAkB,CAAC;YAChD,QAAQ,EAAE,IAAI,CAAC,QAAQ;SAC1B,CAAC,CAAC;IACP,CAAC;IACD,sBAAsB,CAAC,GAAG,KAAK;QAC3B,OAAO,IAAI,CAAC,cAAc,CAAC;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;YACtB,kBAAkB,EAAE,CAAC,GAAG,IAAI,CAAC,kBAAkB,EAAE,GAAG,KAAK,CAAC;YAC1D,QAAQ,EAAE,IAAI,CAAC,QAAQ;SAC1B,CAAC,CAAC;IACP,CAAC;IACD,WAAW,CAAC,OAAO;QACf,OAAO,IAAI,CAAC,cAAc,CAAC;YACvB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM;YACrC,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,IAAI,IAAI,CAAC,iBAAiB;YACtE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;YAChD,kBAAkB,EAAE;gBAChB,GAAG,IAAI,CAAC,kBAAkB;gBAC1B,GAAG,CAAC,OAAO,CAAC,kBAAkB,IAAI,EAAE,CAAC;aACxC;YACD,QAAQ,EAAE,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE;SAC9D,CAAC,CAAC;IACP,CAAC;CACJ;AA/ID,oCA+IC;AACD,SAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,GAAG,cAAc,EAAE,QAAQ,GAAG,EAAE;IAC7G,OAAO;QACH,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM;QACN,UAAU;QACV,MAAM;QACN,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI;QACnC,KAAK;QACL,QAAQ;KACX,CAAC;AACN,CAAC;AACD;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe,CAAC,SAAS;IACrC,OAAO,GAAG,EAAE,oBAA2B,SAAS,uCAAC,CAAC;AACtD,CAAC;AACD,wCAAwC"}

package/lib/cjs/loader/assets.cjs

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetObjectLoader = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const core_1 = require("@decaf-ts/core");
+const ObjectLoader_js_1 = require("./ObjectLoader.cjs");
+const TEXT_EXTENSIONS = new Set([
+    ".txt",
+    ".md",
+    ".csv",
+    ".html",
+    ".htm",
+    ".xml",
+    ".yaml",
+    ".yml",
+    ".graphql",
+    ".sql",
+]);
+const IMAGE_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".bmp",
+    ".ico",
+    ".avif",
+    ".tiff",
+]);
+const CONTENT_TYPES = {
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".csv": "text/csv",
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".xml": "application/xml",
+    ".yaml": "application/yaml",
+    ".yml": "application/yaml",
+    ".sql": "application/sql",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+    ".avif": "image/avif",
+    ".tiff": "image/tiff",
+};
+function contentTypeFor(extension) {
+    return CONTENT_TYPES[extension] ?? "application/octet-stream";
+}
+/**
+ * @summary Load asset files as content instead of importing a class.
+ * @description Assets (locale files, images, templates, ...) are *not* modules;
+ * they are read from disk and decoded. Hooks run on the {@link LoadedAsset}
+ * record so callers can inspect or replace content before it enters the system.
+ *
+ * A `"json"` encoding parses the file content, `"utf8"` returns text,
+ * `"base64"` returns a base64 string, and `"binary"` returns the raw
+ * `Buffer`. `"auto"` picks `json` for `.json`, `utf8` for known text
+ * extensions, and `binary` otherwise.
+ */
+class AssetObjectLoader extends ObjectLoader_js_1.ObjectLoader {
+    constructor(options = {}) {
+        super({ ...options, family: "asset" });
+    }
+    async loadAsset(source, options = {}) {
+        const path = this.toFilePath(source);
+        const name = (0, node_path_1.basename)(path);
+        const extension = (0, node_path_1.extname)(path).toLowerCase();
+        const encoding = this.resolveEncoding(extension, options.encoding ?? "auto");
+        const buffer = await (0, promises_1.readFile)(path);
+        const content = this.decode(buffer, encoding);
+        const asset = {
+            source: this.normalizeSource(source),
+            path,
+            name,
+            extension,
+            encoding,
+            contentType: contentTypeFor(extension),
+            content,
+        };
+        const context = this.createContext(asset.source, name, {}, "afterResolve", {
+            ...this.metadata,
+            ...(options.metadata ?? {}),
+            encoding,
+            contentType: asset.contentType,
+        });
+        return this.runHooks(asset, context, options);
+    }
+    async loadText(source, options = {}) {
+        const asset = await this.loadAsset(source, {
+            ...options,
+            encoding: options.encoding && options.encoding !== "auto"
+                ? options.encoding
+                : "utf8",
+        });
+        return asset.content;
+    }
+    async loadJson(source, options = {}) {
+        const asset = await this.loadAsset(source, {
+            ...options,
+            encoding: "json",
+        });
+        return asset.content;
+    }
+    async loadBinary(source, options = {}) {
+        const asset = await this.loadAsset(source, {
+            ...options,
+            encoding: "binary",
+        });
+        return asset.content;
+    }
+    resolveEncoding(extension, requested) {
+        if (requested !== "auto")
+            return requested;
+        if (extension === ".json")
+            return "json";
+        if (TEXT_EXTENSIONS.has(extension))
+            return "utf8";
+        if (IMAGE_EXTENSIONS.has(extension))
+            return "binary";
+        return "binary";
+    }
+    decode(buffer, encoding) {
+        switch (encoding) {
+            case "json":
+                return JSON.parse(buffer.toString("utf8"));
+            case "base64":
+                return buffer.toString("base64");
+            case "binary":
+                return buffer;
+            case "utf8":
+            default:
+                return buffer.toString("utf8");
+        }
+    }
+    toFilePath(source) {
+        if (source instanceof URL) {
+            if (source.protocol !== "file:") {
+                throw new core_1.UnsupportedError(`AssetObjectLoader only supports local file sources, received "${source.href}".`);
+            }
+            return (0, node_url_1.fileURLToPath)(source);
+        }
+        if (source.startsWith("file:")) {
+            return (0, node_url_1.fileURLToPath)(source);
+        }
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(source)) {
+            throw new core_1.UnsupportedError(`AssetObjectLoader only supports local file sources, received "${source}".`);
+        }
+        return (0, node_path_1.isAbsolute)(source) ? source : (0, node_path_1.resolve)(source);
+    }
+}
+exports.AssetObjectLoader = AssetObjectLoader;
+//# sourceMappingURL=assets.js.map
+//# sourceMappingURL=assets.cjs.map

package/lib/cjs/loader/assets.cjs.map

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