@sheetxl/scripting 0.7.27 → 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.
Files changed (83) hide show
  1. package/README.md +206 -247
  2. package/browser/cjs/1_xhnTjP6m5oj6za.cjs +21 -0
  3. package/browser/cjs/Bu4cZ8iSZ3rij-oV.cjs +1 -0
  4. package/browser/cjs/BvG8N7G_8CXIAlT-.cjs +1 -0
  5. package/browser/cjs/C_7w8EJZpHw8ueuq.cjs +1 -0
  6. package/browser/cjs/C_IEgjM-hSJCv6Gm.cjs +1 -0
  7. package/browser/cjs/CctaCN_w3o34V9AR.cjs +1 -0
  8. package/browser/cjs/DSEShe7kGtxvljOr.cjs +1 -0
  9. package/browser/cjs/btgKzY3qMXIaaNlB.cjs +1 -0
  10. package/browser/cjs/g7NzVvjLm_oCf_dd.cjs +1 -0
  11. package/browser/cjs/index.cjs +1 -6
  12. package/browser/cjs/qWYyYsBboXc9p0Lw.cjs +7 -0
  13. package/browser/esm/3M5kvBOeC9dO1anl.mjs +12 -0
  14. package/browser/esm/BO33MdJ1knSwnDFc.mjs +421 -0
  15. package/browser/esm/Buk8t7jbvkBl210h.mjs +25 -0
  16. package/browser/esm/DEMLy75ghnJrOdbg.mjs +23 -0
  17. package/browser/esm/D_RaFJ9L6p0FWrsc.mjs +87 -0
  18. package/browser/esm/DkclmJ-rIJcNsfWQ.mjs +27 -0
  19. package/browser/esm/DqlXZuvMsFv7k9Op.mjs +105 -0
  20. package/browser/esm/S3dk0h6UOMvLEQYW.mjs +152 -0
  21. package/browser/esm/SJ37xnNH-b4AhQOe.mjs +8 -0
  22. package/browser/esm/index.mjs +40 -20
  23. package/browser/esm/xhrsKI0xcttmWNAI.mjs +15 -0
  24. package/node/esm/BvEpRtUTq_sFtAnk.mjs +421 -0
  25. package/node/esm/BzB380N0KvPvx3Va.mjs +23 -0
  26. package/node/esm/CYHVS16ZrqxOoRVQ.mjs +17 -0
  27. package/node/esm/CcqVU5-hFGk6MS45.mjs +27 -0
  28. package/node/esm/DBuGDPGKGMJGN0-R.mjs +12 -0
  29. package/node/esm/Dx2TL-2TFdOTGPZo.mjs +14 -0
  30. package/node/esm/SJ37xnNH-b4AhQOe.mjs +8 -0
  31. package/node/esm/fVQ1ZTi1igB3_IOU.mjs +152 -0
  32. package/node/esm/index.mjs +144 -20
  33. package/package.json +11 -8
  34. package/types/index.d.ts +2 -165
  35. package/types/src/ScriptCompiler.d.ts +40 -0
  36. package/types/src/compiler/Bundler.d.ts +7 -0
  37. package/types/src/compiler/TypescriptCompiler.d.ts +27 -0
  38. package/types/src/compiler/TypescriptCompiler.impl.d.ts +17 -0
  39. package/types/src/compiler/TypescriptCompiler.worker.d.ts +2 -0
  40. package/types/src/compiler/compiler.browser.d.ts +8 -0
  41. package/types/src/compiler/compiler.node.d.ts +14 -0
  42. package/types/src/compiler/constants.d.ts +10 -0
  43. package/types/src/compiler/insertYieldBetweenStatements.d.ts +5 -0
  44. package/types/src/compiler/transformAwaitToYield.d.ts +6 -0
  45. package/types/src/index.d.ts +7 -0
  46. package/types/src/lib/esbuild/esbuild.browser.d.ts +4 -0
  47. package/types/src/lib/esbuild/esbuild.node.d.ts +11 -0
  48. package/types/src/lib/typescript/typescript.browser.d.ts +4 -0
  49. package/types/src/lib/typescript/typescript.node.d.ts +4 -0
  50. package/types/src/linter/Linter.d.ts +63 -0
  51. package/types/src/linter/index.d.ts +2 -0
  52. package/types/src/loader/index.d.ts +2 -0
  53. package/types/src/loader/loadCompiledModule.d.ts +19 -0
  54. package/types/src/loader/moduleLoader.browser.d.ts +11 -0
  55. package/types/src/loader/moduleLoader.node.d.ts +15 -0
  56. package/types/src/plugin/generate.d.ts +17 -0
  57. package/types/src/plugin/vite.d.ts +24 -0
  58. package/types/src/runtime/Constants.d.ts +9 -0
  59. package/types/src/runtime/index.d.ts +2 -0
  60. package/types/src/tags/DocTags.d.ts +46 -0
  61. package/types/src/tags/index.d.ts +2 -0
  62. package/types/src/type/CompileOptions.d.ts +58 -0
  63. package/types/src/type/CompiledModule.d.ts +70 -0
  64. package/types/src/type/Diagnostic.d.ts +120 -0
  65. package/types/src/type/Types.d.ts +72 -0
  66. package/types/src/type/index.d.ts +6 -0
  67. package/types/src/worker/WorkerWrapper.d.ts +44 -0
  68. package/types/src/worker/index.d.ts +2 -0
  69. package/browser/cjs/B4lAANRqTGnvOqGs.cjs +0 -1518
  70. package/browser/cjs/BRnBwa7X_-2hZkPR.cjs +0 -6
  71. package/browser/cjs/BgmE5dDR60P-0D05.cjs +0 -6
  72. package/browser/cjs/C6FgXFuZyUBSYx74.cjs +0 -6
  73. package/browser/cjs/Cmsp48m0ZoKEApI_.cjs +0 -32
  74. package/browser/esm/BCtqf7TlVX2XI9Sk.mjs +0 -29
  75. package/browser/esm/BUrlmQqFvt49Snxt.mjs +0 -1593
  76. package/browser/esm/BeDi9Rjq6Mj_zC_O.mjs +0 -24
  77. package/browser/esm/C1nmZG6Nh598I5Cy.mjs +0 -266
  78. package/browser/esm/C9oTtQ5kcPvveo9r.mjs +0 -21
  79. package/node/esm/B8mFYKKfM-fFEqr4.mjs +0 -1593
  80. package/node/esm/D3tC0pmcUWYhM3aH.mjs +0 -14
  81. package/node/esm/DUk3E5XxCEk6dBja.mjs +0 -16
  82. package/node/esm/Db6wgeAGcGPbeesO.mjs +0 -266
  83. package/node/esm/YSXanagcUr6QMDaF.mjs +0 -29
package/README.md CHANGED
@@ -1,336 +1,295 @@
1
- # SheetXL — the api-first spreadsheet
1
+ # SheetXL Scripting
2
2
 
3
3
  <p align="center">
4
- <img src="./static/img/social-light.png#gh-light-mode-only">
5
- <img src="./static/img/social-dark.png#gh-dark-mode-only">
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
- [![Discord](https://img.shields.io/discord/1141404921246257223)](https://discord.gg/NTKdwUgK9p)
9
- [![npm (tag)](https://img.shields.io/npm/v/@sheetxl/studio-mui/latest?color=blue)](https://www.npmjs.com/package/@sheetxl/studio-mui)
10
- [![npm](https://img.shields.io/npm/dt/@sheetxl/studio-mui)](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
- ### The full stack spreadsheet — for developers
11
+ [![npm (tag)](https://img.shields.io/npm/v/@sheetxl/scripting/latest?color=blue)](https://www.npmjs.com/package/@sheetxl/scripting)
12
+ [![npm](https://img.shields.io/npm/dt/@sheetxl/scripting)](https://www.npmjs.com/package/@sheetxl/scripting)
13
13
 
14
- **SheetXL is the open spreadsheet ecosystem** — modular, embeddable, and fully scriptable.
14
+ ## Overview
15
15
 
16
- **Excel-compatible. API-first. Built for speed.**
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
- If you like SheetXL **[give us a star ⭐](https://github.com/sheetxl/sheetxl)** and help others find us!
18
+ **Key Features**:
19
19
 
20
- Whether you're building a custom UI, adding live scripting, or integrating spreadsheet logic into your app, SheetXL
21
- gives you full control with zero platform lock-in.
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
- ![SheetXL Animated Demo Link](./static/img/sheetxl-animated-preview.gif)
24
- *Headless API. Live Scripting. CLI Tools. Built for developers.*
27
+ ## Use Cases
25
28
 
26
- ### Try it now — Complete Excel-compatible App
29
+ ### Standalone Compilation
27
30
 
28
- 👉 [See a full SheetXL demo](https://demo.sheetxl.com)
31
+ Use `ScriptCompiler` directly to compile (or just lint) TypeScript source into an executable
32
+ module:
29
33
 
30
- ## 🚀 Getting Started
34
+ ```typescript
35
+ import { ScriptCompiler } from '@sheetxl/scripting';
31
36
 
32
- Get started in minutes with our production ready application.
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
- ### 1. Installation
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
- ```bash
37
- # Using npm
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
- For more advanced setup options, check out our full
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
- At the core of the ecosystem is a **headless, high-performance SDK** [`@sheetxl/sdk`](https://www.npmjs.com/package/@sheetxl/sdk),
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
- Key features:
64
+ ```typescript
65
+ import { Workbook } from '@sheetxl/sdk';
73
66
 
74
- * **Blazing Speed:** Executes 10M+ operations per second and handles spreadsheets with 17B+ cells.
75
- * **Powerful API:** A modern, vectorized, range-based API for precise, scriptable control over data — independent of any UI.
67
+ const workbook = new Workbook();
68
+ const scripts = workbook.getScripts();
76
69
 
77
- ### Applications and UI Toolkits
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
- Build UIs your way — from plug-and-play dashboards to fully custom design systems.
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
- * **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.
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
- ### I/O Connectors
85
-
86
- Easily load and save workbooks in popular formats:
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
- ![SheetXL Module Architecture](./static/img/modules-overview.png)
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
- | Category | Module | Description | License |
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
- </details>
98
+ ```typescript
99
+ await workbook.getScripts().run(`
100
+ export default function (workbook) {
101
+ workbook.getRange('A1').setValue(42);
102
+ }
103
+ `);
104
+ ```
116
105
 
117
- ## Key Features
106
+ ### Build-Time Formula Generation
118
107
 
119
- SheetXL is built on four core pillars: extreme performance, deep Excel compatibility, unparalleled developer power, and a modern, extensible architecture.
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
- * **Performance & Scale**
112
+ ## Function Types
122
113
 
123
- Process 10M+ ops/second and manage massive 17B+ cell workbooks, all in-browser.
114
+ The scripting engine supports two types of exported functions:
124
115
 
125
- * **True Excel Fidelity**
116
+ ### Formula Functions (UDFs)
126
117
 
127
- Go beyond basic formulas. Get the Excel-grade features your users demand, from tables and charts to cross-sheet copy/paste.
118
+ Custom functions usable in spreadsheet formulas:
128
119
 
129
- * **Unmatched Developer Power**
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
- With a headless core, a powerful vectorized API, and a built-in scripting engine, you have the ultimate control to build any experience.
125
+ ### Macro Functions
132
126
 
133
- * **Modern, Open Architecture**
127
+ Imperative operations that modify spreadsheet state:
134
128
 
135
- Built with TypeScript and a flexible plugin model, including a fully open-sourced MIT-licensed MUI design system.
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
- ## 🔥 Power Features
134
+ ## Compilation Output
138
135
 
139
- ### Live Scripting Engine
136
+ `ScriptCompiler.compile` returns a `CompileResult` — the compiled artifact plus this compile's
137
+ diagnostics:
140
138
 
141
- Write and execute TypeScript/JavaScript directly inside your spreadsheet. Perfect for complex data transformations, custom validation, and real-time calculations.
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
- ![Live Scripting Demo](./static/img/live-scripting-demo.gif)
145
+ interface CompiledModule {
146
+ // Declaration + descriptor pair per exported function (type signature, summary, metadata).
147
+ functions: [IFunction.DeclarationJSON, IFunction.DescriptorJSON][];
144
148
 
145
- ### Command-Line Interface
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
- Automate spreadsheet operations, run batch processes, and integrate SheetXL into your build pipeline with our full-featured CLI.
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
- ![CLI Demo](./static/img/cli-demo.gif)
161
+ ## Installation
150
162
 
151
163
  ```bash
152
- # Run custom scripts
153
- sheetxl run process-data.ts --workbook sales.xlsx
164
+ npm install @sheetxl/scripting typescript esbuild-wasm
165
+ # or
166
+ pnpm add @sheetxl/scripting typescript esbuild-wasm
154
167
  ```
155
168
 
156
- ### 🏷️ User Features
169
+ **Note**: `typescript` and `esbuild-wasm` are peer dependencies.
157
170
 
158
- * 17B+ cells (The same as Excel)
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
- <details>
165
- <summary><b>Click to see the full list of additional User Features...</b></summary>
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
- * Formatted Copy/Paste (Compatible with Microsoft Excel and Google Sheet)
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
- </details>
179
+ Compiles TypeScript source into an executable module.
190
180
 
191
- ### 🛠️ Developer Features
192
-
193
- * Typescript
194
- * Easy Integration
195
-
196
- <details>
197
- <summary><b>Click to see the full list of Developer Features...</b></summary>
198
-
199
- * Built in scripting & Formula support.
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
- * Reduce errors on data due to import/export copying of data.
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
- ### Why not just a spreadsheet component?
193
+ ### ScriptCompiler.lint(source)
249
194
 
250
- As a Microsoft Excel user and a React developer I have always wanted a solution that combines the flexibility and ease of use of Excel with the control and specific capabilities of my custom application.
195
+ Lints source against SheetXL's authoring rules and returns positioned diagnostics, without emitting
196
+ JavaScript. The fast path for editors.
251
197
 
252
- I wanted my custom applications to have spreadsheet features!
198
+ **Returns**: `Promise<Diagnostic[]>`
253
199
 
254
- Several great spreadsheet components exists but none of them have:
200
+ ### ScriptCompiler.cleanup()
255
201
 
256
- * Excel compatibility and features.
257
- * Simple integration.
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
- ## The Competitive Landscape
205
+ ### Platform Support
265
206
 
266
- We encourage you to explore the landscape. We're confident you'll see why we built SheetXL.
207
+ The package builds for dual targets:
267
208
 
268
- <details>
269
- <summary><b>👐 Open-source Spreadsheets Components...</b></summary>
209
+ - **Browser**: Uses Web Workers for non-blocking compilation
210
+ - **Node.js**: Direct compilation with native modules
270
211
 
271
- * <https://dream-num.github.io/LuckysheetDemo/> <https://github.com/dream-num/Luckysheet> (14,500 :star:)
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
- </details>
214
+ ## Examples & Templates
279
215
 
280
- <details>
281
- <summary><b>💲 Paid Spreadsheets Components...</b></summary>
216
+ Explore ready-to-use scripting templates at:
217
+ **[github.com/sheetxl/scripting-templates](https://github.com/sheetxl/scripting-templates)**
282
218
 
283
- * <https://demos.devexpress.com/ASPxSpreadSheetDemos/Features/Charts.aspx>
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
- </details>
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
- <details>
291
- <summary><b>💲 Paid Data-grids...</b></summary>
227
+ ## Architecture
292
228
 
293
- A data-grid is a sub-component within a spreadsheet that provides base grid-level rendering but without many of the
294
- spreadsheet features (user styling, formulas, Excel compatibility, etc). Features vary by product but generally
295
- include sorting, filtering, grouping, and basic cell editing.
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
- * <https://handsontable.com/demo> (18,100 :star:)
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
- </details>
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
- <details>
305
- <summary><b>💲 SAAS Spreadsheets...</b></summary>
266
+ ## License
306
267
 
307
- SAAS spreadsheets are still closed solutions and lack the full experience of Excel.
268
+ Commercial license. See [LICENSE](../../LICENSE.md) for details.
308
269
 
309
- * <https://www.equals.app>
310
- * <https://www.rows.com>
311
- * <https://www.quadratichq.com/>
312
- * <https://sourcetable.com//>
270
+ ## Related Packages
313
271
 
314
- </details>
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
- ## 🙏 Credits / 🎉 Special Thanks
276
+ ## Resources
317
277
 
318
- * [Formula.js](https://formulajs.info) (For function references)
319
- * [Fast Formula Parser](https://github.com/LesterLyu/fast-formula-parser) (For grammar support)
320
- * [SheetJS](https://sheetjs.com) (For original number format parsing and Excel import/export)
321
- * [Papa Parse](https://www.papaparse.com) (For CSV parsing)
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/guides)** - Guides and tutorials.
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}});