@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 CHANGED
@@ -1,3 +1,51 @@
1
- # Temporary Holding Version
1
+ # @wae/open-excel
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
+ The session API behind the `open-excel` CLI: one workbook handle for reading, editing, inspecting, searching, recalculating and exporting.
4
+
5
+ ## API surface
6
+
7
+ `new OpenExcel(options?)` creates a session. Nothing is opened until an async method runs; `dispose()` releases every workbook handle the session still tracks.
8
+
9
+ ```ts
10
+ const excel = new OpenExcel({ locale: 'en' });
11
+
12
+ await excel.capabilities(); // formats, checks, formulas, renderers, export targets
13
+
14
+ const book = await excel.create({ title: 'Ledger' });
15
+ const opened = await excel.open({ path: 'ledger.oexcel' });
16
+ await excel.summary(book); // sheets, revisions and cell counts
17
+ await excel.save(book, { target: 'copy.oexcel', overwrite: true });
18
+
19
+ await excel.edit(book, { operations }); // atomic batch; one revision advance
20
+ await excel.cell(book, { sheet: 'Sheet1', address: 'B4' });
21
+ await excel.range(book, { sheet: 'Sheet1', range: 'A1:D10' });
22
+ await excel.recalc(book); // recompute every formula
23
+ await excel.find(book, { query: 'invoice' }); // values and formulas, 500-hit cap
24
+
25
+ await excel.export(book, { format: 'xlsx', target: 'ledger.xlsx', overwrite: true });
26
+ const svg = await excel.render(book, { sheet: 'Sheet1' });
27
+ await excel.dispose();
28
+ ```
29
+
30
+ `edit()` accepts these operations: `cell.set`, `range.set`, `range.copy`, `range.move`, `range.swap`, `range.flip`, `range.sort`, `range.fillSeries`, `range.transpose`, `range.clear`, `range.clearContents`, `format.set`, `format.clear`, `format.copy`, `merge.set`, `sheet.freeze`, `sheet.setVisibility`, `sheet.add`, `sheet.rename`, `sheet.remove`, `sheet.duplicate`, `sheet.move`, `row.insert`, `row.delete`, `column.insert`, `column.delete`, `row.setHeight`, `column.setWidth` and `cell.replaceText` (range optional, with `limit`). Pass `expectedRevision` to reject a stale writer.
31
+
32
+ Export targets are `xlsx`, `csv`, `tsv`, `json`, `html` and `pdf`; `xlsm` export is not available. CSV, TSV and HTML write the primary sheet and report skipped sheets as losses. PDF is partial and reports its own loss codes. `open()` reads a path to `.oexcel`, `.xlsx`, `.xlsm`, `.csv` or `.tsv`; in-memory bytes and non-edit intents are rejected. Failures are `OpenExcelError` instances with one of the stable codes from `errorCodes`.
33
+
34
+ ## Example
35
+
36
+ ```ts
37
+ import { OpenExcel } from '@wae/open-excel';
38
+
39
+ const excel = new OpenExcel();
40
+ const book = await excel.create({ title: 'Ledger' });
41
+ await excel.edit(book, {
42
+ operations: [{ op: 'cell.set', sheet: 'Sheet1', reference: 'A1', formula: '=SUM(B1:B3)' }],
43
+ });
44
+ console.log((await excel.cell(book, { address: 'A1' })).value);
45
+ ```
46
+
47
+ ## Related packages
48
+
49
+ - [OpenExcel root README](../../../readme.md)
50
+ - [@wae/open-excel-skills](../open-excel-skills/README.md)
51
+ - [@wae/open-excel-ui](../open-excel-ui/README.md)
package/dist/cli.d.ts ADDED
@@ -0,0 +1,10 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Command-line assembly only.
4
+ *
5
+ * Every command maps options onto one method of `new OpenExcel()`; workbook
6
+ * logic, saving and export stay native. Help text and errors come from
7
+ * `@wae/commander`, so the CLI does not grow its own parser.
8
+ */
9
+ declare const cli: import("@wae/commander").Cli;
10
+ export { cli };