@sheetxl/scripting 0.7.21 → 0.7.23-beta.1
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 +208 -229
- package/browser/cjs/1_xhnTjP6m5oj6za.cjs +21 -0
- package/browser/cjs/6XTQ1BNSLrTHmFNH.cjs +1 -0
- package/browser/cjs/Bu4cZ8iSZ3rij-oV.cjs +1 -0
- package/browser/cjs/BvG8N7G_8CXIAlT-.cjs +1 -0
- package/browser/cjs/C_7w8EJZpHw8ueuq.cjs +1 -0
- package/browser/cjs/C_IEgjM-hSJCv6Gm.cjs +1 -0
- package/browser/cjs/CctaCN_w3o34V9AR.cjs +1 -0
- package/browser/cjs/DSEShe7kGtxvljOr.cjs +1 -0
- package/browser/cjs/GBmIbvhpXGNyZh4W.cjs +1 -0
- package/browser/cjs/index.cjs +1 -6
- package/browser/cjs/qWYyYsBboXc9p0Lw.cjs +7 -0
- package/browser/esm/B2O6_lZVwu7HGlcx.mjs +8 -0
- package/browser/esm/B7Axspg8vBnT9M3x.mjs +421 -0
- package/browser/esm/BVMNJQoqhXCkbrAc.mjs +87 -0
- package/browser/esm/BX3qwglupa6Y59lz.mjs +27 -0
- package/browser/esm/C1gdnq2DZdt3y7zD.mjs +23 -0
- package/browser/esm/CD2q23uuB7okp3Dl.mjs +152 -0
- package/browser/esm/CabN_0aQQRRyMDbw.mjs +12 -0
- package/browser/esm/D8K5BUCHuJ9gEpKs.mjs +105 -0
- package/browser/esm/DYjJCR6wkeLLkRm6.mjs +15 -0
- package/browser/esm/Qyh7uNkqdCcPtgBO.mjs +25 -0
- package/browser/esm/index.mjs +40 -20
- package/node/esm/47V_H-QS1YIyY07o.mjs +14 -0
- package/node/esm/B2O6_lZVwu7HGlcx.mjs +8 -0
- package/node/esm/CFY3Dm5Wl-fatf70.mjs +421 -0
- package/node/esm/CPB_iNIWuPOW5OPJ.mjs +152 -0
- package/node/esm/CaKTS-uKPFUYE8z9.mjs +27 -0
- package/node/esm/DGA9ykmJTQwzArFh.mjs +17 -0
- package/node/esm/DXc-q9b4X6dKKFs-.mjs +12 -0
- package/node/esm/index.mjs +144 -20
- package/node/esm/jw7wu0yKXfqYBchM.mjs +23 -0
- package/package.json +11 -8
- package/types/index.d.ts +2 -165
- package/types/src/ScriptCompiler.d.ts +40 -0
- package/types/src/ScriptCompiler.d.ts.map +1 -0
- package/types/src/compiler/Bundler.d.ts +7 -0
- package/types/src/compiler/Bundler.d.ts.map +1 -0
- package/types/src/compiler/TypescriptCompiler.d.ts +27 -0
- package/types/src/compiler/TypescriptCompiler.d.ts.map +1 -0
- package/types/src/compiler/TypescriptCompiler.impl.d.ts +17 -0
- package/types/src/compiler/TypescriptCompiler.impl.d.ts.map +1 -0
- package/types/src/compiler/TypescriptCompiler.worker.d.ts +2 -0
- package/types/src/compiler/TypescriptCompiler.worker.d.ts.map +1 -0
- package/types/src/compiler/compiler.browser.d.ts +8 -0
- package/types/src/compiler/compiler.browser.d.ts.map +1 -0
- package/types/src/compiler/compiler.node.d.ts +14 -0
- package/types/src/compiler/compiler.node.d.ts.map +1 -0
- package/types/src/compiler/constants.d.ts +10 -0
- package/types/src/compiler/constants.d.ts.map +1 -0
- package/types/src/compiler/insertYieldBetweenStatements.d.ts +5 -0
- package/types/src/compiler/insertYieldBetweenStatements.d.ts.map +1 -0
- package/types/src/compiler/transformAwaitToYield.d.ts +6 -0
- package/types/src/compiler/transformAwaitToYield.d.ts.map +1 -0
- package/types/src/index.d.ts +7 -0
- package/types/src/index.d.ts.map +1 -0
- package/types/src/lib/esbuild/esbuild.browser.d.ts +4 -0
- package/types/src/lib/esbuild/esbuild.browser.d.ts.map +1 -0
- package/types/src/lib/esbuild/esbuild.node.d.ts +11 -0
- package/types/src/lib/esbuild/esbuild.node.d.ts.map +1 -0
- package/types/src/lib/typescript/typescript.browser.d.ts +4 -0
- package/types/src/lib/typescript/typescript.browser.d.ts.map +1 -0
- package/types/src/lib/typescript/typescript.node.d.ts +4 -0
- package/types/src/lib/typescript/typescript.node.d.ts.map +1 -0
- package/types/src/linter/Linter.d.ts +63 -0
- package/types/src/linter/Linter.d.ts.map +1 -0
- package/types/src/linter/index.d.ts +2 -0
- package/types/src/linter/index.d.ts.map +1 -0
- package/types/src/loader/index.d.ts +2 -0
- package/types/src/loader/index.d.ts.map +1 -0
- package/types/src/loader/loadCompiledModule.d.ts +19 -0
- package/types/src/loader/loadCompiledModule.d.ts.map +1 -0
- package/types/src/loader/moduleLoader.browser.d.ts +11 -0
- package/types/src/loader/moduleLoader.browser.d.ts.map +1 -0
- package/types/src/loader/moduleLoader.node.d.ts +15 -0
- package/types/src/loader/moduleLoader.node.d.ts.map +1 -0
- package/types/src/plugin/generate.d.ts +17 -0
- package/types/src/plugin/generate.d.ts.map +1 -0
- package/types/src/plugin/vite.d.ts +24 -0
- package/types/src/plugin/vite.d.ts.map +1 -0
- package/types/src/runtime/Constants.d.ts +9 -0
- package/types/src/runtime/Constants.d.ts.map +1 -0
- package/types/src/runtime/index.d.ts +2 -0
- package/types/src/runtime/index.d.ts.map +1 -0
- package/types/src/tags/DocTags.d.ts +46 -0
- package/types/src/tags/DocTags.d.ts.map +1 -0
- package/types/src/tags/index.d.ts +2 -0
- package/types/src/tags/index.d.ts.map +1 -0
- package/types/src/type/CompileOptions.d.ts +58 -0
- package/types/src/type/CompileOptions.d.ts.map +1 -0
- package/types/src/type/CompiledModule.d.ts +70 -0
- package/types/src/type/CompiledModule.d.ts.map +1 -0
- package/types/src/type/Diagnostic.d.ts +120 -0
- package/types/src/type/Diagnostic.d.ts.map +1 -0
- package/types/src/type/Types.d.ts +72 -0
- package/types/src/type/Types.d.ts.map +1 -0
- package/types/src/type/index.d.ts +6 -0
- package/types/src/type/index.d.ts.map +1 -0
- package/types/src/worker/WorkerWrapper.d.ts +44 -0
- package/types/src/worker/WorkerWrapper.d.ts.map +1 -0
- package/types/src/worker/index.d.ts +2 -0
- package/types/src/worker/index.d.ts.map +1 -0
- package/browser/cjs/B0y4r3JJPPSwiDzx.cjs +0 -6
- package/browser/cjs/CGLLj80MYA2hDUWX.cjs +0 -1512
- package/browser/cjs/CTIIZ0KnyksL075e.cjs +0 -32
- package/browser/cjs/CUcC81sgg70TCSkb.cjs +0 -6
- package/browser/cjs/DR9eQnRTjdCvZ_vn.cjs +0 -6
- package/browser/esm/C3Kam_ffnenXH9Ry.mjs +0 -264
- package/browser/esm/CWnC_tpttjXTMAYH.mjs +0 -29
- package/browser/esm/D9QqdtRf0J6jc-i7.mjs +0 -21
- package/browser/esm/Dfs-JW1Cpyj6GJ8P.mjs +0 -1587
- package/browser/esm/DpMJmUGhnNbeI2fN.mjs +0 -24
- package/node/esm/Bk7d3p9VfcJCsNVL.mjs +0 -264
- package/node/esm/CLf-vRuFGkk8X4S9.mjs +0 -29
- package/node/esm/CQR30SbeLa27Szfg.mjs +0 -1587
- package/node/esm/DL3QM-qR0v00NdZZ.mjs +0 -16
- package/node/esm/u4BUV-OpkSGdvi-w.mjs +0 -14
package/README.md
CHANGED
|
@@ -1,316 +1,295 @@
|
|
|
1
|
-
# SheetXL
|
|
1
|
+
# SheetXL Scripting
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
|
-
<
|
|
5
|
-
|
|
4
|
+
<a href="https://www.sheetxl.com" target="_blank">
|
|
5
|
+
<img src="https://www.sheetxl.com/logo-text.svg" alt="SheetXL Logo" width="180" />
|
|
6
|
+
</a>
|
|
6
7
|
</p>
|
|
7
8
|
|
|
8
|
-
|
|
9
|
-
[](https://www.npmjs.com/package/@sheetxl/studio-mui)
|
|
10
|
-
[](https://www.npmjs.com/package/@sheetxl/studio-mui)
|
|
9
|
+
Scripting engine for SheetXL. Compile and execute custom macros and user-defined functions (UDFs) with full type safety and modern tooling.
|
|
11
10
|
|
|
12
|
-
|
|
11
|
+
[](https://www.npmjs.com/package/@sheetxl/scripting)
|
|
12
|
+
[](https://www.npmjs.com/package/@sheetxl/scripting)
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## Overview
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
`@sheetxl/scripting` is the compilation engine that powers SheetXL's live scripting capabilities. It compiles TypeScript/JavaScript source code into optimized, executable modules containing **macros** and **formula functions (UDFs)**.
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
**Key Features**:
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
- 🔧 TypeScript and JavaScript compilation with full type checking
|
|
21
|
+
- ⚡ Browser and Node.js support with platform-optimized builds
|
|
22
|
+
- 🎯 Generates function manifests with type signatures and metadata
|
|
23
|
+
- 🔒 Code minification and bundling for production deployments
|
|
24
|
+
- 🌐 Web Worker support for non-blocking compilation
|
|
25
|
+
- 📦 ESBuild and TypeScript integration
|
|
21
26
|
|
|
22
|
-
|
|
23
|
-
*Headless API. Live Scripting. Built for developers.*
|
|
27
|
+
## Use Cases
|
|
24
28
|
|
|
25
|
-
###
|
|
29
|
+
### Standalone Compilation
|
|
26
30
|
|
|
27
|
-
|
|
31
|
+
Use `ScriptCompiler` directly to compile (or just lint) TypeScript source into an executable
|
|
32
|
+
module:
|
|
28
33
|
|
|
29
|
-
|
|
34
|
+
```typescript
|
|
35
|
+
import { ScriptCompiler } from '@sheetxl/scripting';
|
|
30
36
|
|
|
31
|
-
|
|
37
|
+
const { module, diagnostics } = await ScriptCompiler.compile({
|
|
38
|
+
source: `
|
|
39
|
+
/**
|
|
40
|
+
* @summary Calculate compound interest
|
|
41
|
+
*/
|
|
42
|
+
export function compoundInterest(
|
|
43
|
+
principal: number,
|
|
44
|
+
rate: number,
|
|
45
|
+
years: number
|
|
46
|
+
): number {
|
|
47
|
+
return principal * Math.pow(1 + rate, years);
|
|
48
|
+
}
|
|
49
|
+
`
|
|
50
|
+
});
|
|
32
51
|
|
|
33
|
-
|
|
52
|
+
// diagnostics: positioned errors + warnings for this compile.
|
|
53
|
+
// module: the CompiledModule (functions + executable code), or null if there was no source.
|
|
54
|
+
// When any diagnostic has severity 'error', module.compiled is omitted and must not run.
|
|
34
55
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
npm install @sheetxl/sdk @sheetxl/studio-mui @mui/material @emotion/react @emotion/styled
|
|
38
|
-
|
|
39
|
-
# Using yarn
|
|
40
|
-
yarn add @sheetxl/sdk @sheetxl/studio-mui @mui/material @emotion/react @emotion/styled
|
|
56
|
+
// Fast path for editors — diagnostics only, no code emit:
|
|
57
|
+
const problems = await ScriptCompiler.lint(`export function f(x: number) { return x; }`);
|
|
41
58
|
```
|
|
42
59
|
|
|
43
|
-
###
|
|
44
|
-
|
|
45
|
-
```javascript
|
|
46
|
-
import React from 'react';
|
|
47
|
-
import { Studio } from '@sheetxl/studio-mui';
|
|
48
|
-
|
|
49
|
-
function App() {
|
|
50
|
-
// SheetXL will fill it's parent container.
|
|
51
|
-
return (
|
|
52
|
-
<div style={{ height: '600px', width: '100%' }}>
|
|
53
|
-
<Studio />
|
|
54
|
-
</div>
|
|
55
|
-
);
|
|
56
|
-
}
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
For more advanced setup options, check out our full
|
|
60
|
-
[Getting Started Guides](https://www.sheetxl.com/docs/guides/category/getting-started).
|
|
61
|
-
|
|
62
|
-
### 📚 Ecosystem Overview
|
|
63
|
-
|
|
64
|
-
The SheetXL ecosystem is modular by design. You can use only what you need — or compose it all together.
|
|
65
|
-
|
|
66
|
-
### SDK
|
|
67
|
-
|
|
68
|
-
At the core of the ecosystem is a **headless, high-performance SDK** [`@sheetxl/sdk`](https://www.npmjs.com/package/@sheetxl/sdk),
|
|
69
|
-
built to power everything from lightweight grid widgets to massive enterprise-scale calculation engines
|
|
70
|
-
|
|
71
|
-
Key features:
|
|
72
|
-
|
|
73
|
-
* **Blazing Speed:** Executes 10M+ operations per second and handles spreadsheets with 17B+ cells.
|
|
74
|
-
* **Powerful API:** A modern, vectorized, range-based API for precise, scriptable control over data — independent of any UI.
|
|
75
|
-
|
|
76
|
-
### Applications and UI Toolkits
|
|
77
|
-
|
|
78
|
-
Build UIs your way — from plug-and-play dashboards to fully custom design systems.
|
|
79
|
-
|
|
80
|
-
* **Rapid Deployment** [`@sheetxl/studio-mui`](https://www.npmjs.com/package/@sheetxl/studio-mui): A complete, open-source spreadsheet UI with Excel-grade features. Ready to ship.
|
|
81
|
-
* **Custom Interface** [`@sheetxl/react`](https://www.npmjs.com/package/@sheetxl/react): A flexible component and hook library for deep customization.
|
|
82
|
-
|
|
83
|
-
### I/O Connectors
|
|
60
|
+
### Integration with @sheetxl/sdk
|
|
84
61
|
|
|
85
|
-
|
|
62
|
+
Primary use case — enables macros and custom UDFs within spreadsheets via `workbook.getScripts()`:
|
|
86
63
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
* `parquet` (in progress)
|
|
90
|
-
* `json` (native format)
|
|
64
|
+
```typescript
|
|
65
|
+
import { Workbook } from '@sheetxl/sdk';
|
|
91
66
|
|
|
92
|
-
|
|
93
|
-
|
|
67
|
+
const workbook = new Workbook();
|
|
68
|
+
const scripts = workbook.getScripts();
|
|
94
69
|
|
|
95
|
-
|
|
70
|
+
// Compile and register a reusable module
|
|
71
|
+
const module = await scripts.createModule({
|
|
72
|
+
source: `
|
|
73
|
+
/**
|
|
74
|
+
* @summary Double the value
|
|
75
|
+
*/
|
|
76
|
+
export function DOUBLE(value: number): number {
|
|
77
|
+
return value * 2;
|
|
78
|
+
}
|
|
96
79
|
|
|
97
|
-
|
|
80
|
+
/**
|
|
81
|
+
* @summary Set active cell value
|
|
82
|
+
*/
|
|
83
|
+
export function setCellValue(cell: ICell, value: any): void {
|
|
84
|
+
cell.setValue(value);
|
|
85
|
+
}
|
|
86
|
+
`
|
|
87
|
+
});
|
|
98
88
|
|
|
99
|
-
|
|
100
|
-
|--------------|-------------------------|-----------------------------|---------|
|
|
101
|
-
| Core | @sheetxl/sdk 💎 | Headless spreadsheet API | Commercial |
|
|
102
|
-
| | @sheetxl/formulas | Collection of 400+ formulas | MIT |
|
|
103
|
-
| | @sheetxl/primitives | Low level types (Scalar, IRange) | MIT |
|
|
104
|
-
| | @sheetxl/scripting 💎 | Scripting engine and compiler | Commercial |
|
|
105
|
-
| IO | @sheetxl/io | Import/export (xlsx, csv, json) | MIT |
|
|
106
|
-
| Applications | @sheetxl/studio-vanilla | Framework-agnostic spreadsheet app | MIT |
|
|
107
|
-
| | @sheetxl/studio-mui | Spreadsheet app powered by React/MUI | MIT |
|
|
108
|
-
| UI Toolkits | @sheetxl/react 💎 | Spreadsheet React UI components and hooks | Commercial |
|
|
109
|
-
| | @sheetxl/grid-react 💎 | Lightweight, standalone React data grid | Commercial |
|
|
110
|
-
| Utils | @sheetxl/utils | Headless utilities (math, ranges, etc) | MIT |
|
|
111
|
-
| | @sheetxl/utils-react | React UI helpers | MIT |
|
|
112
|
-
| | @sheetxl/utils-mui | MUI UI helpers (color picker, dialogs, etc) | MIT |
|
|
89
|
+
scripts.addModule('my-functions', module);
|
|
113
90
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
SheetXL is built on four core pillars: extreme performance, deep Excel compatibility, unparalleled developer power, and a modern, extensible architecture.
|
|
119
|
-
|
|
120
|
-
* **Performance & Scale**
|
|
121
|
-
|
|
122
|
-
Process 10M+ ops/second and manage massive 17B+ cell workbooks, all in-browser.
|
|
123
|
-
|
|
124
|
-
* **True Excel Fidelity**
|
|
125
|
-
|
|
126
|
-
Go beyond basic formulas. Get the Excel-grade features your users demand, from tables and charts to cross-sheet copy/paste.
|
|
91
|
+
// Use in formulas: =DOUBLE(A1)
|
|
92
|
+
// Execute a macro: scripts.executeMacro('setCellValue', 'my-functions')
|
|
93
|
+
```
|
|
127
94
|
|
|
128
|
-
|
|
95
|
+
For a single "make a change" action you don't need to register, use the one-shot primitive — it
|
|
96
|
+
runs the default export once inside a single undo transaction:
|
|
129
97
|
|
|
130
|
-
|
|
98
|
+
```typescript
|
|
99
|
+
await workbook.getScripts().run(`
|
|
100
|
+
export default function (workbook) {
|
|
101
|
+
workbook.getRange('A1').setValue(42);
|
|
102
|
+
}
|
|
103
|
+
`);
|
|
104
|
+
```
|
|
131
105
|
|
|
132
|
-
|
|
106
|
+
### Build-Time Formula Generation
|
|
133
107
|
|
|
134
|
-
|
|
108
|
+
To author built-in formulas as TypeScript source and generate a registry at build time, use the
|
|
109
|
+
Vite plugin exported at `@sheetxl/scripting/vite/formula-compiler`. See
|
|
110
|
+
[README-FORMULA-COMPILER-PLUGIN.md](./README-FORMULA-COMPILER-PLUGIN.md).
|
|
135
111
|
|
|
136
|
-
|
|
112
|
+
## Function Types
|
|
137
113
|
|
|
138
|
-
|
|
139
|
-
* 400+ Excel-compatible formulas
|
|
140
|
-
* Full fidelity Excel import/export
|
|
141
|
-
* Scripting Engine
|
|
142
|
-
* Fast. Autofill 1,048,576 rows with formulas in 0.7s (10M+ formulas/second)
|
|
114
|
+
The scripting engine supports two types of exported functions:
|
|
143
115
|
|
|
144
|
-
|
|
145
|
-
<summary><b>Click to see the full list of additional User Features...</b></summary>
|
|
116
|
+
### Formula Functions (UDFs)
|
|
146
117
|
|
|
147
|
-
|
|
148
|
-
* Hidden Rows/Columns
|
|
149
|
-
* Frozen Rows/Columns
|
|
150
|
-
* Resizable, Auto-fit Rows/Columns
|
|
151
|
-
* Office Theme (Color Picker, Theme Selector)
|
|
152
|
-
* Cell Styles (Themes and Formatting)
|
|
153
|
-
* Preset Cell Style Selector
|
|
154
|
-
* Overflow, Word-wrap
|
|
155
|
-
* Borders
|
|
156
|
-
* Tables
|
|
157
|
-
* Drawings
|
|
158
|
-
* Multi-range selection
|
|
159
|
-
* Merged Cells
|
|
160
|
-
* Autofill
|
|
161
|
-
* Keyboard Accessible Support for all Excel shortcut keys
|
|
162
|
-
* Undo/Redo
|
|
163
|
-
* Find/Replace
|
|
164
|
-
* Sort
|
|
165
|
-
* Zoom
|
|
166
|
-
* Hyperlinks
|
|
167
|
-
* Mobile Friendly (Touch / Small screen accommodation)
|
|
118
|
+
Custom functions usable in spreadsheet formulas:
|
|
168
119
|
|
|
169
|
-
|
|
120
|
+
- Accept: `number`, `string`, `boolean`, `IRange`, `IReferenceRange`, arrays, variadic args
|
|
121
|
+
- Return: Any scalar value, array, or `IRange`
|
|
122
|
+
- Invoked: During formula calculation/recalculation
|
|
123
|
+
- Example: `export function TAX(amount: number, rate: number): number`
|
|
170
124
|
|
|
171
|
-
###
|
|
125
|
+
### Macro Functions
|
|
172
126
|
|
|
173
|
-
|
|
174
|
-
* Easy Integration
|
|
127
|
+
Imperative operations that modify spreadsheet state:
|
|
175
128
|
|
|
176
|
-
|
|
177
|
-
|
|
129
|
+
- Accept: `ICell`, `ICellRange`, `ISheet`, `IWorkbook`, scalars (via UI prompt)
|
|
130
|
+
- Return: `void`, `Promise<void>`, or cleanup function `() => void`
|
|
131
|
+
- Invoked: Via UI menu, buttons, or as autorun on workbook load
|
|
132
|
+
- Example: `export function formatHeader(range: ICellRange): void`
|
|
178
133
|
|
|
179
|
-
|
|
180
|
-
* Built from the ground up using React and CSS-in-JS components.
|
|
181
|
-
* Fully functional MIT Open-sourced Material-UI Application.
|
|
182
|
-
* Headless spreadsheet API can be used without UI and on server or as library.
|
|
183
|
-
* Easily extend functions with simple registration.
|
|
134
|
+
## Compilation Output
|
|
184
135
|
|
|
185
|
-
|
|
136
|
+
`ScriptCompiler.compile` returns a `CompileResult` — the compiled artifact plus this compile's
|
|
137
|
+
diagnostics:
|
|
186
138
|
|
|
187
|
-
|
|
139
|
+
```typescript
|
|
140
|
+
interface CompileResult {
|
|
141
|
+
module: CompiledModule | null; // null when there was no source to compile
|
|
142
|
+
diagnostics: Diagnostic[]; // positioned errors + warnings for this compile
|
|
143
|
+
}
|
|
188
144
|
|
|
189
|
-
|
|
145
|
+
interface CompiledModule {
|
|
146
|
+
// Declaration + descriptor pair per exported function (type signature, summary, metadata).
|
|
147
|
+
functions: [IFunction.DeclarationJSON, IFunction.DescriptorJSON][];
|
|
190
148
|
|
|
191
|
-
|
|
192
|
-
|
|
149
|
+
source?: string; // original human-readable source
|
|
150
|
+
compiled?: string; // executable code, ready to run (omitted when there are error diagnostics)
|
|
151
|
+
sourceMap?: string; // source map for the compiled code, when enabled
|
|
152
|
+
language?: string; // defaults to 'typescript'
|
|
153
|
+
autoRun?: string; // name of a function to run automatically on load
|
|
154
|
+
}
|
|
155
|
+
```
|
|
193
156
|
|
|
194
|
-
|
|
157
|
+
Diagnostics live on the (transient) `CompileResult`, not on the persisted `CompiledModule` — they
|
|
158
|
+
are a function of the source and are recomputable. When any diagnostic has `severity: 'error'`,
|
|
159
|
+
`module.compiled` is omitted and the artifact must not run.
|
|
195
160
|
|
|
196
|
-
|
|
197
|
-
* Full Styling in Excel Export
|
|
198
|
-
* Full Charting (nearly complete)
|
|
199
|
-
* Multi-key shortcuts
|
|
200
|
-
* Pivot
|
|
201
|
-
* Sparklines
|
|
202
|
-
* Slicer/Timeline
|
|
203
|
-
* Accessibility <https://www.w3.org/TR/WCAG21/>
|
|
204
|
-
* Printing
|
|
161
|
+
## Installation
|
|
205
162
|
|
|
206
|
-
|
|
163
|
+
```bash
|
|
164
|
+
npm install @sheetxl/scripting typescript esbuild-wasm
|
|
165
|
+
# or
|
|
166
|
+
pnpm add @sheetxl/scripting typescript esbuild-wasm
|
|
167
|
+
```
|
|
207
168
|
|
|
208
|
-
|
|
209
|
-
* Collaboration
|
|
169
|
+
**Note**: `typescript` and `esbuild-wasm` are peer dependencies.
|
|
210
170
|
|
|
211
|
-
|
|
171
|
+
## API Reference
|
|
212
172
|
|
|
213
|
-
|
|
173
|
+
`ScriptCompiler` is the compile/lint facade. The heavy engine (compiler worker, linter) is loaded
|
|
174
|
+
lazily via dynamic `import()`, so referencing `ScriptCompiler` does not pull it into a bundle until
|
|
175
|
+
you actually compile or lint.
|
|
214
176
|
|
|
215
|
-
|
|
177
|
+
### ScriptCompiler.compile(options)
|
|
216
178
|
|
|
217
|
-
|
|
179
|
+
Compiles TypeScript source into an executable module.
|
|
218
180
|
|
|
219
|
-
|
|
220
|
-
|
|
181
|
+
```typescript
|
|
182
|
+
interface CompileOptions {
|
|
183
|
+
source: string; // TypeScript source code
|
|
184
|
+
declarationsOnly?: boolean; // validation only — emit declarations, skip the bundle
|
|
185
|
+
disableBundle?: boolean; // omit the executable bundle from the result (validation)
|
|
186
|
+
disableSourceMap?: boolean; // omit the source map from the result
|
|
187
|
+
commitId?: string; // identifier stamped on the compiled module
|
|
188
|
+
}
|
|
189
|
+
```
|
|
221
190
|
|
|
222
|
-
|
|
223
|
-
* Real time integration/validation of your data.
|
|
224
|
-
* Complete control of data as your data never leaves your systems.
|
|
225
|
-
* Improved user productivity.
|
|
226
|
-
* Combine custom user enhancements with flexible data manipulation.
|
|
191
|
+
**Returns**: `Promise<CompileResult>`
|
|
227
192
|
|
|
228
|
-
###
|
|
193
|
+
### ScriptCompiler.lint(source)
|
|
229
194
|
|
|
230
|
-
|
|
195
|
+
Lints source against SheetXL's authoring rules and returns positioned diagnostics, without emitting
|
|
196
|
+
JavaScript. The fast path for editors.
|
|
231
197
|
|
|
232
|
-
|
|
198
|
+
**Returns**: `Promise<Diagnostic[]>`
|
|
233
199
|
|
|
234
|
-
|
|
200
|
+
### ScriptCompiler.cleanup()
|
|
235
201
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
* Billions of cells.
|
|
239
|
-
* Comprehensive support for keyboard shortcuts (e.g. tabbing within multi-selected ranges, arrow-keys within cells).
|
|
240
|
-
* Enable advanced copy / paste between Excel/Excel Online/Google Sheets.
|
|
241
|
-
* Easily extendable libraries that use open-source and modern design patterns.
|
|
242
|
-
* Real-time integration to data providing a single source of truth; no copying data between systems using complex APIs.
|
|
202
|
+
Terminates the compiler worker and releases resources. Optional but recommended when the host needs
|
|
203
|
+
to free the worker.
|
|
243
204
|
|
|
244
|
-
|
|
205
|
+
### Platform Support
|
|
245
206
|
|
|
246
|
-
|
|
207
|
+
The package builds for dual targets:
|
|
247
208
|
|
|
248
|
-
|
|
249
|
-
|
|
209
|
+
- **Browser**: Uses Web Workers for non-blocking compilation
|
|
210
|
+
- **Node.js**: Direct compilation with native modules
|
|
250
211
|
|
|
251
|
-
|
|
252
|
-
* <https://github.com/jspreadsheet/ce> <https://jspreadsheet.com/v8> (6,400 :star:)
|
|
253
|
-
* <https://github.com/myliang/x-spreadsheet> <https://myliang.github.io/x-spreadsheet> (13,500 :star:)
|
|
254
|
-
* <https://github.com/nadbm/react-datasheet> <https://nadbm.github.io/react-datasheet> (5,300 :star:)
|
|
255
|
-
* <https://github.com/adazzle/react-data-grid> (6,200 :star:)
|
|
256
|
-
* <https://iddan.github.io/react-spreadsheet> (1,000 :star:)
|
|
212
|
+
Platform detection is automatic via conditional exports.
|
|
257
213
|
|
|
258
|
-
|
|
214
|
+
## Examples & Templates
|
|
259
215
|
|
|
260
|
-
|
|
261
|
-
|
|
216
|
+
Explore ready-to-use scripting templates at:
|
|
217
|
+
**[github.com/sheetxl/scripting-templates](https://github.com/sheetxl/scripting-templates)**
|
|
262
218
|
|
|
263
|
-
|
|
264
|
-
* <https://www.igniteui.com/spreadsheet/overview> <https://www.infragistics.com/products/ignite-ui-jquery/grids-and-lists/spreadsheet>
|
|
265
|
-
* <https://ej2.syncfusion.com/react/demos/#/bootstrap5/spreadsheet/default>
|
|
266
|
-
* <https://webix.com/demos/spreadsheet>
|
|
219
|
+
Templates include:
|
|
267
220
|
|
|
268
|
-
|
|
221
|
+
- Data validation and transformation
|
|
222
|
+
- Advanced calculations (financial, statistical)
|
|
223
|
+
- Batch operations and automation
|
|
224
|
+
- External API integration
|
|
225
|
+
- Custom data import/export
|
|
269
226
|
|
|
270
|
-
|
|
271
|
-
<summary><b>💲 Paid Data-grids...</b></summary>
|
|
227
|
+
## Architecture
|
|
272
228
|
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
229
|
+
``` bash
|
|
230
|
+
┌─────────────────────────────────────────┐
|
|
231
|
+
│ TypeScript/JavaScript Source Code │
|
|
232
|
+
└────────────┬────────────────────────────┘
|
|
233
|
+
│
|
|
234
|
+
▼
|
|
235
|
+
┌─────────────────────────────────────────┐
|
|
236
|
+
│ TypeScript Compiler + ESBuild │
|
|
237
|
+
│ - Type checking │
|
|
238
|
+
│ - Manifest generation │
|
|
239
|
+
│ - Code minification │
|
|
240
|
+
└────────────┬────────────────────────────┘
|
|
241
|
+
│
|
|
242
|
+
▼
|
|
243
|
+
┌─────────────────────────────────────────┐
|
|
244
|
+
│ CompiledModule │
|
|
245
|
+
│ - Executable code │
|
|
246
|
+
│ - Function manifest │
|
|
247
|
+
│ - Type signatures │
|
|
248
|
+
└────────────┬────────────────────────────┘
|
|
249
|
+
│
|
|
250
|
+
▼
|
|
251
|
+
┌─────────────────────────────────────────┐
|
|
252
|
+
│ Runtime Execution │
|
|
253
|
+
│ - SDK integration │
|
|
254
|
+
│ - Formula evaluation │
|
|
255
|
+
│ - Macro execution │
|
|
256
|
+
└─────────────────────────────────────────┘
|
|
257
|
+
```
|
|
276
258
|
|
|
277
|
-
|
|
278
|
-
* <https://www.ag-grid.com/example> (10,500 :star:)
|
|
279
|
-
* <https://mui.com/x/react-data-grid> (6,100 :star:)
|
|
280
|
-
* <https://www.datagridxl.com/>
|
|
259
|
+
## Performance
|
|
281
260
|
|
|
282
|
-
|
|
261
|
+
- **Compilation**: Runs in Web Workers (browser) to avoid blocking the main thread
|
|
262
|
+
- **Caching**: Compiled modules are cached to avoid recompilation
|
|
263
|
+
- **Minification**: Production code is optimized and minified
|
|
264
|
+
- **Lazy Loading**: TypeScript and ESBuild are loaded on-demand
|
|
283
265
|
|
|
284
|
-
|
|
285
|
-
<summary><b>💲 SAAS Spreadsheets...</b></summary>
|
|
266
|
+
## License
|
|
286
267
|
|
|
287
|
-
|
|
268
|
+
Commercial license. See [LICENSE](../../LICENSE.md) for details.
|
|
288
269
|
|
|
289
|
-
|
|
290
|
-
* <https://www.rows.com>
|
|
291
|
-
* <https://www.quadratichq.com/>
|
|
292
|
-
* <https://sourcetable.com//>
|
|
270
|
+
## Related Packages
|
|
293
271
|
|
|
294
|
-
|
|
272
|
+
- **[@sheetxl/sdk](https://npmjs.com/package/@sheetxl/sdk)** - Headless spreadsheet engine (primary integration point)
|
|
273
|
+
- **[@sheetxl/primitives](https://npmjs.com/package/@sheetxl/primitives)** - Core types and interfaces
|
|
274
|
+
- **[@sheetxl/utils](https://npmjs.com/package/@sheetxl/utils)** - Utility functions
|
|
295
275
|
|
|
296
|
-
##
|
|
276
|
+
## Resources
|
|
297
277
|
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
278
|
+
- 📘 [Documentation](https://www.sheetxl.com/docs/concepts/scripting) - Complete scripting guide
|
|
279
|
+
- 🔌 [API Reference](https://api.sheetxl.com) - Full API documentation
|
|
280
|
+
- 💬 [Discord Community](https://discord.gg/NTKdwUgK9p) - Get help and share ideas
|
|
281
|
+
- ⭐ [GitHub](https://github.com/sheetxl/sheetxl) - Star us and follow development
|
|
302
282
|
|
|
303
283
|
## 🔗 Learn More
|
|
304
284
|
|
|
305
285
|
Whether you're ready to build, need help, or just want to see more examples, here's where to go next.
|
|
306
286
|
|
|
307
|
-
* 💬 **[Join our Discord Community](https://discord.gg/NTKdwUgK9p)** - Get help and connect with the
|
|
287
|
+
* 💬 **[Join our Discord Community](https://discord.gg/NTKdwUgK9p)** - Get help and connect with the team.
|
|
308
288
|
* ⭐ **[Star us on GitHub](https://github.com/sheetxl/sheetxl)** - If you like SheetXL give us a star ⭐ and help others find us!
|
|
309
|
-
* 📘 **[Developer Docs](https://www.sheetxl.com/docs
|
|
289
|
+
* 📘 **[Developer Docs](https://www.sheetxl.com/docs)** - Guides and tutorials.
|
|
310
290
|
* 🔌 **[API Reference](https://api.sheetxl.com)** - Detailed documentation for all packages.
|
|
311
291
|
* 👀 **[Live Demo Gallery](https://www.sheetxl.com/demos)** - A showcase of interactive examples.
|
|
312
292
|
* 🖼️ **[Storybook](https://storybook.sheetxl.com)** - Explore and test individual UI components.
|
|
313
|
-
team.
|
|
314
293
|
* 🌐 **[Website](https://www.sheetxl.com)** - Our Website.
|
|
315
294
|
|
|
316
295
|
---
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
const e=require("./CctaCN_w3o34V9AR.cjs"),t=require("./qWYyYsBboXc9p0Lw.cjs"),n=require("./BvG8N7G_8CXIAlT-.cjs");let r=require("@sheetxl/utils");var i=null,a=null,o={compilerOptions:{target:`esnext`}};async function s(t,n,r=`/script.js`,s=e.n){try{let e=await async function(){if(i)return i;if(a){if(await a,!i)throw Error(`ESBuild initialization promise resolved, but instance is not available.`);return i}let e,t;a=new Promise((n,r)=>{e=n,t=r});try{let{initialize:t}=await Promise.resolve().then(()=>require("./C_7w8EJZpHw8ueuq.cjs"));return i=await t(),e(),i}catch(e){throw console.error(`Failed to import or initialize esbuild:`,e),a=null,t(e),e}}(),t=`@sheetxl/primitives`,c=`\n export const FormulaContext = globalThis.${s}?.FormulaContext;\n export const ScalarType = globalThis.${s}?.ScalarType;\n export const Observable = globalThis.${s}?.Observable;\n export const IRange = globalThis.${s}?.IRange;\n export const FormulaError = globalThis.${s}?.FormulaError;\n // Add more exports as needed\n `,l=await e.build({entryPoints:[r],bundle:!0,write:!1,format:`esm`,plugins:[{name:`sheetxl-esbuild-in-memory`,setup(e){let i=`sheetxl-`+new Date().getTime();e.onResolve({filter:RegExp(`^(${r.replace(`/`,`\\/`)}|${t})$`)},e=>({path:e.path,namespace:i})),e.onResolve({filter:/.*/},e=>{if(e.namespace!==i)return console.warn(`esbuild: Treating import "${e.path}" as external.`),{path:e.path,external:!0}}),e.onLoad({filter:/.*/,namespace:i},e=>{let a;if(e.path===r)a=n;else{if(e.path!==t)return{errors:[{text:`Cannot load unknown path in ${i}: ${e.path}`}]};a=c}return{contents:a,loader:`ts`}})}}],sourcemap:`inline`,tsconfigRaw:o,minify:!0,platform:`neutral`});if(l.outputFiles&&l.outputFiles.length>0)return l.outputFiles[0].text;throw l.errors&&l.errors.length>0?Error(`esbuild bundling failed: ${l.errors.map(e=>e.text).join(`
|
|
2
|
+
`)}`):Error(`esbuild did not produce an output file.`)}catch(e){throw console.error(`esbuild bundling process failed:`,e),e}}var c=async()=>`
|
|
3
|
+
interface FirstTest {
|
|
4
|
+
isTrue?: boolean;
|
|
5
|
+
}
|
|
6
|
+
`,l=null;async function u(){if(l)return l;try{return await(await Promise.resolve().then(()=>require("./C_IEgjM-hSJCv6Gm.cjs"))).initialize()}catch(e){throw l=null,e}finally{l=null}}exports.compileModule=async function(i){let a=i?.source??null;if(!a)return{module:null,diagnostics:[]};let o=(i.disableBundle||i.declarationsOnly)??!1,[l,d]=await Promise.all([c(),u()]),f=``,p={allowJs:!0,declaration:!1,sourceMap:!1,inlineSourceMap:!1,inlineSources:!1,isolatedModules:!0,preserveConstEnums:!1,module:99,noResolve:!0,emitDeclarationOnly:!1,target:d.ScriptTarget.ES2020},m=`script`,h=`${m}.ts`,g=`lib.d.ts`,_=`global.d.ts`,v={[h]:a,[g]:`
|
|
7
|
+
/**
|
|
8
|
+
* Represents the completion of an asynchronous operation
|
|
9
|
+
*/
|
|
10
|
+
interface Promise<T> {
|
|
11
|
+
/**
|
|
12
|
+
* Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The
|
|
13
|
+
* resolved value cannot be modified from the callback.
|
|
14
|
+
* @param onfinally The callback to execute when the Promise is settled (fulfilled or rejected).
|
|
15
|
+
* @returns A Promise for the completion of the callback.
|
|
16
|
+
*/
|
|
17
|
+
finally(onfinally?: (() => void) | undefined | null): Promise<T>;
|
|
18
|
+
}
|
|
19
|
+
`,[_]:l},y=d.createProgram([h,_],p,{getSourceFile:(e,t,n,r)=>d.createSourceFile(e,v[e],d.ScriptTarget.Latest,!0),fileExists:e=>v[e]!==void 0,readFile:e=>v[e],writeFile:(e,t)=>{v[e]=t},getCurrentDirectory:()=>`./`,getCanonicalFileName:e=>e,useCaseSensitiveFileNames:()=>!0,getDefaultLibFileName:e=>g,getNewLine:()=>`
|
|
20
|
+
`}),b=y.getTypeChecker(),x=y.getSourceFile(h);y.emit(),f=v[`${m}.js`]??``;let S=y.getSyntacticDiagnostics(x).map(e=>({start:e.start??0,length:e.length??0,severity:`error`,code:`TS${e.code}`,message:d.flattenDiagnosticMessageText(e.messageText,`
|
|
21
|
+
`)})),C=t.analyzeModule(d,x,b,{builtInNames:i.builtInNames}),w=[...S,...C.diagnostics],T=C.functions,E=C.autoRun,D=w.some(e=>e.severity===`error`),O=`${r.CommonUtils.uuidV4()}-script`,k=null;if(D)f=``;else{try{o||(f=await s(0,f,m))}catch{console.warn(`Error bundling script`)}let t=f.indexOf(n.t);t>-1&&(k=f.substring(t+n.t.length+1,f.length),f=f.substring(0,t),f=f.replaceAll(`globalThis.`+e.n,e.n))}let A={functions:T,commitId:O,source:a,name:`Script`,language:`typescript`,compiled:f};return k&&(A.sourceMap=k),E&&(A.autoRun=E),{module:A,diagnostics:w}};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
exports.TypeScriptCompiler=class{constructor(e={}){this.workerWrapper=null}async getWorkerWrapper(){if(this.workerWrapper)return this.workerWrapper;let{createCompilerWorker:e}=await Promise.resolve().then(()=>require("./GBmIbvhpXGNyZh4W.cjs"));return this.workerWrapper=await e(),this.workerWrapper}async compileModule(e){try{return(await this.getWorkerWrapper()).execute(e)}catch(e){throw console.error(`Failed to compile using worker:`,e),e}}terminate(){this.workerWrapper?.terminate(),this.workerWrapper=null}};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
const e=require("./BvG8N7G_8CXIAlT-.cjs");exports.loadCompiledModule=async function(t,n){let r=t;return n?.sourceMap&&(r+=`\n${e.t}=${n.sourceMap}`),Function(`url`,`return import(url)`)(`data:text/javascript,${encodeURIComponent(r)}`)};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return`//# sourceMappingURL`}});
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
var e=null;exports.initialize=async function(){return e||=new Promise(async(e,t)=>{try{let t=`0.20.2`,n=`https://esm.sh/esbuild-wasm@${t}`,r=`https://esm.sh/esbuild-wasm@${t}/esbuild.wasm`,i=(await import(n)).default;await i.initialize({wasmURL:r,worker:!1}),e(i)}catch(e){console.error(`Error initializing esbuild:`,e),t(e)}})};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
var e=null;exports.initialize=async function(){return e||=new Promise(async(e,t)=>{let n=null;try{n=await import(`https://esm.sh/typescript@5.7.2`)}catch(e){console.error(`Error initializing Browser TypeScript module:`,e)}n||console.log(`use script fallback`),e(n)})};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
var e=Object.defineProperty,t=((t,n)=>{let r={};for(var i in t)e(r,i,{get:t[i],enumerable:!0});return n||e(r,Symbol.toStringTag,{value:`Module`}),r})({GLOBAL_CONTEXT_VARIABLE:()=>n}),n=`__SHEETXL`;Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return n}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
var e=Object.freeze({NoBody:`SXL1001`,Anonymous:`SXL1002`,ParseError:`SXL1003`,InvalidParamType:`SXL2001`,InvalidReturnType:`SXL2002`,UndefinedInput:`SXL2003`,MissingType:`SXL2004`,UntypedArray:`SXL2005`,GenericArity:`SXL2006`,MultipleModifiers:`SXL2007`,ContextNotFirst:`SXL2010`,MultipleLambda:`SXL2020`,LambdaNotLast:`SXL2021`,LambdaScalarMismatch:`SXL2022`,LambdaReturn:`SXL2023`,FunctionReturn:`SXL2024`,LambdaArity:`SXL2025`,ArrayDepth:`SXL2030`,RepeatingPosition:`SXL2040`,MultipleRepeating:`SXL2041`,RepeatingSlots:`SXL2042`,RepeatingOptional:`SXL2043`,NoExports:`SXL3001`,UnknownParam:`SXL3002`,BuiltInName:`SXL3003`,MissingSummary:`SXL9001`,MissingParamDescription:`SXL9002`,MissingReturns:`SXL9003`}),t=[{name:`summary`,group:`sheetxl`,description:`Short description shown in function tooltips and autocomplete.`},{name:`param`,group:`jsdoc`,description:`Document a parameter. A string union type becomes a dropdown of allowed options.`,snippet:"param ${1:name} ${2:description}"},{name:`returns`,aliases:[`return`],group:`jsdoc`,description:`Describe the return value.`},{name:`category`,group:`sheetxl`,description:`Group the function under a category in the function list.`,snippet:"category ${1:name}"},{name:`name`,group:`sheetxl`,description:`Override the displayed function name.`,snippet:"name ${1:NAME}"},{name:`description`,group:`sheetxl`,description:`A longer description of the function.`},{name:`deprecated`,group:`sheetxl`,standalone:!0,description:`Mark the function as deprecated (optionally with a reason).`},{name:`hidden`,group:`sheetxl`,standalone:!0,description:`Hide the function from the function list.`},{name:`example`,group:`jsdoc`,description:`Provide a usage example.`},{name:`see`,group:`jsdoc`,description:`Reference a related function or link.`}],n=(()=>{let e=new Map;for(let n of t)if(e.set(n.name,n),n.aliases)for(let t of n.aliases)e.set(t,n);return e})();function r(e){return!0===function(e){if(!e)return;let t=(e.startsWith(`@`)?e.slice(1):e).toLowerCase();return n.get(t)}(e)?.standalone}Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return e}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});
|