@noy-db/as-xlsx 0.2.0-pre.23 → 0.2.0-pre.24

package/dist/index.d.cts

@@ -268,6 +268,45 @@ interface AsXlsxSheetOptions {
      * global LANG cell via `VLOOKUP(code, …, MATCH(LANG, …))`.
      */
     readonly dictFields?: Record<string, string>;
+    /**
+     * Multi-vault export only: pull FK-referenced fields from a supporting vault
+     * into this sheet as extra columns. Each entry resolves `localField` on the
+     * primary record against the `keyField` of another vault's collection (matched
+     * by `from.label`/`from.collection`), and emits the `pick` field value as
+     * `column`. Appended AFTER the declared `columns` in declaration order.
+     * Unresolved FK (row not in the supporting-vault index) → empty cell.
+     * Ignored by single-vault `toBytes`.
+     */
+    readonly denormalize?: readonly MultiVaultDenormColumn[];
+}
+/**
+ * One denormalized column in a multi-vault export: pulls a field from a
+ * supporting vault into the primary sheet via an in-memory join.
+ *
+ * @example
+ * ```ts
+ * {
+ *   column: 'entityName',   // new column header in the primary sheet
+ *   localField: 'entityId', // FK field on the primary record
+ *   from: { label: 'directory', collection: 'entities', keyField: 'id', pick: 'name' },
+ * }
+ * ```
+ */
+interface MultiVaultDenormColumn {
+    /** Header of the new column to append to the primary sheet. */
+    readonly column: string;
+    /** Field on the primary record whose value is the FK. */
+    readonly localField: string;
+    readonly from: {
+        /** Label of the supporting vault entry (matches `MultiVaultXlsxEntry.label`). */
+        readonly label: string;
+        /** Collection in the supporting vault. */
+        readonly collection: string;
+        /** Field in the supporting record that is the join key (usually `'id'`). */
+        readonly keyField: string;
+        /** Field in the supporting record to copy as the denorm value. */
+        readonly pick: string;
+    };
 }
 /** One aggregate column in a smart-mode summary sheet (#414 P3). */
 interface AsXlsxSummaryAggregate {
@@ -351,6 +390,61 @@ declare function download(vault: Vault, options: AsXlsxDownloadOptions): Promise
  * plaintext xlsx persists past the process (Tier 3 egress).
  */
 declare function write(vault: Vault, path: string, options: AsXlsxWriteOptions): Promise<void>;
+/**
+ * One vault entry in a multi-vault export. Supplies the pre-opened
+ * vault, the sheet specs to render for it, and an optional closure
+ * (per-collection id allowlist computed externally by the orchestrator).
+ */
+interface MultiVaultXlsxEntry {
+    readonly vault: Vault;
+    readonly sheets: readonly AsXlsxSheetOptions[];
+    /**
+     * Optional per-collection id allowlist (e.g. from walkCrossVaultClosure).
+     * When set, only rows whose `id` appears in the set are exported for that
+     * collection. Omit to export all rows.
+     */
+    readonly closure?: ReadonlyMap<string, ReadonlySet<string>>;
+    /**
+     * Optional display label for sheet-name prefixing.
+     * Defaults to `vault.name`.
+     */
+    readonly label?: string;
+}
+/** Options for {@link toBytesMultiVault}. */
+interface MultiVaultXlsxOptions {
+    /**
+     * Separator inserted between the vault label and the sheet name when
+     * building tab names. Default `'_'`. Names are then truncated to 31 chars
+     * (Excel limit) by `writeXlsx`.
+     */
+    readonly sheetSeparator?: string;
+}
+/**
+ * Build an `.xlsx` byte stream spanning **multiple vaults**. Each entry
+ * supplies a pre-opened vault with its sheet specs and an optional
+ * per-collection id-closure (rows filtered to exactly those ids). A
+ * `_manifest` sheet is prepended that lists every vault-collection pair
+ * and its exported record count.
+ *
+ * ## Auth
+ * Every vault in `entries` must independently hold `assertCanExport('plaintext','xlsx')`.
+ * The check fires fail-fast before any rows are materialised.
+ *
+ * ## Architecture
+ * This function is **edge-pure** — it takes pre-opened vaults and a
+ * pre-computed closure; it performs no cross-vault FK walk itself.
+ * Cross-vault orchestration lives in `@klum-db/lobby` (allowed direction).
+ *
+ * ## Two-pass execution (when `denormalize` is declared)
+ * **Pass 1** — load and closure-filter ALL entries' rows, building a
+ * `Map<"${label}/${collection}", Map<keyValue, row>>` index keyed by each
+ * sheet's `keyField` (default `'id'`). Only closure-filtered rows are indexed,
+ * so an FK pointing outside the closure yields an empty cell (correct: that
+ * row was not referenced / not exported).
+ * **Pass 2** — emit each sheet; for sheets with `denormalize`, append each
+ * denorm column AFTER the declared columns by resolving the index lookup.
+ */
+declare function toBytesMultiVault(entries: readonly MultiVaultXlsxEntry[], options?: MultiVaultXlsxOptions): Promise<Uint8Array>;
 
 type ImportPolicy = 'merge' | 'replace' | 'insert-only';
 /**
@@ -441,4 +535,4 @@ interface AsXlsxImportPlan {
  */
 declare function fromBytes(vault: Vault, bytes: Uint8Array, options: AsXlsxImportOptions): Promise<AsXlsxImportPlan>;
 
-export { type AsXlsxDownloadOptions, type AsXlsxImportOptions, type AsXlsxImportPlan, type AsXlsxOptions, type AsXlsxSheetOptions, type AsXlsxSummaryAggregate, type AsXlsxSummarySpec, type AsXlsxWriteOptions, type ImportPolicy, type InferredCollection, type InferredField, type InferredSchema, type InferredType, type ReadXlsxResult, type ReadXlsxRow, type ReadXlsxSheet, XlsxDictAmbiguityError, type XlsxFormulaCell, type XlsxRow, type XlsxSheet, type XlsxStyledCell, type XlsxValidation, colLetter, download, formula, fromBytes, inferSchema, readXlsx, styled, toBytes, toBytesFromCollection, write, writeXlsx, zodSourceFor };
+export { type AsXlsxDownloadOptions, type AsXlsxImportOptions, type AsXlsxImportPlan, type AsXlsxOptions, type AsXlsxSheetOptions, type AsXlsxSummaryAggregate, type AsXlsxSummarySpec, type AsXlsxWriteOptions, type ImportPolicy, type InferredCollection, type InferredField, type InferredSchema, type InferredType, type MultiVaultDenormColumn, type MultiVaultXlsxEntry, type MultiVaultXlsxOptions, type ReadXlsxResult, type ReadXlsxRow, type ReadXlsxSheet, XlsxDictAmbiguityError, type XlsxFormulaCell, type XlsxRow, type XlsxSheet, type XlsxStyledCell, type XlsxValidation, colLetter, download, formula, fromBytes, inferSchema, readXlsx, styled, toBytes, toBytesFromCollection, toBytesMultiVault, write, writeXlsx, zodSourceFor };

package/dist/index.d.ts

@@ -268,6 +268,45 @@ interface AsXlsxSheetOptions {
      * global LANG cell via `VLOOKUP(code, …, MATCH(LANG, …))`.
      */
     readonly dictFields?: Record<string, string>;
+    /**
+     * Multi-vault export only: pull FK-referenced fields from a supporting vault
+     * into this sheet as extra columns. Each entry resolves `localField` on the
+     * primary record against the `keyField` of another vault's collection (matched
+     * by `from.label`/`from.collection`), and emits the `pick` field value as
+     * `column`. Appended AFTER the declared `columns` in declaration order.
+     * Unresolved FK (row not in the supporting-vault index) → empty cell.
+     * Ignored by single-vault `toBytes`.
+     */
+    readonly denormalize?: readonly MultiVaultDenormColumn[];
+}
+/**
+ * One denormalized column in a multi-vault export: pulls a field from a
+ * supporting vault into the primary sheet via an in-memory join.
+ *
+ * @example
+ * ```ts
+ * {
+ *   column: 'entityName',   // new column header in the primary sheet
+ *   localField: 'entityId', // FK field on the primary record
+ *   from: { label: 'directory', collection: 'entities', keyField: 'id', pick: 'name' },
+ * }
+ * ```
+ */
+interface MultiVaultDenormColumn {
+    /** Header of the new column to append to the primary sheet. */
+    readonly column: string;
+    /** Field on the primary record whose value is the FK. */
+    readonly localField: string;
+    readonly from: {
+        /** Label of the supporting vault entry (matches `MultiVaultXlsxEntry.label`). */
+        readonly label: string;
+        /** Collection in the supporting vault. */
+        readonly collection: string;
+        /** Field in the supporting record that is the join key (usually `'id'`). */
+        readonly keyField: string;
+        /** Field in the supporting record to copy as the denorm value. */
+        readonly pick: string;
+    };
 }
 /** One aggregate column in a smart-mode summary sheet (#414 P3). */
 interface AsXlsxSummaryAggregate {
@@ -351,6 +390,61 @@ declare function download(vault: Vault, options: AsXlsxDownloadOptions): Promise
  * plaintext xlsx persists past the process (Tier 3 egress).
  */
 declare function write(vault: Vault, path: string, options: AsXlsxWriteOptions): Promise<void>;
+/**
+ * One vault entry in a multi-vault export. Supplies the pre-opened
+ * vault, the sheet specs to render for it, and an optional closure
+ * (per-collection id allowlist computed externally by the orchestrator).
+ */
+interface MultiVaultXlsxEntry {
+    readonly vault: Vault;
+    readonly sheets: readonly AsXlsxSheetOptions[];
+    /**
+     * Optional per-collection id allowlist (e.g. from walkCrossVaultClosure).
+     * When set, only rows whose `id` appears in the set are exported for that
+     * collection. Omit to export all rows.
+     */
+    readonly closure?: ReadonlyMap<string, ReadonlySet<string>>;
+    /**
+     * Optional display label for sheet-name prefixing.
+     * Defaults to `vault.name`.
+     */
+    readonly label?: string;
+}
+/** Options for {@link toBytesMultiVault}. */
+interface MultiVaultXlsxOptions {
+    /**
+     * Separator inserted between the vault label and the sheet name when
+     * building tab names. Default `'_'`. Names are then truncated to 31 chars
+     * (Excel limit) by `writeXlsx`.
+     */
+    readonly sheetSeparator?: string;
+}
+/**
+ * Build an `.xlsx` byte stream spanning **multiple vaults**. Each entry
+ * supplies a pre-opened vault with its sheet specs and an optional
+ * per-collection id-closure (rows filtered to exactly those ids). A
+ * `_manifest` sheet is prepended that lists every vault-collection pair
+ * and its exported record count.
+ *
+ * ## Auth
+ * Every vault in `entries` must independently hold `assertCanExport('plaintext','xlsx')`.
+ * The check fires fail-fast before any rows are materialised.
+ *
+ * ## Architecture
+ * This function is **edge-pure** — it takes pre-opened vaults and a
+ * pre-computed closure; it performs no cross-vault FK walk itself.
+ * Cross-vault orchestration lives in `@klum-db/lobby` (allowed direction).
+ *
+ * ## Two-pass execution (when `denormalize` is declared)
+ * **Pass 1** — load and closure-filter ALL entries' rows, building a
+ * `Map<"${label}/${collection}", Map<keyValue, row>>` index keyed by each
+ * sheet's `keyField` (default `'id'`). Only closure-filtered rows are indexed,
+ * so an FK pointing outside the closure yields an empty cell (correct: that
+ * row was not referenced / not exported).
+ * **Pass 2** — emit each sheet; for sheets with `denormalize`, append each
+ * denorm column AFTER the declared columns by resolving the index lookup.
+ */
+declare function toBytesMultiVault(entries: readonly MultiVaultXlsxEntry[], options?: MultiVaultXlsxOptions): Promise<Uint8Array>;
 
 type ImportPolicy = 'merge' | 'replace' | 'insert-only';
 /**
@@ -441,4 +535,4 @@ interface AsXlsxImportPlan {
  */
 declare function fromBytes(vault: Vault, bytes: Uint8Array, options: AsXlsxImportOptions): Promise<AsXlsxImportPlan>;
 
-export { type AsXlsxDownloadOptions, type AsXlsxImportOptions, type AsXlsxImportPlan, type AsXlsxOptions, type AsXlsxSheetOptions, type AsXlsxSummaryAggregate, type AsXlsxSummarySpec, type AsXlsxWriteOptions, type ImportPolicy, type InferredCollection, type InferredField, type InferredSchema, type InferredType, type ReadXlsxResult, type ReadXlsxRow, type ReadXlsxSheet, XlsxDictAmbiguityError, type XlsxFormulaCell, type XlsxRow, type XlsxSheet, type XlsxStyledCell, type XlsxValidation, colLetter, download, formula, fromBytes, inferSchema, readXlsx, styled, toBytes, toBytesFromCollection, write, writeXlsx, zodSourceFor };
+export { type AsXlsxDownloadOptions, type AsXlsxImportOptions, type AsXlsxImportPlan, type AsXlsxOptions, type AsXlsxSheetOptions, type AsXlsxSummaryAggregate, type AsXlsxSummarySpec, type AsXlsxWriteOptions, type ImportPolicy, type InferredCollection, type InferredField, type InferredSchema, type InferredType, type MultiVaultDenormColumn, type MultiVaultXlsxEntry, type MultiVaultXlsxOptions, type ReadXlsxResult, type ReadXlsxRow, type ReadXlsxSheet, XlsxDictAmbiguityError, type XlsxFormulaCell, type XlsxRow, type XlsxSheet, type XlsxStyledCell, type XlsxValidation, colLetter, download, formula, fromBytes, inferSchema, readXlsx, styled, toBytes, toBytesFromCollection, toBytesMultiVault, write, writeXlsx, zodSourceFor };

package/dist/index.js

@@ -564,6 +564,95 @@ async function write(vault, path, options) {
   const { writeFile } = await import("fs/promises");
   await writeFile(path, bytes);
 }
+async function toBytesMultiVault(entries, options = {}) {
+  const sep = options.sheetSeparator ?? "_";
+  for (const entry of entries) {
+    entry.vault.assertCanExport("plaintext", "xlsx");
+  }
+  const loaded = [];
+  const denormIndex = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const prefix = entry.label ?? entry.vault.name;
+    for (const s of entry.sheets) {
+      const all = await entry.vault.collection(s.collection).list();
+      const records = [];
+      for (const item of all) {
+        const r = item;
+        const allow = entry.closure?.get(s.collection);
+        if (allow && !allow.has(String(r.id))) continue;
+        if (s.filter && !s.filter(r)) continue;
+        records.push(r);
+      }
+      loaded.push({ entry, prefix, sheetOpt: s, records });
+      const indexKey = `${prefix}/${s.collection}`;
+      const collectionIndex = denormIndex.get(indexKey) ?? /* @__PURE__ */ new Map();
+      denormIndex.set(indexKey, collectionIndex);
+      for (const r of records) {
+        const idVal = r.id;
+        if (idVal != null) collectionIndex.set(safeStringify(idVal), r);
+      }
+    }
+  }
+  for (const ls of loaded) {
+    for (const d of ls.sheetOpt.denormalize ?? []) {
+      if (d.from.keyField === "id") continue;
+      const indexKey = `${d.from.label}/${d.from.collection}`;
+      const idx = denormIndex.get(indexKey);
+      if (!idx) continue;
+      const srcLoaded = loaded.find(
+        (l) => l.prefix === d.from.label && l.sheetOpt.collection === d.from.collection
+      );
+      if (!srcLoaded) continue;
+      for (const r of srcLoaded.records) {
+        const kv = r[d.from.keyField];
+        if (kv != null) idx.set(safeStringify(kv), r);
+      }
+    }
+  }
+  const allSheets = [];
+  const manifestRows = [];
+  for (const { prefix, sheetOpt: s, records } of loaded) {
+    const baseColumns = s.columns ?? inferColumns(records);
+    const denormDefs = s.denormalize ?? [];
+    if (denormDefs.length === 0) {
+      const sheetName2 = `${prefix}${sep}${s.name}`;
+      allSheets.push(buildFlatSheet(sheetName2, baseColumns, records));
+      manifestRows.push([prefix, s.collection, records.length]);
+      continue;
+    }
+    const allColumns = [...baseColumns, ...denormDefs.map((d) => d.column)];
+    const sheetName = `${prefix}${sep}${s.name}`;
+    const rows = records.map((r) => {
+      const baseCells = baseColumns.map((c) => r[c] ?? null);
+      const denormCells = denormDefs.map((d) => {
+        const idxKey = `${d.from.label}/${d.from.collection}`;
+        const idx = denormIndex.get(idxKey);
+        if (!idx) return "";
+        const fkVal = r[d.localField];
+        if (fkVal == null) return "";
+        const supporting = idx.get(safeStringify(fkVal));
+        if (!supporting) return "";
+        return supporting[d.from.pick] ?? "";
+      });
+      return [...baseCells, ...denormCells];
+    });
+    allSheets.push({ name: sheetName, header: allColumns, rows });
+    manifestRows.push([prefix, s.collection, records.length]);
+  }
+  allSheets.unshift({
+    name: "_manifest",
+    header: ["Vault", "Collection", "Records"],
+    rows: manifestRows
+  });
+  return writeXlsx(allSheets);
+}
+function buildFlatSheet(name, columns, records) {
+  return {
+    name,
+    header: [...columns],
+    rows: records.map((r) => columns.map((c) => r[c] ?? null))
+  };
+}
 function safeStringify(v) {
   if (typeof v === "string") return v;
   if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
@@ -1023,6 +1112,7 @@ export {
   styled,
   toBytes,
   toBytesFromCollection,
+  toBytesMultiVault,
   write,
   writeXlsx,
   zodSourceFor