@noiselang/core 0.1.1

package/README.md

@@ -0,0 +1,87 @@
+# @noiselang/core
+
+The [Noise](https://noise-lang.dev) probabilistic-language engine, compiled to WebAssembly and
+wrapped in a small typed API. Parse and run `.noise` programs — including variable introspection —
+from any JavaScript/TypeScript project.
+
+The `.wasm` binary ships **inside** this package. The generated glue references it with
+`new URL('noise_bg.wasm', import.meta.url)`, so any bundler that understands that pattern
+(Vite, Rollup, webpack 5, esbuild) fingerprints the binary and emits it as an asset of **your**
+build. No copying files into `public/`, no CDN, no runtime configuration.
+
+## Install
+
+```sh
+npm add @noiselang/core   # or: pnpm add / yarn add
+```
+
+## Usage
+
+```ts
+import { run } from '@noiselang/core';
+
+const result = await run(`
+  coin ~ rand::bernoulli(0.5);
+  P(coin)
+`);
+
+console.log(result.value);   // e.g. "0.4997"
+console.log(result.stats);   // { forcings, samples, ops, rng_draws }
+console.log(result.elapsedMs);
+```
+
+`run` never throws — parse/eval failures come back on `result.error` (with a source span).
+
+The module instantiates lazily on first use. To warm it up ahead of time (e.g. on app mount):
+
+```ts
+import { load } from '@noiselang/core';
+await load();
+```
+
+### Variable introspection
+
+Run a program and interrogate its retained scope without editing the source — describe a
+variable's distribution, correlate two, or explain what drives one:
+
+```ts
+import { runWithIntrospection } from '@noiselang/core';
+
+const r = await runWithIntrospection(src, [
+  { vars: ['height'] },                       // describe(height)
+  { vars: ['weight'], explain: true },        // explain(weight)
+  { vars: ['height', 'weight'] },             // corr(height, weight)
+]);
+
+r.bindings;        // live top-level variables (for a picker)
+r.introspections;  // one tagged result per request, in order
+r.log;             // Print lines + plot::* charts, in source order
+```
+
+Passing `[]` still returns `bindings`, so a plain run can populate a variable picker.
+
+## Bundler notes
+
+- **Vite** — works out of the box for app builds. If Vite's dependency optimizer trips on the
+  `import.meta.url` asset reference in dev, add the package to `optimizeDeps.exclude`:
+  ```js
+  // vite.config.js
+  export default { optimizeDeps: { exclude: ['@noiselang/core'] } }
+  ```
+- **Node.js** — the module targets browsers/bundlers (it uses `fetch` to load the `.wasm`). For a
+  server runtime, instantiate the raw `wasm-pack` glue under `@noiselang/core/wasm` yourself.
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `run(src)` | Parse + evaluate a program → `NoiseResult`. |
+| `runWithIntrospection(src, requests)` | Run + resolve introspection requests → `NoiseIntrospectResult`. |
+| `version()` | The engine (crate) version string. |
+| `load()` | Force one-time WASM instantiation (optional warm-up). |
+
+Full types (`NoiseResult`, `NoiseStats`, `Introspection`, `IntrospectRequest`, …) are exported.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Initialize the WASM module exactly once; subsequent calls await the same promise.
+ *
+ * Called implicitly by `run` / `runWithIntrospection` / `version`, so most callers never need it.
+ * Call it directly to warm the engine (e.g. on app mount) so the first real run doesn't pay the
+ * ~one-off instantiation cost.
+ */
+export declare function load(): Promise<void>;
+/** Run-time counters from the engine — what the program actually computed (see Rust `stats`). */
+export interface NoiseStats {
+    /** Forcing operations (`P`/`E`/`Var`/`Q`/`sample`) the program ran. */
+    forcings: number;
+    /** Total Monte-Carlo draws across all forcings. */
+    samples: number;
+    /** Total per-lane operations executed (Σ draws × cone-node-count). */
+    ops: number;
+    /** Total random source draws (Σ draws × source-node-count). */
+    rng_draws: number;
+}
+export interface NoiseResult {
+    ok: boolean;
+    /** Display form of the program's final value, or null for `unit` / on error. */
+    value: string | null;
+    /** Everything `Print` emitted, in order. */
+    output: string;
+    /** Error message (with a source span) on failure, else null. */
+    error: string | null;
+    /** Engine run-time counters (zeroed if a program forced no sampling). */
+    stats: NoiseStats;
+    /** Wall-clock time of the WASM `run` call, in milliseconds (measured here, not in Rust). */
+    elapsedMs: number;
+}
+/** Parse + evaluate a Noise program. Never throws — failures come back in `error`. */
+export declare function run(src: string): Promise<NoiseResult>;
+/** The engine (crate) version, e.g. `"0.1.1"`. */
+export declare function version(): Promise<string>;
+/** A live top-level binding of the program — what a variable picker would list. */
+export interface Binding {
+    name: string;
+    /** Value kind, e.g. `dist<number>` / `dist<bool>` (introspectable) or `number` / `array`. */
+    kind: string;
+}
+/** A histogram to draw: equal-width buckets `bins` spanning `[lo, hi]`. */
+export interface Hist {
+    lo: number;
+    hi: number;
+    bins: number[];
+}
+/** One introspection result, tagged by `type` (mirrors the Rust `IntrospectionOut`). */
+export type Introspection = {
+    type: 'dist1';
+    label: string;
+    n: number;
+    mean: number;
+    sd: number;
+    min: number;
+    max: number;
+    q05: number;
+    q25: number;
+    q50: number;
+    q75: number;
+    q95: number;
+    boolean: boolean;
+    hist: Hist;
+    head: number[];
+} | {
+    type: 'dist2';
+    label: string;
+    label_b: string;
+    n: number;
+    corr: number;
+    cov: number;
+    mean_a: number;
+    mean_b: number;
+    sd_a: number;
+    sd_b: number;
+    points: [number, number][];
+} | {
+    type: 'explain';
+    label: string;
+    sd: number;
+    drivers: {
+        name: string;
+        corr: number;
+        share: number;
+    }[];
+} | {
+    type: 'value';
+    label: string;
+    val: number;
+    se: number;
+} | {
+    type: 'grid';
+    label: string;
+    rows: number;
+    cols: number;
+    /** true → vector (series view); false → matrix (heatmap view). */
+    series: boolean;
+    mean: number[];
+    sd: number[];
+} | {
+    type: 'corrmatrix';
+    label: string;
+    n: number;
+    corr: number[];
+} | {
+    type: 'error';
+    error: string;
+};
+/** A request: one variable (`describe`/`explain`) or two (`corr`), with an optional condition. */
+export interface IntrospectRequest {
+    /** One or two variable *expressions*, evaluated in the program's scope. */
+    vars: string[];
+    /** Optional condition expression — `describe(v | given)`. */
+    given?: string;
+    /** When true, the one-variable request becomes `explain(v)` (driver fan-out). */
+    explain?: boolean;
+    /** When true, a single (array) variable becomes `corr(v)` (element correlation heatmap). */
+    correlate?: boolean;
+}
+/** One item in the program's output stream: a `Print` line or a `plot::*` chart, in source order. */
+export type LogItem = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'plot';
+    plot: Introspection;
+};
+export interface NoiseIntrospectResult extends NoiseResult {
+    /** The program's live top-level variables (for a picker). */
+    bindings: Binding[];
+    /** One result per request, in request order. */
+    introspections: Introspection[];
+    /** The output stream in source order: `Print` lines and `plot::*` charts, interleaved. */
+    log: LogItem[];
+}
+/**
+ * Run a program and, against its retained scope, resolve a list of introspection requests — the
+ * sidecar that powers a variable inspector. Passing `[]` requests still returns `bindings`, so a
+ * plain run can populate a variable picker. Never throws; failures surface in `error` (and
+ * per-request failures as `{ type: 'error' }` entries).
+ */
+export declare function runWithIntrospection(src: string, requests: IntrospectRequest[]): Promise<NoiseIntrospectResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,62 @@
+// Public API for @noiselang/core — the Noise engine compiled to WebAssembly.
+//
+// The .wasm binary ships inside this package (see ./wasm, generated by `wasm-pack build`). The
+// generated glue instantiates it via `new URL('noise_bg.wasm', import.meta.url)`, so any bundler
+// that understands that pattern (Vite, Rollup, webpack 5, esbuild) fingerprints the .wasm and
+// emits it as an asset of the *consuming* app's build — no copying, no CDN, no runtime config.
+import init, { run as wasmRun, run_with_introspection as wasmRunIntrospect, version as wasmVersion, } from '../wasm/noise.js';
+let ready = null;
+/**
+ * Initialize the WASM module exactly once; subsequent calls await the same promise.
+ *
+ * Called implicitly by `run` / `runWithIntrospection` / `version`, so most callers never need it.
+ * Call it directly to warm the engine (e.g. on app mount) so the first real run doesn't pay the
+ * ~one-off instantiation cost.
+ */
+export function load() {
+    if (!ready) {
+        // No argument → the glue resolves the .wasm via `new URL('noise_bg.wasm', import.meta.url)`,
+        // i.e. the asset the consumer's bundler emitted next to this module.
+        ready = init().then(() => undefined);
+    }
+    return ready;
+}
+const ZERO_STATS = { forcings: 0, samples: 0, ops: 0, rng_draws: 0 };
+/** Parse + evaluate a Noise program. Never throws — failures come back in `error`. */
+export async function run(src) {
+    await load();
+    // Time only the engine call (module load is excluded — it's a one-off, not per-run cost).
+    const t0 = performance.now();
+    const raw = wasmRun(src);
+    const elapsedMs = performance.now() - t0;
+    const parsed = JSON.parse(raw);
+    // The defensive serialization-error fallback omits `stats`; default it so callers needn't guard.
+    return { ...parsed, stats: parsed.stats ?? ZERO_STATS, elapsedMs };
+}
+/** The engine (crate) version, e.g. `"0.1.1"`. */
+export async function version() {
+    await load();
+    return wasmVersion();
+}
+/**
+ * Run a program and, against its retained scope, resolve a list of introspection requests — the
+ * sidecar that powers a variable inspector. Passing `[]` requests still returns `bindings`, so a
+ * plain run can populate a variable picker. Never throws; failures surface in `error` (and
+ * per-request failures as `{ type: 'error' }` entries).
+ */
+export async function runWithIntrospection(src, requests) {
+    await load();
+    const t0 = performance.now();
+    const raw = wasmRunIntrospect(src, JSON.stringify(requests));
+    const elapsedMs = performance.now() - t0;
+    const parsed = JSON.parse(raw);
+    return {
+        ...parsed,
+        stats: parsed.stats ?? ZERO_STATS,
+        bindings: parsed.bindings ?? [],
+        introspections: parsed.introspections ?? [],
+        log: parsed.log ?? [],
+        elapsedMs,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,+FAA+F;AAC/F,iGAAiG;AACjG,8FAA8F;AAC9F,+FAA+F;AAC/F,OAAO,IAAI,EAAE,EACX,GAAG,IAAI,OAAO,EACd,sBAAsB,IAAI,iBAAiB,EAC3C,OAAO,IAAI,WAAW,GACvB,MAAM,kBAAkB,CAAC;AAE1B,IAAI,KAAK,GAAyB,IAAI,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,UAAU,IAAI;IAClB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,6FAA6F;QAC7F,qEAAqE;QACrE,KAAK,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AA4BD,MAAM,UAAU,GAAe,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;AAEjF,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,GAAW;IACnC,MAAM,IAAI,EAAE,CAAC;IACb,0FAA0F;IAC1F,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACzB,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmC,CAAC;IACjE,iGAAiG;IACjG,OAAO,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,UAAU,EAAE,SAAS,EAAE,CAAC;AACrE,CAAC;AAED,kDAAkD;AAClD,MAAM,CAAC,KAAK,UAAU,OAAO;IAC3B,MAAM,IAAI,EAAE,CAAC;IACb,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AA8FD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAW,EACX,QAA6B;IAE7B,MAAM,IAAI,EAAE,CAAC;IACb,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7D,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA6C,CAAC;IAC3E,OAAO;QACL,GAAG,MAAM;QACT,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,UAAU;QACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,EAAE;QAC/B,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,EAAE;QAC3C,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,EAAE;QACrB,SAAS;KACV,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@noiselang/core",
+  "version": "0.1.1",
+  "description": "The Noise probabilistic language engine, compiled to WebAssembly. Parse and run .noise programs (with variable introspection) from any JS/TS project — the .wasm ships in the package and bundles into your build.",
+  "license": "MIT",
+  "author": "Manu Mtz.-Almeida <manu.valladolid@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/manucorporat/noise-lang",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "wasm"
+  ],
+  "scripts": {
+    "build:wasm": "cd ../.. && PATH=\"$HOME/.cargo/bin:$PATH\" wasm-pack build crates/noise-wasm --target web --out-dir ../../packages/core/wasm --out-name noise --release",
+    "build:ts": "tsc -p tsconfig.json",
+    "build": "pnpm run build:wasm && pnpm run build:ts",
+    "prepublishOnly": "pnpm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}