@sheetxl/scripting 0.7.26 → 0.7.28-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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/1FxoZcQW9Jtuz8rC.cjs +0 -6
  70. package/browser/cjs/BVflpadZI0FMHzPP.cjs +0 -6
  71. package/browser/cjs/Bgxi3ZUQTg5EKFnv.cjs +0 -1518
  72. package/browser/cjs/DL2hE-VUVbfy6Zem.cjs +0 -32
  73. package/browser/cjs/Ms_ibGXEX6074qzl.cjs +0 -6
  74. package/browser/esm/C1DZmlRCcKmg_HLd.mjs +0 -266
  75. package/browser/esm/C_2SCwrJ3CRR32wO.mjs +0 -29
  76. package/browser/esm/DHtoG6tI2hwnhrwX.mjs +0 -24
  77. package/browser/esm/DPCvyj5K9rQVitWC.mjs +0 -21
  78. package/browser/esm/Dg6kfw8Ea-sxI1gY.mjs +0 -1593
  79. package/node/esm/0Q-PVUbTe0_lgcA4.mjs +0 -1593
  80. package/node/esm/CZnHRAY4OIqaUtzw.mjs +0 -29
  81. package/node/esm/DWz-8-6mYiVKd77G.mjs +0 -14
  82. package/node/esm/DZrPx9_OUGxc6TPg.mjs +0 -16
  83. package/node/esm/z6mcRv7V2HRJW0d0.mjs +0 -266
@@ -0,0 +1,7 @@
1
+ export * from './type';
2
+ export * from './tags';
3
+ export * from './runtime';
4
+ export * from './loader';
5
+ export type * from './linter';
6
+ export { ScriptCompiler } from './ScriptCompiler';
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,4 @@
1
+ import type * as esbuild from 'esbuild-wasm';
2
+ export type EsbuildInstance = typeof esbuild;
3
+ export declare function initialize(): Promise<EsbuildInstance>;
4
+ //# sourceMappingURL=esbuild.browser.d.ts.map
@@ -0,0 +1,11 @@
1
+ import * as esbuild from 'esbuild-wasm';
2
+ export type EsbuildInstance = typeof esbuild;
3
+ /**
4
+ * Initializes esbuild-wasm under Node.
5
+ *
6
+ * The Node entry of esbuild-wasm runs the wasm via a child process and rejects all browser-only
7
+ * options (`wasmURL`, `wasmModule`, `worker`). So `initialize()` must be called with no options -
8
+ * no network fetch, no native binary, always version-matched to the installed package.
9
+ */
10
+ export declare function initialize(): Promise<EsbuildInstance>;
11
+ //# sourceMappingURL=esbuild.node.d.ts.map
@@ -0,0 +1,4 @@
1
+ type TypeScriptModule = typeof import('typescript');
2
+ export declare function initialize(): Promise<TypeScriptModule>;
3
+ export {};
4
+ //# sourceMappingURL=typescript.browser.d.ts.map
@@ -0,0 +1,4 @@
1
+ type TypeScriptModule = typeof import('typescript');
2
+ export declare function initialize(): Promise<TypeScriptModule>;
3
+ export {};
4
+ //# sourceMappingURL=typescript.node.d.ts.map
@@ -0,0 +1,63 @@
1
+ import { default as ts } from 'typescript';
2
+ import { IFunction } from '@sheetxl/primitives';
3
+ import { Diagnostic } from '../type';
4
+ /**
5
+ * The result of analyzing a script module: the function declarations/descriptors that the compiler
6
+ * needs, the auto-run entry point (if any), and the positioned diagnostics produced by our semantic
7
+ * rules.
8
+ */
9
+ export interface Analysis {
10
+ /**
11
+ * The `Declaration`/`Descriptor` pairs for each exported function. Always populated for functions
12
+ * that parsed, even when error-severity diagnostics exist (so partial results remain useful).
13
+ */
14
+ functions: [IFunction.DeclarationJSON, IFunction.DescriptorJSON][];
15
+ /**
16
+ * The name of the `export default` function to run automatically, if any.
17
+ */
18
+ autoRun: string | null;
19
+ /**
20
+ * Positioned diagnostics (errors + warnings).
21
+ */
22
+ diagnostics: Diagnostic[];
23
+ }
24
+ /**
25
+ * What the analysis needs from the host — facts this package cannot know on its own.
26
+ */
27
+ export interface AnalyzeOptions {
28
+ /**
29
+ * The names of the host's built-in functions. A calculation function that takes one is reported
30
+ * ({@link DiagnosticCode.BuiltInName}); omitted, the rule does not run. Compared
31
+ * case-insensitively.
32
+ */
33
+ builtInNames?: readonly string[];
34
+ }
35
+ /**
36
+ * Walks an already-parsed/checked source file and applies SheetXL's semantic authoring rules.
37
+ *
38
+ * @param ts The TypeScript module (compiler API).
39
+ * @param sourceFile The script source file (must be created with `setParentNodes = true`).
40
+ * @param checker The type checker from the program containing `sourceFile`.
41
+ * @param options {@link AnalyzeOptions} — host facts the rules need.
42
+ *
43
+ * @remarks
44
+ * This is the single environment-agnostic engine. It does not emit, bundle, touch the DOM, or read
45
+ * the filesystem. {@link compileModule} calls it to build declarations and decide whether to emit;
46
+ * {@link lintScript} calls it to produce diagnostics for editors/CLIs.
47
+ */
48
+ export declare function analyzeModule(ts: typeof import('typescript'), sourceFile: ts.SourceFile, checker: ts.TypeChecker, options?: AnalyzeOptions): Analysis;
49
+ /**
50
+ * Lints a script source string and returns positioned diagnostics.
51
+ *
52
+ * @param ts The TypeScript module (compiler API).
53
+ * @param source The script source to lint.
54
+ * @param options {@link AnalyzeOptions} — host facts the rules need (the built-in function names).
55
+ *
56
+ * @remarks
57
+ * This is the public, environment-agnostic entry point for adapters (Monaco markers, the `sheetxl
58
+ * lint` CLI, a VSCode language-service plugin). It builds a lightweight, emit-free program — our
59
+ * rules match type names by text, so the ambient SheetXL types do not need to be loaded here.
60
+ * TypeScript's own type checking is layered separately by each editor's TS worker.
61
+ */
62
+ export declare function lintScript(ts: typeof import('typescript'), source: string, options?: AnalyzeOptions): Diagnostic[];
63
+ //# sourceMappingURL=Linter.d.ts.map
@@ -0,0 +1,2 @@
1
+ export type { Analysis, AnalyzeOptions } from './Linter';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,2 @@
1
+ export { loadCompiledModule } from './loadCompiledModule';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Loads a compiled module string and returns its namespace (the executor side of scripting).
3
+ *
4
+ * This is the public, environment-agnostic entry point. The actual loading is environment-split
5
+ * behind the internal `@sheetxl/scripting/loader` conditional export - a real temp `.mjs` under Node
6
+ * (breakpoints, Bun, Vitest), a `data:` URL in the browser.
7
+ *
8
+ * The explicit `Promise<any>` signature is deliberate: it keeps this module's generated declaration
9
+ * self-contained, so cross-package consumers (the sdk runtime) depend only on `@sheetxl/scripting`'s
10
+ * public types - never on the internal loader's per-file declarations (which avoids a composite
11
+ * project-reference build error).
12
+ *
13
+ * @param compiled The compiled JavaScript module source.
14
+ * @param options Optional `sourceMap` to append for debugging.
15
+ */
16
+ export declare function loadCompiledModule(compiled: string, options?: {
17
+ sourceMap?: string;
18
+ }): Promise<any>;
19
+ //# sourceMappingURL=loadCompiledModule.d.ts.map
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Browser/`default` half of the `@sheetxl/scripting/loader` conditional export.
3
+ *
4
+ * Loads a compiled module string by importing it as a `data:` URL. The `new Function` indirection
5
+ * keeps bundlers (webpack/vite) from statically analyzing the dynamic import. CSP-aware and the path
6
+ * used when applying a script to live client state.
7
+ */
8
+ export declare function loadCompiledModule(compiled: string, options?: {
9
+ sourceMap?: string;
10
+ }): Promise<any>;
11
+ //# sourceMappingURL=moduleLoader.browser.d.ts.map
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Node half of the `@sheetxl/scripting/loader` conditional export.
3
+ *
4
+ * Writes the compiled module to a uniquely-named `.mjs` in the OS temp dir and imports the file URL.
5
+ * Unlike a `data:` URL this gives the module a real path - so breakpoints and stack traces resolve
6
+ * in vscode - and it runs under Bun and Vitest's VM (where `data:` dynamic imports fail).
7
+ *
8
+ * The file is intentionally left on disk: the module's functions execute lazily (a macro runs when
9
+ * invoked, not at import), so a debugger must still be able to resolve the source afterwards. The OS
10
+ * reclaims its temp dir; session-scoped cleanup can be tied to module disposal later.
11
+ */
12
+ export declare function loadCompiledModule(compiled: string, options?: {
13
+ sourceMap?: string;
14
+ }): Promise<any>;
15
+ //# sourceMappingURL=moduleLoader.node.d.ts.map
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Simple logging interface that matches console methods
3
+ * This removes the dependency on Vite's Logger
4
+ */
5
+ export interface SimpleLogger {
6
+ info(message: string): void;
7
+ warn(message: string): void;
8
+ error(message: string): void;
9
+ }
10
+ export interface CompileOptions {
11
+ inputDir: string;
12
+ outputDir: string;
13
+ /** Simple logger interface */
14
+ logger?: SimpleLogger;
15
+ }
16
+ export declare function compile(options: CompileOptions): Promise<any>;
17
+ //# sourceMappingURL=generate.d.ts.map
@@ -0,0 +1,24 @@
1
+ import { Plugin } from 'vite';
2
+ /**
3
+ * Vite plugin to compile built-in formulas from TypeScript files.
4
+ * This plugin generates a single `index.ts` file containing all built-in formulas
5
+ * and watches for changes in the input directory during development.
6
+ */
7
+ export interface FormulaCompilerPluginOptions {
8
+ /** Directory containing input TypeScript files (relative to {@link root}). */
9
+ inputDir: string;
10
+ /** Directory to output compiled files (relative to {@link root}). */
11
+ outputDir: string;
12
+ /** Base for resolving {@link inputDir}/{@link outputDir}. Defaults to the Vite project root (`process.cwd()`). */
13
+ root?: string;
14
+ /** Whether to run compiler during build (default: true) */
15
+ runOnBuild?: boolean;
16
+ /** Whether to watch for file changes in dev mode (default: true) */
17
+ watchInDev?: boolean;
18
+ /** Enable verbose logging (default: false) */
19
+ verbose?: boolean;
20
+ /** Skip if output is newer than input (default: false) */
21
+ skipIfUpCurrent?: boolean;
22
+ }
23
+ export declare function FormulaCompilerPlugin(options: FormulaCompilerPluginOptions): Plugin;
24
+ //# sourceMappingURL=vite.d.ts.map
@@ -0,0 +1,9 @@
1
+ /**
2
+ * The global variable the compiled script reads its formula/run context from (`globalThis.__SHEETXL`).
3
+ *
4
+ * @remarks
5
+ * Language-agnostic runtime contract: the compiled script references it and any executor must match
6
+ * it.
7
+ */
8
+ export declare const GLOBAL_CONTEXT_VARIABLE = "__SHEETXL";
9
+ //# sourceMappingURL=Constants.d.ts.map
@@ -0,0 +1,2 @@
1
+ export * as Constants from './Constants';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,46 @@
1
+ /**
2
+ * Definition for JSDoc tags the script compiler understands.
3
+ */
4
+ export interface DocTagDef {
5
+ /** Canonical tag name, lower-case, without the leading `@`. */
6
+ readonly name: string;
7
+ /** Alternate spellings (lower-case) that resolve to this tag, e.g. `return` for `returns`. */
8
+ readonly aliases?: readonly string[];
9
+ /** Human readable description (shown in editor autocomplete). */
10
+ readonly description: string;
11
+ /**
12
+ * Whether the tag is meaningful with no trailing value (e.g. `@deprecated`, `@hidden`).
13
+ * Non-standalone tags require a value/comment.
14
+ */
15
+ readonly standalone?: boolean;
16
+ /**
17
+ * Where the tag originates - `'sheetxl'` for SheetXL-specific tags, `'jsdoc'` for standard ones.
18
+ * Used as the autocomplete detail label.
19
+ */
20
+ readonly group: 'sheetxl' | 'jsdoc';
21
+ /**
22
+ * Optional editor insertion snippet (without the leading `@`); may contain `${n:placeholder}`
23
+ * fields. Falls back to {@link JSDocTagDef.name} when omitted.
24
+ */
25
+ readonly snippet?: string;
26
+ }
27
+ /**
28
+ * The recognized Doc tags.
29
+ *
30
+ * @remarks
31
+ * Keep aligned with the tag handling in {@link analyzeModule}.
32
+ */
33
+ export declare const DocTags: readonly DocTagDef[];
34
+ /**
35
+ * Resolves a tag definition by name or alias (case-insensitive).
36
+ *
37
+ * @param name The tag name with or without a leading `@`.
38
+ */
39
+ export declare function getJSDocTag(name: string): DocTagDef | undefined;
40
+ /**
41
+ * Whether a tag is meaningful with no trailing value (e.g. `@deprecated`, `@hidden`).
42
+ *
43
+ * @param name The tag name with or without a leading `@`.
44
+ */
45
+ export declare function isStandaloneJSDocTag(name: string): boolean;
46
+ //# sourceMappingURL=DocTags.d.ts.map
@@ -0,0 +1,2 @@
1
+ export { DocTags } from './DocTags';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,58 @@
1
+ import { CompiledModule } from './CompiledModule';
2
+ import { Diagnostic } from './Diagnostic';
3
+ /**
4
+ * Options for compiling a script module.
5
+ */
6
+ export interface CompileOptions {
7
+ /**
8
+ * The source code of the script module to compile.
9
+ */
10
+ source: string;
11
+ /**
12
+ * If true, this will not include the bundle in the compiled module.
13
+ *
14
+ * @remarks
15
+ * This is useful for validation
16
+ */
17
+ disableBundle?: boolean;
18
+ /**
19
+ * If true, this will not include the source map in the compiled module.
20
+ */
21
+ disableSourceMap?: boolean;
22
+ /**
23
+ * For validation
24
+ */
25
+ declarationsOnly?: boolean;
26
+ /**
27
+ * The commit ID for the compilation.
28
+ */
29
+ commitId?: string;
30
+ /**
31
+ * The names of the host's built-in functions, so a calculation function that takes one can be
32
+ * reported here rather than at registration.
33
+ *
34
+ * @remarks
35
+ * Supplied by the caller because this package has no registry of its own: the names come from
36
+ * wherever the script will run (a workbook's calculation engine). Omitted, the rule simply does
37
+ * not run - the collision is still refused when the function is registered, just later and
38
+ * without a position. Compared case-insensitively.
39
+ */
40
+ builtInNames?: readonly string[];
41
+ }
42
+ /**
43
+ * The result of a compile operation: the compiled artifact plus this compile's positioned
44
+ * diagnostics.
45
+ *
46
+ * @remarks
47
+ * Diagnostics live HERE — on the transient operation result — NOT on the persisted
48
+ * {@link CompiledModule}/`.sxlm` artifact (they are a function of the source and recomputable).
49
+ * When any diagnostic has `severity: 'error'`, `module.compiled` is omitted and the artifact must
50
+ * not run. Conceptually mirrors a run's `RunResults` (outcome + diagnostics).
51
+ */
52
+ export interface CompileResult {
53
+ /** The compiled artifact, or `null` when there was no source to compile. */
54
+ module: CompiledModule | null;
55
+ /** Positioned diagnostics (errors + warnings) produced by this compile. */
56
+ diagnostics: Diagnostic[];
57
+ }
58
+ //# sourceMappingURL=CompileOptions.d.ts.map
@@ -0,0 +1,70 @@
1
+ import { IFunction } from '@sheetxl/primitives';
2
+ /**
3
+ * A compiled collection of functions — the serialized form of one module.
4
+ *
5
+ * @remarks
6
+ * This is the on-disk shape of a `.sxlm` macro artifact and the wire shape shipped from the MCP
7
+ * server to the VS Code webview. It is a self-contained container: human-readable {@link source},
8
+ * runnable {@link compiled} JS, a {@link sourceMap}, and the {@link functions} declarations. Aliased
9
+ * as `IModule.JSON` in the SDK. Produced by `ScriptCompiler.compile` (Node, which returns
10
+ * it inside a {@link CompileResult} alongside diagnostics) and executed compiler-free via
11
+ * `loadCompiledModule`. Compile diagnostics are NOT part of this artifact — they live on
12
+ * {@link CompileResult}. See `private-assets/design/SXLM-FORMAT.md` for the normative reference.
13
+ */
14
+ export interface CompiledModule {
15
+ /**
16
+ * An array of `Declaration` and `Description pairs describing the functions within the script.
17
+ *
18
+ * @remarks
19
+ * This array can be empty. It is possible that a script might contain only comments or other non-executable code.
20
+ */
21
+ functions: [IFunction.DeclarationJSON, IFunction.DescriptorJSON][];
22
+ /**
23
+ * The human-readable source code of the script.
24
+ *
25
+ * @remarks
26
+ * If this property is missing, the script will not be displayed but the 'actions' will still be available if `compiled` is present.
27
+ */
28
+ source?: string;
29
+ /**
30
+ * The compiled or pre-processed version of the script, ready for execution.
31
+ *
32
+ * @remarks
33
+ * If this property is missing, the script will be compiled on demand if possible.
34
+ */
35
+ compiled?: string;
36
+ /**
37
+ * If provided this will include a source map for the compiled script.
38
+ */
39
+ sourceMap?: string;
40
+ /**
41
+ * The language the function is written in.
42
+ *
43
+ * @defaultValue typescript
44
+ */
45
+ language?: string;
46
+ /**
47
+ * The name of the module.
48
+ */
49
+ name?: string;
50
+ /**
51
+ * A unique identifier for the function (e.g., a Git commit ID).
52
+ * // https://stackoverflow.com/questions/29106996/what-is-a-git-commit-id
53
+ */
54
+ commitId?: string;
55
+ /**
56
+ * The name of the function to run automatically when the script is loaded.
57
+ */
58
+ autoRun?: string;
59
+ /**
60
+ * ** NOT IMPLEMENTED **
61
+ * Available in functions via the 'this' value.
62
+ * Will auto persist values on save.
63
+ *
64
+ * TODO - this doesn't belong here.
65
+ * Create a new interface for session state.
66
+ * TODO - rename to sessionData
67
+ */
68
+ scope?: any;
69
+ }
70
+ //# sourceMappingURL=CompiledModule.d.ts.map
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Severity of a {@link Diagnostic}.
3
+ *
4
+ * - `error` blocks compilation (the script will not run).
5
+ * - `warning` allows compilation but nudges authoring quality (missing docs, etc.).
6
+ */
7
+ export type DiagnosticSeverity = 'error' | 'warning';
8
+ /**
9
+ * A positioned diagnostic produced by the SheetXL script linter.
10
+ *
11
+ * @remarks
12
+ * These are environment-agnostic (TypeScript compiler API only) so the same shape can be adapted to
13
+ * Monaco markers, a CLI reporter, or a VSCode language-service plugin. Positions are character
14
+ * offsets into the original source so adapters can map them to the surface they care about.
15
+ */
16
+ export interface Diagnostic {
17
+ /**
18
+ * Zero-based character offset of the start of the offending node (`node.getStart()`).
19
+ */
20
+ start: number;
21
+ /**
22
+ * Width of the offending node in characters (`node.getWidth()`).
23
+ */
24
+ length: number;
25
+ /**
26
+ * Severity of the diagnostic.
27
+ */
28
+ severity: DiagnosticSeverity;
29
+ /**
30
+ * A stable diagnostic code, e.g. `'SXL2001'`.
31
+ *
32
+ * @remarks
33
+ * Codes are stable across releases so adapters, docs, and agents can key off them. The leading
34
+ * `SXL` distinguishes our semantic rules from TypeScript's own `TS####` diagnostics. See
35
+ * {@link DiagnosticCode}.
36
+ */
37
+ code: string;
38
+ /**
39
+ * A human-readable, didactic message.
40
+ *
41
+ * @remarks
42
+ * Messages are written to be machine-friendly: for type errors they spell out the *allowed set*.
43
+ * Agents iterate against this text, so message quality directly reduces iteration count.
44
+ */
45
+ message: string;
46
+ }
47
+ /**
48
+ * The catalog of stable diagnostic codes emitted by the linter.
49
+ *
50
+ * @remarks
51
+ * `SXL1###` structural, `SXL2###` type rules, `SXL3###` module rules, `SXL9###` quality warnings.
52
+ * Codes are append-only — never reuse a retired number.
53
+ */
54
+ export declare const DiagnosticCode: Readonly<{
55
+ /** Exported function has no body. */
56
+ readonly NoBody: "SXL1001";
57
+ /** Anonymous exported function is not allowed. */
58
+ readonly Anonymous: "SXL1002";
59
+ /** Internal parse failure while analyzing the module. */
60
+ readonly ParseError: "SXL1003";
61
+ /** Invalid parameter type. */
62
+ readonly InvalidParamType: "SXL2001";
63
+ /** Invalid return type. */
64
+ readonly InvalidReturnType: "SXL2002";
65
+ /** `undefined` / `null` / `void` is not valid as an input type. */
66
+ readonly UndefinedInput: "SXL2003";
67
+ /** A type annotation is required but missing. */
68
+ readonly MissingType: "SXL2004";
69
+ /** An `Array` must be typed (e.g. `number[]`, not bare `[]`). */
70
+ readonly UntypedArray: "SXL2005";
71
+ /** A generic type must be supplied exactly one type argument. */
72
+ readonly GenericArity: "SXL2006";
73
+ /** A return type cannot combine multiple modifiers (e.g. async + stream). */
74
+ readonly MultipleModifiers: "SXL2007";
75
+ /** A context parameter must be the first parameter. */
76
+ readonly ContextNotFirst: "SXL2010";
77
+ /** More than one `Lambda` parameter. */
78
+ readonly MultipleLambda: "SXL2020";
79
+ /** A `Lambda` parameter must be the last parameter. */
80
+ readonly LambdaNotLast: "SXL2021";
81
+ /** A `Lambda` parameter/return scalar type mismatch. */
82
+ readonly LambdaScalarMismatch: "SXL2022";
83
+ /** `Lambda` is not valid as a return type. */
84
+ readonly LambdaReturn: "SXL2023";
85
+ /** A bare function type is not valid as a return type. */
86
+ readonly FunctionReturn: "SXL2024";
87
+ /** A `Lambda` function type has the wrong number of parameters. */
88
+ readonly LambdaArity: "SXL2025";
89
+ /** Arrays of more than 2 dimensions are not supported. */
90
+ readonly ArrayDepth: "SXL2030";
91
+ /** `Repeating<T>` used somewhere it cannot be (a return type, a rest parameter, nested in an array). */
92
+ readonly RepeatingPosition: "SXL2040";
93
+ /** More than one `Repeating<T>` parameter. */
94
+ readonly MultipleRepeating: "SXL2041";
95
+ /** A `Repeating<T>` group's slots are malformed (unlabelled tuple member, or a 1-element tuple). */
96
+ readonly RepeatingSlots: "SXL2042";
97
+ /** An optional parameter/slot where a repeating group does not allow one. */
98
+ readonly RepeatingOptional: "SXL2043";
99
+ /** No exported functions found in the module. */
100
+ readonly NoExports: "SXL3001";
101
+ /** A `@param` tag references a parameter that does not exist. */
102
+ readonly UnknownParam: "SXL3002";
103
+ /** A calculation function takes a built-in function's name. */
104
+ readonly BuiltInName: "SXL3003";
105
+ /** Missing `@summary` / function description. */
106
+ readonly MissingSummary: "SXL9001";
107
+ /** A `@param` is missing a description. */
108
+ readonly MissingParamDescription: "SXL9002";
109
+ /**
110
+ * Missing `@returns` on a non-void function.
111
+ * @deprecated Retained for code stability but no longer emitted - Excel-style tooltips describe
112
+ * behavior via the summary, so a standalone `@returns` warning is noise.
113
+ */
114
+ readonly MissingReturns: "SXL9003";
115
+ }>;
116
+ /**
117
+ * Union of the stable diagnostic code string values.
118
+ */
119
+ export type DiagnosticCode = (typeof DiagnosticCode)[keyof typeof DiagnosticCode];
120
+ //# sourceMappingURL=Diagnostic.d.ts.map
@@ -0,0 +1,72 @@
1
+ import { IFunction, ScalarType, Scalar, IFormulaContext } from '@sheetxl/primitives';
2
+ /**
3
+ * Type for bind signature for typed functions.
4
+ */
5
+ export interface FunctionBinder {
6
+ (mapBind: Map<string, IFunction>, getContext: () => IFormulaContext, implementations: Implementations, declarations: MinifiedDeclarations, getDynamicDescriptors?: DynamicDescriptors, defaultCategory?: string): void;
7
+ }
8
+ /**
9
+ * The default export of a compiled formula module (produced by the FormulaCompiler): given the
10
+ * runtime `getContext` and a {@link FunctionBinder}, it binds its functions into `mapBind` (creating
11
+ * one if omitted) and returns it. This is the unit of formula registration - a consumer passes their
12
+ * compiled module's default export to register custom functions.
13
+ */
14
+ export interface FunctionProvider {
15
+ (getContext: () => IFormulaContext, bindFn: FunctionBinder, mapBind?: Map<string, IFunction>): Map<string, IFunction>;
16
+ }
17
+ /**
18
+ * Minified value.
19
+ */
20
+ export interface MinifiedValue {
21
+ s?: string;
22
+ r?: 'p' | 'r' | 'm' | '*';
23
+ l?: ScalarType | '*' | 'raw';
24
+ a?: number;
25
+ d?: number;
26
+ }
27
+ /**
28
+ * Minified params.
29
+ */
30
+ export interface MinifiedParameter extends MinifiedValue {
31
+ n: string;
32
+ m?: '?' | '...';
33
+ e?: string[];
34
+ o?: 'accept' | 'accept-ref';
35
+ g?: MinifiedParameter[];
36
+ v?: Scalar;
37
+ u?: 1;
38
+ w?: Scalar;
39
+ }
40
+ /**
41
+ * The function declaration needed to autoMarshall and execute.
42
+ */
43
+ export interface MinifiedDeclaration {
44
+ fn?: string;
45
+ c?: boolean;
46
+ p?: MinifiedParameter[];
47
+ r?: MinifiedValue;
48
+ }
49
+ /**
50
+ * The descriptor used for a function
51
+ */
52
+ export interface MinifiedDescriptor {
53
+ s?: string;
54
+ c?: string;
55
+ p?: Record<string, any>;
56
+ h?: string | boolean;
57
+ l?: [url: string, text?: string][];
58
+ }
59
+ export type MinifiedDeclarations = {
60
+ [name: string]: MinifiedDeclaration;
61
+ };
62
+ export interface Implementations {
63
+ [functionName: string]: (...args: any) => any;
64
+ }
65
+ export interface MinifiedDescriptors {
66
+ [name: string]: MinifiedDescriptor;
67
+ }
68
+ export interface DescriptorModule {
69
+ default: MinifiedDescriptors;
70
+ }
71
+ export type DynamicDescriptors = () => Promise<DescriptorModule>;
72
+ //# sourceMappingURL=Types.d.ts.map
@@ -0,0 +1,6 @@
1
+ export type * from './Types';
2
+ export type * from './CompileOptions';
3
+ export type * from './CompiledModule';
4
+ export type { Diagnostic, DiagnosticSeverity } from './Diagnostic';
5
+ export { DiagnosticCode } from './Diagnostic';
6
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,44 @@
1
+ export interface IWorkerWrapper<TResult = any, TParams = any> {
2
+ start(): Promise<void>;
3
+ execute(params: TParams): Promise<TResult>;
4
+ terminate(): void;
5
+ }
6
+ /**
7
+ * Generic worker wrapper for use in libraries
8
+ * Takes a worker factory function to create the worker instance.
9
+ */
10
+ export declare class WorkerWrapper<TResult = any, TParams = any> implements IWorkerWrapper<TResult, TParams> {
11
+ private _worker;
12
+ private _workerFactory;
13
+ private _nextId;
14
+ private _pendingRequests;
15
+ /**
16
+ * Creates a new worker
17
+ *
18
+ * @param workerFactory - Factory function to create the worker instance.
19
+ */
20
+ constructor(workerFactory: () => Worker);
21
+ /**
22
+ * Initializes the worker if it hasn't been created yet
23
+ * Will throw an error if the environment does not support Web Workers.
24
+ */
25
+ start(): Promise<void>;
26
+ /**
27
+ * Executes a task in the worker
28
+ * @param params - Parameters to pass to the worker
29
+ * @returns Promise that resolves with the worker result
30
+ */
31
+ execute(params: TParams): Promise<TResult>;
32
+ /**
33
+ * Terminates the worker
34
+ */
35
+ terminate(): void;
36
+ }
37
+ export declare class SyncWrapper<TResult = any, TParams = any> implements IWorkerWrapper<TResult, TParams> {
38
+ private _onExecute;
39
+ constructor(onExecute: (params: TParams) => Promise<TResult>);
40
+ execute(params: TParams): Promise<TResult>;
41
+ start(): Promise<void>;
42
+ terminate(): void;
43
+ }
44
+ //# sourceMappingURL=WorkerWrapper.d.ts.map
@@ -0,0 +1,2 @@
1
+ export * from './WorkerWrapper';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -1,6 +0,0 @@
1
- "use strict";/**
2
- * @license @sheetxl/scripting - Scripting - Scripting engine for Macros and formulas; includes TypeScript and EsBuild. - v0.7.26
3
- *
4
- * (C) 2025-present SheetXL Inc. & Michael T. Ford
5
- * License: The license can be found at https://www.sheetxl.com/license.
6
- */Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});exports.TypeScriptCompiler=class{constructor(r={}){this.workerWrapper=null}async getWorkerWrapper(){if(this.workerWrapper)return this.workerWrapper;const{createCompilerWorker:r}=await Promise.resolve().then(()=>require("./Bgxi3ZUQTg5EKFnv.cjs"));return this.workerWrapper=await r(),this.workerWrapper}async compileModule(r){try{return(await this.getWorkerWrapper()).execute(r)}catch(e){throw console.error("Failed to compile using worker:",e),e}}terminate(){this.workerWrapper?.terminate(),this.workerWrapper=null}};