@noy-db/as-xlsx 0.1.0-pre.3

package/dist/index.d.ts

@@ -0,0 +1,274 @@
+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
+ */
+/** One row in a sheet. Values are coerced per type at emit time. */
+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[];
+}
+/**
+ * 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>;
+/**
+ * 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>;
+
+/**
+ * **@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;
+}
+/** Single-collection convenience — passed where a sheet-list is accepted. */
+interface AsXlsxOptions {
+    /** One or more sheets. At least one required. */
+    readonly sheets: readonly AsXlsxSheetOptions[];
+}
+/** 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>;
+
+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[]>>;
+}
+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 AsXlsxWriteOptions, type ImportPolicy, type ReadXlsxResult, type ReadXlsxRow, type ReadXlsxSheet, XlsxDictAmbiguityError, type XlsxRow, type XlsxSheet, colLetter, download, fromBytes, readXlsx, toBytes, toBytesFromCollection, write, writeXlsx };