@onda-lang/wasm-compiler 0.7.5 → 0.8.1

package/dist/version.js

@@ -1 +1 @@
-export const ONDA_VERSION = "0.7.5";
+export const ONDA_VERSION = "0.8.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onda-lang/wasm-compiler",
-  "version": "0.7.5",
+  "version": "0.8.1",
   "type": "module",
   "description": "Onda source-to-WebAssembly compiler for browsers and Node.js",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "bin",
     "dist",
     "src",
+    "api.md",
     "LICENSE",
     "README.md",
     "THIRD_PARTY_NOTICES.md"
@@ -54,12 +55,12 @@
     "check:versions": "node ../../scripts/sync-package-versions.mjs --check",
     "test": "npm run build && npm run test:built",
     "test:built": "node --test ./test/*.test.js",
-    "test:pack": "node ./scripts/test-package.mjs",
-    "test:pack:built": "node ./scripts/test-package.mjs --skip-build",
-    "prepack": "npm run build"
+    "test:pack": "node ../../scripts/stage-web-api-docs.mjs && node ./scripts/test-package.mjs",
+    "test:pack:built": "node ../../scripts/stage-web-api-docs.mjs && node ./scripts/test-package.mjs --skip-build",
+    "prepack": "npm run build && node ../../scripts/stage-web-api-docs.mjs"
   },
   "dependencies": {
-    "@onda-lang/processor-abi": "0.7.5",
+    "@onda-lang/processor-abi": "0.8.1",
     "binaryen": "130.0.0"
   },
   "publishConfig": {

package/src/index.d.ts

@@ -47,9 +47,56 @@ export interface OndaCodegenOptions {
 export interface OndaCompileOptions {
   sampleRate?: number;
   blockSize?: number;
+  constants?: Map<string, OndaCompileConstValue>
+    | Record<string, OndaCompileConstValue>;
   codegen?: OndaCodegenOptions;
 }
 
+export interface OndaCompileConstInspectionOptions {
+  sampleRate?: number;
+  blockSize?: number;
+  /** Optional partial overrides; omitted declarations retain their authored values. */
+  constants?: Map<string, OndaCompileConstValue>
+    | Record<string, OndaCompileConstValue>;
+}
+
+export interface OndaLspAnalysisOptions {
+  sampleRate?: number;
+  blockSize?: number;
+}
+
+export type OndaCompileConstValue =
+  | boolean
+  | number
+  | bigint
+  | boolean[]
+  | Uint8Array
+  | Int32Array
+  | BigInt64Array
+  | Float32Array
+  | Float64Array;
+
+export type OndaCompileConstElement = "bool" | "i32" | "i64" | "f32" | "f64";
+export type OndaCompileConstKind = "scalar" | "fixed-array" | "array";
+export type OndaResolvedCompileConstValue =
+  | boolean
+  | number
+  | bigint
+  | Uint8Array
+  | Int32Array
+  | BigInt64Array
+  | Float32Array
+  | Float64Array;
+
+export interface OndaCompileConstDescriptor {
+  name: string;
+  element: OndaCompileConstElement;
+  kind: OndaCompileConstKind;
+  /** One for scalars; the resolved length for either array kind. */
+  elementCount: number;
+  value: OndaResolvedCompileConstValue;
+}
+
 export interface OndaSourceWorkspace {
   entry: string;
   sources: Record<string, string>;
@@ -141,14 +188,26 @@ export interface OndaCompilerInstance {
     source: string,
     options?: OndaCompileOptions,
   ): Promise<OndaCompilationResult>;
+  inspectSourceConstants(
+    source: string,
+    options?: OndaCompileConstInspectionOptions,
+  ): Promise<OndaCompileConstDescriptor[]>;
   compileWorkspace(
     workspace: OndaSourceWorkspace,
     options?: OndaCompileOptions,
   ): Promise<OndaCompilationResult>;
+  inspectWorkspaceConstants(
+    workspace: OndaSourceWorkspace,
+    options?: OndaCompileConstInspectionOptions,
+  ): Promise<OndaCompileConstDescriptor[]>;
   compileProjectImage(
     imageBytes: ArrayBuffer | ArrayBufferView,
     options?: OndaCompileOptions,
   ): Promise<OndaCompilationResult>;
+  inspectProjectImageConstants(
+    imageBytes: ArrayBuffer | ArrayBufferView,
+    options?: OndaCompileConstInspectionOptions,
+  ): Promise<OndaCompileConstDescriptor[]>;
   createProjectImage(
     sourceGraph: OndaSourceGraph,
     buffers?: Map<string, ArrayBuffer | ArrayBufferView>
@@ -174,7 +233,8 @@ export interface OndaCompilerInstance {
   ): Promise<OndaBufferAssetBinding>;
   projectCapabilities(): Promise<OndaProjectCapabilities>;
   sendLspMessage(message: OndaLspMessage): Promise<OndaLspMessage[]>;
-  setLspAnalysisOptions(options?: OndaCompileOptions): Promise<void>;
+  setLspAnalysisOptions(options?: OndaLspAnalysisOptions): Promise<void>;
+  /** Idempotently releases compiler resources. All subsequent operations reject. */
   dispose(): Promise<void>;
 }
 

package/src/index.js

@@ -74,9 +74,17 @@ class OndaCompiler {
     this.frontend = frontend;
     this.compileTrustedMir = compileTrustedMir;
     this.lsp = null;
+    this.disposed = false;
+  }
+
+  assertActive() {
+    if (this.disposed) {
+      throw new OndaCompilerError("compiler was disposed");
+    }
   }
 
   async compileSource(source, options = {}) {
+    this.assertActive();
     if (typeof source !== "string") {
       throw configurationError("source must be a string");
     }
@@ -87,6 +95,7 @@ class OndaCompiler {
         source,
         compile.sampleRate,
         compile.blockSize,
+        compile.constantsJson,
       );
     } catch (error) {
       throw diagnosticsFromFrontend(error);
@@ -101,22 +110,29 @@ class OndaCompiler {
     return { artifact, sourceFiles, sourceGraph };
   }
 
-  async compileWorkspace(workspace, options = {}) {
-    if (!workspace || typeof workspace !== "object" || Array.isArray(workspace)) {
-      throw configurationError("workspace must contain an entry and source map");
-    }
-    if (typeof workspace.entry !== "string" || workspace.entry.length === 0) {
-      throw configurationError("workspace.entry must be a non-empty string");
-    }
-    if (!workspace.sources || typeof workspace.sources !== "object" || Array.isArray(workspace.sources)) {
-      throw configurationError("workspace.sources must be an object of paths to source strings");
+  async inspectSourceConstants(source, options = {}) {
+    this.assertActive();
+    if (typeof source !== "string") {
+      throw configurationError("source must be a string");
     }
-    for (const [path, source] of Object.entries(workspace.sources)) {
-      if (typeof source !== "string") {
-        throw configurationError(`workspace source '${path}' must be a string`);
-      }
+    const compile = normalizeCompileConstInspectionOptions(options);
+    let encoded;
+    try {
+      encoded = this.frontend.inspect_source_compile_constants(
+        source,
+        compile.sampleRate,
+        compile.blockSize,
+        compile.constantsJson,
+      );
+    } catch (error) {
+      throw diagnosticsFromFrontend(error);
     }
+    return decodeCompileConstDescriptors(encoded);
+  }
 
+  async compileWorkspace(workspace, options = {}) {
+    this.assertActive();
+    workspace = normalizeWorkspace(workspace);
     const compile = normalizeCompileOptions(options);
     let frontendCompilation;
     try {
@@ -125,6 +141,7 @@ class OndaCompiler {
         JSON.stringify(workspace.sources),
         compile.sampleRate,
         compile.blockSize,
+        compile.constantsJson,
       );
     } catch (error) {
       throw diagnosticsFromFrontend(error);
@@ -139,7 +156,27 @@ class OndaCompiler {
     return { artifact, sourceFiles, sourceGraph };
   }
 
+  async inspectWorkspaceConstants(workspace, options = {}) {
+    this.assertActive();
+    workspace = normalizeWorkspace(workspace);
+    const compile = normalizeCompileConstInspectionOptions(options);
+    let encoded;
+    try {
+      encoded = this.frontend.inspect_source_workspace_compile_constants(
+        workspace.entry,
+        JSON.stringify(workspace.sources),
+        compile.sampleRate,
+        compile.blockSize,
+        compile.constantsJson,
+      );
+    } catch (error) {
+      throw diagnosticsFromFrontend(error);
+    }
+    return decodeCompileConstDescriptors(encoded);
+  }
+
   async compileProjectImage(imageBytes, options = {}) {
+    this.assertActive();
     const bytes = normalizeBytes(imageBytes, "project image");
     const compile = normalizeCompileOptions(options);
     let frontendCompilation;
@@ -148,6 +185,7 @@ class OndaCompiler {
         bytes,
         compile.sampleRate,
         compile.blockSize,
+        compile.constantsJson,
       );
     } catch (error) {
       throw diagnosticsFromFrontend(error);
@@ -162,7 +200,26 @@ class OndaCompiler {
     return { artifact, sourceFiles, sourceGraph };
   }
 
+  async inspectProjectImageConstants(imageBytes, options = {}) {
+    this.assertActive();
+    const bytes = normalizeBytes(imageBytes, "project image");
+    const compile = normalizeCompileConstInspectionOptions(options);
+    let encoded;
+    try {
+      encoded = this.frontend.inspect_project_image_compile_constants(
+        bytes,
+        compile.sampleRate,
+        compile.blockSize,
+        compile.constantsJson,
+      );
+    } catch (error) {
+      throw diagnosticsFromFrontend(error);
+    }
+    return decodeCompileConstDescriptors(encoded);
+  }
+
   async createProjectImage(sourceGraph, buffers = new Map()) {
+    this.assertActive();
     const graph = normalizeSourceGraph(sourceGraph);
     const builder = new this.frontend.WebProjectImageBuilder(JSON.stringify(graph));
     try {
@@ -182,6 +239,7 @@ class OndaCompiler {
   }
 
   async inspectProjectImage(imageBytes) {
+    this.assertActive();
     try {
       return normalizeProjectImageInfo(JSON.parse(this.frontend.inspect_project_image(
         normalizeBytes(imageBytes, "project image"),
@@ -192,6 +250,7 @@ class OndaCompiler {
   }
 
   async loadProjectFiles(files, projectFilePath = null) {
+    this.assertActive();
     const builder = new this.frontend.WebMaterializedProjectBuilder();
     try {
       if (projectFilePath !== null) {
@@ -213,6 +272,7 @@ class OndaCompiler {
   }
 
   async materializeProjectImage(imageBytes, assetFileNames = new Map()) {
+    this.assertActive();
     let plan;
     try {
       plan = this.frontend.materialize_project_image(
@@ -232,6 +292,7 @@ class OndaCompiler {
   }
 
   async encodeBufferAsset(binding) {
+    this.assertActive();
     const normalized = normalizeBufferBinding(binding);
     try {
       return this.frontend.encode_buffer_asset(
@@ -247,6 +308,7 @@ class OndaCompiler {
   }
 
   async decodeBufferAsset(bytes) {
+    this.assertActive();
     return this.#decodeBuffer(
       () => this.frontend.decode_buffer_asset(normalizeBytes(bytes, "buffer asset")),
       "failed to decode Onda buffer asset",
@@ -254,6 +316,7 @@ class OndaCompiler {
   }
 
   async decodeBufferFile(bytes, path = "buffer") {
+    this.assertActive();
     return this.#decodeBuffer(
       () => this.frontend.decode_buffer_file(
         normalizeBytes(bytes, "buffer file"),
@@ -284,6 +347,7 @@ class OndaCompiler {
   }
 
   async projectCapabilities() {
+    this.assertActive();
     return {
       imageFormatVersion: this.frontend.project_image_format_version(),
       bufferAssetFormatVersion: this.frontend.buffer_asset_format_version(),
@@ -292,6 +356,7 @@ class OndaCompiler {
   }
 
   async sendLspMessage(message) {
+    this.assertActive();
     if (!message || typeof message !== "object" || Array.isArray(message)) {
       throw new OndaCompilerError("LSP message must be a JSON-RPC object");
     }
@@ -308,18 +373,23 @@ class OndaCompiler {
   }
 
   async setLspAnalysisOptions(options = {}) {
-    const compile = normalizeCompileOptions(options);
+    this.assertActive();
+    const analysis = normalizeLspAnalysisOptions(options);
     this.lsp ??= new this.frontend.OndaLsp();
     try {
-      this.lsp.set_analysis_options(compile.sampleRate, compile.blockSize);
+      this.lsp.set_analysis_options(analysis.sampleRate, analysis.blockSize);
     } catch (cause) {
       throw new OndaCompilerError("failed to configure Onda LSP analysis", { cause });
     }
   }
 
   async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
     this.lsp?.free();
     this.lsp = null;
+    this.frontend = null;
+    this.compileTrustedMir = null;
   }
 }
 
@@ -328,6 +398,9 @@ class WorkerOndaCompiler {
     this.worker = worker;
     this.nextRequestId = 1;
     this.pending = new Map();
+    this.disposed = false;
+    this.terminated = false;
+    this.disposePromise = null;
     this.onMessage = (event) => this.handleMessage(event.data);
     this.onError = (event) => this.failAll(event.error ?? new Error(event.message));
     worker.addEventListener("message", this.onMessage);
@@ -342,14 +415,26 @@ class WorkerOndaCompiler {
     return this.request("compileSource", { source, options });
   }
 
+  inspectSourceConstants(source, options = {}) {
+    return this.request("inspectSourceConstants", { source, options });
+  }
+
   compileWorkspace(workspace, options = {}) {
     return this.request("compileWorkspace", { workspace, options });
   }
 
+  inspectWorkspaceConstants(workspace, options = {}) {
+    return this.request("inspectWorkspaceConstants", { workspace, options });
+  }
+
   compileProjectImage(imageBytes, options = {}) {
     return this.request("compileProjectImage", { imageBytes, options });
   }
 
+  inspectProjectImageConstants(imageBytes, options = {}) {
+    return this.request("inspectProjectImageConstants", { imageBytes, options });
+  }
+
   createProjectImage(sourceGraph, buffers = new Map()) {
     return this.request("createProjectImage", { sourceGraph, buffers });
   }
@@ -390,15 +475,21 @@ class WorkerOndaCompiler {
     return this.request("lspAnalysisOptions", { options });
   }
 
-  async dispose() {
-    try {
-      await this.request("dispose");
-    } finally {
+  dispose() {
+    if (this.disposePromise) return this.disposePromise;
+    if (this.disposed) return Promise.resolve();
+    const request = this.request("dispose");
+    this.disposed = true;
+    this.disposePromise = request.finally(() => {
       this.terminate(new OndaCompilerError("compiler worker was disposed"));
-    }
+    });
+    return this.disposePromise;
   }
 
   terminate(error) {
+    if (this.terminated) return;
+    this.disposed = true;
+    this.terminated = true;
     this.worker.removeEventListener("message", this.onMessage);
     this.worker.removeEventListener("error", this.onError);
     this.worker.terminate();
@@ -406,6 +497,9 @@ class WorkerOndaCompiler {
   }
 
   request(type, fields = {}) {
+    if (this.disposed) {
+      return Promise.reject(new OndaCompilerError("compiler was disposed"));
+    }
     const requestId = this.nextRequestId;
     this.nextRequestId += 1;
     return new Promise((resolve, reject) => {
@@ -504,6 +598,48 @@ export function createDefaultImports() {
 }
 
 function normalizeCompileOptions(options) {
+  const compile = normalizeCompileInputOptions(options);
+  if (
+    options.codegen !== undefined
+    && (!options.codegen || typeof options.codegen !== "object" || Array.isArray(options.codegen))
+  ) {
+    throw configurationError("codegen options must be an object");
+  }
+  return {
+    ...compile,
+    codegen: options.codegen ?? {},
+  };
+}
+
+function normalizeCompileConstInspectionOptions(options) {
+  const compile = normalizeCompileInputOptions(options);
+  if (options.codegen !== undefined) {
+    throw configurationError("codegen options do not apply to compile constant inspection");
+  }
+  return compile;
+}
+
+function normalizeCompileInputOptions(options) {
+  return {
+    ...normalizeContextOptions(options),
+    constantsJson: JSON.stringify(normalizeCompileConstants(options.constants ?? {})),
+  };
+}
+
+function normalizeLspAnalysisOptions(options) {
+  const context = normalizeContextOptions(options);
+  if (options.constants !== undefined) {
+    throw configurationError(
+      "constants are compile-request inputs and cannot be set as LSP analysis options",
+    );
+  }
+  if (options.codegen !== undefined) {
+    throw configurationError("codegen options cannot be set as LSP analysis options");
+  }
+  return context;
+}
+
+function normalizeContextOptions(options) {
   if (!options || typeof options !== "object" || Array.isArray(options)) {
     throw configurationError("compiler options must be an object");
   }
@@ -515,13 +651,160 @@ function normalizeCompileOptions(options) {
   if (!Number.isInteger(blockSize) || blockSize <= 0 || blockSize > MAX_BLOCK_SIZE) {
     throw configurationError(`blockSize must be between 1 and ${MAX_BLOCK_SIZE} frames`);
   }
+  return { sampleRate, blockSize };
+}
+
+function normalizeWorkspace(workspace) {
+  if (!workspace || typeof workspace !== "object" || Array.isArray(workspace)) {
+    throw configurationError("workspace must contain an entry and source map");
+  }
+  if (typeof workspace.entry !== "string" || workspace.entry.length === 0) {
+    throw configurationError("workspace.entry must be a non-empty string");
+  }
+  if (!workspace.sources || typeof workspace.sources !== "object" || Array.isArray(workspace.sources)) {
+    throw configurationError("workspace.sources must be an object of paths to source strings");
+  }
+  for (const [path, source] of Object.entries(workspace.sources)) {
+    if (typeof source !== "string") {
+      throw configurationError(`workspace source '${path}' must be a string`);
+    }
+  }
+  return workspace;
+}
+
+function normalizeCompileConstants(constants) {
   if (
-    options.codegen !== undefined
-    && (!options.codegen || typeof options.codegen !== "object" || Array.isArray(options.codegen))
+    !constants
+    || typeof constants !== "object"
+    || Array.isArray(constants)
+    || ArrayBuffer.isView(constants)
   ) {
-    throw configurationError("codegen options must be an object");
+    throw configurationError("constants must be an object or Map");
   }
-  return { sampleRate, blockSize, codegen: options.codegen ?? {} };
+  const entries = constants instanceof Map
+    ? [...constants.entries()]
+    : Object.entries(constants);
+  return entries.map(([rawName, value]) => {
+    const name = String(rawName);
+    if (name.length === 0) {
+      throw configurationError("compile constant names must be non-empty");
+    }
+    if (typeof value === "boolean") {
+      return { name, element: "bool", array: false, values: [value] };
+    }
+    if (typeof value === "number") {
+      return {
+        name,
+        element: "number",
+        array: false,
+        values: [encodeCompileNumber(value)],
+      };
+    }
+    if (typeof value === "bigint") {
+      return { name, element: "i64", array: false, values: [value.toString()] };
+    }
+    if (value instanceof Uint8Array) {
+      const values = [...value];
+      if (values.some((item) => item !== 0 && item !== 1)) {
+        throw configurationError(
+          `boolean compile constant array '${name}' may contain only 0 or 1`,
+        );
+      }
+      return {
+        name,
+        element: "bool",
+        array: true,
+        values: values.map((item) => item !== 0),
+      };
+    }
+    if (value instanceof Int32Array) {
+      return { name, element: "i32", array: true, values: [...value] };
+    }
+    if (value instanceof BigInt64Array) {
+      return {
+        name,
+        element: "i64",
+        array: true,
+        values: [...value].map((item) => item.toString()),
+      };
+    }
+    if (value instanceof Float32Array) {
+      return {
+        name,
+        element: "f32",
+        array: true,
+        values: encodeCompileFloatArray(value),
+      };
+    }
+    if (value instanceof Float64Array) {
+      return {
+        name,
+        element: "f64",
+        array: true,
+        values: encodeCompileFloatArray(value),
+      };
+    }
+    if (Array.isArray(value) && value.every((item) => typeof item === "boolean")) {
+      return { name, element: "bool", array: true, values: value };
+    }
+    throw configurationError(
+      `compile constant '${name}' must be a boolean, number, bigint, or matching typed array`,
+    );
+  });
+}
+
+function encodeCompileFloatArray(values) {
+  return [...values].map(encodeCompileNumber);
+}
+
+function encodeCompileNumber(value) {
+  if (Object.is(value, -0)) return "-0";
+  if (Number.isNaN(value)) return "NaN";
+  if (value === Number.POSITIVE_INFINITY) return "Infinity";
+  if (value === Number.NEGATIVE_INFINITY) return "-Infinity";
+  return value;
+}
+
+function decodeCompileConstDescriptors(encoded) {
+  let descriptors;
+  try {
+    descriptors = JSON.parse(encoded);
+  } catch (cause) {
+    throw new OndaCompilerError("failed to decode compile constant descriptors", { cause });
+  }
+  if (!Array.isArray(descriptors)) {
+    throw new OndaCompilerError("frontend returned invalid compile constant descriptors");
+  }
+  return descriptors.map((descriptor) => ({
+    name: descriptor.name,
+    element: descriptor.element,
+    kind: descriptor.kind,
+    elementCount: descriptor.element_count,
+    value: decodeCompileConstValue(descriptor.element, descriptor.kind, descriptor.values),
+  }));
+}
+
+function decodeCompileConstValue(element, kind, values) {
+  const decoded = element === "i64"
+    ? values.map((value) => BigInt(value))
+    : element === "f32" || element === "f64"
+      ? values.map(decodeCompileFloat)
+      : values;
+  if (kind === "scalar") return decoded[0];
+  if (element === "bool") return Uint8Array.from(decoded, (value) => value ? 1 : 0);
+  if (element === "i32") return Int32Array.from(decoded);
+  if (element === "i64") return BigInt64Array.from(decoded);
+  if (element === "f32") return Float32Array.from(decoded);
+  if (element === "f64") return Float64Array.from(decoded);
+  throw new OndaCompilerError(`frontend returned unknown compile constant element '${element}'`);
+}
+
+function decodeCompileFloat(value) {
+  if (value === "-0") return -0;
+  if (value === "NaN") return Number.NaN;
+  if (value === "Infinity") return Number.POSITIVE_INFINITY;
+  if (value === "-Infinity") return Number.NEGATIVE_INFINITY;
+  return value;
 }
 
 function consumeFrontendCompilation(compilation) {

package/src/worker.js

@@ -19,6 +19,14 @@ globalThis.addEventListener("message", async (event) => {
       respond(requestId, result, [result.artifact.wasm.buffer]);
       return;
     }
+    if (message.type === "inspectSourceConstants") {
+      const result = await (await compiler()).inspectSourceConstants(
+        message.source,
+        message.options,
+      );
+      respond(requestId, result, compileConstTransfers(result));
+      return;
+    }
     if (message.type === "compileWorkspace") {
       const result = await (await compiler()).compileWorkspace(
         message.workspace,
@@ -27,6 +35,14 @@ globalThis.addEventListener("message", async (event) => {
       respond(requestId, result, [result.artifact.wasm.buffer]);
       return;
     }
+    if (message.type === "inspectWorkspaceConstants") {
+      const result = await (await compiler()).inspectWorkspaceConstants(
+        message.workspace,
+        message.options,
+      );
+      respond(requestId, result, compileConstTransfers(result));
+      return;
+    }
     if (message.type === "compileProjectImage") {
       const result = await (await compiler()).compileProjectImage(
         message.imageBytes,
@@ -35,6 +51,14 @@ globalThis.addEventListener("message", async (event) => {
       respond(requestId, result, [result.artifact.wasm.buffer]);
       return;
     }
+    if (message.type === "inspectProjectImageConstants") {
+      const result = await (await compiler()).inspectProjectImageConstants(
+        message.imageBytes,
+        message.options,
+      );
+      respond(requestId, result, compileConstTransfers(result));
+      return;
+    }
     if (message.type === "createProjectImage") {
       const result = await (await compiler()).createProjectImage(
         message.sourceGraph,
@@ -123,3 +147,10 @@ function compiler(frontendWasm) {
 function respond(requestId, value, transfer = []) {
   globalThis.postMessage({ type: "result", requestId, value }, transfer);
 }
+
+function compileConstTransfers(descriptors) {
+  return descriptors
+    .map((descriptor) => descriptor.value)
+    .filter(ArrayBuffer.isView)
+    .map((value) => value.buffer);
+}