@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 +43 -0
- package/LICENSE +7 -0
- package/README.md +235 -2
- package/dist/csv.d.ts +6 -0
- package/dist/csv.d.ts.map +1 -0
- package/dist/errors.d.ts +49 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/formats.d.ts +7 -0
- package/dist/formats.d.ts.map +1 -0
- package/dist/formula.d.ts +41 -0
- package/dist/formula.d.ts.map +1 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3050 -0
- package/dist/index.js.map +1 -0
- package/dist/io.d.ts +4 -0
- package/dist/io.d.ts.map +1 -0
- package/dist/model.d.ts +104 -0
- package/dist/model.d.ts.map +1 -0
- package/dist/profile.d.ts +77 -0
- package/dist/profile.d.ts.map +1 -0
- package/dist/reference-index.d.ts +17 -0
- package/dist/reference-index.d.ts.map +1 -0
- package/dist/types.d.ts +24 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/xlsx-read.d.ts +4 -0
- package/dist/xlsx-read.d.ts.map +1 -0
- package/dist/xlsx-write.d.ts +5 -0
- package/dist/xlsx-write.d.ts.map +1 -0
- package/dist/xml.d.ts +14 -0
- package/dist/xml.d.ts.map +1 -0
- package/dist/zip.d.ts +3 -0
- package/dist/zip.d.ts.map +1 -0
- package/metadata.json +30 -0
- package/package.json +54 -3
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
|
-
#
|
|
1
|
+
# @happyvertical/spreadsheets
|
|
2
2
|
|
|
3
|
-
|
|
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"}
|
package/dist/errors.d.ts
ADDED
|
@@ -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"}
|
package/dist/index.d.ts
ADDED
|
@@ -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"}
|