@sheetxl/scripting 0.7.26 → 0.7.28-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 +206 -247
- package/browser/cjs/1_xhnTjP6m5oj6za.cjs +21 -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/btgKzY3qMXIaaNlB.cjs +1 -0
- package/browser/cjs/g7NzVvjLm_oCf_dd.cjs +1 -0
- package/browser/cjs/index.cjs +1 -6
- package/browser/cjs/qWYyYsBboXc9p0Lw.cjs +7 -0
- package/browser/esm/3M5kvBOeC9dO1anl.mjs +12 -0
- package/browser/esm/BO33MdJ1knSwnDFc.mjs +421 -0
- package/browser/esm/Buk8t7jbvkBl210h.mjs +25 -0
- package/browser/esm/DEMLy75ghnJrOdbg.mjs +23 -0
- package/browser/esm/D_RaFJ9L6p0FWrsc.mjs +87 -0
- package/browser/esm/DkclmJ-rIJcNsfWQ.mjs +27 -0
- package/browser/esm/DqlXZuvMsFv7k9Op.mjs +105 -0
- package/browser/esm/S3dk0h6UOMvLEQYW.mjs +152 -0
- package/browser/esm/SJ37xnNH-b4AhQOe.mjs +8 -0
- package/browser/esm/index.mjs +40 -20
- package/browser/esm/xhrsKI0xcttmWNAI.mjs +15 -0
- package/node/esm/BvEpRtUTq_sFtAnk.mjs +421 -0
- package/node/esm/BzB380N0KvPvx3Va.mjs +23 -0
- package/node/esm/CYHVS16ZrqxOoRVQ.mjs +17 -0
- package/node/esm/CcqVU5-hFGk6MS45.mjs +27 -0
- package/node/esm/DBuGDPGKGMJGN0-R.mjs +12 -0
- package/node/esm/Dx2TL-2TFdOTGPZo.mjs +14 -0
- package/node/esm/SJ37xnNH-b4AhQOe.mjs +8 -0
- package/node/esm/fVQ1ZTi1igB3_IOU.mjs +152 -0
- package/node/esm/index.mjs +144 -20
- package/package.json +11 -8
- package/types/index.d.ts +2 -165
- package/types/src/ScriptCompiler.d.ts +40 -0
- package/types/src/compiler/Bundler.d.ts +7 -0
- package/types/src/compiler/TypescriptCompiler.d.ts +27 -0
- package/types/src/compiler/TypescriptCompiler.impl.d.ts +17 -0
- package/types/src/compiler/TypescriptCompiler.worker.d.ts +2 -0
- package/types/src/compiler/compiler.browser.d.ts +8 -0
- package/types/src/compiler/compiler.node.d.ts +14 -0
- package/types/src/compiler/constants.d.ts +10 -0
- package/types/src/compiler/insertYieldBetweenStatements.d.ts +5 -0
- package/types/src/compiler/transformAwaitToYield.d.ts +6 -0
- package/types/src/index.d.ts +7 -0
- package/types/src/lib/esbuild/esbuild.browser.d.ts +4 -0
- package/types/src/lib/esbuild/esbuild.node.d.ts +11 -0
- package/types/src/lib/typescript/typescript.browser.d.ts +4 -0
- package/types/src/lib/typescript/typescript.node.d.ts +4 -0
- package/types/src/linter/Linter.d.ts +63 -0
- package/types/src/linter/index.d.ts +2 -0
- package/types/src/loader/index.d.ts +2 -0
- package/types/src/loader/loadCompiledModule.d.ts +19 -0
- package/types/src/loader/moduleLoader.browser.d.ts +11 -0
- package/types/src/loader/moduleLoader.node.d.ts +15 -0
- package/types/src/plugin/generate.d.ts +17 -0
- package/types/src/plugin/vite.d.ts +24 -0
- package/types/src/runtime/Constants.d.ts +9 -0
- package/types/src/runtime/index.d.ts +2 -0
- package/types/src/tags/DocTags.d.ts +46 -0
- package/types/src/tags/index.d.ts +2 -0
- package/types/src/type/CompileOptions.d.ts +58 -0
- package/types/src/type/CompiledModule.d.ts +70 -0
- package/types/src/type/Diagnostic.d.ts +120 -0
- package/types/src/type/Types.d.ts +72 -0
- package/types/src/type/index.d.ts +6 -0
- package/types/src/worker/WorkerWrapper.d.ts +44 -0
- package/types/src/worker/index.d.ts +2 -0
- package/browser/cjs/1FxoZcQW9Jtuz8rC.cjs +0 -6
- package/browser/cjs/BVflpadZI0FMHzPP.cjs +0 -6
- package/browser/cjs/Bgxi3ZUQTg5EKFnv.cjs +0 -1518
- package/browser/cjs/DL2hE-VUVbfy6Zem.cjs +0 -32
- package/browser/cjs/Ms_ibGXEX6074qzl.cjs +0 -6
- package/browser/esm/C1DZmlRCcKmg_HLd.mjs +0 -266
- package/browser/esm/C_2SCwrJ3CRR32wO.mjs +0 -29
- package/browser/esm/DHtoG6tI2hwnhrwX.mjs +0 -24
- package/browser/esm/DPCvyj5K9rQVitWC.mjs +0 -21
- package/browser/esm/Dg6kfw8Ea-sxI1gY.mjs +0 -1593
- package/node/esm/0Q-PVUbTe0_lgcA4.mjs +0 -1593
- package/node/esm/CZnHRAY4OIqaUtzw.mjs +0 -29
- package/node/esm/DWz-8-6mYiVKd77G.mjs +0 -14
- package/node/esm/DZrPx9_OUGxc6TPg.mjs +0 -16
- package/node/esm/z6mcRv7V2HRJW0d0.mjs +0 -266
package/README.md
CHANGED
|
@@ -1,336 +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
|
-
|
|
21
|
-
|
|
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
|
|
22
26
|
|
|
23
|
-
|
|
24
|
-
*Headless API. Live Scripting. CLI Tools. Built for developers.*
|
|
27
|
+
## Use Cases
|
|
25
28
|
|
|
26
|
-
###
|
|
29
|
+
### Standalone Compilation
|
|
27
30
|
|
|
28
|
-
|
|
31
|
+
Use `ScriptCompiler` directly to compile (or just lint) TypeScript source into an executable
|
|
32
|
+
module:
|
|
29
33
|
|
|
30
|
-
|
|
34
|
+
```typescript
|
|
35
|
+
import { ScriptCompiler } from '@sheetxl/scripting';
|
|
31
36
|
|
|
32
|
-
|
|
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
|
+
});
|
|
33
51
|
|
|
34
|
-
|
|
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.
|
|
35
55
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
npm install @sheetxl/sdk @sheetxl/studio-mui @mui/material @emotion/react @emotion/styled
|
|
39
|
-
|
|
40
|
-
# Using yarn
|
|
41
|
-
yarn add @sheetxl/sdk @sheetxl/studio-mui @mui/material @emotion/react @emotion/styled
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
### 2. Basic Usage
|
|
45
|
-
|
|
46
|
-
```javascript
|
|
47
|
-
import React from 'react';
|
|
48
|
-
import { Studio } from '@sheetxl/studio-mui';
|
|
49
|
-
|
|
50
|
-
function App() {
|
|
51
|
-
// Studio will fill it's parent container.
|
|
52
|
-
return (
|
|
53
|
-
<div style={{ height: '600px', width: '100%' }}>
|
|
54
|
-
<Studio />
|
|
55
|
-
</div>
|
|
56
|
-
);
|
|
57
|
-
}
|
|
56
|
+
// Fast path for editors — diagnostics only, no code emit:
|
|
57
|
+
const problems = await ScriptCompiler.lint(`export function f(x: number) { return x; }`);
|
|
58
58
|
```
|
|
59
59
|
|
|
60
|
-
|
|
61
|
-
[Getting Started Guides](https://www.sheetxl.com/docs/guides/category/getting-started).
|
|
62
|
-
|
|
63
|
-
### 📚 Ecosystem Overview
|
|
64
|
-
|
|
65
|
-
The SheetXL ecosystem is modular by design. You can use only what you need — or compose it all together.
|
|
66
|
-
|
|
67
|
-
### SDK
|
|
60
|
+
### Integration with @sheetxl/sdk
|
|
68
61
|
|
|
69
|
-
|
|
70
|
-
built to power everything from lightweight grid widgets to massive enterprise-scale calculation engines
|
|
62
|
+
Primary use case — enables macros and custom UDFs within spreadsheets via `workbook.getScripts()`:
|
|
71
63
|
|
|
72
|
-
|
|
64
|
+
```typescript
|
|
65
|
+
import { Workbook } from '@sheetxl/sdk';
|
|
73
66
|
|
|
74
|
-
|
|
75
|
-
|
|
67
|
+
const workbook = new Workbook();
|
|
68
|
+
const scripts = workbook.getScripts();
|
|
76
69
|
|
|
77
|
-
|
|
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
|
+
}
|
|
78
79
|
|
|
79
|
-
|
|
80
|
+
/**
|
|
81
|
+
* @summary Set active cell value
|
|
82
|
+
*/
|
|
83
|
+
export function setCellValue(cell: ICell, value: any): void {
|
|
84
|
+
cell.setValue(value);
|
|
85
|
+
}
|
|
86
|
+
`
|
|
87
|
+
});
|
|
80
88
|
|
|
81
|
-
|
|
82
|
-
* **Custom Interface** [`@sheetxl/react`](https://www.npmjs.com/package/@sheetxl/react): A flexible component and hook library for deep customization.
|
|
89
|
+
scripts.addModule('my-functions', module);
|
|
83
90
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
* `xlsx` (Excel)
|
|
89
|
-
* `csv`
|
|
90
|
-
* `parquet` (in progress)
|
|
91
|
-
* `json` (native format)
|
|
92
|
-
|
|
93
|
-
<details>
|
|
94
|
-
<summary><b>Click to see the a detailed overview of all modules...</b></summary>
|
|
95
|
-
|
|
96
|
-

|
|
97
|
-
|
|
98
|
-
`Items marked with 💎 are part of the premium licensing.`
|
|
91
|
+
// Use in formulas: =DOUBLE(A1)
|
|
92
|
+
// Execute a macro: scripts.executeMacro('setCellValue', 'my-functions')
|
|
93
|
+
```
|
|
99
94
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
| Core | @sheetxl/sdk 💎 | Headless spreadsheet API | Commercial |
|
|
103
|
-
| | @sheetxl/formulas | Collection of 400+ formulas | MIT |
|
|
104
|
-
| | @sheetxl/primitives | Low level types (Scalar, IRange) | MIT |
|
|
105
|
-
| | @sheetxl/scripting 💎 | Scripting engine and compiler | Commercial |
|
|
106
|
-
| IO | @sheetxl/io | Import/export (xlsx, csv, json) | MIT |
|
|
107
|
-
| Applications | @sheetxl/studio-vanilla | Framework-agnostic spreadsheet app | MIT |
|
|
108
|
-
| | @sheetxl/studio-mui | Spreadsheet app powered by React/MUI | MIT |
|
|
109
|
-
| UI Toolkits | @sheetxl/react 💎 | Spreadsheet React UI components and hooks | Commercial |
|
|
110
|
-
| | @sheetxl/grid-react 💎 | Lightweight, standalone React data grid | Commercial |
|
|
111
|
-
| Utils | @sheetxl/utils | Headless utilities (math, ranges, etc) | MIT |
|
|
112
|
-
| | @sheetxl/utils-react | React UI helpers | MIT |
|
|
113
|
-
| | @sheetxl/utils-mui | MUI UI helpers (color picker, dialogs, etc) | MIT |
|
|
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:
|
|
114
97
|
|
|
115
|
-
|
|
98
|
+
```typescript
|
|
99
|
+
await workbook.getScripts().run(`
|
|
100
|
+
export default function (workbook) {
|
|
101
|
+
workbook.getRange('A1').setValue(42);
|
|
102
|
+
}
|
|
103
|
+
`);
|
|
104
|
+
```
|
|
116
105
|
|
|
117
|
-
|
|
106
|
+
### Build-Time Formula Generation
|
|
118
107
|
|
|
119
|
-
|
|
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).
|
|
120
111
|
|
|
121
|
-
|
|
112
|
+
## Function Types
|
|
122
113
|
|
|
123
|
-
|
|
114
|
+
The scripting engine supports two types of exported functions:
|
|
124
115
|
|
|
125
|
-
|
|
116
|
+
### Formula Functions (UDFs)
|
|
126
117
|
|
|
127
|
-
|
|
118
|
+
Custom functions usable in spreadsheet formulas:
|
|
128
119
|
|
|
129
|
-
|
|
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`
|
|
130
124
|
|
|
131
|
-
|
|
125
|
+
### Macro Functions
|
|
132
126
|
|
|
133
|
-
|
|
127
|
+
Imperative operations that modify spreadsheet state:
|
|
134
128
|
|
|
135
|
-
|
|
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`
|
|
136
133
|
|
|
137
|
-
##
|
|
134
|
+
## Compilation Output
|
|
138
135
|
|
|
139
|
-
|
|
136
|
+
`ScriptCompiler.compile` returns a `CompileResult` — the compiled artifact plus this compile's
|
|
137
|
+
diagnostics:
|
|
140
138
|
|
|
141
|
-
|
|
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
|
+
}
|
|
142
144
|
|
|
143
|
-
|
|
145
|
+
interface CompiledModule {
|
|
146
|
+
// Declaration + descriptor pair per exported function (type signature, summary, metadata).
|
|
147
|
+
functions: [IFunction.DeclarationJSON, IFunction.DescriptorJSON][];
|
|
144
148
|
|
|
145
|
-
|
|
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
|
+
```
|
|
146
156
|
|
|
147
|
-
|
|
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.
|
|
148
160
|
|
|
149
|
-
|
|
161
|
+
## Installation
|
|
150
162
|
|
|
151
163
|
```bash
|
|
152
|
-
|
|
153
|
-
|
|
164
|
+
npm install @sheetxl/scripting typescript esbuild-wasm
|
|
165
|
+
# or
|
|
166
|
+
pnpm add @sheetxl/scripting typescript esbuild-wasm
|
|
154
167
|
```
|
|
155
168
|
|
|
156
|
-
|
|
169
|
+
**Note**: `typescript` and `esbuild-wasm` are peer dependencies.
|
|
157
170
|
|
|
158
|
-
|
|
159
|
-
* 400+ Excel-compatible formulas
|
|
160
|
-
* Full fidelity Excel import/export
|
|
161
|
-
* Scripting Engine
|
|
162
|
-
* Fast. Autofill 1,048,576 rows with formulas in 0.7s (10M+ formulas/second)
|
|
171
|
+
## API Reference
|
|
163
172
|
|
|
164
|
-
|
|
165
|
-
|
|
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.
|
|
166
176
|
|
|
167
|
-
|
|
168
|
-
* Hidden Rows/Columns
|
|
169
|
-
* Frozen Rows/Columns
|
|
170
|
-
* Resizable, Auto-fit Rows/Columns
|
|
171
|
-
* Office Theme (Color Picker, Theme Selector)
|
|
172
|
-
* Cell Styles (Themes and Formatting)
|
|
173
|
-
* Preset Cell Style Selector
|
|
174
|
-
* Overflow, Word-wrap
|
|
175
|
-
* Borders
|
|
176
|
-
* Tables
|
|
177
|
-
* Drawings
|
|
178
|
-
* Multi-range selection
|
|
179
|
-
* Merged Cells
|
|
180
|
-
* Autofill
|
|
181
|
-
* Keyboard Accessible Support for all Excel shortcut keys
|
|
182
|
-
* Undo/Redo
|
|
183
|
-
* Find/Replace
|
|
184
|
-
* Sort
|
|
185
|
-
* Zoom
|
|
186
|
-
* Hyperlinks
|
|
187
|
-
* Mobile Friendly (Touch / Small screen accommodation)
|
|
177
|
+
### ScriptCompiler.compile(options)
|
|
188
178
|
|
|
189
|
-
|
|
179
|
+
Compiles TypeScript source into an executable module.
|
|
190
180
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
* Built from the ground up using React and CSS-in-JS components.
|
|
201
|
-
* Fully functional MIT Open-sourced Material-UI Application.
|
|
202
|
-
* Headless spreadsheet API can be used without UI and on server or as library.
|
|
203
|
-
* Easily extend functions with simple registration.
|
|
204
|
-
|
|
205
|
-
</details>
|
|
206
|
-
|
|
207
|
-
## Roadmap
|
|
208
|
-
|
|
209
|
-
* Table Filtering (in progress)
|
|
210
|
-
|
|
211
|
-
<details>
|
|
212
|
-
<summary><b>🧭 Click to see the full Roadmap...</b></summary>
|
|
213
|
-
|
|
214
|
-
### 2025 Roadmap
|
|
215
|
-
|
|
216
|
-
* Conditional formatting
|
|
217
|
-
* Full Styling in Excel Export
|
|
218
|
-
* Full Charting (nearly complete)
|
|
219
|
-
* Multi-key shortcuts
|
|
220
|
-
* Pivot
|
|
221
|
-
* Sparklines
|
|
222
|
-
* Slicer/Timeline
|
|
223
|
-
* Accessibility <https://www.w3.org/TR/WCAG21/>
|
|
224
|
-
* Printing
|
|
225
|
-
|
|
226
|
-
### 2026 Roadmap
|
|
227
|
-
|
|
228
|
-
* Google Sheets Interop
|
|
229
|
-
* Collaboration
|
|
230
|
-
|
|
231
|
-
</details>
|
|
232
|
-
|
|
233
|
-
## 🤔 Why SheetXL?
|
|
234
|
-
|
|
235
|
-
We believe developers have been forced to compromise between powerful but closed spreadsheet apps and flexible but limited data grids for too long. SheetXL was built to end that compromise.
|
|
236
|
-
|
|
237
|
-
### Why not just a spreadsheet app?
|
|
238
|
-
|
|
239
|
-
Importing and Exporting data from a spreadsheet is a broken part of nearly every business workflow. Instead of
|
|
240
|
-
importing/exporting data, just import the spreadsheet.
|
|
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
|
+
```
|
|
241
190
|
|
|
242
|
-
|
|
243
|
-
* Real time integration/validation of your data.
|
|
244
|
-
* Complete control of data as your data never leaves your systems.
|
|
245
|
-
* Improved user productivity.
|
|
246
|
-
* Combine custom user enhancements with flexible data manipulation.
|
|
191
|
+
**Returns**: `Promise<CompileResult>`
|
|
247
192
|
|
|
248
|
-
###
|
|
193
|
+
### ScriptCompiler.lint(source)
|
|
249
194
|
|
|
250
|
-
|
|
195
|
+
Lints source against SheetXL's authoring rules and returns positioned diagnostics, without emitting
|
|
196
|
+
JavaScript. The fast path for editors.
|
|
251
197
|
|
|
252
|
-
|
|
198
|
+
**Returns**: `Promise<Diagnostic[]>`
|
|
253
199
|
|
|
254
|
-
|
|
200
|
+
### ScriptCompiler.cleanup()
|
|
255
201
|
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
* Billions of cells.
|
|
259
|
-
* Comprehensive support for keyboard shortcuts (e.g. tabbing within multi-selected ranges, arrow-keys within cells).
|
|
260
|
-
* Enable advanced copy / paste between Excel/Excel Online/Google Sheets.
|
|
261
|
-
* Easily extendable libraries that use open-source and modern design patterns.
|
|
262
|
-
* 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.
|
|
263
204
|
|
|
264
|
-
|
|
205
|
+
### Platform Support
|
|
265
206
|
|
|
266
|
-
|
|
207
|
+
The package builds for dual targets:
|
|
267
208
|
|
|
268
|
-
|
|
269
|
-
|
|
209
|
+
- **Browser**: Uses Web Workers for non-blocking compilation
|
|
210
|
+
- **Node.js**: Direct compilation with native modules
|
|
270
211
|
|
|
271
|
-
|
|
272
|
-
* <https://github.com/jspreadsheet/ce> <https://jspreadsheet.com/v8> (6,400 :star:)
|
|
273
|
-
* <https://github.com/myliang/x-spreadsheet> <https://myliang.github.io/x-spreadsheet> (13,500 :star:)
|
|
274
|
-
* <https://github.com/nadbm/react-datasheet> <https://nadbm.github.io/react-datasheet> (5,300 :star:)
|
|
275
|
-
* <https://github.com/adazzle/react-data-grid> (6,200 :star:)
|
|
276
|
-
* <https://iddan.github.io/react-spreadsheet> (1,000 :star:)
|
|
212
|
+
Platform detection is automatic via conditional exports.
|
|
277
213
|
|
|
278
|
-
|
|
214
|
+
## Examples & Templates
|
|
279
215
|
|
|
280
|
-
|
|
281
|
-
|
|
216
|
+
Explore ready-to-use scripting templates at:
|
|
217
|
+
**[github.com/sheetxl/scripting-templates](https://github.com/sheetxl/scripting-templates)**
|
|
282
218
|
|
|
283
|
-
|
|
284
|
-
* <https://www.igniteui.com/spreadsheet/overview> <https://www.infragistics.com/products/ignite-ui-jquery/grids-and-lists/spreadsheet>
|
|
285
|
-
* <https://ej2.syncfusion.com/react/demos/#/bootstrap5/spreadsheet/default>
|
|
286
|
-
* <https://webix.com/demos/spreadsheet>
|
|
219
|
+
Templates include:
|
|
287
220
|
|
|
288
|
-
|
|
221
|
+
- Data validation and transformation
|
|
222
|
+
- Advanced calculations (financial, statistical)
|
|
223
|
+
- Batch operations and automation
|
|
224
|
+
- External API integration
|
|
225
|
+
- Custom data import/export
|
|
289
226
|
|
|
290
|
-
|
|
291
|
-
<summary><b>💲 Paid Data-grids...</b></summary>
|
|
227
|
+
## Architecture
|
|
292
228
|
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
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
|
+
```
|
|
296
258
|
|
|
297
|
-
|
|
298
|
-
* <https://www.ag-grid.com/example> (10,500 :star:)
|
|
299
|
-
* <https://mui.com/x/react-data-grid> (6,100 :star:)
|
|
300
|
-
* <https://www.datagridxl.com/>
|
|
259
|
+
## Performance
|
|
301
260
|
|
|
302
|
-
|
|
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
|
|
303
265
|
|
|
304
|
-
|
|
305
|
-
<summary><b>💲 SAAS Spreadsheets...</b></summary>
|
|
266
|
+
## License
|
|
306
267
|
|
|
307
|
-
|
|
268
|
+
Commercial license. See [LICENSE](../../LICENSE.md) for details.
|
|
308
269
|
|
|
309
|
-
|
|
310
|
-
* <https://www.rows.com>
|
|
311
|
-
* <https://www.quadratichq.com/>
|
|
312
|
-
* <https://sourcetable.com//>
|
|
270
|
+
## Related Packages
|
|
313
271
|
|
|
314
|
-
|
|
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
|
|
315
275
|
|
|
316
|
-
##
|
|
276
|
+
## Resources
|
|
317
277
|
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
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
|
|
322
282
|
|
|
323
283
|
## 🔗 Learn More
|
|
324
284
|
|
|
325
285
|
Whether you're ready to build, need help, or just want to see more examples, here's where to go next.
|
|
326
286
|
|
|
327
|
-
* 💬 **[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.
|
|
328
288
|
* ⭐ **[Star us on GitHub](https://github.com/sheetxl/sheetxl)** - If you like SheetXL give us a star ⭐ and help others find us!
|
|
329
|
-
* 📘 **[Developer Docs](https://www.sheetxl.com/docs
|
|
289
|
+
* 📘 **[Developer Docs](https://www.sheetxl.com/docs)** - Guides and tutorials.
|
|
330
290
|
* 🔌 **[API Reference](https://api.sheetxl.com)** - Detailed documentation for all packages.
|
|
331
291
|
* 👀 **[Live Demo Gallery](https://www.sheetxl.com/demos)** - A showcase of interactive examples.
|
|
332
292
|
* 🖼️ **[Storybook](https://storybook.sheetxl.com)** - Explore and test individual UI components.
|
|
333
|
-
team.
|
|
334
293
|
* 🌐 **[Website](https://www.sheetxl.com)** - Our Website.
|
|
335
294
|
|
|
336
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
|
+
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}});
|