@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.
Files changed (117) hide show
  1. package/README.md +208 -229
  2. package/browser/cjs/1_xhnTjP6m5oj6za.cjs +21 -0
  3. package/browser/cjs/6XTQ1BNSLrTHmFNH.cjs +1 -0
  4. package/browser/cjs/Bu4cZ8iSZ3rij-oV.cjs +1 -0
  5. package/browser/cjs/BvG8N7G_8CXIAlT-.cjs +1 -0
  6. package/browser/cjs/C_7w8EJZpHw8ueuq.cjs +1 -0
  7. package/browser/cjs/C_IEgjM-hSJCv6Gm.cjs +1 -0
  8. package/browser/cjs/CctaCN_w3o34V9AR.cjs +1 -0
  9. package/browser/cjs/DSEShe7kGtxvljOr.cjs +1 -0
  10. package/browser/cjs/GBmIbvhpXGNyZh4W.cjs +1 -0
  11. package/browser/cjs/index.cjs +1 -6
  12. package/browser/cjs/qWYyYsBboXc9p0Lw.cjs +7 -0
  13. package/browser/esm/B2O6_lZVwu7HGlcx.mjs +8 -0
  14. package/browser/esm/B7Axspg8vBnT9M3x.mjs +421 -0
  15. package/browser/esm/BVMNJQoqhXCkbrAc.mjs +87 -0
  16. package/browser/esm/BX3qwglupa6Y59lz.mjs +27 -0
  17. package/browser/esm/C1gdnq2DZdt3y7zD.mjs +23 -0
  18. package/browser/esm/CD2q23uuB7okp3Dl.mjs +152 -0
  19. package/browser/esm/CabN_0aQQRRyMDbw.mjs +12 -0
  20. package/browser/esm/D8K5BUCHuJ9gEpKs.mjs +105 -0
  21. package/browser/esm/DYjJCR6wkeLLkRm6.mjs +15 -0
  22. package/browser/esm/Qyh7uNkqdCcPtgBO.mjs +25 -0
  23. package/browser/esm/index.mjs +40 -20
  24. package/node/esm/47V_H-QS1YIyY07o.mjs +14 -0
  25. package/node/esm/B2O6_lZVwu7HGlcx.mjs +8 -0
  26. package/node/esm/CFY3Dm5Wl-fatf70.mjs +421 -0
  27. package/node/esm/CPB_iNIWuPOW5OPJ.mjs +152 -0
  28. package/node/esm/CaKTS-uKPFUYE8z9.mjs +27 -0
  29. package/node/esm/DGA9ykmJTQwzArFh.mjs +17 -0
  30. package/node/esm/DXc-q9b4X6dKKFs-.mjs +12 -0
  31. package/node/esm/index.mjs +144 -20
  32. package/node/esm/jw7wu0yKXfqYBchM.mjs +23 -0
  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/ScriptCompiler.d.ts.map +1 -0
  37. package/types/src/compiler/Bundler.d.ts +7 -0
  38. package/types/src/compiler/Bundler.d.ts.map +1 -0
  39. package/types/src/compiler/TypescriptCompiler.d.ts +27 -0
  40. package/types/src/compiler/TypescriptCompiler.d.ts.map +1 -0
  41. package/types/src/compiler/TypescriptCompiler.impl.d.ts +17 -0
  42. package/types/src/compiler/TypescriptCompiler.impl.d.ts.map +1 -0
  43. package/types/src/compiler/TypescriptCompiler.worker.d.ts +2 -0
  44. package/types/src/compiler/TypescriptCompiler.worker.d.ts.map +1 -0
  45. package/types/src/compiler/compiler.browser.d.ts +8 -0
  46. package/types/src/compiler/compiler.browser.d.ts.map +1 -0
  47. package/types/src/compiler/compiler.node.d.ts +14 -0
  48. package/types/src/compiler/compiler.node.d.ts.map +1 -0
  49. package/types/src/compiler/constants.d.ts +10 -0
  50. package/types/src/compiler/constants.d.ts.map +1 -0
  51. package/types/src/compiler/insertYieldBetweenStatements.d.ts +5 -0
  52. package/types/src/compiler/insertYieldBetweenStatements.d.ts.map +1 -0
  53. package/types/src/compiler/transformAwaitToYield.d.ts +6 -0
  54. package/types/src/compiler/transformAwaitToYield.d.ts.map +1 -0
  55. package/types/src/index.d.ts +7 -0
  56. package/types/src/index.d.ts.map +1 -0
  57. package/types/src/lib/esbuild/esbuild.browser.d.ts +4 -0
  58. package/types/src/lib/esbuild/esbuild.browser.d.ts.map +1 -0
  59. package/types/src/lib/esbuild/esbuild.node.d.ts +11 -0
  60. package/types/src/lib/esbuild/esbuild.node.d.ts.map +1 -0
  61. package/types/src/lib/typescript/typescript.browser.d.ts +4 -0
  62. package/types/src/lib/typescript/typescript.browser.d.ts.map +1 -0
  63. package/types/src/lib/typescript/typescript.node.d.ts +4 -0
  64. package/types/src/lib/typescript/typescript.node.d.ts.map +1 -0
  65. package/types/src/linter/Linter.d.ts +63 -0
  66. package/types/src/linter/Linter.d.ts.map +1 -0
  67. package/types/src/linter/index.d.ts +2 -0
  68. package/types/src/linter/index.d.ts.map +1 -0
  69. package/types/src/loader/index.d.ts +2 -0
  70. package/types/src/loader/index.d.ts.map +1 -0
  71. package/types/src/loader/loadCompiledModule.d.ts +19 -0
  72. package/types/src/loader/loadCompiledModule.d.ts.map +1 -0
  73. package/types/src/loader/moduleLoader.browser.d.ts +11 -0
  74. package/types/src/loader/moduleLoader.browser.d.ts.map +1 -0
  75. package/types/src/loader/moduleLoader.node.d.ts +15 -0
  76. package/types/src/loader/moduleLoader.node.d.ts.map +1 -0
  77. package/types/src/plugin/generate.d.ts +17 -0
  78. package/types/src/plugin/generate.d.ts.map +1 -0
  79. package/types/src/plugin/vite.d.ts +24 -0
  80. package/types/src/plugin/vite.d.ts.map +1 -0
  81. package/types/src/runtime/Constants.d.ts +9 -0
  82. package/types/src/runtime/Constants.d.ts.map +1 -0
  83. package/types/src/runtime/index.d.ts +2 -0
  84. package/types/src/runtime/index.d.ts.map +1 -0
  85. package/types/src/tags/DocTags.d.ts +46 -0
  86. package/types/src/tags/DocTags.d.ts.map +1 -0
  87. package/types/src/tags/index.d.ts +2 -0
  88. package/types/src/tags/index.d.ts.map +1 -0
  89. package/types/src/type/CompileOptions.d.ts +58 -0
  90. package/types/src/type/CompileOptions.d.ts.map +1 -0
  91. package/types/src/type/CompiledModule.d.ts +70 -0
  92. package/types/src/type/CompiledModule.d.ts.map +1 -0
  93. package/types/src/type/Diagnostic.d.ts +120 -0
  94. package/types/src/type/Diagnostic.d.ts.map +1 -0
  95. package/types/src/type/Types.d.ts +72 -0
  96. package/types/src/type/Types.d.ts.map +1 -0
  97. package/types/src/type/index.d.ts +6 -0
  98. package/types/src/type/index.d.ts.map +1 -0
  99. package/types/src/worker/WorkerWrapper.d.ts +44 -0
  100. package/types/src/worker/WorkerWrapper.d.ts.map +1 -0
  101. package/types/src/worker/index.d.ts +2 -0
  102. package/types/src/worker/index.d.ts.map +1 -0
  103. package/browser/cjs/B0y4r3JJPPSwiDzx.cjs +0 -6
  104. package/browser/cjs/CGLLj80MYA2hDUWX.cjs +0 -1512
  105. package/browser/cjs/CTIIZ0KnyksL075e.cjs +0 -32
  106. package/browser/cjs/CUcC81sgg70TCSkb.cjs +0 -6
  107. package/browser/cjs/DR9eQnRTjdCvZ_vn.cjs +0 -6
  108. package/browser/esm/C3Kam_ffnenXH9Ry.mjs +0 -264
  109. package/browser/esm/CWnC_tpttjXTMAYH.mjs +0 -29
  110. package/browser/esm/D9QqdtRf0J6jc-i7.mjs +0 -21
  111. package/browser/esm/Dfs-JW1Cpyj6GJ8P.mjs +0 -1587
  112. package/browser/esm/DpMJmUGhnNbeI2fN.mjs +0 -24
  113. package/node/esm/Bk7d3p9VfcJCsNVL.mjs +0 -264
  114. package/node/esm/CLf-vRuFGkk8X4S9.mjs +0 -29
  115. package/node/esm/CQR30SbeLa27Szfg.mjs +0 -1587
  116. package/node/esm/DL3QM-qR0v00NdZZ.mjs +0 -16
  117. package/node/esm/u4BUV-OpkSGdvi-w.mjs +0 -14
package/README.md CHANGED
@@ -1,316 +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 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
21
26
 
22
- ![SheetXL Animated Demo Link](./static/img/sheetxl-animated-preview.gif)
23
- *Headless API. Live Scripting. Built for developers.*
27
+ ## Use Cases
24
28
 
25
- ### Try it now — Complete Excel-compatible App
29
+ ### Standalone Compilation
26
30
 
27
- 👉 [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:
28
33
 
29
- ## 🚀 Getting Started
34
+ ```typescript
35
+ import { ScriptCompiler } from '@sheetxl/scripting';
30
36
 
31
- 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
+ });
32
51
 
33
- ### 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.
34
55
 
35
- ```bash
36
- # Using npm
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
- ### 2. Basic Usage
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
- Easily load and save workbooks in popular formats:
62
+ Primary use case — enables macros and custom UDFs within spreadsheets via `workbook.getScripts()`:
86
63
 
87
- * `xlsx` (Excel)
88
- * `csv`
89
- * `parquet` (in progress)
90
- * `json` (native format)
64
+ ```typescript
65
+ import { Workbook } from '@sheetxl/sdk';
91
66
 
92
- <details>
93
- <summary><b>Click to see the a detailed overview of all modules...</b></summary>
67
+ const workbook = new Workbook();
68
+ const scripts = workbook.getScripts();
94
69
 
95
- ![SheetXL Module Architecture](./static/img/modules-overview.png)
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
- `Items marked with 💎 are part of the premium licensing.`
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
- | Category | Module | Description | License |
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
- </details>
115
-
116
- ## Key Features
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
- * **Unmatched Developer Power**
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
- With a headless core, a powerful vectorized API, and a built-in scripting engine, you have the ultimate control to build any experience.
98
+ ```typescript
99
+ await workbook.getScripts().run(`
100
+ export default function (workbook) {
101
+ workbook.getRange('A1').setValue(42);
102
+ }
103
+ `);
104
+ ```
131
105
 
132
- * **Modern, Open Architecture**
106
+ ### Build-Time Formula Generation
133
107
 
134
- Built with TypeScript and a flexible plugin model, including a fully open-sourced MIT-licensed MUI design system.
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
- ### 🏷️ User Features
112
+ ## Function Types
137
113
 
138
- * 17B+ cells (The same as Excel)
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
- <details>
145
- <summary><b>Click to see the full list of additional User Features...</b></summary>
116
+ ### Formula Functions (UDFs)
146
117
 
147
- * Formatted Copy/Paste (Compatible with Microsoft Excel and Google Sheet)
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
- </details>
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
- ### 🛠️ Developer Features
125
+ ### Macro Functions
172
126
 
173
- * Typescript
174
- * Easy Integration
127
+ Imperative operations that modify spreadsheet state:
175
128
 
176
- <details>
177
- <summary><b>Click to see the full list of Developer Features...</b></summary>
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
- * Built in scripting & Formula support.
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
- </details>
136
+ `ScriptCompiler.compile` returns a `CompileResult` — the compiled artifact plus this compile's
137
+ diagnostics:
186
138
 
187
- ## Roadmap
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
- * Table Filtering (in progress)
145
+ interface CompiledModule {
146
+ // Declaration + descriptor pair per exported function (type signature, summary, metadata).
147
+ functions: [IFunction.DeclarationJSON, IFunction.DescriptorJSON][];
190
148
 
191
- <details>
192
- <summary><b>🧭 Click to see the full Roadmap...</b></summary>
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
- ### 2025 Roadmap
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
- * Conditional formatting
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
- ### 2026 Roadmap
163
+ ```bash
164
+ npm install @sheetxl/scripting typescript esbuild-wasm
165
+ # or
166
+ pnpm add @sheetxl/scripting typescript esbuild-wasm
167
+ ```
207
168
 
208
- * Google Sheets Interop
209
- * Collaboration
169
+ **Note**: `typescript` and `esbuild-wasm` are peer dependencies.
210
170
 
211
- </details>
171
+ ## API Reference
212
172
 
213
- ## 🤔 Why SheetXL?
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
- 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.
177
+ ### ScriptCompiler.compile(options)
216
178
 
217
- ### Why not just a spreadsheet app?
179
+ Compiles TypeScript source into an executable module.
218
180
 
219
- Importing and Exporting data from a spreadsheet is a broken part of nearly every business workflow. Instead of
220
- 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
+ ```
221
190
 
222
- * Reduce errors on data due to import/export copying of data.
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
- ### Why not just a spreadsheet component?
193
+ ### ScriptCompiler.lint(source)
229
194
 
230
- 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.
231
197
 
232
- I wanted my custom applications to have spreadsheet features!
198
+ **Returns**: `Promise<Diagnostic[]>`
233
199
 
234
- Several great spreadsheet components exists but none of them have:
200
+ ### ScriptCompiler.cleanup()
235
201
 
236
- * Excel compatibility and features.
237
- * Simple integration.
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
- ## The Competitive Landscape
205
+ ### Platform Support
245
206
 
246
- We encourage you to explore the landscape. We're confident you'll see why we built SheetXL.
207
+ The package builds for dual targets:
247
208
 
248
- <details>
249
- <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
250
211
 
251
- * <https://dream-num.github.io/LuckysheetDemo/> <https://github.com/dream-num/Luckysheet> (14,500 :star:)
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
- </details>
214
+ ## Examples & Templates
259
215
 
260
- <details>
261
- <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)**
262
218
 
263
- * <https://demos.devexpress.com/ASPxSpreadSheetDemos/Features/Charts.aspx>
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
- </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
269
226
 
270
- <details>
271
- <summary><b>💲 Paid Data-grids...</b></summary>
227
+ ## Architecture
272
228
 
273
- A data-grid is a sub-component within a spreadsheet that provides base grid-level rendering but without many of the
274
- spreadsheet features (user styling, formulas, Excel compatibility, etc). Features vary by product but generally
275
- 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
+ ```
276
258
 
277
- * <https://handsontable.com/demo> (18,100 :star:)
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
- </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
283
265
 
284
- <details>
285
- <summary><b>💲 SAAS Spreadsheets...</b></summary>
266
+ ## License
286
267
 
287
- SAAS spreadsheets are still closed solutions and lack the full experience of Excel.
268
+ Commercial license. See [LICENSE](../../LICENSE.md) for details.
288
269
 
289
- * <https://www.equals.app>
290
- * <https://www.rows.com>
291
- * <https://www.quadratichq.com/>
292
- * <https://sourcetable.com//>
270
+ ## Related Packages
293
271
 
294
- </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
295
275
 
296
- ## 🙏 Credits / 🎉 Special Thanks
276
+ ## Resources
297
277
 
298
- * [Formula.js](https://formulajs.info) (For function references)
299
- * [Fast Formula Parser](https://github.com/LesterLyu/fast-formula-parser) (For grammar support)
300
- * [SheetJS](https://sheetjs.com) (For original number format parsing and Excel import/export)
301
- * [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
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/guides)** - Guides and tutorials.
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}});