@sheetxl/scripting 0.7.22 → 0.7.23-beta.2

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/BsZkw6_kfPB5b80k.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/D9Oz5YU4OTd5nNFg.cjs +1 -0
  10. package/browser/cjs/DSEShe7kGtxvljOr.cjs +1 -0
  11. package/browser/cjs/index.cjs +1 -6
  12. package/browser/cjs/qWYyYsBboXc9p0Lw.cjs +7 -0
  13. package/browser/esm/B609eaWQPO1XuznE.mjs +421 -0
  14. package/browser/esm/BbWhc8uJ8fNhVS5l.mjs +105 -0
  15. package/browser/esm/BvBLYHivUCrzyetH.mjs +87 -0
  16. package/browser/esm/CB6ULc6IX1XDHZi_.mjs +152 -0
  17. package/browser/esm/C_dDiKP0qhT8BhBm.mjs +27 -0
  18. package/browser/esm/CibjE6zDpZbn9Tch.mjs +12 -0
  19. package/browser/esm/DRa-YITYJZzB6CN0.mjs +8 -0
  20. package/browser/esm/DYVVBj4MfOVWrWWg.mjs +25 -0
  21. package/browser/esm/ESZQAKxwcZjX497y.mjs +15 -0
  22. package/browser/esm/UxKnYr9eSfIMndHc.mjs +23 -0
  23. package/browser/esm/index.mjs +40 -20
  24. package/node/esm/07eMkALj6l3ic2-e.mjs +23 -0
  25. package/node/esm/BpJRg8aS8svFd1fz.mjs +14 -0
  26. package/node/esm/DRa-YITYJZzB6CN0.mjs +8 -0
  27. package/node/esm/DX7jQUpPgudcUIMl.mjs +17 -0
  28. package/node/esm/H2OlmRdD_MaeXWfw.mjs +152 -0
  29. package/node/esm/LMRQvZ1FTfeeBOAm.mjs +27 -0
  30. package/node/esm/MHtkzgv6-lmftCf4.mjs +12 -0
  31. package/node/esm/index.mjs +144 -20
  32. package/node/esm/t_oN97enVU1dxwlA.mjs +421 -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/BSbIAsHhYU7A5end.cjs +0 -6
  104. package/browser/cjs/CBX--k0ZF7N3ca9G.cjs +0 -6
  105. package/browser/cjs/CK5E20Dn71XrTL6f.cjs +0 -1513
  106. package/browser/cjs/CqvlpYJcTXwLSCeF.cjs +0 -6
  107. package/browser/cjs/X_4PpRMAyEugNQVF.cjs +0 -32
  108. package/browser/esm/BLVMvYOWPFJLAiVU.mjs +0 -1588
  109. package/browser/esm/BrgkkarCKAJwXqVq.mjs +0 -24
  110. package/browser/esm/CESLtyXDfsydQVVg.mjs +0 -29
  111. package/browser/esm/D3or5W11kF3AtQDv.mjs +0 -266
  112. package/browser/esm/abRLINET0a_kxRah.mjs +0 -21
  113. package/node/esm/-NP1i_GBpal8QBm3.mjs +0 -1588
  114. package/node/esm/CkU2dBuZtTuNqHcn.mjs +0 -266
  115. package/node/esm/D3lnhtV6t_HipNni.mjs +0 -16
  116. package/node/esm/DI8Xz2qZF4qNjBVV.mjs +0 -29
  117. package/node/esm/DlKzpSFnzfag8ZYJ.mjs +0 -14
@@ -0,0 +1,421 @@
1
+ /**
2
+ * @license @sheetxl/scripting - Scripting - Scripting engine for Macros and formulas; includes TypeScript and EsBuild. - v0.7.23-beta.2
3
+ *
4
+ * (C) 2026-present SheetXL Inc. & Michael T. Ford
5
+ * License: The license can be found at https://www.sheetxl.com/license.
6
+ */
7
+ import { DiagnosticCode as e, n as t } from "./index.mjs";
8
+ import { InteropScalarType as n, ScalarType as r } from "@sheetxl/primitives";
9
+ var i = /* @__PURE__ */ new Map([["IReferenceRange", "p"], ["IRange", "r"]]), a = /* @__PURE__ */ new Map([
10
+ ["IWorkbook", "workbook"],
11
+ ["ISheet", "sheet"],
12
+ ["ICellRanges", "ranges"],
13
+ ["ICellRange", "range"]
14
+ ]), o = Array.from(a.keys()), s = (e, t) => {
15
+ Array.from(t.keys()).forEach((n) => {
16
+ let r = t.get(n);
17
+ t.set(`${e}.${n}`, r);
18
+ });
19
+ }, c = /* @__PURE__ */ new Map([
20
+ ["Scalar", "*"],
21
+ ["Lambda", "l"],
22
+ ["FormulaError.Known", r.Error],
23
+ ["Date", n.Date],
24
+ ["IRichData", n.RichData]
25
+ ]), l = /* @__PURE__ */ new Map([["Repeating", "repeating"]]), u = /* @__PURE__ */ new Set(["Flatten", "SheetXL.Flatten"]), d = /* @__PURE__ */ new Map([["AcceptError", "accept"], ["AcceptRefError", "accept-ref"]]), f = /* @__PURE__ */ new Set(["Omittable"]), p = "SheetXL";
26
+ s(p, i), s(p, a), s(p, l), s(p, d), f.add(`${p}.Omittable`);
27
+ var m = /* @__PURE__ */ new Map([["Promise", () => ({ async: !0 })], ["Observable", () => ({ stream: !0 })]]), h = "__scriptContext__", g = /* @__PURE__ */ new Set([
28
+ "IScript.ScriptContext",
29
+ `${p}.IScript.ScriptContext`,
30
+ "ScriptContext"
31
+ ]), _ = (e) => {
32
+ if (!e || e.length === 0) return "";
33
+ let t = "";
34
+ for (let n = 0; n < e.length; n++) {
35
+ let r = e[n], i = r.kind;
36
+ if (i !== "link") {
37
+ if (i === "linkName") {
38
+ let i = e[n + 1];
39
+ if (i?.kind === "linkText" && i.text.trim()) continue;
40
+ t += r.text;
41
+ continue;
42
+ }
43
+ t += i === "linkText" ? r.text.trim() : r.text;
44
+ }
45
+ }
46
+ return t.replace(/\r\n?/g, "\n").split(/\n[^\S\n]*\n\s*/).map((e) => e.split("\n").map((e) => e.trim()).filter(Boolean).join(" ")).filter(Boolean).join("\n").trim();
47
+ };
48
+ function v(n, s, v, y) {
49
+ let b = y?.builtInNames?.length ? new Set(y.builtInNames.map((e) => e.toUpperCase())) : null, x = [], S = [], C = null, w = (e, t, n, r) => {
50
+ let { start: i, length: a } = ((e) => {
51
+ if (!e || typeof e.getStart != "function") return {
52
+ start: 0,
53
+ length: 0
54
+ };
55
+ try {
56
+ return {
57
+ start: e.getStart(),
58
+ length: e.getWidth()
59
+ };
60
+ } catch {
61
+ return {
62
+ start: 0,
63
+ length: 0
64
+ };
65
+ }
66
+ })(e);
67
+ S.push({
68
+ start: i,
69
+ length: a,
70
+ severity: n,
71
+ code: t,
72
+ message: r
73
+ });
74
+ }, T = (e, t, n) => {
75
+ w(e, t, "error", n);
76
+ }, E = (e) => e?.parent?.name?.escapedText, D = (t, n, r, i, a = !1, o = !1) => {
77
+ let s = { count: 0 }, c = k(t, n, r, i, s, a, o);
78
+ return s.count >= 2 && (n.range || (n.range = "m", s.count -= 2), !i && s.count >= 1 && (--s.count, s.count > 0 && T(t, e.ArrayDepth, `Arrays of more than 2 dimensions are not supported: '${E(t)}'.`))), s.count > 0 && (n.arrayDepth = s.count), c;
79
+ }, O = (e, t, r, i, a) => {
80
+ if (t !== "Lambda" && t !== `${p}.Lambda`) return !1;
81
+ let o = e.typeArguments, s = "*";
82
+ if (o && o.length === 2) if (a && o[0].kind === n.SyntaxKind.TupleType && (r.lambdaArity = o[0].elements.length), o[1].kind === n.SyntaxKind.AnyKeyword) s = "raw";
83
+ else {
84
+ let e = {};
85
+ k(o[1], e, i, !1, { count: 0 }), s = e.scalar ?? "*";
86
+ }
87
+ else if (o && o.length === 1 && o[0].kind !== n.SyntaxKind.TupleType && o[0].kind !== n.SyntaxKind.ArrayType) if (a && (r.lambdaArity = 2), o[0].kind === n.SyntaxKind.AnyKeyword) s = "raw";
88
+ else {
89
+ let e = {};
90
+ k(o[0], e, i, !1, { count: 0 }), s = e.scalar ?? "*";
91
+ }
92
+ return r.lambda = s, !0;
93
+ }, k = (t, s, _, v, y, b = !1, x = !1) => {
94
+ if (t) {
95
+ if (t.kind === n.SyntaxKind.ParenthesizedType) return k(t.type, s, _, v, y, b, x);
96
+ if (t.kind === n.SyntaxKind.UnionType) {
97
+ let i = (e) => e.kind === n.SyntaxKind.UndefinedKeyword || e.kind === n.SyntaxKind.VoidKeyword || e.kind === n.SyntaxKind.NullKeyword || e.kind === n.SyntaxKind.LiteralType && e.literal?.kind === n.SyntaxKind.NullKeyword, a = t.types.filter((e) => !i(e));
98
+ if (a.length === 1) return k(a[0], s, _, v, y, b, x);
99
+ let o = (e) => {
100
+ if (e.kind !== n.SyntaxKind.LiteralType) return;
101
+ let t = e.literal;
102
+ return t?.kind === n.SyntaxKind.NumericLiteral || t?.kind === n.SyntaxKind.PrefixUnaryExpression && t.operand?.kind === n.SyntaxKind.NumericLiteral ? n.SyntaxKind.NumericLiteral : t?.kind === n.SyntaxKind.StringLiteral ? n.SyntaxKind.StringLiteral : void 0;
103
+ }, c = o(a[0]);
104
+ if (c !== void 0 && a.every((e) => o(e) === c)) return void (s.scalar = c === n.SyntaxKind.NumericLiteral ? r.Number : r.String);
105
+ if (!v) return void (s.scalar = "*");
106
+ if (a.length === 2) {
107
+ let e = (e) => {
108
+ if (e.kind !== n.SyntaxKind.TypeReference) return !1;
109
+ let t = n.isTypeReferenceNode(e) ? e.typeName.getText() : "";
110
+ return t === "Lambda" || t === `${p}.Lambda`;
111
+ }, t = a.findIndex(e);
112
+ if (t >= 0 && !e(a[1 - t])) return k(a[1 - t], s, _, v, y, b, x), void O(a[t], a[t].typeName.getText(), s, _, v);
113
+ }
114
+ T(t, e.InvalidParamType, `Union parameter types are not supported: '${E(t)}'. Use a single type, optionally with '| null' or '| undefined', or 'T | Lambda<…>' for a value-or-lambda slot.`);
115
+ return;
116
+ }
117
+ if (t.kind === n.SyntaxKind.NumberKeyword) s.scalar = r.Number;
118
+ else if (t.kind === n.SyntaxKind.StringKeyword) s.scalar = r.String;
119
+ else if (t.kind === n.SyntaxKind.BooleanKeyword) s.scalar = r.Boolean;
120
+ else if (t.kind === n.SyntaxKind.UndefinedKeyword || t.kind === n.SyntaxKind.NullKeyword || t.kind === n.SyntaxKind.VoidKeyword) {
121
+ if (v) return void T(t, e.UndefinedInput, `'undefined' is not a valid type for input: '${E(t)}'.`);
122
+ s.scalar = r.Null;
123
+ } else if (t.kind === n.SyntaxKind.BigIntKeyword) s.scalar = r.Number;
124
+ else if (t.kind === n.SyntaxKind.AnyKeyword) v && (s.range = "*");
125
+ else if (t.kind === n.SyntaxKind.ArrayType) {
126
+ let n = t.elementType;
127
+ if (!n) return void T(t, e.UntypedArray, `'Array' must be typed: '${E(t)}'.`);
128
+ if (v && x) {
129
+ let e = s, r = e.name ?? E(t) ?? "parameter", i = e.errors;
130
+ delete e.errors;
131
+ let a = { name: r };
132
+ D(n, a, _, !0), i && !a.errors && (a.errors = i), e.repeating = [a];
133
+ return;
134
+ }
135
+ y.count++, k(n, s, _, v, y);
136
+ } else if (t.kind !== n.SyntaxKind.TupleType) if (t.kind === n.SyntaxKind.TypeReference) {
137
+ let r = t.typeName?.getText?.() ?? null, p = d.get(r);
138
+ if (p) {
139
+ let n = E(t);
140
+ if (!v) return void T(t, e.InvalidReturnType, `'${r}' is not a valid return type: '${n}'. Error-policy markers apply to parameters only.`);
141
+ let i = s;
142
+ if (i.errors) return void T(t, e.InvalidParamType, `'${n}' declares more than one error-policy marker ('${i.errors}' and '${p}'). Only one is allowed.`);
143
+ let a = t.typeArguments;
144
+ return a && a.length === 1 ? (i.errors = p, k(a[0], s, _, v, y, b, x)) : void T(t, e.GenericArity, `'${r}' must be typed with exactly 1 type: '${n}'.`);
145
+ }
146
+ if (f.has(r)) {
147
+ let i = s.name ?? E(t);
148
+ if (!v) return void T(t, e.InvalidReturnType, `'Omittable' is not a valid return type: '${i}'. It describes how an ARGUMENT is received.`);
149
+ let a = t.typeArguments;
150
+ if (!a || a.length < 1 || a.length > 2) return void T(t, e.GenericArity, `'${r}' must be typed with 1 or 2 types: '${i}'.`);
151
+ let o = s;
152
+ if (o.omittable = !0, a.length === 2) {
153
+ let s = ((e, t) => {
154
+ let n = t.literal;
155
+ if (n === void 0) return;
156
+ let r = e.SyntaxKind;
157
+ switch (n.kind) {
158
+ case r.StringLiteral: return n.text;
159
+ case r.NumericLiteral: return parseFloat(n.text);
160
+ case r.TrueKeyword: return !0;
161
+ case r.FalseKeyword: return !1;
162
+ case r.NullKeyword: return null;
163
+ case r.PrefixUnaryExpression: return n.operator === r.MinusToken && n.operand?.kind === r.NumericLiteral ? -parseFloat(n.operand.text) : void 0;
164
+ default: return;
165
+ }
166
+ })(n, a[1]);
167
+ if (s === void 0) return void T(t, e.InvalidParamType, `'${i}' declares '${r}' with a second type that is not a literal value. Use a number, string, boolean or null - the engine substitutes it for an omitted argument.`);
168
+ o.omittedValue = s;
169
+ }
170
+ return k(a[0], s, _, v, y, b, x);
171
+ }
172
+ if (u.has(r)) {
173
+ let n = s.name ?? E(t);
174
+ if (!v) return void T(t, e.InvalidReturnType, `'Flatten' is not a valid return type: '${n}'. It describes how an ARGUMENT is received.`);
175
+ let i = t.typeArguments;
176
+ return i && i.length === 1 ? (y.count++, k(i[0], s, _, v, y, b)) : void T(t, e.GenericArity, `'${r}' must be typed with exactly 1 type: '${n}'.`);
177
+ }
178
+ if (l.get(r) === "repeating") {
179
+ let i = s.name ?? E(t);
180
+ if (!v) return void T(t, e.RepeatingPosition, `'Repeating' is not a valid return type: '${i}'.`);
181
+ if (y.count !== 0) return void T(t, e.RepeatingPosition, `'Repeating' cannot be nested inside another type: '${i}'.`);
182
+ let a = s, o = t.typeArguments;
183
+ if (!o || o.length !== 1) return void T(t, e.GenericArity, `'${r}' must be typed with exactly 1 type: '${i}'.`);
184
+ let c = a.errors;
185
+ delete a.errors;
186
+ let l = ((t, r, i, a) => {
187
+ let o = (e, t, n) => {
188
+ let r = { name: e };
189
+ return D(t, r, i, !0), n && (r.optional = !0), a && !r.errors && (r.errors = a), r;
190
+ };
191
+ if (t.kind !== n.SyntaxKind.TupleType) return [o(r, t, !1)];
192
+ let s = t.elements;
193
+ if (s.length < 2) return T(t, e.RepeatingSlots, `'${r}': a repeating group of period ${s.length} must be spelled 'Repeating<T>' without the tuple.`), null;
194
+ let c = [];
195
+ for (let t = 0; t < s.length; t++) {
196
+ let i = s[t];
197
+ if (i.kind !== n.SyntaxKind.NamedTupleMember) return T(i, e.RepeatingSlots, `'${r}': every slot of a repeating group must be labelled, e.g. 'Repeating<[criteriaRange: IRange, criteria: Scalar]>'.`), null;
198
+ let a = !!i.questionToken;
199
+ if (a && t !== s.length - 1) return T(i, e.RepeatingOptional, `'${r}': only the LAST slot of a repeating group may be optional (slot '${i.name?.getText?.()}' is not).`), null;
200
+ c.push(o(i.name?.getText?.() ?? `${t}`, i.type, a));
201
+ }
202
+ return c;
203
+ })(o[0], i ?? "parameter", _, c);
204
+ l && (a.repeating = l);
205
+ return;
206
+ }
207
+ let S = i.get(r), C = !1;
208
+ S && (s.range = S, C = !0);
209
+ let w = c.get(r);
210
+ if (w && (s.scalar = w), w !== void 0 && (C = !0), O(t, r, s, _, v)) return;
211
+ if (v) {
212
+ if (g.has(r)) return h;
213
+ let e = a.get(r);
214
+ if (e) return e;
215
+ } else {
216
+ let n = m.get(r);
217
+ if (n) {
218
+ let i = Object.assign(s, n()), a = 0;
219
+ if (i.async && a++, i.stream && a++, a > 1) return void T(t, e.MultipleModifiers, `'${r}' cannot have multiple modifiers: '${E(t)}'.`);
220
+ C = !0;
221
+ }
222
+ }
223
+ if (!C) {
224
+ let n = "number, string, boolean, Scalar, Lambda, Date, FormulaError.Known, IRichData, IRange, IReferenceRange (and arrays of these; optionally wrapped in AcceptError<T>/AcceptRefError<T>, or grouped with Repeating<T>)", i;
225
+ i = v ? b ? `'${r}' is not a valid first parameter: '${E(t)}'. The first parameter is EITHER a macro target (making this a macro) OR a calculation input (making this a calculation function). Allowed: ${o.join(", ")} (macro target); ${n} (calculation input).` : `'${r}' is not a valid parameter type: '${E(t)}'. Allowed: ${n}.` : `'${r}' is not a valid return type: '${E(t)}'. Allowed: number, string, boolean, Scalar, Date, FormulaError.Known, IRichData, IRange, Promise<T>, Observable<T> (and arrays of these).`, T(t, v ? e.InvalidParamType : e.InvalidReturnType, i);
226
+ return;
227
+ }
228
+ let A = t.typeArguments;
229
+ if (A) {
230
+ if (A.length !== 1) return void T(t, e.GenericArity, `'${r}' must be typed with exactly 1 type: '${E(t)}'.`);
231
+ D(A[0], s, _, v);
232
+ }
233
+ } else t.kind === n.SyntaxKind.FunctionType && ((t, r, i, a) => {
234
+ if (!a) return void T(t, e.FunctionReturn, `Function type is not a valid return type: '${E(t)}'. Declare a 'Lambda' return instead.`);
235
+ let o = t.type, s = {}, c = "*";
236
+ o && (o.kind === n.SyntaxKind.AnyKeyword ? c = "raw" : (k(o, s, i, !1, { count: 0 }), c = s.scalar ?? "*"));
237
+ let l = t.parameters;
238
+ l && !l.some((e) => e.dotDotDotToken) && (r.lambdaArity = l.length), r.lambda = c;
239
+ })(t, s, _, v);
240
+ } else T(t, e.MissingType, `Type is not defined for '${s?.name ?? "return"}'.`);
241
+ };
242
+ try {
243
+ n.forEachChild(s, (r) => {
244
+ if (((e) => (n.getCombinedModifierFlags(e) & n.ModifierFlags.Export) !== 0)(r) && n.isFunctionDeclaration(r)) {
245
+ let i = r?.name?.getText();
246
+ if (!r.body) return void T(r, e.NoBody, `'${i}': function has no body.`);
247
+ if (!i) return void T(r, e.Anonymous, "Anonymous exported functions are not allowed.");
248
+ let a = {}, o = { parameters: {} };
249
+ try {
250
+ a.name = i;
251
+ let s = _(v.getSymbolAtLocation(r.name)?.getDocumentationComment(v));
252
+ s && (o.summary = s);
253
+ let c = {};
254
+ D(r.type, c, a, !1), a.returnType = c;
255
+ let l = {};
256
+ ((e) => (n.getCombinedModifierFlags(e) & n.ModifierFlags.Default) !== 0)(r) && (l.default = !0, C = i), Object.keys(l).length > 0 && (a.behavior = l), a.parameters = [];
257
+ let u = /* @__PURE__ */ new Map(), d = /* @__PURE__ */ new Map(), f = /* @__PURE__ */ new Set(), p = null, m = null, g = null, y = 0, S = !1, E = 0;
258
+ for (let t = 0; t < r.parameters.length; t++) {
259
+ let i = r.parameters[t], s = {};
260
+ s.name = i.name?.getText();
261
+ let c = a.parameters.length === 0, l = D(i.type, s, a, !0, c, !i.dotDotDotToken);
262
+ if (l === h) {
263
+ t === 0 && a.context === void 0 && (a.context = "script");
264
+ continue;
265
+ }
266
+ if (l) {
267
+ if (a.parameters.length !== 0) return void T(i, e.ContextNotFirst, `'${a.name}' contexts must be the first parameter: '${s.name}'.`);
268
+ a.context = l;
269
+ continue;
270
+ }
271
+ if (s.lambda !== void 0) {
272
+ if (p !== null) return void T(i, e.MultipleLambda, `'${a.name}' has more than one Lambda parameter ('${p}' and '${s.name}'). Only one Lambda parameter is allowed.`);
273
+ p = s.name;
274
+ } else if (p !== null) return void T(i, e.LambdaNotLast, `'${a.name}' Lambda parameter ('${p}') must be the last parameter, but '${s.name}' follows it.`);
275
+ let b = i.initializer !== void 0 && i.initializer !== null || i.questionToken !== void 0 && i.questionToken !== null, x;
276
+ if (b && (s.optional = !0, i.initializer)) try {
277
+ i.initializer.kind === n.SyntaxKind.StringLiteral ? x = i.initializer.text : i.initializer.kind === n.SyntaxKind.NumericLiteral ? x = parseFloat(i.initializer.text) : i.initializer.kind === n.SyntaxKind.TrueKeyword || i.initializer.kind === n.SyntaxKind.FalseKeyword ? x = i.initializer.kind === n.SyntaxKind.TrueKeyword : i.initializer.kind === n.SyntaxKind.NullKeyword && (x = null);
278
+ } catch (e) {
279
+ console.warn(`Couldn't extract default value for parameter '${s.name}'`, e);
280
+ }
281
+ i.dotDotDotToken && (s.rest = !0);
282
+ let C = s.repeating;
283
+ if (C) {
284
+ if (s.rest) return void T(i, e.RepeatingPosition, `'${a.name}' parameter '${s.name}' is both a rest parameter and a repeating group. A group already repeats — drop the '...'.`);
285
+ if (b && C.length === 1) return void T(i, e.RepeatingOptional, `'${a.name}' parameter '${s.name}' cannot be an optional repeating group. Use '...${s.name}: T[]' for zero-or-more, or drop the '?' for one-or-more.`);
286
+ if (m !== null) return void T(i, e.MultipleRepeating, `'${a.name}' has more than one repeating group ('${m}' and '${s.name}'). Only one is allowed — two would make the argument count ambiguous.`);
287
+ if (g !== null) return void T(i, e.RepeatingOptional, `'${a.name}' parameter '${g}' is optional and precedes the repeating group '${s.name}'. Every parameter outside a group must be required.`);
288
+ m = s.name, y = C.length, S = !0 === C[C.length - 1].optional;
289
+ } else {
290
+ if (m !== null && s.rest) return void T(i, e.RepeatingOptional, `'${a.name}' parameter '${s.name}' is a rest parameter and follows the repeating group '${m}'. Two variadic tails would make the argument count ambiguous.`);
291
+ if (m !== null && b) {
292
+ if (E >= y - 1) return void T(i, e.RepeatingOptional, y === 1 ? `'${a.name}' parameter '${s.name}' is optional and follows the period-1 repeating group '${m}'. One more argument is indistinguishable from one more repetition — make it required, or give the group a period.` : `'${a.name}' has ${E + 1} optional parameters after the repeating group '${m}', which has period ${y}. At most ${y - 1} may be optional, or the argument count no longer decides the parse.`);
293
+ if (S) return void T(i, e.RepeatingOptional, `'${a.name}' parameter '${s.name}' is optional and follows '${m}', whose own last slot is already optional. Both omissions reach the same argument count — drop one.`);
294
+ E++;
295
+ }
296
+ }
297
+ b && !C && (g = s.name);
298
+ let w = (s.range ? 2 : 0) + (s.arrayDepth ?? 0), O = s.range === "r" || s.range === "p" || s.range === "*", k = s.rest || O ? 3 : 2;
299
+ if (w > k) return void T(i, e.ArrayDepth, `'${a.name}' parameter '${s.name}' has an array depth of ${w}; the maximum is ${k}${s.rest ? " for a rest parameter" : " (use a rest parameter for one more level, or an IRange)"}.`);
300
+ a.parameters.push(s);
301
+ let A = { description: "" };
302
+ if (o.parameters[s.name] = A, A.description = _(v.getSymbolAtLocation(i.name)?.getDocumentationComment(v)), x !== void 0 && (s.defaultValue = x), u.set(s.name, s), d.set(s.name, i), C && C.length > 1) {
303
+ f.add(s.name);
304
+ for (let e of C) {
305
+ let t = `${s.name}.${e.name}`;
306
+ o.parameters[t] = { description: "" }, u.set(t, e), d.set(t, i);
307
+ }
308
+ }
309
+ }
310
+ if (r.jsDoc && r.jsDoc.length > 0) {
311
+ let s = r.jsDoc, c = s.length;
312
+ for (let r = 0; r < c; r++) {
313
+ let c = s[r]?.tags;
314
+ if (!c) continue;
315
+ let l = c.length;
316
+ for (let r = 0; r < l; r++) {
317
+ let s = c[r], l = s?.tagName?.text;
318
+ if (!l) continue;
319
+ l = l.toLowerCase();
320
+ let d = s.comment, f = t(l);
321
+ if ((typeof d == "string" || f) && (typeof d == "string" && (d = d.replace(/\r\n?/g, "\n").trim()), f || !d || (d = d.split("\n")[0].trim(), d && d.length !== 0))) {
322
+ if (d && typeof d == "string") {
323
+ let e = /\{@link(code|plain)?\s+([^}|]+)(?:\s*\|\s*([^}]+))?\}/g, t, n = d, r = [];
324
+ for (; (t = e.exec(d)) !== null;) {
325
+ let [e, n, r, i] = t, a = [r.trim()];
326
+ i && a.push(i.trim());
327
+ }
328
+ d = n, r.length > 0 && l === "see" && (o.links ||= [], o.links.push(...r));
329
+ }
330
+ if (l === "name") {
331
+ let e = d;
332
+ e !== i && (o.name = e);
333
+ } else if (l !== "description") {
334
+ if (l === "summary") {
335
+ let e = d;
336
+ e && (o.summary = e);
337
+ } else if (l === "param") {
338
+ let t = s.name?.getText?.() ?? s.name?.text, r = u.get(t);
339
+ if (!r) {
340
+ T(s, e.UnknownParam, `Parameter '${t}' not found in function '${i}'.`);
341
+ continue;
342
+ }
343
+ let a = o.parameters?.[t];
344
+ if (a && !a.description && typeof d == "string" && d && (a.description = d), s.typeExpression && s.typeExpression.type) try {
345
+ let e = s.typeExpression.type;
346
+ if (e.kind === n.SyntaxKind.UnionType) {
347
+ let t = [];
348
+ r.enums = t, e.types.forEach((e) => {
349
+ if (e.kind === n.SyntaxKind.LiteralType) {
350
+ let n = e.literal.text;
351
+ n && t.push(n);
352
+ }
353
+ });
354
+ }
355
+ } catch (e) {
356
+ console.warn("Error parsing JSDoc type expression:", e);
357
+ }
358
+ } else if (l === "returns" || l === "return") a.returnType.description = d;
359
+ else if (l === "category") o.category = d;
360
+ else if (l === "deprecated" || l === "hidden") {
361
+ let e = !0, t = d?.toLowerCase();
362
+ t === "false" ? e = !1 : t !== "true" && (e = d), !1 !== e && (o.deprecated = e ?? !0);
363
+ }
364
+ }
365
+ }
366
+ }
367
+ }
368
+ }
369
+ Object.keys(a.returnType).length === 0 && delete a.returnType, o.summary || w(r.name ?? r, e.MissingSummary, "warning", `'${i}': missing a description. Add a JSDoc summary or '@summary'.`);
370
+ let O = !a.context;
371
+ if (O && b?.has(i.toUpperCase())) return void T(r.name ?? r, e.BuiltInName, `'${i}' is a built-in function. Choose a different name - a calculation function cannot replace a built-in.`);
372
+ if (O) {
373
+ let t = o.parameters ?? {};
374
+ for (let [n, r] of Object.entries(t)) if (!f.has(n) && !r.description) {
375
+ let t = d.get(n);
376
+ w(t, e.MissingParamDescription, "warning", `'${i}': parameter '${n}' is missing a description. Add an '@param ${n}' tag.`);
377
+ }
378
+ }
379
+ x.push([a, o]);
380
+ } catch (t) {
381
+ T(r, e.ParseError, `'${i}': ${t.message}`);
382
+ }
383
+ }
384
+ });
385
+ } catch (t) {
386
+ T(void 0, e.ParseError, `Unable to analyze module: ${t?.message ?? t}`);
387
+ }
388
+ return {
389
+ functions: x,
390
+ autoRun: C,
391
+ diagnostics: S
392
+ };
393
+ }
394
+ function y(e, t, n) {
395
+ let r = "script.ts", i = "lib.d.ts", a = {
396
+ [r]: t ?? "",
397
+ [i]: ""
398
+ }, o = e.createProgram([r], {
399
+ allowJs: !0,
400
+ noResolve: !0,
401
+ noLib: !0,
402
+ isolatedModules: !0,
403
+ module: 99,
404
+ target: e.ScriptTarget.ES2020
405
+ }, {
406
+ getSourceFile: (t) => {
407
+ let n = a[t];
408
+ if (n !== void 0) return e.createSourceFile(t, n, e.ScriptTarget.Latest, !0);
409
+ },
410
+ fileExists: (e) => a[e] !== void 0,
411
+ readFile: (e) => a[e],
412
+ writeFile: () => {},
413
+ getCurrentDirectory: () => "./",
414
+ getCanonicalFileName: (e) => e,
415
+ useCaseSensitiveFileNames: () => !0,
416
+ getDefaultLibFileName: () => i,
417
+ getNewLine: () => "\n"
418
+ }), s = o.getTypeChecker(), c = o.getSourceFile(r);
419
+ return c ? v(e, c, s, n).diagnostics : [];
420
+ }
421
+ export { v as analyzeModule, y as lintScript };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@sheetxl/scripting",
3
3
  "description": "Scripting - Scripting engine for Macros and formulas; includes TypeScript and EsBuild.",
4
- "version": "0.7.22",
4
+ "version": "0.7.23-beta.2",
5
5
  "license": "SEE LICENSE IN <LICENSE>",
6
6
  "type": "module",
7
7
  "exports": {
@@ -16,9 +16,9 @@
16
16
  "types": "./types/index.d.ts",
17
17
  "module": "./browser/esm/index.mjs",
18
18
  "main": "./browser/cjs/index.cjs",
19
- "sideEffects": true,
19
+ "sideEffects": false,
20
20
  "engines": {
21
- "node": ">=20 <21 || >=22"
21
+ "node": ">=22"
22
22
  },
23
23
  "engineStrict": true,
24
24
  "homepage": "https://sheetxl.com",
@@ -40,12 +40,15 @@
40
40
  "scripting"
41
41
  ],
42
42
  "dependencies": {
43
- "@sheetxl/primitives": "^0.7.22",
44
- "@sheetxl/utils": "^0.7.22",
45
- "path-browserify": "^1.0.1"
43
+ "@sheetxl/primitives": "^0.7.23-beta.2",
44
+ "@sheetxl/utils": "^0.7.23-beta.2"
46
45
  },
47
46
  "peerDependencies": {
48
- "esbuild-wasm": "^0.25.7",
49
- "typescript": "^5.9.0"
47
+ "esbuild-wasm": ">=0.25.7",
48
+ "typescript": "^5.9.0 || ^6.0.0",
49
+ "vite": "^8.0.0"
50
+ },
51
+ "devDependencies": {
52
+ "@types/node": "^26.1.2"
50
53
  }
51
54
  }
package/types/index.d.ts CHANGED
@@ -1,165 +1,2 @@
1
- import { IFormulaContext } from '@sheetxl/primitives';
2
- import { IFunction } from '@sheetxl/primitives';
3
-
4
- /**
5
- * Represents a compile collections of functions.
6
- */
7
- export declare interface CompiledModule {
8
- /**
9
- * An array of `Declaration` and `Description pairs describing the functions within the script.
10
- *
11
- * @remarks
12
- * This array can be empty. It is possible that a script might contain only comments or other non-executable code.
13
- */
14
- functions: [IFunction.DeclarationJSON, IFunction.DescriptorJSON][];
15
- /**
16
- * The human-readable source code of the script.
17
- *
18
- * @remarks
19
- * If this property is missing, the script will not be displayed but the 'actions' will still be available if `compiled` is present.
20
- */
21
- source?: string;
22
- /**
23
- * The compiled or pre-processed version of the script, ready for execution.
24
- *
25
- * @remarks
26
- * If this property is missing, the script will be compiled on demand if possible.
27
- */
28
- compiled?: string;
29
- /**
30
- * The language the function is written in.
31
- *
32
- * @defaultValue typescript
33
- */
34
- language?: string;
35
- /**
36
- * The name of the module.
37
- */
38
- name?: string;
39
- /**
40
- * A unique identifier for the function (e.g., a Git commit ID).
41
- * // https://stackoverflow.com/questions/29106996/what-is-a-git-commit-id
42
- */
43
- commitId?: string;
44
- /**
45
- * The name of the function to run automatically when the script is loaded.
46
- */
47
- autoRun?: string;
48
- /**
49
- * ** NOT IMPLEMENTED **
50
- * Available in functions via the 'this' value.
51
- * Will auto persist values on save.
52
- *
53
- * TODO - this doesn't belong here.
54
- * Create a new interface for session state.
55
- * TODO - rename to sessionData
56
- */
57
- scope?: any;
58
- }
59
-
60
- /**
61
- * Options for compiling a script module.
62
- */
63
- export declare interface CompileOptions {
64
- /**
65
- * The source code of the script module to compile.
66
- */
67
- source: string;
68
- /**
69
- * If true, this will not include the bundle in the compiled module.
70
- *
71
- * @remarks
72
- * This is useful for validation
73
- */
74
- disableBundle?: boolean;
75
- /**
76
- * If true, this will not include the source map in the compiled module.
77
- */
78
- disableSourceMap?: boolean;
79
- /**
80
- * For validation
81
- */
82
- declarationsOnly?: boolean;
83
- /**
84
- * The commit ID for the compilation.
85
- */
86
- commitId?: string;
87
- }
88
-
89
- /**
90
- * The return type for Compile.
91
- */
92
- export declare interface CompileResults {
93
- module: CompiledModule;
94
- errors: any;
95
- }
96
-
97
- /**
98
- * Converts a typescript string into a `CompiledModule`.
99
- *
100
- * @param options Optional compilation options
101
- */
102
- declare function compileTypescript(options: CompileOptions): Promise<CompiledModule>;
103
-
104
- export declare interface DescriptorModule {
105
- default: MinifiedDescriptors;
106
- }
107
-
108
- export declare type DynamicDescriptors = () => Promise<DescriptorModule>;
109
-
110
- /**
111
- * Type for bind signature for typed functions.
112
- */
113
- export declare interface FunctionBinder {
114
- (mapBind: Map<string, IFunction>, getContext: () => IFormulaContext, implementations: Implementations, declarations: MinifiedDeclarations, getDynamicDescriptors?: DynamicDescriptors, defaultCategory?: string): void;
115
- }
116
-
117
- export declare interface Implementations {
118
- [functionName: string]: (...args: any) => any;
119
- }
120
-
121
- /**
122
- * The function declaration needed to autoMarshall and execute.
123
- */
124
- export declare interface MinifiedDeclaration {
125
- fn?: string;
126
- c?: boolean;
127
- p?: MinifiedParameter[];
128
- }
129
-
130
- export declare type MinifiedDeclarations = {
131
- [name: string]: MinifiedDeclaration;
132
- };
133
-
134
- /**
135
- * The descriptor used for a function
136
- */
137
- export declare interface MinifiedDescriptor {
138
- s?: string;
139
- c?: string;
140
- p?: Record<string, any>;
141
- h?: string | boolean;
142
- l?: [url: string, text?: string][];
143
- }
144
-
145
- export declare interface MinifiedDescriptors {
146
- [name: string]: MinifiedDescriptor;
147
- }
148
-
149
- /**
150
- * Minified params.
151
- */
152
- export declare interface MinifiedParameter {
153
- n: string;
154
- s?: string;
155
- r?: 'r' | 'l' | 'a';
156
- d?: number;
157
- m?: '?' | '...';
158
- e?: string[];
159
- }
160
-
161
- export declare const ScriptingUtils: Readonly<{
162
- compileTypescript: typeof compileTypescript;
163
- }>;
164
-
165
- export { }
1
+ export * from './src/index'
2
+ export {}
@@ -0,0 +1,40 @@
1
+ import { CompileOptions, CompileResult, Diagnostic } from './type';
2
+ import { AnalyzeOptions } from './linter';
3
+ /**
4
+ * Compiles a typescript string into a {@link CompileResult} (the compiled `module` + this compile's
5
+ * `diagnostics`). Diagnostics are on the result, not the persisted module artifact.
6
+ *
7
+ * @param options Optional compilation options
8
+ */
9
+ declare function compile(options: CompileOptions): Promise<CompileResult>;
10
+ /**
11
+ * Lints TypeScript source against SheetXL's semantic authoring rules and returns positioned
12
+ * diagnostics. Does **not** emit JavaScript - this is the fast path for editors and `sheetxl lint`.
13
+ *
14
+ * @param source The script source to lint.
15
+ * @param options Host facts the rules need — today the built-in function names, without which the
16
+ * built-in-name rule does not run.
17
+ *
18
+ * @remarks
19
+ * The TypeScript module is loaded lazily on first call, so importing this does not pull the compiler
20
+ * into a bundle until linting actually happens.
21
+ */
22
+ declare function lint(source: string, options?: AnalyzeOptions): Promise<Diagnostic[]>;
23
+ /**
24
+ * Optional but recommended: A function to clean up the worker
25
+ * if the application needs to release resources.
26
+ */
27
+ declare function cleanup(): void;
28
+ /**
29
+ * The scripting compile/lint facade. Language-agnostic by intent — `compile`/`lint` take TypeScript
30
+ * today; a future backend (e.g. Python) can be dispatched behind the same entry without changing the
31
+ * public surface. The heavy engine (compiler worker / linter) is reached only lazily via dynamic
32
+ * `import()`, so referencing `ScriptCompiler` does not pull it into a consumer bundle.
33
+ */
34
+ export declare const ScriptCompiler: Readonly<{
35
+ compile: typeof compile;
36
+ lint: typeof lint;
37
+ cleanup: typeof cleanup;
38
+ }>;
39
+ export {};
40
+ //# sourceMappingURL=ScriptCompiler.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ScriptCompiler.d.ts","sourceRoot":"","sources":["../../../src/ScriptCompiler.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAClF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAsB/C;;;;;GAKG;AACH,iBAAe,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CActE;AAeD;;;;;;;;;;;GAWG;AACH,iBAAe,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAMnF;AAED;;;GAGG;AACH,iBAAS,OAAO,IAAI,IAAI,CAMvB;AAcD;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;EAIzB,CAAC"}