@noy-db/as-xlsx 0.2.0-pre.8 → 0.3.0-pre.1

package/dist/index.d.ts

@@ -39,7 +39,39 @@ import { DictEntry, VaultDiff, Vault } from '@noy-db/hub';
  *
  * @module
  */
-/** One row in a sheet. Values are coerced per type at emit time. */
+/**
+ * A formula cell. Emits `<f>` so the spreadsheet recomputes live; `v` is an
+ * optional cached result (what the formula currently evaluates to) so the value
+ * shows immediately on open and survives a round-trip read. Build via
+ * {@link formula}. The formula string must NOT include a leading `=`.
+ */
+interface XlsxFormulaCell {
+    readonly __xlsxFormula: string;
+    readonly v?: string | number | boolean;
+}
+/** Build a {@link XlsxFormulaCell}. `f` is the formula body without a leading `=`. */
+declare function formula(f: string, cachedValue?: string | number | boolean): XlsxFormulaCell;
+/**
+ * A value cell carrying a number-format code (e.g. `'#,##0.00'` for currency,
+ * `'yyyy-mm-dd'` for dates). Build via {@link styled}. The format only renders
+ * meaningfully on numeric values.
+ */
+interface XlsxStyledCell {
+    readonly __xlsxStyle: string;
+    readonly v: string | number | boolean | null;
+}
+/** Build a {@link XlsxStyledCell} — a value plus an Excel number-format code. */
+declare function styled(value: string | number | boolean | null, numberFormat: string): XlsxStyledCell;
+/** A data-validation rule (dropdown) over a cell range. */
+interface XlsxValidation {
+    /** Target range in A1 notation, e.g. `'B2:B100'`. */
+    readonly sqref: string;
+    /** Inline allowed values → a `"a,b,c"` list. Mutually exclusive with `formula1`. */
+    readonly values?: readonly string[];
+    /** Explicit `formula1` (e.g. a range ref `Clients!$A$2:$A$999`). */
+    readonly formula1?: string;
+}
+/** One row in a sheet. A cell is a primitive value or an {@link XlsxFormulaCell}. */
 type XlsxRow = ReadonlyArray<unknown>;
 /** One sheet in a workbook. */
 interface XlsxSheet {
@@ -60,12 +92,19 @@ interface XlsxSheet {
      * for "auto" columns and a number for explicit widths.
      */
     readonly widths?: ReadonlyArray<number | undefined>;
+    /** Data-validation dropdowns applied to ranges on this sheet. */
+    readonly validations?: readonly XlsxValidation[];
 }
 /**
  * Build a complete `.xlsx` byte stream from the supplied sheet data.
  * Pure — no I/O beyond the internal zip concatenation.
  */
-declare function writeXlsx(sheets: readonly XlsxSheet[]): Promise<Uint8Array>;
+declare function writeXlsx(sheets: readonly XlsxSheet[], options?: {
+    definedNames?: ReadonlyArray<{
+        readonly name: string;
+        readonly ref: string;
+    }>;
+}): Promise<Uint8Array>;
 /**
  * Convert a 1-based column index to Excel A1 letter notation.
  * 1 → A, 26 → Z, 27 → AA, 702 → ZZ, 703 → AAA.
@@ -115,6 +154,30 @@ interface ReadXlsxResult {
  */
 declare function readXlsx(bytes: Uint8Array): Promise<ReadXlsxResult>;
 
+type InferredType = 'string' | 'number' | 'boolean' | 'date';
+interface InferredField {
+    readonly type: InferredType;
+    /** Target collection (sheet) name when this field looks like a foreign key. */
+    readonly references?: string;
+}
+interface InferredCollection {
+    readonly idField: string;
+    readonly fields: Record<string, InferredField>;
+}
+interface InferredSchema {
+    readonly collections: Record<string, InferredCollection>;
+}
+/**
+ * Infer a {@link InferredSchema} from an `.xlsx` byte stream. Sheets whose name
+ * starts with `_` (our smart-export meta sheets) are skipped; pass `skipSheets`
+ * to exclude more (e.g. summary sheets).
+ */
+declare function inferSchema(bytes: Uint8Array, options?: {
+    skipSheets?: readonly string[];
+}): Promise<InferredSchema>;
+/** Emit a Zod schema snippet (guidance) from an {@link InferredSchema}. */
+declare function zodSourceFor(schema: InferredSchema): string;
+
 /**
  * **@noy-db/as-xlsx** — Excel spreadsheet plaintext export for noy-db.
  *
@@ -179,11 +242,123 @@ interface AsXlsxSheetOptions {
      * mirrors `XlsxSheet.widths`, which it threads through.
      */
     readonly widths?: ReadonlyArray<number | undefined>;
+    /**
+     * Smart mode only: per-field Excel number-format codes (e.g.
+     * `{ amount: '#,##0.00' }` for currency). The value is coerced to a number so
+     * the format renders. Money has no introspection signal, so currency
+     * formatting is opt-in here.
+     */
+    readonly numberFormats?: Record<string, string>;
+    /**
+     * Smart mode only: per-field explicit dropdown value lists. Overrides the
+     * auto-detected enum/ref dropdown for that field.
+     */
+    readonly dropdowns?: Record<string, readonly string[]>;
+    /**
+     * Smart mode only: fields whose stored value is a multi-locale i18n map
+     * (`{ en: '…', th: '…' }`). Each becomes per-locale columns plus a display
+     * column resolved **live by the global LANG cell** (change LANG → every label
+     * re-renders). Read raw, so open the export vault without an active locale.
+     */
+    readonly i18nFields?: readonly string[];
+    /**
+     * Smart mode only: map a dict-backed (code) field to its dictionary name, e.g.
+     * `{ status: 'status' }`. Emits a hidden `_Lookups_<dict>` sheet (code +
+     * per-locale labels) and a `<field>__label` display column resolved by the
+     * 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 {
+    /** Column header for this aggregate. */
+    readonly label: string;
+    readonly op: 'sum' | 'count' | 'avg';
+    /** Field to aggregate — required for `sum`/`avg`, ignored for `count`. */
+    readonly field?: string;
+}
+/**
+ * A groupBy summary sheet (#414 P3): groups the source collection's sheet by
+ * `groupBy` and emits live SUMIFS/COUNTIFS/AVERAGEIFS columns (values cached at
+ * export). The source value columns must be numeric for the live formulas to
+ * compute (apply `numberFormats` to money fields).
+ */
+interface AsXlsxSummarySpec {
+    /** Summary sheet name. */
+    readonly name: string;
+    /** Source collection (must be exported as a sheet). */
+    readonly from: string;
+    /** Field to group by. */
+    readonly groupBy: string;
+    readonly aggregates: readonly AsXlsxSummaryAggregate[];
 }
 /** Single-collection convenience — passed where a sheet-list is accepted. */
 interface AsXlsxOptions {
     /** One or more sheets. At least one required. */
     readonly sheets: readonly AsXlsxSheetOptions[];
+    /** Smart mode only: groupBy summary sheets (live SUMIFS/COUNTIFS/AVERAGEIFS). */
+    readonly summaries?: readonly AsXlsxSummarySpec[];
+    /**
+     * Smart mode only: summary formula dialect. `'excel'` (default) emits
+     * cross-compatible per-row SUMIFS/COUNTIFS/AVERAGEIFS. `'sheets'` emits a
+     * single Google-Sheets `QUERY` formula per summary — **Sheets-only** (QUERY
+     * errors in Excel); use when the target is Google Sheets.
+     */
+    readonly dialect?: 'excel' | 'sheets';
+    /**
+     * Smart-workbook mode (#414). Emits a relational workbook instead of a flat
+     * dump:
+     *   - every sheet is **id-first** (record `id` in column A);
+     *   - each foreign-key field (auto-detected via `vault.dumpSchema()`) gets a
+     *     `<field>__label` column — a cross-sheet `VLOOKUP` that resolves the
+     *     reference to the target's first field, carrying a **cached** label so it
+     *     shows immediately and recomputes live on edit;
+     *   - a `_manifest` index sheet lists every collection, its row count, and
+     *     its refs.
+     *
+     * Requires unique sheet names ≤ 31 chars (so cross-sheet refs resolve) and an
+     * `id` field on records. Defaults to the existing flat export when omitted.
+     */
+    readonly smart?: boolean;
 }
 /** Options for `download()` — adds optional filename. */
 interface AsXlsxDownloadOptions extends AsXlsxOptions {
@@ -215,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 the outward orchestration layer (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';
 /**
@@ -267,6 +497,14 @@ interface AsXlsxImportOptions {
      * Unknown labels (no match in any locale) pass through as-is.
      */
     readonly dicts?: Readonly<Record<string, readonly DictEntry[]>>;
+    /**
+     * Read a sheet produced by smart export (#414 P4). Reverses the smart layout:
+     * reconstructs i18n fields from their per-locale columns (`<f>__<loc>` →
+     * `{ loc: value }`), and drops derived columns — the i18n display column and
+     * every `<f>__label` (FK/dict) formula column. Code columns (the real values)
+     * pass through. Maps onto the existing collection schema (Mode A).
+     */
+    readonly smart?: boolean;
 }
 interface AsXlsxImportPlan {
     readonly plan: VaultDiff;
@@ -297,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 AsXlsxWriteOptions, type ImportPolicy, type ReadXlsxResult, type ReadXlsxRow, type ReadXlsxSheet, XlsxDictAmbiguityError, type XlsxRow, type XlsxSheet, colLetter, download, fromBytes, readXlsx, toBytes, toBytesFromCollection, write, writeXlsx };
+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 };