@happyvertical/spreadsheets 0.0.0-stage → 0.112.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENT.md ADDED
@@ -0,0 +1,43 @@
1
+ # @happyvertical/spreadsheets
2
+
3
+ <!-- BEGIN AGENT:GENERATED -->
4
+ ## Purpose
5
+ Bounded browser-safe XLSX and CSV adapters with structural workbook profiling
6
+
7
+ ## Package Map
8
+ - Package: `@happyvertical/spreadsheets`
9
+ - Hierarchy path: `@happyvertical/sdk > packages > spreadsheets`
10
+ - Workspace position: `29 of 34` local packages
11
+ - Internal dependencies: `@happyvertical/files`
12
+ - Internal dependents: none
13
+ - Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
14
+
15
+ ## Build & Test
16
+ ```bash
17
+ pnpm --filter @happyvertical/spreadsheets build
18
+ pnpm --filter @happyvertical/spreadsheets test
19
+ pnpm --filter @happyvertical/spreadsheets typecheck
20
+ pnpm --filter @happyvertical/spreadsheets lint
21
+ ```
22
+
23
+ ## Agent Correction Loops
24
+ - If module resolution or export errors mention a workspace dependency, build the dependency first (`pnpm --filter @happyvertical/files build`) and then rerun `pnpm --filter @happyvertical/spreadsheets build`.
25
+ - If you hit type-only regressions, run `pnpm --filter @happyvertical/spreadsheets typecheck` before rerunning the package build or tests to isolate the failing surface.
26
+ - If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
27
+
28
+ ## Ecosystem Relationships
29
+ - Provides: Bounded browser-safe XLSX and CSV adapters with structural workbook profiling
30
+ - Implements: none
31
+ - Requires: @happyvertical/files, fflate
32
+ - Stability: stable (Primary package surface is described as implemented and production-oriented.)
33
+ <!-- END AGENT:GENERATED -->
34
+
35
+
36
+ ## Bounded processing
37
+
38
+ Untrusted workbook processing uses operation-local formula caches and a single
39
+ name/table index per read/profile. Preserve limits on metadata counts, repeated
40
+ part references, formula depth/tokens/cache size and inner work. Profile budgets
41
+ must count inner iterations and text lengths, not only outer reference calls.
42
+ `hostile.test.ts` records wall-clock timings and asserts each adversarial case
43
+ finishes or throws `SpreadsheetError` with `LIMIT_EXCEEDED` within five seconds.
package/LICENSE ADDED
@@ -0,0 +1,7 @@
1
+ Copyright <2025> <Happy Vertical Corporation>
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
4
+
5
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
6
+
7
+ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,236 @@
1
- # Temporary Holding Version
1
+ # @happyvertical/spreadsheets
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Bounded, network-free XLSX and CSV adapters for Node and browsers. Read workbook
4
+ structure, retain formulas and cached values, export a workbook, and profile the
5
+ evidence in its cells. Formulas are never evaluated.
6
+
7
+ ```ts
8
+ import {
9
+ getSpreadsheets,
10
+ profileWorkbook,
11
+ createWorkbook,
12
+ createSheet,
13
+ parseFormula,
14
+ } from '@happyvertical/spreadsheets';
15
+
16
+ const xlsx = await getSpreadsheets({ type: 'xlsx', maxCells: 100_000 });
17
+ const workbook = await xlsx.read(bytes); // Uint8Array or ArrayBuffer
18
+ const profile = profileWorkbook(workbook);
19
+ const output = await xlsx.write(workbook, {
20
+ boldHeaderRow: true,
21
+ columnWidths: [24, 16, 16],
22
+ });
23
+
24
+ const sheet = createSheet('Orders');
25
+ sheet.cells.set('A1', { type: 'text', value: 'Quantity' });
26
+ sheet.cells.set(2, 1, { type: 'number', value: 3 });
27
+ sheet.cells.set('B2', {
28
+ type: 'number', value: 30, // cached value supplied by the caller
29
+ formula: parseFormula('A2*10'),
30
+ numberFormat: '$#,##0.00',
31
+ });
32
+ await xlsx.write(createWorkbook([sheet]));
33
+ ```
34
+
35
+ ## Model
36
+
37
+ All coordinates are **one-based**. Ranges have inclusive `start` and `end`
38
+ coordinates. `SparseCells` supports `get('A1')`, `get(row, col)`, matching `set`
39
+ overloads, `[point, cell]` iteration, and `rows()` yielding sorted
40
+ `[row, ReadonlyMap<column, Cell>]` pairs. Empty dimensions never allocate dense
41
+ arrays. Use `point`, `address`, `range`, and `rangeAddress` to convert A1 notation.
42
+
43
+ The workbook carries sheets, defined names, a date system, and source format.
44
+ Sheets carry visibility, dimensions, merges, tables, validation rules, frozen
45
+ panes, and optional column widths. Cells carry typed values, number formats,
46
+ format kinds, errors, and formula metadata. Formula text omits its leading `=`;
47
+ its dialect is `excel-a1`. Shared formulas expand per cell; array anchors retain
48
+ `arrayRange`. The formula cell's value is its cached result, or null when absent.
49
+
50
+ References retain absolute flags, quoted sheet names, A1 ranges, whole-column/
51
+ row ranges, and defined/table names. Named references resolve against local then
52
+ global names and common table selectors, including `[@Column]`. Unresolved names
53
+ retain `name`; their placeholder range must not be treated as a resolved target.
54
+ Arbitrary Excel expressions and external-workbook references are not evaluated.
55
+ Original formula text is always retained; profiling exposes only resolved edges.
56
+
57
+ Dates are UTC `Date` values derived from number formats and the 1900/1904 flag.
58
+ `raw` preserves the serial. Excel's fictitious serial 60 maps to 1900-02-28 in
59
+ JavaScript; `raw: 60` distinguishes it from serial 59 and is retained on export
60
+ while the value remains unchanged. Time-only formats use the same serial epoch.
61
+
62
+ ## CSV
63
+
64
+ ```ts
65
+ const csv = await getSpreadsheets({ type: 'csv' });
66
+ const workbook = await csv.read(bytes); // comma, semicolon, tab or pipe detection
67
+ const output = await csv.write(workbook, { delimiter: ',', bom: true });
68
+ ```
69
+
70
+ CSV supports RFC 4180 quoting, embedded newlines, escaped quotes, UTF-8 BOM,
71
+ ragged/empty rows, and explicit delimiters. Detection counts separators outside
72
+ quotes on the first record. There is one sheet; multi-sheet CSV writes fail.
73
+ Numbers with leading zeroes, surrounding whitespace, more than 15 digits or
74
+ unsafe magnitude stay text. Booleans and valid ISO dates/UTC timestamps are
75
+ typed. Every parsed field retains `originalText`; writing preserves it while it
76
+ still represents the current value. CSV text beginning with `=` stays text.
77
+ Output uses CRLF. Expanding sparse coordinates into CSV is bounded by `maxCells`.
78
+
79
+ ## Profiling
80
+
81
+ `profileWorkbook` is pure and deterministic. It reports four-neighbor connected
82
+ blocks of occupied cells as rectangular regions. Up to the first three rows
83
+ are header candidates when at least 60% of columns contain nonformula text;
84
+ the first candidate is excluded from statistics. Trailing rows with `SUM`,
85
+ `SUBTOTAL`, or `AGGREGATE` references into the block above are totals candidates
86
+ and are also excluded from column statistics. These are explicit structural
87
+ heuristics, not inferred business meanings.
88
+
89
+ Column statistics include headers, type and blank counts, distinct nonblank
90
+ values, uniqueness (distinct / nonblank), samples, dominant format kind, and
91
+ formula counts by R1C1-relative pattern. Min/max use numeric, chronological,
92
+ lexical, or boolean order for homogeneous values; mixed types omit extrema.
93
+ Dependency edges run **from the formula column to the column it reads**.
94
+ Lookup evidence covers direct VLOOKUP/XLOOKUP and INDEX with MATCH arguments;
95
+ aggregate evidence covers SUMIF(S), COUNTIF(S), and AVERAGEIF(S). Dynamic targets
96
+ remain unresolved. Cross-sheet overlaps are directional, type-sensitive shares
97
+ of distinct values, with a default threshold of 0.5.
98
+
99
+ Options: `overlapThreshold` (0–1), `sampleSize` (5), `maxProfileCells` (2,000,000),
100
+ `maxColumnPairs` (100,000), `maxDependencyChecks` (8,000,000), and
101
+ `maxProfileWork` (256,000,000). Structural and formula limits from the adapter
102
+ limits below can also be supplied to profiling. Work-limit
103
+ exhaustion throws `SpreadsheetError` rather than returning partial evidence.
104
+
105
+ ## Safety and limits
106
+
107
+ `SpreadsheetError.code` is a closed union: `UNSUPPORTED_FORMAT`, `INVALID_INPUT`,
108
+ `INVALID_ZIP`, `UNSAFE_ZIP`, `UNSUPPORTED_ZIP`, `INVALID_XML`, `LIMIT_EXCEEDED`,
109
+ `INVALID_WORKBOOK`. Errors never include cell contents or archive paths.
110
+ All adapter limits can be set at construction or overridden per read/write:
111
+
112
+ | Option | Default |
113
+ | --- | ---: |
114
+ | maxInputBytes | 32 MiB |
115
+ | maxEntries | 10,000 |
116
+ | maxEntryBytes | 128 MiB |
117
+ | maxTotalBytes | 256 MiB |
118
+ | maxCompressionRatio | 1,000 |
119
+ | compressionRatioFloorBytes | 8 MiB |
120
+ | maxPathBytes | 1,024 |
121
+ | maxXmlDepth | 64 |
122
+ | maxXmlText (UTF-16 code units, text and attributes per part) | 33,554,432 |
123
+ | maxXmlNodes (per part) | 5,000,000 |
124
+ | maxSheets | 128 |
125
+ | maxCells (also bounds column-width expansion) | 1,000,000 |
126
+ | maxSharedStrings | 500,000 |
127
+ | maxFormulaLength | 8,192 |
128
+ | maxDefinedNames (workbook) | 10,000 |
129
+ | maxTables (workbook) | 1,000 |
130
+ | maxDataValidations (rules and cumulative target ranges) | 10,000 |
131
+ | maxMerges (workbook) | 10,000 |
132
+ | maxPartReferences (per archive part) | 1 |
133
+ | maxReadWork (reader/serialization operation units) | 268,435,456 |
134
+ | maxFormulaWork (operation units per read/profile) | 128,000,000 |
135
+ | maxFormulaDepth | 128 |
136
+ | maxFormulaTokens (per formula) | 2,048 |
137
+ | maxFormulaCacheEntries (per read/profile) | 50,000 |
138
+ | maxRows | 1,048,576 |
139
+ | maxColumns | 16,384 |
140
+
141
+ Names are indexed by lowercased name and scope once per read/profile. Tables
142
+ have name/column maps and a per-sheet column/row index for contextual selectors;
143
+ references never rebuild or scan the workbook's name/table arrays. XML parts
144
+ are parsed once, and repeated references are limited. Raising
145
+ `maxPartReferences` permits repeated tablePart references while retaining one
146
+ parsed table; repeated worksheet parts remain invalid.
147
+
148
+ The formula tokenizer makes one character pass and one pass over its tokens,
149
+ using a cache keyed by formula text for each read/profile operation. References,
150
+ function/argument spans and relative patterns reuse that scan. Unclosed strings
151
+ remain verbatim; excessive nesting/tokens/work fail with typed
152
+ `LIMIT_EXCEEDED`. Cache saturation stops retaining new scans; it never rejects a
153
+ formula. Uncached scans still charge their full work. Shared-formula expansion
154
+ charges generated text before copying. Error literals are atomic tokens;
155
+ `#REF!` and sheet-qualified broken references retain `name: '#REF!'` with an
156
+ unresolved placeholder range, and never produce dependency edges. References
157
+ and functions following an error literal are still extracted.
158
+
159
+ Work budgets charge XML node/attribute allocation, inner loops, sorting
160
+ comparisons or conservative sort
161
+ bounds, visited reference/column pairs, and processed/output string lengths.
162
+ Profiling uses sets for totals membership and distinct samples, visits each
163
+ region cell once during discovery, and preflights cross-sheet overlap products.
164
+ Shared long values, wide tables, formula copies, CSV fields and output expansion
165
+ consume budgets even when their input strings were shared. Exceeding a budget
166
+ returns no partial result.
167
+
168
+ Default work ceilings are sized from the structural caps: `maxReadWork` equals
169
+ the default aggregate inflated-byte cap (256 Mi units), covering the CSV reader's
170
+ two character passes over its 32 MiB input cap and XML allocation/sorting charges.
171
+ `maxFormulaWork` allows 128 units per default `maxCells` (128 million);
172
+ `maxProfileWork` allows 128 units per default `maxProfileCells` (256 million),
173
+ and `maxDependencyChecks` allows eight checks per default `maxCells`.
174
+ These are fixed defaults; changing a size cap does not automatically raise a
175
+ work cap. A million short numeric/formula cells fit these operation ceilings;
176
+ longer formulas, many regions and shared large values can still exhaust them.
177
+ The 128 MiB part, five-million XML-node and 32 Mi-code-unit text/attribute caps
178
+ allow a million ordinary numeric or inline-string cells, including one cell per row; the former
179
+ 32 MiB/two-million/eight-million caps did not. The node ceiling allows five nodes per default cell: four for each inline-string
180
+ row/cell/is/t chain plus wrapper and metadata headroom. Long inline text remains bounded
181
+ independently of cell count.
182
+
183
+ The reader builds an XML tree and a sparse cell model in memory. Million-cell
184
+ read/write is a heavyweight Node batch workload (roughly 2 GiB peak RSS in the
185
+ regression run), not an interactive browser sizing target. Applications can start
186
+ with a lower admission policy such as `{ maxCells: 250_000 }` for interactive or
187
+ browser uploads, then measure their own content and device memory; this is not a
188
+ browser capacity guarantee. Smaller browser-root
189
+ round trips remain covered by the browser Web API smoke test. These limits may
190
+ reject otherwise valid large files;
191
+ raise the relevant option explicitly for a trusted workload.
192
+
193
+ ZIP metadata inspection reuses the browser-safe `@happyvertical/files/archive`
194
+ subpath. It rejects
195
+ traversal, collisions, symlinks/special files, encryption, ZIP64, and multi-disk
196
+ archives. It accepts standard data descriptors only at the exact centrally
197
+ declared boundary. Inflation runs in small chunks with actual-byte checks and
198
+ CRC verification. Absolute per-entry and aggregate inflated-byte caps are
199
+ enforced on every output chunk independently of declared sizes. The per-entry
200
+ ratio check is secondary: it compares actual inflated bytes with compressed
201
+ entry bytes only after the actual size exceeds `compressionRatioFloorBytes`.
202
+ The 8 MiB floor and 1,000:1 ratio are configurable at construction or per read.
203
+ Small repetitive XML parts are accepted regardless of ratio while absolute caps
204
+ remain active. No path is extracted to the filesystem. Output uses DEFLATE at
205
+ fflate's default compression level.
206
+
207
+ Runtime dependencies are the SDK's `@happyvertical/files/archive` entry and
208
+ **fflate**, imported through its browser entry.
209
+ A purpose-built UTF-8 XML tokenizer handles OOXML's needed grammar with bounded
210
+ depth, text, and nodes; it rejects all DTD/declaration markup, unknown entities,
211
+ and malformed nesting. Only the five predefined XML entities and numeric
212
+ character references are decoded. It never fetches external entities or parts.
213
+ This avoids another parser dependency and any configurable entity expansion.
214
+
215
+ XLSX writing supports typed values, formulas, number formats, optional bold
216
+ headers, widths, multiple sheets, merges, names, tables, validation lists, and
217
+ panes. Unsupported artwork, charts, pivots, comments, macros and other OOXML
218
+ parts are ignored on read and omitted on write. This is a structural data export,
219
+ not a lossless document editor. ODS, XLS and service adapters are outside scope.
220
+
221
+ ## Development
222
+
223
+ ```bash
224
+ pnpm install --frozen-lockfile
225
+ pnpm --filter @happyvertical/spreadsheets build
226
+ pnpm --filter @happyvertical/spreadsheets test
227
+ pnpm --filter @happyvertical/spreadsheets typecheck
228
+ pnpm --filter @happyvertical/spreadsheets lint
229
+ ```
230
+
231
+ Tests build detailed fixtures in code, check hostile archives/XML, profile a
232
+ small-business workbook, and bundle/run the root with browser Web APIs and no
233
+ Node imports. Small independent Excel, LibreOffice and Google Sheets fixtures
234
+ from readxl have [pinned provenance and license](test/fixtures/README.md).
235
+ Opening exports in the actual three applications remains a separate manual
236
+ interoperability check.
package/dist/csv.d.ts ADDED
@@ -0,0 +1,6 @@
1
+ import { type SpreadsheetLimits } from './errors.js';
2
+ import { type Workbook } from './model.js';
3
+ import type { ReadOptions, WriteOptions } from './types.js';
4
+ export declare function readCsv(bytes: Uint8Array, limits: SpreadsheetLimits, options: ReadOptions): Workbook;
5
+ export declare function writeCsv(workbook: Workbook, limits: SpreadsheetLimits, options: WriteOptions): Uint8Array;
6
+ //# sourceMappingURL=csv.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"csv.d.ts","sourceRoot":"","sources":["../src/csv.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,aAAa,CAAC;AAErB,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA8B5D,wBAAgB,OAAO,CACrB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,WAAW,GACnB,QAAQ,CA8DV;AAsCD,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,YAAY,GACpB,UAAU,CAwDZ"}
@@ -0,0 +1,49 @@
1
+ /** Closed failure contract. Messages never interpolate workbook content. */
2
+ export type SpreadsheetErrorCode = 'UNSUPPORTED_FORMAT' | 'INVALID_INPUT' | 'INVALID_ZIP' | 'UNSAFE_ZIP' | 'UNSUPPORTED_ZIP' | 'INVALID_XML' | 'LIMIT_EXCEEDED' | 'INVALID_WORKBOOK';
3
+ export declare class SpreadsheetError extends Error {
4
+ readonly code: SpreadsheetErrorCode;
5
+ readonly limit?: keyof SpreadsheetLimits | undefined;
6
+ constructor(code: SpreadsheetErrorCode, message: string, limit?: keyof SpreadsheetLimits | undefined);
7
+ }
8
+ export interface SpreadsheetLimits {
9
+ maxInputBytes: number;
10
+ maxEntries: number;
11
+ maxEntryBytes: number;
12
+ maxTotalBytes: number;
13
+ maxCompressionRatio: number;
14
+ /** Apply the secondary ratio guard only above this actual inflated size. */
15
+ compressionRatioFloorBytes: number;
16
+ maxPathBytes: number;
17
+ maxXmlDepth: number;
18
+ maxXmlText: number;
19
+ maxXmlNodes: number;
20
+ maxSheets: number;
21
+ maxCells: number;
22
+ maxSharedStrings: number;
23
+ maxFormulaLength: number;
24
+ maxDefinedNames: number;
25
+ maxTables: number;
26
+ maxDataValidations: number;
27
+ maxMerges: number;
28
+ maxPartReferences: number;
29
+ maxReadWork: number;
30
+ maxFormulaWork: number;
31
+ maxFormulaDepth: number;
32
+ maxFormulaTokens: number;
33
+ maxFormulaCacheEntries: number;
34
+ maxRows: number;
35
+ maxColumns: number;
36
+ }
37
+ export declare const DEFAULT_LIMITS: Readonly<SpreadsheetLimits>;
38
+ export declare function resolveLimits(options?: Partial<SpreadsheetLimits>, base?: Readonly<SpreadsheetLimits>): SpreadsheetLimits;
39
+ export declare function checkLimit(actual: number, key: keyof SpreadsheetLimits, limits: SpreadsheetLimits): void;
40
+ export declare function invalid(message?: string): never;
41
+ /** Counts inner operations and processed/output text, not just outer calls. */
42
+ export declare class WorkBudget {
43
+ private readonly maximum;
44
+ private readonly limit?;
45
+ private used;
46
+ constructor(maximum: number, limit?: keyof SpreadsheetLimits | undefined);
47
+ spend(amount?: number): void;
48
+ }
49
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,MAAM,oBAAoB,GAC5B,oBAAoB,GACpB,eAAe,GACf,aAAa,GACb,YAAY,GACZ,iBAAiB,GACjB,aAAa,GACb,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,IAAI,EAAE,oBAAoB;aAE1B,KAAK,CAAC,EAAE,MAAM,iBAAiB;gBAF/B,IAAI,EAAE,oBAAoB,EAC1C,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,MAAM,iBAAiB,YAAA;CAKlD;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,0BAA0B,EAAE,MAAM,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,iBAAiB,CA2BrD,CAAC;AAEH,wBAAgB,aAAa,CAC3B,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAM,EACxC,IAAI,GAAE,QAAQ,CAAC,iBAAiB,CAAkB,GACjD,iBAAiB,CAanB;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,iBAAiB,EAC5B,MAAM,EAAE,iBAAiB,GACxB,IAAI,CAON;AAED,wBAAgB,OAAO,CAAC,OAAO,SAAgC,GAAG,KAAK,CAEtE;AAED,+EAA+E;AAC/E,qBAAa,UAAU;IAGnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IAHzB,OAAO,CAAC,IAAI,CAAK;gBAEE,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,iBAAiB,YAAA;IAElD,KAAK,CAAC,MAAM,SAAI,GAAG,IAAI;CASxB"}
@@ -0,0 +1,7 @@
1
+ import type { FormatKind } from './model.js';
2
+ export declare const BUILTIN_FORMATS: Record<number, string>;
3
+ export declare function formatKind(format?: string): FormatKind;
4
+ /** Serial 60 maps to 1900-02-28; raw preserves Excel's fictitious 1900-02-29. */
5
+ export declare function serialDate(serial: number, system: 1900 | 1904): Date;
6
+ export declare function dateSerial(date: Date, system: 1900 | 1904): number;
7
+ //# sourceMappingURL=formats.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../src/formats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAwDlD,CAAC;AACF,wBAAgB,UAAU,CAAC,MAAM,SAAY,GAAG,UAAU,CAmDzD;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAMpE;AACD,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,CAIlE"}
@@ -0,0 +1,41 @@
1
+ import { type SpreadsheetLimits } from './errors.js';
2
+ import { type Formula, type Point, type Reference } from './model.js';
3
+ export interface ReferenceToken {
4
+ from: number;
5
+ to: number;
6
+ reference: Reference;
7
+ }
8
+ export interface ArgumentSpan {
9
+ from: number;
10
+ to: number;
11
+ refStart: number;
12
+ refEnd: number;
13
+ }
14
+ export interface CallToken {
15
+ name: string;
16
+ from: number;
17
+ to: number;
18
+ args: ArgumentSpan[];
19
+ }
20
+ export interface FormulaScan {
21
+ text: string;
22
+ references: ReferenceToken[];
23
+ calls: CallToken[];
24
+ functions: string[];
25
+ }
26
+ /** Operation-local cache. Lexing and call/argument construction are linear passes. */
27
+ export declare class FormulaScanner {
28
+ readonly limits: SpreadsheetLimits;
29
+ private readonly charge;
30
+ private readonly cache;
31
+ private readonly budget;
32
+ constructor(limits?: SpreadsheetLimits, charge?: (n: number) => void);
33
+ spend(n?: number): void;
34
+ scan(input: string): FormulaScan;
35
+ }
36
+ export declare function referenceTokens(text: string, scanner?: FormulaScanner): ReferenceToken[];
37
+ export declare function parseFormula(input: string, limits?: SpreadsheetLimits, scanner?: FormulaScanner): Formula;
38
+ export declare function translateFormula(text: string, from: Point, to: Point, limits: SpreadsheetLimits, scanner?: FormulaScanner): Formula;
39
+ export declare function normalizeFormula(formula: Formula, origin: Point, scanner?: FormulaScanner): string;
40
+ export declare function directReference(input: string, scanner?: FormulaScanner): Reference | undefined;
41
+ //# sourceMappingURL=formula.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"formula.d.ts","sourceRoot":"","sources":["../src/formula.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,KAAK,OAAO,EACZ,KAAK,KAAK,EAEV,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,CAAC;CACtB;AACD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB;AACD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAqBD,sFAAsF;AACtF,qBAAa,cAAc;IAIvB,QAAQ,CAAC,MAAM,EAAE,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;gBAEzB,MAAM,GAAE,iBAAyC,EACzC,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAe;IAIzD,KAAK,CAAC,CAAC,SAAI,GAAG,IAAI;IAIlB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;CAgKjC;AAuCD,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,iBAAuB,GAC7B,cAAc,EAAE,CAElB;AACD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,iBAAyC,EACjD,OAAO,iBAA6B,GACnC,OAAO,CAWT;AACD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,KAAK,EACX,EAAE,EAAE,KAAK,EACT,MAAM,EAAE,iBAAiB,EACzB,OAAO,iBAA6B,GACnC,OAAO,CA8BT;AACD,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,KAAK,EACb,OAAO,CAAC,EAAE,cAAc,GACvB,MAAM,CA6BR;AACD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,OAAO,iBAAuB,GAC7B,SAAS,GAAG,SAAS,CAQvB"}
@@ -0,0 +1,10 @@
1
+ import type { SpreadsheetAdapter, SpreadsheetOptions } from './types.js';
2
+ export type { SpreadsheetErrorCode, SpreadsheetLimits } from './errors.js';
3
+ export { DEFAULT_LIMITS, SpreadsheetError } from './errors.js';
4
+ export { normalizeFormula, parseFormula } from './formula.js';
5
+ export * from './model.js';
6
+ export * from './profile.js';
7
+ export type * from './types.js';
8
+ /** Construct an isolated adapter; service adapters will use separate entries. */
9
+ export declare function getSpreadsheets(options: SpreadsheetOptions): Promise<SpreadsheetAdapter>;
10
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC9D,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,mBAAmB,YAAY,CAAC;AAEhC,iFAAiF;AACjF,wBAAsB,eAAe,CACnC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAmC7B"}