@wae/open-excel 0.0.0-stage → 0.0.0
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/README.md +50 -2
- package/dist/cli.d.ts +10 -0
- package/dist/cli.js +1137 -0
- package/dist/errors.d.ts +50 -0
- package/dist/errors.js +55 -0
- package/dist/formats.d.ts +44 -0
- package/dist/formats.js +39 -0
- package/dist/gui.d.ts +53 -0
- package/dist/gui.js +90 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +13 -0
- package/dist/native.d.ts +36 -0
- package/dist/native.js +55 -0
- package/dist/open-excel.d.ts +55 -0
- package/dist/open-excel.js +225 -0
- package/dist/service.d.ts +47 -0
- package/dist/service.js +95 -0
- package/dist/smoke.test.d.ts +10 -0
- package/dist/smoke.test.js +159 -0
- package/dist/types.d.ts +640 -0
- package/dist/types.js +11 -0
- package/locales/en-US/cli.json +90 -0
- package/locales/locales.json +7 -0
- package/package.json +58 -4
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,640 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Workbook types of `@wae/open-excel`.
|
|
3
|
+
*
|
|
4
|
+
* This is the frozen P0 shape of the surface: `new OpenExcel(options?)` creates
|
|
5
|
+
* a session, `create`/`open` return a `Workbook` summary, and every sheet keeps
|
|
6
|
+
* a stable identity plus an index used only for ordering.
|
|
7
|
+
*
|
|
8
|
+
* Addresses are A1-style strings. Geometry and pixels never enter the model; a
|
|
9
|
+
* future renderer projects the engine's own layout.
|
|
10
|
+
*/
|
|
11
|
+
import type { WorkbookFormat, WorkbookIntent } from './formats.js';
|
|
12
|
+
/** Opaque workbook identity. */
|
|
13
|
+
export type WorkbookId = string;
|
|
14
|
+
/** Opaque sheet identity; the index is order only. */
|
|
15
|
+
export type SheetId = string;
|
|
16
|
+
/** A1-style cell address such as `B4`. */
|
|
17
|
+
export type CellAddress = string;
|
|
18
|
+
/** Hard limits applied before work starts. */
|
|
19
|
+
export interface ResourceBudgets {
|
|
20
|
+
readonly maxWorkbookBytes?: number;
|
|
21
|
+
readonly maxSheetCount?: number;
|
|
22
|
+
readonly maxCellCount?: number;
|
|
23
|
+
}
|
|
24
|
+
/** Structured diagnostic emitted during open, inspection or export. */
|
|
25
|
+
export interface WorkbookDiagnostic {
|
|
26
|
+
readonly code: string;
|
|
27
|
+
readonly severity: 'info' | 'warning' | 'error';
|
|
28
|
+
readonly revision?: number;
|
|
29
|
+
readonly sheetId?: SheetId;
|
|
30
|
+
readonly cell?: CellAddress;
|
|
31
|
+
readonly message: string;
|
|
32
|
+
}
|
|
33
|
+
/** Session options. Constructing a session opens no window, file or socket. */
|
|
34
|
+
export interface OpenExcelOptions {
|
|
35
|
+
/** BCP-47 tag used for diagnostics and default copy. Defaults to `en`. */
|
|
36
|
+
readonly locale?: string;
|
|
37
|
+
readonly budgets?: ResourceBudgets;
|
|
38
|
+
readonly diagnostics?: (event: WorkbookDiagnostic) => void;
|
|
39
|
+
}
|
|
40
|
+
/** Disclosure level. `partial` always ships a loss path and diagnostic codes. */
|
|
41
|
+
export type SupportLevel = 'supported' | 'partial' | 'unsupported';
|
|
42
|
+
/** Inspection rules understood by `workbook.inspect()`. */
|
|
43
|
+
export type InspectCheck = 'formulas' | 'references' | 'cycles' | 'types' | 'ranges' | 'styles';
|
|
44
|
+
/** Per-sheet render targets. */
|
|
45
|
+
export type RenderFormat = 'svg' | 'png' | 'pdf';
|
|
46
|
+
/** Formats `Workbook.export()` can write. */
|
|
47
|
+
export type ExportFormat = 'xlsx' | 'xlsm' | 'csv' | 'tsv' | 'json' | 'html' | 'pdf';
|
|
48
|
+
/** What the installed engine can do per format. */
|
|
49
|
+
export interface FormatCapability {
|
|
50
|
+
readonly import: SupportLevel;
|
|
51
|
+
readonly edit: SupportLevel;
|
|
52
|
+
readonly export: SupportLevel;
|
|
53
|
+
readonly inspect: SupportLevel;
|
|
54
|
+
/** Codes reported when a `partial` path loses something. */
|
|
55
|
+
readonly lossCodes: readonly string[];
|
|
56
|
+
}
|
|
57
|
+
/** Result of `OpenExcel.capabilities()`. Read this instead of assuming a method works. */
|
|
58
|
+
export interface OpenExcelCapabilities {
|
|
59
|
+
readonly engine: {
|
|
60
|
+
readonly package: string;
|
|
61
|
+
readonly version: string;
|
|
62
|
+
};
|
|
63
|
+
/** Whole-project container support; `unsupported` while no engine ships. */
|
|
64
|
+
readonly project: SupportLevel;
|
|
65
|
+
readonly formats: Readonly<Record<WorkbookFormat, FormatCapability>>;
|
|
66
|
+
readonly checks: Readonly<Record<InspectCheck, SupportLevel>>;
|
|
67
|
+
/** Formula functions the engine evaluates and how it treats the rest. */
|
|
68
|
+
readonly formulas: FormulaCapability;
|
|
69
|
+
readonly renderers: Readonly<Record<RenderFormat, SupportLevel>>;
|
|
70
|
+
readonly exportTargets: Readonly<Record<ExportFormat, SupportLevel>>;
|
|
71
|
+
/** What each `partial` export target approximates or drops. */
|
|
72
|
+
readonly exportLimits?: Readonly<Partial<Record<ExportFormat, readonly string[]>>>;
|
|
73
|
+
}
|
|
74
|
+
/** Formula disclosure of the installed engine. */
|
|
75
|
+
export interface FormulaCapability {
|
|
76
|
+
/** Function names the evaluator implements, uppercase. */
|
|
77
|
+
readonly functions: readonly string[];
|
|
78
|
+
/**
|
|
79
|
+
* `preserve-cached` means a formula using an unknown function keeps the
|
|
80
|
+
* value the source workbook cached instead of `#NAME?`.
|
|
81
|
+
*/
|
|
82
|
+
readonly unsupportedBehavior: 'preserve-cached';
|
|
83
|
+
}
|
|
84
|
+
/** Options of `OpenExcel.create()`. */
|
|
85
|
+
export interface WorkbookCreateOptions {
|
|
86
|
+
readonly title?: string;
|
|
87
|
+
/** Template name or path the engine should start from. */
|
|
88
|
+
readonly template?: string;
|
|
89
|
+
readonly locale?: string;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Input of `OpenExcel.open()`.
|
|
93
|
+
*
|
|
94
|
+
* Exactly one of `path` or `bytes` must be present, so the engine never guesses
|
|
95
|
+
* whether a string is a file name or serialized content.
|
|
96
|
+
*/
|
|
97
|
+
export type WorkbookInput = {
|
|
98
|
+
readonly path: string;
|
|
99
|
+
readonly intent?: WorkbookIntent;
|
|
100
|
+
} | {
|
|
101
|
+
readonly bytes: Uint8Array;
|
|
102
|
+
readonly filename?: string;
|
|
103
|
+
readonly intent?: WorkbookIntent;
|
|
104
|
+
};
|
|
105
|
+
/** One sheet of a workbook summary. */
|
|
106
|
+
export interface SheetSummary {
|
|
107
|
+
readonly id: SheetId;
|
|
108
|
+
readonly index: number;
|
|
109
|
+
readonly name: string;
|
|
110
|
+
readonly hidden: boolean;
|
|
111
|
+
/** Non-empty cells on this sheet. */
|
|
112
|
+
readonly cells: number;
|
|
113
|
+
}
|
|
114
|
+
/** One cell, used when a caller asks for a single address. */
|
|
115
|
+
export interface CellSummary {
|
|
116
|
+
readonly sheetId: SheetId;
|
|
117
|
+
readonly address: CellAddress;
|
|
118
|
+
readonly kind: 'text' | 'number' | 'boolean' | 'error' | 'empty' | 'formula';
|
|
119
|
+
readonly formula: string | null;
|
|
120
|
+
readonly value: string | number | boolean | null;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Opened workbook summary. `revision` is monotonic and changes on every
|
|
124
|
+
* committed mutation, so callers can reject a stale writer.
|
|
125
|
+
*/
|
|
126
|
+
export interface Workbook {
|
|
127
|
+
readonly id: WorkbookId;
|
|
128
|
+
readonly revision: number;
|
|
129
|
+
readonly title: string | null;
|
|
130
|
+
readonly sheets: readonly SheetSummary[];
|
|
131
|
+
/** Total non-empty cells across every sheet. */
|
|
132
|
+
readonly cells: number;
|
|
133
|
+
}
|
|
134
|
+
/** Options of `OpenExcel.inspect()`. */
|
|
135
|
+
export interface InspectOptions {
|
|
136
|
+
readonly checks?: readonly InspectCheck[];
|
|
137
|
+
}
|
|
138
|
+
/** One finding of an inspection run. */
|
|
139
|
+
export interface InspectIssue {
|
|
140
|
+
readonly code: string;
|
|
141
|
+
readonly severity: 'info' | 'warning' | 'error';
|
|
142
|
+
readonly revision: number;
|
|
143
|
+
readonly sheetId?: SheetId;
|
|
144
|
+
readonly cell?: CellAddress;
|
|
145
|
+
readonly recoverable: boolean;
|
|
146
|
+
readonly message: string;
|
|
147
|
+
}
|
|
148
|
+
/** Result of `OpenExcel.inspect()` or `Workbook.inspect()`. Rules only, never a score. */
|
|
149
|
+
export interface InspectReport {
|
|
150
|
+
readonly revision: number;
|
|
151
|
+
readonly checkerVersion: string;
|
|
152
|
+
readonly issues: readonly InspectIssue[];
|
|
153
|
+
readonly passed: boolean;
|
|
154
|
+
}
|
|
155
|
+
/** Options of saving a native project (not an exchange format). */
|
|
156
|
+
export interface SaveOptions {
|
|
157
|
+
readonly target: string;
|
|
158
|
+
readonly overwrite?: boolean;
|
|
159
|
+
}
|
|
160
|
+
/** Result of a save. */
|
|
161
|
+
export interface SaveReport {
|
|
162
|
+
readonly target: string;
|
|
163
|
+
readonly revision: number;
|
|
164
|
+
readonly sheets: number;
|
|
165
|
+
readonly bytes: number;
|
|
166
|
+
}
|
|
167
|
+
/** Options of `Workbook.export()`. */
|
|
168
|
+
export interface ExportOptions {
|
|
169
|
+
readonly format: ExportFormat;
|
|
170
|
+
readonly target: string;
|
|
171
|
+
readonly overwrite?: boolean;
|
|
172
|
+
}
|
|
173
|
+
/** One thing a projection could not keep. */
|
|
174
|
+
export interface ExportLoss {
|
|
175
|
+
readonly code: string;
|
|
176
|
+
readonly severity: 'warning' | 'error';
|
|
177
|
+
readonly sheetId?: SheetId;
|
|
178
|
+
readonly cell?: CellAddress;
|
|
179
|
+
readonly message: string;
|
|
180
|
+
}
|
|
181
|
+
/** Result of a projection. Reports what the target actually kept. */
|
|
182
|
+
export interface ExportReport {
|
|
183
|
+
readonly revision: number;
|
|
184
|
+
readonly format: ExportFormat;
|
|
185
|
+
readonly target: string;
|
|
186
|
+
readonly losses: readonly ExportLoss[];
|
|
187
|
+
/** False for projections such as PDF that cannot be reopened for editing. */
|
|
188
|
+
readonly editable: boolean;
|
|
189
|
+
}
|
|
190
|
+
/** Options of rendering one or more sheets. */
|
|
191
|
+
export interface RenderOptions {
|
|
192
|
+
readonly format: RenderFormat;
|
|
193
|
+
readonly sheets?: 'all' | readonly SheetId[];
|
|
194
|
+
readonly target?: string;
|
|
195
|
+
}
|
|
196
|
+
/** One rendered sheet. */
|
|
197
|
+
export interface RenderPage {
|
|
198
|
+
readonly sheetId: SheetId;
|
|
199
|
+
readonly path?: string;
|
|
200
|
+
readonly bytes?: number;
|
|
201
|
+
}
|
|
202
|
+
/** Result of a render run. */
|
|
203
|
+
export interface RenderReport {
|
|
204
|
+
readonly revision: number;
|
|
205
|
+
readonly format: RenderFormat;
|
|
206
|
+
readonly pages: readonly RenderPage[];
|
|
207
|
+
readonly diagnostics: readonly WorkbookDiagnostic[];
|
|
208
|
+
}
|
|
209
|
+
/** Options of `Workbook.render()`. */
|
|
210
|
+
export interface WorkbookRenderOptions {
|
|
211
|
+
readonly format?: RenderFormat;
|
|
212
|
+
/** Sheet id or name; the first visible sheet when omitted. */
|
|
213
|
+
readonly sheet?: string;
|
|
214
|
+
}
|
|
215
|
+
/** SVG result of rendering one sheet. */
|
|
216
|
+
export interface SvgRender {
|
|
217
|
+
readonly revision: number;
|
|
218
|
+
readonly format: 'svg';
|
|
219
|
+
readonly sheet: string;
|
|
220
|
+
readonly sheetId: SheetId;
|
|
221
|
+
readonly svg: string;
|
|
222
|
+
}
|
|
223
|
+
/** Value accepted by `cell.set`. */
|
|
224
|
+
export type CellValueInput = string | number | boolean | null | {
|
|
225
|
+
readonly kind: 'text';
|
|
226
|
+
readonly text: string;
|
|
227
|
+
} | {
|
|
228
|
+
readonly kind: 'number';
|
|
229
|
+
readonly number: number;
|
|
230
|
+
} | {
|
|
231
|
+
readonly kind: 'bool';
|
|
232
|
+
readonly value: boolean;
|
|
233
|
+
} | {
|
|
234
|
+
readonly kind: 'error';
|
|
235
|
+
readonly code: string;
|
|
236
|
+
} | {
|
|
237
|
+
readonly kind: 'empty';
|
|
238
|
+
};
|
|
239
|
+
/** JSON projection of one evaluated cell value. Errors keep their literal. */
|
|
240
|
+
export type CellPrimitive = string | number | boolean | null;
|
|
241
|
+
/** What one cell holds after evaluation. */
|
|
242
|
+
export type CellKind = 'text' | 'number' | 'boolean' | 'error' | 'empty' | 'formula';
|
|
243
|
+
/** Result of reading one cell. `value` is the evaluated result. */
|
|
244
|
+
export interface CellDetail {
|
|
245
|
+
readonly sheet: string;
|
|
246
|
+
readonly address: CellAddress;
|
|
247
|
+
readonly kind: CellKind;
|
|
248
|
+
readonly formula: string | null;
|
|
249
|
+
/** Evaluated value: what a reader shows. */
|
|
250
|
+
readonly value: CellPrimitive;
|
|
251
|
+
/** Value the source workbook carried next to the formula, when it had one. */
|
|
252
|
+
readonly cached: CellPrimitive;
|
|
253
|
+
/**
|
|
254
|
+
* How the last evaluation ended: `unsupported` when the engine kept the
|
|
255
|
+
* cached value because it cannot evaluate a function in the formula.
|
|
256
|
+
*/
|
|
257
|
+
readonly computedState: 'computed' | 'unsupported' | null;
|
|
258
|
+
}
|
|
259
|
+
/** One cell of a range matrix. */
|
|
260
|
+
export interface RangeCell {
|
|
261
|
+
readonly address: CellAddress;
|
|
262
|
+
readonly value: CellPrimitive;
|
|
263
|
+
readonly formula: string | null;
|
|
264
|
+
}
|
|
265
|
+
/** Result of reading a rectangle, row by row. */
|
|
266
|
+
export interface RangeMatrix {
|
|
267
|
+
readonly sheet: string;
|
|
268
|
+
readonly range: string;
|
|
269
|
+
readonly rows: readonly (readonly RangeCell[])[];
|
|
270
|
+
}
|
|
271
|
+
/** Result of `Workbook.recalc()`. */
|
|
272
|
+
export interface RecalcReport {
|
|
273
|
+
readonly revision: number;
|
|
274
|
+
/** Formula cells whose evaluated value changed. */
|
|
275
|
+
readonly changed: number;
|
|
276
|
+
}
|
|
277
|
+
/** Options of reading one cell. */
|
|
278
|
+
export interface CellQuery {
|
|
279
|
+
/** Sheet name or id; the first visible sheet when omitted. */
|
|
280
|
+
readonly sheet?: string;
|
|
281
|
+
readonly address: CellAddress;
|
|
282
|
+
}
|
|
283
|
+
/** Options of reading one rectangle. */
|
|
284
|
+
export interface RangeQuery {
|
|
285
|
+
/** Sheet name or id; the first visible sheet when omitted. */
|
|
286
|
+
readonly sheet?: string;
|
|
287
|
+
/** A1 range such as `A1:C4`. */
|
|
288
|
+
readonly range: string;
|
|
289
|
+
}
|
|
290
|
+
/** One `range.set` entry: a literal, `null` to clear, or a formula with an optional cached value. */
|
|
291
|
+
export type CellInput = CellValueInput | {
|
|
292
|
+
readonly formula: string;
|
|
293
|
+
readonly value?: CellValueInput;
|
|
294
|
+
};
|
|
295
|
+
/** Visual properties accepted by `format.set`. Omitted properties keep their current value. */
|
|
296
|
+
export interface CellStyleInput {
|
|
297
|
+
readonly bold?: boolean;
|
|
298
|
+
readonly italic?: boolean;
|
|
299
|
+
readonly fontSize?: number;
|
|
300
|
+
readonly fontColor?: string;
|
|
301
|
+
readonly fill?: string;
|
|
302
|
+
readonly numberFormat?: string;
|
|
303
|
+
readonly align?: 'left' | 'center' | 'right' | 'justify' | 'distribute' | 'fill';
|
|
304
|
+
readonly wrap?: boolean;
|
|
305
|
+
}
|
|
306
|
+
/** Sheet tab visibility accepted by `sheet.setVisibility`. */
|
|
307
|
+
export type SheetVisibility = 'visible' | 'hidden' | 'veryHidden';
|
|
308
|
+
/** Parsed options of the `freeze` command; exactly one mode applies. */
|
|
309
|
+
export interface FreezeCommandOptions {
|
|
310
|
+
readonly sheet?: string;
|
|
311
|
+
/** A1 cell that marks the freeze boundary, such as `C2`. */
|
|
312
|
+
readonly at?: CellAddress;
|
|
313
|
+
/** Number of frozen rows when no `--at` cell is given. */
|
|
314
|
+
readonly rows?: number;
|
|
315
|
+
/** Number of frozen columns when no `--at` cell is given. */
|
|
316
|
+
readonly columns?: number;
|
|
317
|
+
/** Clear the frozen pane. */
|
|
318
|
+
readonly clear?: boolean;
|
|
319
|
+
}
|
|
320
|
+
/** Parsed options of the `sheet` visibility flags; exactly one name applies. */
|
|
321
|
+
export interface SheetVisibilityCommandOptions {
|
|
322
|
+
readonly hide?: string;
|
|
323
|
+
readonly show?: string;
|
|
324
|
+
readonly veryHidden?: string;
|
|
325
|
+
}
|
|
326
|
+
/** One rectangle an edit operation rewrote, as reported by `Workbook.edit()`. */
|
|
327
|
+
export interface AffectedRange {
|
|
328
|
+
readonly op: 'range.sort' | 'range.fillSeries' | 'range.transpose' | 'range.copy' | 'range.move' | 'range.swap' | 'range.flip' | 'cell.replaceText';
|
|
329
|
+
readonly sheet: string;
|
|
330
|
+
/** A1 rectangle such as `A1:A5`. */
|
|
331
|
+
readonly range: string;
|
|
332
|
+
/** Occurrences replaced by a `cell.replaceText` operation. */
|
|
333
|
+
readonly replaced?: number;
|
|
334
|
+
}
|
|
335
|
+
/**
|
|
336
|
+
* Copies `range` into the rectangle anchored at `target` and keeps the source.
|
|
337
|
+
* Values, formula sources, cached results and styles move verbatim, while
|
|
338
|
+
* relative references inside formulas are not rewritten. The source is
|
|
339
|
+
* snapshotted before writing, so overlapping source and target stay
|
|
340
|
+
* deterministic; merged ranges intersecting either rectangle are rejected.
|
|
341
|
+
*/
|
|
342
|
+
export interface RangeCopyOperation {
|
|
343
|
+
readonly op: 'range.copy';
|
|
344
|
+
readonly sheet: string;
|
|
345
|
+
readonly range: string;
|
|
346
|
+
/** Top-left cell of the destination rectangle. */
|
|
347
|
+
readonly target: CellAddress;
|
|
348
|
+
}
|
|
349
|
+
/**
|
|
350
|
+
* Moves `range` into the rectangle anchored at `target` and clears the source.
|
|
351
|
+
* Values, formula sources, cached results and styles move verbatim, while
|
|
352
|
+
* relative references inside formulas are not rewritten. The source is
|
|
353
|
+
* snapshotted before either rectangle is cleared, so overlapping source and
|
|
354
|
+
* target stay deterministic; merged ranges intersecting either rectangle are
|
|
355
|
+
* rejected.
|
|
356
|
+
*/
|
|
357
|
+
export interface RangeMoveOperation {
|
|
358
|
+
readonly op: 'range.move';
|
|
359
|
+
readonly sheet: string;
|
|
360
|
+
readonly range: string;
|
|
361
|
+
/** Top-left cell of the destination rectangle. */
|
|
362
|
+
readonly target: CellAddress;
|
|
363
|
+
}
|
|
364
|
+
/**
|
|
365
|
+
* Exchanges `range` with the equal-sized rectangle anchored at `target`.
|
|
366
|
+
* Values, formula sources, cached results and styles travel verbatim, while
|
|
367
|
+
* relative references inside formulas are not rewritten. Both rectangles are
|
|
368
|
+
* snapshotted before either is cleared, so overlapping rectangles stay
|
|
369
|
+
* deterministic; merged ranges intersecting either rectangle are rejected.
|
|
370
|
+
*/
|
|
371
|
+
export interface RangeSwapOperation {
|
|
372
|
+
readonly op: 'range.swap';
|
|
373
|
+
readonly sheet: string;
|
|
374
|
+
readonly range: string;
|
|
375
|
+
/** Top-left cell of the second, equal-sized rectangle. */
|
|
376
|
+
readonly target: CellAddress;
|
|
377
|
+
}
|
|
378
|
+
/**
|
|
379
|
+
* Mirrors `range` in place along `axis`.
|
|
380
|
+
*
|
|
381
|
+
* `horizontal` swaps columns left to right while rows keep their position;
|
|
382
|
+
* `vertical` swaps rows top to bottom while columns keep theirs. Cell contents,
|
|
383
|
+
* styles and formula sources travel verbatim, while relative references inside
|
|
384
|
+
* formulas are not rewritten. The rectangle is snapshotted before it is
|
|
385
|
+
* cleared; merged cells inside the rectangle are rejected.
|
|
386
|
+
*/
|
|
387
|
+
export interface RangeFlipOperation {
|
|
388
|
+
readonly op: 'range.flip';
|
|
389
|
+
readonly sheet: string;
|
|
390
|
+
readonly range: string;
|
|
391
|
+
/** `horizontal` mirrors columns; `vertical` mirrors rows. */
|
|
392
|
+
readonly axis: 'horizontal' | 'vertical';
|
|
393
|
+
}
|
|
394
|
+
/** One operation of `Workbook.edit()`. */
|
|
395
|
+
export type EditOperation = {
|
|
396
|
+
readonly op: 'cell.set';
|
|
397
|
+
readonly sheet: string;
|
|
398
|
+
readonly reference: CellAddress;
|
|
399
|
+
readonly value?: CellValueInput;
|
|
400
|
+
readonly formula?: string;
|
|
401
|
+
} | {
|
|
402
|
+
readonly op: 'range.set';
|
|
403
|
+
readonly sheet: string;
|
|
404
|
+
/** Top-left cell of the matrix. */
|
|
405
|
+
readonly start: CellAddress;
|
|
406
|
+
readonly rows: readonly (readonly CellInput[])[];
|
|
407
|
+
} | {
|
|
408
|
+
readonly op: 'format.set';
|
|
409
|
+
readonly sheet: string;
|
|
410
|
+
readonly range: string;
|
|
411
|
+
readonly style: CellStyleInput;
|
|
412
|
+
} | {
|
|
413
|
+
/** Removes values and formulas in `range` while every cell style stays in place. */
|
|
414
|
+
readonly op: 'range.clearContents';
|
|
415
|
+
readonly sheet: string;
|
|
416
|
+
/** A1 range such as `A1:C4`. */
|
|
417
|
+
readonly range: string;
|
|
418
|
+
} | {
|
|
419
|
+
/** Removes every cell style in `range`; values and formulas stay in place. */
|
|
420
|
+
readonly op: 'format.clear';
|
|
421
|
+
readonly sheet: string;
|
|
422
|
+
/** A1 range such as `A1:C4`. */
|
|
423
|
+
readonly range: string;
|
|
424
|
+
} | {
|
|
425
|
+
/** Copies the style of one cell onto every cell in `target`, values untouched. */
|
|
426
|
+
readonly op: 'format.copy';
|
|
427
|
+
readonly sheet: string;
|
|
428
|
+
/** One-cell source such as `B2`; it must already carry content or a style. */
|
|
429
|
+
readonly source: string;
|
|
430
|
+
/** A1 target range such as `B2:D8`. */
|
|
431
|
+
readonly target: string;
|
|
432
|
+
} | {
|
|
433
|
+
/** Merges `start:end` when `merge` is true and unmerges it otherwise. */
|
|
434
|
+
readonly op: 'merge.set';
|
|
435
|
+
readonly sheet: string;
|
|
436
|
+
readonly start: CellAddress;
|
|
437
|
+
readonly end: CellAddress;
|
|
438
|
+
readonly merge: boolean;
|
|
439
|
+
} | {
|
|
440
|
+
/**
|
|
441
|
+
* Freezes rows and columns of one sheet. A `cell` boundary such as `C2`
|
|
442
|
+
* freezes the rows above it and the columns left of it, so `C2` means
|
|
443
|
+
* `rows: 1` and `columns: 2`. Explicit `rows` and `columns` are counts.
|
|
444
|
+
* `clear: true`, or omitting every boundary, removes the frozen pane.
|
|
445
|
+
*/
|
|
446
|
+
readonly op: 'sheet.freeze';
|
|
447
|
+
readonly sheet: string;
|
|
448
|
+
/** A1 cell whose top-left corner is the freeze boundary. */
|
|
449
|
+
readonly cell?: CellAddress;
|
|
450
|
+
/** Number of frozen rows when no `cell` is given. */
|
|
451
|
+
readonly rows?: number;
|
|
452
|
+
/** Number of frozen columns when no `cell` is given. */
|
|
453
|
+
readonly columns?: number;
|
|
454
|
+
/** Removes the frozen pane. */
|
|
455
|
+
readonly clear?: boolean;
|
|
456
|
+
} | {
|
|
457
|
+
/** Sets one column width in Excel character units; `hidden` hides the column. */
|
|
458
|
+
readonly op: 'column.setWidth';
|
|
459
|
+
readonly sheet: string;
|
|
460
|
+
/** One-based column number or a column letter such as `B`. */
|
|
461
|
+
readonly column: number | string;
|
|
462
|
+
readonly width: number;
|
|
463
|
+
readonly hidden?: boolean;
|
|
464
|
+
} | {
|
|
465
|
+
/** Sets one row height in points; `hidden` hides the row. */
|
|
466
|
+
readonly op: 'row.setHeight';
|
|
467
|
+
readonly sheet: string;
|
|
468
|
+
/** One-based row number. */
|
|
469
|
+
readonly row: number;
|
|
470
|
+
readonly height: number;
|
|
471
|
+
readonly hidden?: boolean;
|
|
472
|
+
} | {
|
|
473
|
+
readonly op: 'sheet.setVisibility';
|
|
474
|
+
readonly sheet: string;
|
|
475
|
+
readonly visibility: SheetVisibility;
|
|
476
|
+
} | {
|
|
477
|
+
/**
|
|
478
|
+
* Inserts `count` empty rows before `row`, moving cells, merged ranges,
|
|
479
|
+
* frozen panes, row heights, column widths and local formula references.
|
|
480
|
+
*/
|
|
481
|
+
readonly op: 'row.insert';
|
|
482
|
+
readonly sheet: string;
|
|
483
|
+
/** One-based row the new rows appear before. */
|
|
484
|
+
readonly row: number;
|
|
485
|
+
/** Number of rows to insert; defaults to 1. */
|
|
486
|
+
readonly count?: number;
|
|
487
|
+
} | {
|
|
488
|
+
/** Deletes `count` rows starting at `row`; the band must stay inside the sheet. */
|
|
489
|
+
readonly op: 'row.delete';
|
|
490
|
+
readonly sheet: string;
|
|
491
|
+
/** One-based first row to delete. */
|
|
492
|
+
readonly row: number;
|
|
493
|
+
/** Number of rows to delete; defaults to 1. */
|
|
494
|
+
readonly count?: number;
|
|
495
|
+
} | {
|
|
496
|
+
/** Inserts `count` empty columns before `column`, moving every column-bearing field. */
|
|
497
|
+
readonly op: 'column.insert';
|
|
498
|
+
readonly sheet: string;
|
|
499
|
+
/** One-based column number or a column letter such as `B`. */
|
|
500
|
+
readonly column: number | string;
|
|
501
|
+
/** Number of columns to insert; defaults to 1. */
|
|
502
|
+
readonly count?: number;
|
|
503
|
+
} | {
|
|
504
|
+
/** Deletes `count` columns starting at `column`; the band must stay inside the sheet. */
|
|
505
|
+
readonly op: 'column.delete';
|
|
506
|
+
readonly sheet: string;
|
|
507
|
+
/** One-based column number or a column letter such as `B`. */
|
|
508
|
+
readonly column: number | string;
|
|
509
|
+
/** Number of columns to delete; defaults to 1. */
|
|
510
|
+
readonly count?: number;
|
|
511
|
+
} | {
|
|
512
|
+
/**
|
|
513
|
+
* Replaces text inside `range` and reports the replacement count.
|
|
514
|
+
* When `range` is omitted the sheet's used rectangle is scanned.
|
|
515
|
+
* Formula cells are skipped; `limit` caps the occurrences replaced,
|
|
516
|
+
* scanning cells in row-major order.
|
|
517
|
+
*/
|
|
518
|
+
readonly op: 'cell.replaceText';
|
|
519
|
+
readonly sheet: string;
|
|
520
|
+
/** A1 rectangle such as `A1:C4`; defaults to the used rectangle. */
|
|
521
|
+
readonly range?: string;
|
|
522
|
+
readonly find: string;
|
|
523
|
+
readonly replace: string;
|
|
524
|
+
readonly matchCase?: boolean;
|
|
525
|
+
/** Maximum occurrences to replace; unlimited when omitted. */
|
|
526
|
+
readonly limit?: number;
|
|
527
|
+
} | {
|
|
528
|
+
readonly op: 'sheet.add';
|
|
529
|
+
readonly name: string;
|
|
530
|
+
readonly index?: number;
|
|
531
|
+
} | {
|
|
532
|
+
readonly op: 'sheet.rename';
|
|
533
|
+
readonly sheet: string;
|
|
534
|
+
readonly name: string;
|
|
535
|
+
} | {
|
|
536
|
+
readonly op: 'sheet.remove';
|
|
537
|
+
readonly sheet: string;
|
|
538
|
+
} | {
|
|
539
|
+
readonly op: 'sheet.duplicate';
|
|
540
|
+
readonly sheet: string;
|
|
541
|
+
readonly name?: string;
|
|
542
|
+
} | {
|
|
543
|
+
readonly op: 'sheet.move';
|
|
544
|
+
readonly sheet: string;
|
|
545
|
+
readonly index: number;
|
|
546
|
+
} | {
|
|
547
|
+
/**
|
|
548
|
+
* Sorts whole rows of `range` by `column`, moving formulas with their
|
|
549
|
+
* row. `column` is a one-based offset inside the range or an absolute
|
|
550
|
+
* column letter. Numbers sort before text, text before booleans, and
|
|
551
|
+
* blanks always trail. The operation is rejected when the range
|
|
552
|
+
* overlaps a merged range.
|
|
553
|
+
*/
|
|
554
|
+
readonly op: 'range.sort';
|
|
555
|
+
readonly sheet: string;
|
|
556
|
+
readonly range: string;
|
|
557
|
+
readonly column: number | string;
|
|
558
|
+
/** Ascending when true, which is the default. */
|
|
559
|
+
readonly ascending?: boolean;
|
|
560
|
+
/** Keeps the first row of `range` in place. */
|
|
561
|
+
readonly hasHeader?: boolean;
|
|
562
|
+
} | {
|
|
563
|
+
/**
|
|
564
|
+
* Fills `range`, a single row or a single column, with a linear numeric
|
|
565
|
+
* series. The first cell seeds the start and, when two numeric cells are
|
|
566
|
+
* present, the second seeds the step. Existing styles stay in place and
|
|
567
|
+
* formulas inside the range are replaced.
|
|
568
|
+
*/
|
|
569
|
+
readonly op: 'range.fillSeries';
|
|
570
|
+
readonly sheet: string;
|
|
571
|
+
readonly range: string;
|
|
572
|
+
/** First value; defaults to the numeric first cell of `range`. */
|
|
573
|
+
readonly start?: number;
|
|
574
|
+
/** Step; defaults to the difference of the first two cells, else `1`. */
|
|
575
|
+
readonly step?: number;
|
|
576
|
+
} | {
|
|
577
|
+
/**
|
|
578
|
+
* Moves `range` into the transposed rectangle anchored at `target`.
|
|
579
|
+
* Cell contents, styles and formula sources move verbatim, while
|
|
580
|
+
* relative references inside formulas are not rewritten. Merged cells
|
|
581
|
+
* and destinations that overlap the source are rejected.
|
|
582
|
+
*/
|
|
583
|
+
readonly op: 'range.transpose';
|
|
584
|
+
readonly sheet: string;
|
|
585
|
+
readonly range: string;
|
|
586
|
+
/** Top-left cell of the destination rectangle. */
|
|
587
|
+
readonly target: CellAddress;
|
|
588
|
+
} | RangeCopyOperation | RangeMoveOperation | RangeSwapOperation | RangeFlipOperation | {
|
|
589
|
+
readonly op: 'range.clear';
|
|
590
|
+
readonly sheet: string;
|
|
591
|
+
readonly range: string;
|
|
592
|
+
};
|
|
593
|
+
/** Request of `Workbook.edit()`. */
|
|
594
|
+
export interface EditRequest {
|
|
595
|
+
/** Rejects the write when the workbook moved past this revision. */
|
|
596
|
+
readonly expectedRevision?: number;
|
|
597
|
+
readonly operations: readonly EditOperation[];
|
|
598
|
+
}
|
|
599
|
+
/** Result of one committed edit. */
|
|
600
|
+
export interface EditResult {
|
|
601
|
+
readonly revision: number;
|
|
602
|
+
readonly workbook: Workbook;
|
|
603
|
+
/** Occurrences changed by `cell.replaceText` operations. */
|
|
604
|
+
readonly replacements: number;
|
|
605
|
+
/** Rectangles and replacement counts recorded by the batch. */
|
|
606
|
+
readonly affected?: readonly AffectedRange[];
|
|
607
|
+
}
|
|
608
|
+
/** Which field a find hit matched. */
|
|
609
|
+
export type FindField = 'value' | 'formula';
|
|
610
|
+
/** Options of `Workbook.find()`. Both channels are searched by default. */
|
|
611
|
+
export interface FindOptions {
|
|
612
|
+
/** Match case exactly; defaults to false. */
|
|
613
|
+
readonly matchCase?: boolean;
|
|
614
|
+
/** Search formula sources; defaults to true. */
|
|
615
|
+
readonly formulas?: boolean;
|
|
616
|
+
/** Search evaluated values; defaults to true. */
|
|
617
|
+
readonly values?: boolean;
|
|
618
|
+
}
|
|
619
|
+
/** Request of `Workbook.find()`. */
|
|
620
|
+
export interface FindRequest {
|
|
621
|
+
readonly query: string;
|
|
622
|
+
/** Sheet name or id; every sheet when omitted. */
|
|
623
|
+
readonly sheet?: string;
|
|
624
|
+
readonly options?: FindOptions;
|
|
625
|
+
}
|
|
626
|
+
/** One match, with character offsets into the searched field. */
|
|
627
|
+
export interface FindHit {
|
|
628
|
+
readonly sheet: string;
|
|
629
|
+
readonly address: CellAddress;
|
|
630
|
+
readonly field: FindField;
|
|
631
|
+
readonly start: number;
|
|
632
|
+
readonly end: number;
|
|
633
|
+
readonly text: string;
|
|
634
|
+
}
|
|
635
|
+
/** Result of `Workbook.find()`. */
|
|
636
|
+
export interface FindResult {
|
|
637
|
+
readonly hits: readonly FindHit[];
|
|
638
|
+
/** True when the engine stopped at its 500-hit cap with more matches left. */
|
|
639
|
+
readonly truncated: boolean;
|
|
640
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Workbook types of `@wae/open-excel`.
|
|
3
|
+
*
|
|
4
|
+
* This is the frozen P0 shape of the surface: `new OpenExcel(options?)` creates
|
|
5
|
+
* a session, `create`/`open` return a `Workbook` summary, and every sheet keeps
|
|
6
|
+
* a stable identity plus an index used only for ordering.
|
|
7
|
+
*
|
|
8
|
+
* Addresses are A1-style strings. Geometry and pixels never enter the model; a
|
|
9
|
+
* future renderer projects the engine's own layout.
|
|
10
|
+
*/
|
|
11
|
+
export {};
|