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

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,84 @@ 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>;
+}
+/** 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 {
@@ -267,6 +403,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 +441,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 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 };