@noy-db/as-xlsx 0.2.0-pre.30 → 0.2.0-pre.31

package/dist/index.d.cts

@@ -1,538 +0,0 @@
-import { DictEntry, VaultDiff, Vault } from '@noy-db/hub';
-
-/**
- * Minimal zero-dependency XLSX writer.
- *
- * An `.xlsx` file is a ZIP archive (Office Open XML / OOXML) with
- * SpreadsheetML inside. This writer emits the six parts needed for
- * a valid worksheet and hands them to `@noy-db/as-zip`'s
- * `writeZip()` to assemble the final `.xlsx` bytes.
- *
- * ## Emitted parts
- *
- * ```
- * [Content_Types].xml            # MIME descriptors
- * _rels/.rels                    # root → workbook pointer
- * xl/workbook.xml                # sheet list
- * xl/_rels/workbook.xml.rels     # sheet-part pointers
- * xl/worksheets/sheet<N>.xml     # cell data
- * xl/sharedStrings.xml           # string pool (Unicode-safe)
- * ```
- *
- * Strings route through the shared-string table (`sharedStrings.xml`)
- * rather than being inlined on cells, which is:
- *
- *   1. Slightly more compact when strings repeat (client names,
- *      status labels, locale codes).
- *   2. Consistent with how Excel writes its own files — some
- *      strict-OOXML readers refuse inline strings.
- *
- * Numbers, booleans, and dates are written as typed cells; strings
- * and everything else fall back to the shared-string path.
- *
- * ## Not supported
- *
- * - Cell styles (fonts, colours, borders, number formats).
- * - Formulas, merged cells, frozen panes, auto-filter.
- * - Charts, images, drawings.
- * - Zip64 / archives > 4 GiB.
- *
- * @module
- */
-/**
- * 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 {
-    /** Sheet tab name — Excel caps at 31 chars; we truncate with `…`. */
-    readonly name: string;
-    /** Header row, rendered as row 1. Omit to skip the header. */
-    readonly header?: readonly string[];
-    /** Data rows — each is an array aligned with `header` if present. */
-    readonly rows: readonly XlsxRow[];
-    /**
-     * Optional per-column widths in Excel character units (same scale as
-     * SheetJS's `wch`). When set, emits a `<cols>` block so Excel opens
-     * the file with the columns sized as specified instead of the default
-     * 10-character width. Index aligned with `header` / row cells.
-     *
-     * Non-finite or non-positive entries are skipped (column falls back
-     * to Excel's default width). A consumer typically passes `undefined`
-     * 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[], 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.
- */
-declare function colLetter(n: number): string;
-
-/**
- * Minimal OOXML reader. Inverse of `writeXlsx` in `xlsx.ts`.
- *
- * Walks the three parts the writer emits:
- *
- *   - `xl/sharedStrings.xml`       → string table (idx → string)
- *   - `xl/workbook.xml`            → sheet name list (with sheetId)
- *   - `xl/_rels/workbook.xml.rels` → sheetId → sheet part path
- *   - `xl/worksheets/sheet<N>.xml` → cell data
- *
- * Cell types matched to the writer's emission rules:
- *   - no `t` attribute → number (`<v>` is parsed as Number)
- *   - `t="s"`         → shared-string ref
- *   - `t="b"`         → boolean (`1` ↔ true, `0` ↔ false)
- *   - empty `<c />`   → undefined
- *
- * Excel date serials are NOT auto-converted — the writer outputs ISO-
- * 8601 strings via the shared-string path, so dates round-trip as
- * strings unless the consumer opts into `dateFields` coercion (handled
- * one layer up in `index.ts:fromBytes`).
- *
- * @module
- */
-/** A row of cell values keyed by column letter (`'A' → 'foo'`). */
-type ReadXlsxRow = Record<string, unknown>;
-interface ReadXlsxSheet {
-    /** Sheet tab name from `xl/workbook.xml`. */
-    readonly name: string;
-    /** All rows in declaration order. Columns indexed by Excel letter. */
-    readonly rows: readonly ReadXlsxRow[];
-}
-interface ReadXlsxResult {
-    readonly sheets: readonly ReadXlsxSheet[];
-}
-/**
- * Decode an `.xlsx` (OOXML) byte stream into per-sheet row data. The
- * caller decides what to do with the rows (header inference, type
- * coercion, record building) — the reader stays format-only.
- *
- * Throws on malformed XML, missing parts, or sheet-id mismatches.
- */
-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.
- *
- * Produces a real `.xlsx` file (Office Open XML / OOXML) from one
- * or more noy-db collections. Opens natively in Excel, Numbers,
- * LibreOffice Calc, Google Sheets, and every modern spreadsheet
- * tool.
- *
- * Zero runtime dependencies — the XLSX encoder builds the required
- * SpreadsheetML parts and assembles them with
- * `@noy-db/as-zip`'s `writeZip()` (STORE method; most xlsx
- * contents are XML text which Excel compresses at open time anyway).
- *
- * Part of the `@noy-db/as-*` portable-artefact family, plaintext
- * tier. See [`docs/patterns/as-exports.md`](https://github.com/vLannaAi/noy-db/blob/main/docs/patterns/as-exports.md).
- *
- * ## Authorisation
- *
- * Every call is gated by `assertCanExport('plaintext', 'xlsx')`.
- *
- * ```ts
- * await db.grant('firm', {
- *   userId: 'accountant', role: 'viewer', passphrase: '…',
- *   exportCapability: { plaintext: ['xlsx'] },
- * })
- * ```
- *
- * @packageDocumentation
- */
-
-/** Per-sheet options for the noy-db consumer API. */
-interface AsXlsxSheetOptions {
-    /**
-     * Sheet tab name. Excel caps at 31 chars; longer names are
-     * truncated with `…`. Duplicates are suffixed `(2)`, `(3)`.
-     */
-    readonly name: string;
-    /** Source collection. Must be in the caller's read ACL. */
-    readonly collection: string;
-    /**
-     * Field list + order. When omitted, columns are inferred from
-     * the union of keys across all records (first-record-wins order).
-     */
-    readonly columns?: readonly string[];
-    /**
-     * Optional predicate against each decrypted record. Runs after
-     * decryption; doesn't reduce I/O.
-     */
-    readonly filter?: (record: unknown) => boolean;
-    /**
-     * Optional per-column character widths (Excel `wch` units). When set,
-     * the emitted sheet opens with the requested column widths instead of
-     * Excel's default 10-character fallback. Index aligned with
-     * `columns` / inferred-column order.
-     *
-     * Non-finite or non-positive entries are skipped so consumers can
-     * mix explicit + auto (pass `undefined` for "auto").
-     *
-     * Length is NOT validated against `columns.length` — extra entries
-     * are harmless (no `<col>` is emitted past the column count) and a
-     * short array leaves trailing columns at Excel's default. This
-     * 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 {
-    /** Filename offered to the browser. Default `'export.xlsx'`. */
-    readonly filename?: string;
-}
-/** Options for `write()` — requires explicit risk acknowledgement. */
-interface AsXlsxWriteOptions extends AsXlsxOptions {
-    /** Tier 3 egress — see `docs/patterns/as-exports.md`. */
-    readonly acknowledgeRisks: true;
-}
-/**
- * Convenience — single-collection shorthand. Equivalent to
- * `toBytes(vault, { sheets: [{ name: collectionName, collection: collectionName }] })`.
- */
-declare function toBytesFromCollection(vault: Vault, collectionName: string): Promise<Uint8Array>;
-/**
- * Build the `.xlsx` byte stream from one or more sheets. Pure
- * beyond the auth check + store reads.
- */
-declare function toBytes(vault: Vault, options: AsXlsxOptions): Promise<Uint8Array>;
-/**
- * Browser download. Requires a browser-like environment with
- * `URL.createObjectURL` + `document.createElement`.
- */
-declare function download(vault: Vault, options: AsXlsxDownloadOptions): Promise<void>;
-/**
- * Node file-write. Requires `acknowledgeRisks: true` because the
- * 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';
-/**
- * Thrown when a dict field contains two different keys whose labels are
- * identical in any locale — making label→key inversion ambiguous.
- *
- * @example
- *   dict has: { key: 'a', labels: { en: 'Open' } } and { key: 'b', labels: { th: 'Open' } }
- *   → XlsxDictAmbiguityError('status', 'Open')
- */
-declare class XlsxDictAmbiguityError extends Error {
-    readonly column: string;
-    readonly label: string;
-    constructor(column: string, label: string);
-}
-interface AsXlsxImportOptions {
-    /** Target collection. xlsx has no native collection grouping. */
-    readonly collection: string;
-    /**
-     * Sheet name to read. Defaults to the first sheet in the workbook.
-     */
-    readonly sheet?: string;
-    /**
-     * 1-based header row index. Default `1` (first row).
-     */
-    readonly headerRow?: number;
-    /**
-     * Optional field type hints. xlsx cells already have a type
-     * (number, boolean, shared-string), so this is for the few cases
-     * where the writer's emission rules don't preserve intent —
-     * notably ISO-date strings the writer routed through the shared-
-     * string path. `'date'` parses the value with `new Date()` and
-     * keeps the result as an ISO-8601 string for stable round-tripping.
-     */
-    readonly fieldTypes?: Record<string, 'string' | 'number' | 'boolean' | 'date'>;
-    /** Field carrying the record id. Default `'id'`. */
-    readonly idKey?: string;
-    /** Reconciliation policy. Default `'merge'`. */
-    readonly policy?: ImportPolicy;
-    /**
-     * Per-field dict definitions for label→key inversion. When a column
-     * header matches a key here, cell values are matched against every
-     * locale label in the dict entries; matching labels are replaced by
-     * their stable key before building the ImportPlan.
-     *
-     * Takes precedence over any vault dictionary with the same name.
-     * For fields not listed here, `fromBytes` automatically tries
-     * `vault.dictionary(fieldName).list()` as a fallback.
-     *
-     * 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;
-    readonly policy: ImportPolicy;
-    apply(): Promise<void>;
-}
-/**
- * Build an import plan from an `.xlsx` byte stream. Inverts what
- * `toBytes()` writes — the first row is the header, subsequent rows
- * are records keyed by the column letters in the header row.
- *
- * Capability: `assertCanImport('plaintext', 'xlsx')`.
- * Atomicity: `apply()` runs inside `vault.noydb.transaction()`.
- *
- * **Not supported (matches the writer scope):**
- * - Cell styles / number formats / date format codes
- * - Formulas, merged cells, frozen panes
- * - Inline strings → handled defensively (since some upstream tools
- *   emit them) but the writer never produces them
- * - Excel date serials → not auto-detected; pass `fieldTypes: { ts:
- *   'date' }` to coerce a numeric serial to ISO. Date round-trip via
- *   the writer (which emits ISO strings) works without a hint.
- *
- * **Dict-label inversion** — supply `dicts` per field (or populate vault
- * dictionaries with `withI18n()`) and the reader automatically inverts
- * human labels back to their stable keys. Ambiguous labels throw
- * `XlsxDictAmbiguityError`; unknown labels pass through unchanged.
- */
-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 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 };