@nadrif/thread 0.1.0

package/src/gpu/helpers.js

@@ -0,0 +1,240 @@
+/**
+ * @file Pure utility functions for GPU compute — type helpers, auto-boxing,
+ * JS→WGSL transpilation, and format detection.
+ *
+ * These functions have zero coupling to GPU state and can be used
+ * independently of the {@link GPUCompute} class.
+ *
+ * @module gpu/helpers
+ */
+
+import { GPUComputeError } from '../error.js';
+
+// ---------------------------------------------------------------------------
+// Output type helpers
+// ---------------------------------------------------------------------------
+
+/** Map of human-readable names to TypedArray constructors. */
+export const OUTPUT_TYPES = {
+  f32: Float32Array,
+  i32: Int32Array,
+  u32: Uint32Array,
+  f16: Float32Array, // JS has no Float16Array; use Float32Array
+  f64: Float64Array,
+};
+
+/**
+ * Resolve a type name or constructor to a TypedArray constructor.
+ *
+ * @param {string|typeof TypedArray} type
+ * @returns {typeof TypedArray}
+ */
+export function resolveType(type) {
+  if (typeof type === 'function') return type;
+  const resolved = OUTPUT_TYPES[type];
+  if (!resolved) throw new TypeError(`Unknown output type: "${type}"`);
+  return resolved;
+}
+
+// ---------------------------------------------------------------------------
+// Auto-boxing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Auto-box a value into a TypedArray.
+ *
+ * - `number` → `Float32Array([n])`
+ * - `number[]` → `Float32Array(arr)`
+ * - `TypedArray` → returned as-is
+ *
+ * @param {*} val
+ * @returns {TypedArray}
+ */
+export function box(val) {
+  if (val instanceof Float32Array || val instanceof Int32Array || val instanceof Uint32Array) return val;
+  if (typeof val === 'number') return new Float32Array([val]);
+  if (Array.isArray(val)) return new Float32Array(val);
+  return val;
+}
+
+/**
+ * Box all values in a plain object.
+ *
+ * @param {Object<string, *>} obj
+ * @returns {Object<string, TypedArray>}
+ */
+export function boxAll(obj) {
+  if (!obj) return {};
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) out[k] = box(v);
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Format detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect whether the second arg to `run()` is the old format
+ * `{ inputs, uniforms, outputs, ... }` or the new flat format `inputs`.
+ *
+ * @param {*} arg
+ * @returns {boolean}
+ */
+export function isOldRunFormat(arg) {
+  return arg != null && typeof arg === 'object' && !ArrayBuffer.isView(arg) &&
+    ('inputs' in arg || 'uniforms' in arg || 'outputBuffers' in arg || 'outputs' in arg);
+}
+
+// ---------------------------------------------------------------------------
+// JS → WGSL transpilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Transpile a WGSL expression string (JS-flavored) to valid WGSL.
+ *
+ * Handles: ternary→select, ===→==, &&→&, ||→|, **→^,
+ * Math.*→WGSL equivalents, integer→float literals.
+ *
+ * @param {string} expr - JS-flavored expression
+ * @returns {string} Valid WGSL expression
+ */
+export function transpileExpression(expr) {
+  const MATH_MAP = {
+    'Math.sqrt': 'sqrt', 'Math.abs': 'abs', 'Math.sin': 'sin',
+    'Math.cos': 'cos', 'Math.tan': 'tan', 'Math.asin': 'asin',
+    'Math.acos': 'acos', 'Math.atan': 'atan', 'Math.atan2': 'atan2',
+    'Math.exp': 'exp', 'Math.log': 'log', 'Math.log2': 'log2',
+    'Math.log10': 'log10', 'Math.pow': 'pow', 'Math.max': 'max',
+    'Math.min': 'min', 'Math.floor': 'floor', 'Math.ceil': 'ceil',
+    'Math.round': 'round', 'Math.trunc': 'trunc', 'Math.sign': 'sign',
+    'Math.PI': '3.14159265', 'Math.E': '2.71828182',
+    'Math.tanh': 'tanh', 'Math.sinh': 'sinh', 'Math.cosh': 'cosh',
+    'Math.cbrt': 'cbrt', 'Math.expm1': '(exp($1) - 1.0)',
+    'Math.log1p': 'log(1.0 + $1)',
+    'Math.hypot': 'sqrt($1 * $1 + $2 * $2)',
+    'Math.random': 'fract(f32(hash(u32(i))))',
+  };
+
+  let wgsl = expr;
+
+  // Replace ternary: `cond ? a : b` → `select(b, a, cond)`
+  wgsl = wgsl.replace(
+    /(.+?)\s*\?\s*(.+?)\s*:\s*(.+)/g,
+    (_, cond, a, b) => `select(${b.trim()}, ${a.trim()}, ${cond.trim()})`,
+  );
+
+  // Replace JS comparison operators
+  wgsl = wgsl.replace(/===/g, '==');
+  wgsl = wgsl.replace(/!==/g, '!=');
+
+  // Replace JS logical operators
+  wgsl = wgsl.replace(/&&/g, '&');
+  wgsl = wgsl.replace(/\|\|/g, '|');
+  wgsl = wgsl.replace(/!(?=[a-zA-Z_])/g, '!');
+
+  // Replace JS operators
+  wgsl = wgsl.replace(/\*\*/g, '^');
+
+  // Replace JS math calls with WGSL equivalents (longest first)
+  const sortedKeys = Object.keys(MATH_MAP).sort((a, b) => b.length - a.length);
+  for (const jsName of sortedKeys) {
+    const wgslName = MATH_MAP[jsName];
+    if (wgslName.includes('$')) {
+      wgsl = wgsl.replace(
+        new RegExp(jsName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\(([^,)]+),\\s*([^)]+)\\)', 'g'),
+        wgslName.replace('$1', '$1').replace('$2', '$2'),
+      );
+      wgsl = wgsl.replace(
+        new RegExp(jsName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\(([^)]+)\\)', 'g'),
+        wgslName.replace('$1', '$1').replace(/, *\$2.*/, ''),
+      );
+    } else {
+      wgsl = wgsl.split(jsName).join(wgslName);
+    }
+  }
+
+  // Replace bare integer literals in arithmetic with floats
+  wgsl = wgsl.replace(/(?<=[^a-zA-Z_0-9.\[])(\d+)(?=[^a-zA-Z_0-9.\]$)])/g, '$1.0');
+  wgsl = wgsl.replace(/true\.0/g, 'true').replace(/false\.0/g, 'false');
+  wgsl = wgsl.replace(/(\d+\.\d+)\.0/g, '$1');
+
+  return wgsl;
+}
+
+/**
+ * Transpile a `define(name, fn)` function body to a WGSL assignment expression.
+ *
+ * Converts `data.value` → `inputName[i]`, `data.index`/`data.i` → `f32(i)`,
+ * then runs the result through {@link transpileExpression}.
+ *
+ * @param {Function} fn - The JS function `(data, { uniform }) => expression`
+ * @param {string} inputName - The storage buffer name (first param name)
+ * @returns {string} WGSL body like `result[i] = data[i] * alpha + ...;`
+ */
+export function transpileDefineBody(fn, inputName) {
+  const src = fn.toString();
+
+  // Extract body from arrow function
+  let body;
+  const arrowMatch = src.match(/=>\s*\{?\s*(?:return\s+)?(.+?);?\s*\}?\s*$/);
+  if (arrowMatch) {
+    body = arrowMatch[1].trim();
+  } else {
+    throw new GPUComputeError(`Cannot parse define function: ${src}`);
+  }
+
+  // Replace data proxy references with WGSL equivalents
+  // data.value → inputName[i]
+  body = body.replace(/data\.value/g, `${inputName}[i]`);
+  // data.index → f32(i)
+  body = body.replace(/data\.index/g, 'f32(i)');
+  // data.i → f32(i) (but not data.index which was already handled)
+  body = body.replace(/data\.i\b(?!\w)/g, 'f32(i)');
+
+  // Run through expression transpiler for math, ternary, etc.
+  return transpileExpression(body);
+}
+
+/**
+ * Convert a JS function body to a WGSL expression.
+ *
+ * Handles common patterns:
+ *   `x => Math.sqrt(x)`         → `sqrt(x)`
+ *   `x => x * 2 + 1`           → `x * 2.0 + 1.0`
+ *   `x => Math.max(0, x)`      → `max(0.0, x)`
+ *   `(a, b) => a + b`          → `a + b`
+ *   `x => x > 0 ? x : 0`      → select(0.0, x, x > 0.0)
+ *   `x => x === 0 ? 1 : 0`    → select(0.0, 1.0, x == 0.0)
+ *   `x => !x ? 1 : 0`          → select(0.0, 1.0, !x)
+ *
+ * @param {Function} fn
+ * @returns {string} WGSL expression
+ */
+export function jsToWgsl(fn) {
+  const src = fn.toString();
+
+  // Extract the body — works for `x => expr` and `(x) => { return expr; }`
+  let body;
+  const arrowMatch = src.match(/=>\s*\{?\s*(?:return\s+)?(.+?);?\s*\}?\s*$/);
+  if (arrowMatch) {
+    body = arrowMatch[1].trim();
+  } else {
+    throw new GPUComputeError(`Cannot parse function body: ${src}`);
+  }
+
+  return transpileExpression(body);
+}
+
+/**
+ * Extract parameter names from a JS function's signature.
+ *
+ * @param {Function} fn
+ * @returns {string[]}
+ */
+export function getParamNames(fn) {
+  const src = fn.toString();
+  const match = src.match(/\(([^)]*)\)/);
+  if (!match) return ['x'];
+  return match[1].split(',').map(s => s.trim()).filter(Boolean);
+}

package/src/gpu/hooks.js

@@ -0,0 +1,284 @@
+/**
+ * @file Framework-agnostic hooks for GPU compute.
+ *
+ * Provides lifecycle-bound hooks that mirror the thread/pool hooks
+ * but are specialised for {@link GPUCompute} instances.
+ *
+ * The framework (Preact, React, etc.) is resolved at load time via the
+ * thread config system.
+ *
+ * @module gpu/hooks
+ */
+
+import { getHooks } from '../config/index.js';
+import { GPUCompute } from './gpu.js';
+
+// Resolve framework hooks at module load time (top-level await)
+let useRef, useState, useEffect, useCallback, useMemo;
+try {
+  ({ useRef, useState, useEffect, useCallback, useMemo } = await getHooks());
+} catch {
+  const _stub = () => { throw new Error('[thread] No framework installed. Install preact or react to use GPU hooks.'); };
+  useRef = _stub; useState = _stub; useEffect = _stub; useCallback = _stub; useMemo = _stub;
+}
+
+// ---------------------------------------------------------------------------
+// useGPU
+// ---------------------------------------------------------------------------
+
+/**
+ * Create and manage a {@link GPUCompute} instance bound to a component's
+ * lifecycle.
+ *
+ * The GPU device is lazily initialised on the first `run()` call.
+ * The instance is automatically destroyed on unmount.
+ *
+ * @param {import('../types.js').GPUComputeOptions & { destroy?: boolean }} [options={}]
+ *   GPU options plus `destroy: false` to skip automatic cleanup.
+ * @returns {{
+ *   gpu: GPUCompute,
+ *   run: (...args: any[]) => Promise<any>,
+ *   pipe: (name?: string, count?: number) => import('./chains.js').DataPipelineChain,
+ *   define: (name: string, fn: Function) => void,
+ *   result: any,
+ *   loading: boolean,
+ *   error: string|null,
+ *   status: string,
+ *   metrics: import('../types.js').MetricsSnapshot,
+ * }}
+ *
+ * @example
+ * ```jsx
+ * function GPUDemo({ prices }) {
+ *   const { run, result, loading, error, status } = useGPU();
+ *
+ *   const handleEMA = () => {
+ *     run('ema', new Float32Array(prices), { alpha: 0.3 });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>GPU: {status}</p>
+ *       <button onClick={handleEMA} disabled={loading}>
+ *         {loading ? 'Computing...' : 'Run EMA'}
+ *       </button>
+ *       {error && <p className="error">{error}</p>}
+ *       {result && <pre>{JSON.stringify(Array.from(result))}</pre>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useGPU(options = {}) {
+  const { destroy = true, ...gpuOpts } = options;
+
+  const gpuRef = useRef(null);
+  const [result, setResult] = useState(null);
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [status, setStatus] = useState('idle');
+  const [metricsSnapshot, setMetricsSnapshot] = useState({});
+
+  // Create instance once
+  if (gpuRef.current === null) {
+    gpuRef.current = new GPUCompute(gpuOpts);
+  }
+  const gpu = gpuRef.current;
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (gpu && destroy) {
+        gpu.destroy();
+      }
+    };
+  }, [gpu, destroy]);
+
+  // Poll metrics & status
+  useEffect(() => {
+    if (!gpu) return;
+    const interval = setInterval(() => {
+      setStatus(gpu.status);
+      setMetricsSnapshot(gpu.metrics);
+    }, 500);
+    return () => clearInterval(interval);
+  }, [gpu]);
+
+  // Stable run function
+  const run = useCallback(
+    async (...args) => {
+      setLoading(true);
+      setError(null);
+      setStatus(gpu.status);
+      try {
+        const res = await gpu.run(...args);
+        setResult(res);
+        setLoading(false);
+        setStatus(gpu.status);
+        setMetricsSnapshot(gpu.metrics);
+        return res;
+      } catch (err) {
+        const msg = err.message || String(err);
+        setError(msg);
+        setLoading(false);
+        setStatus(gpu.status);
+        throw err;
+      }
+    },
+    [gpu],
+  );
+
+  // Stable pipe
+  const pipe = useCallback(
+    (name, count) => gpu.pipe(name, count),
+    [gpu],
+  );
+
+  // Stable define
+  const define = useCallback(
+    (name, fn) => gpu.define(name, fn),
+    [gpu],
+  );
+
+  return { gpu, run, pipe, define, result, loading, error, status, metrics: metricsSnapshot };
+}
+
+// ---------------------------------------------------------------------------
+// useGPURun
+// ---------------------------------------------------------------------------
+
+/**
+ * Get a stable `run` wrapper around an existing {@link GPUCompute}
+ * instance, with reactive loading / result / error state.
+ *
+ * Use this when you manage the GPU instance yourself (e.g. in a store
+ * or module-level variable).
+ *
+ * @param {GPUCompute} gpu - Existing GPU instance.
+ * @returns {{
+ *   run: (...args: any[]) => Promise<any>,
+ *   result: any,
+ *   loading: boolean,
+ *   error: string|null,
+ * }}
+ *
+ * @example
+ * ```jsx
+ * // Shared GPU across components
+ * const sharedGPU = new GPUCompute();
+ *
+ * function ComponentA() {
+ *   const { run, result, loading } = useGPURun(sharedGPU);
+ *   return <button onClick={() => run('add', data1, data2)}>A</button>;
+ * }
+ * ```
+ */
+export function useGPURun(gpu) {
+  const [result, setResult] = useState(null);
+  const [error, setError] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  const run = useCallback(
+    async (...args) => {
+      if (!gpu) {
+        const msg = 'No GPU instance';
+        setError(msg);
+        throw new Error(msg);
+      }
+      setLoading(true);
+      setError(null);
+      try {
+        const res = await gpu.run(...args);
+        setResult(res);
+        setLoading(false);
+        return res;
+      } catch (err) {
+        const msg = err.message || String(err);
+        setError(msg);
+        setLoading(false);
+        throw err;
+      }
+    },
+    [gpu],
+  );
+
+  return useMemo(() => ({ run, result, loading, error }), [run, result, loading, error]);
+}
+
+// ---------------------------------------------------------------------------
+// useGPUMetrics
+// ---------------------------------------------------------------------------
+
+/**
+ * Subscribe to a {@link GPUCompute} instance's metrics and re-render
+ * on updates.
+ *
+ * @param {GPUCompute} [gpu] - GPU instance.  If `null`/`undefined`,
+ *   returns a zeroed snapshot.
+ * @param {number} [intervalMs=500] - Polling interval in ms.
+ * @returns {import('../types.js').MetricsSnapshot}
+ *
+ * @example
+ * ```jsx
+ * function GPUDashboard({ gpu }) {
+ *   const metrics = useGPUMetrics(gpu, 250);
+ *
+ *   return (
+ *     <div>
+ *       <span>{metrics.count} dispatches</span>
+ *       <span>{metrics.avg?.toFixed(1)}ms avg</span>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useGPUMetrics(gpu, intervalMs = 500) {
+  const [snapshot, setSnapshot] = useState(
+    gpu ? gpu.metrics : { count: 0, errors: 0, avg: 0, min: 0, max: 0, throughput: 0, errorRate: 0 },
+  );
+
+  useEffect(() => {
+    if (!gpu) return;
+    const interval = setInterval(() => {
+      setSnapshot(gpu.metrics);
+    }, intervalMs);
+    return () => clearInterval(interval);
+  }, [gpu, intervalMs]);
+
+  return snapshot;
+}
+
+// ---------------------------------------------------------------------------
+// useGPUStatus
+// ---------------------------------------------------------------------------
+
+/**
+ * Reactive status string for a {@link GPUCompute} instance.
+ *
+ * Returns one of: `'idle'`, `'running'`, `'error'`, `'unavailable'`.
+ *
+ * @param {GPUCompute} [gpu] - GPU instance.
+ * @param {number} [intervalMs=500] - Polling interval in ms.
+ * @returns {string}
+ *
+ * @example
+ * ```jsx
+ * function StatusBadge({ gpu }) {
+ *   const status = useGPUStatus(gpu);
+ *   return <span className={`badge badge-${status}`}>{status}</span>;
+ * }
+ * ```
+ */
+export function useGPUStatus(gpu, intervalMs = 500) {
+  const [status, setStatus] = useState(gpu ? gpu.status : 'idle');
+
+  useEffect(() => {
+    if (!gpu) return;
+    const interval = setInterval(() => {
+      setStatus(gpu.status);
+    }, intervalMs);
+    return () => clearInterval(interval);
+  }, [gpu, intervalMs]);
+
+  return status;
+}

package/src/gpu/index.js

@@ -0,0 +1,16 @@
+/**
+ * @file GPU compute barrel export.
+ *
+ * Re-exports every public symbol from the GPU sub-modules so
+ * consumers can do `import { GPUCompute, ... } from '../gpu/index.js'`.
+ *
+ * @module gpu
+ */
+
+export { GPUCompute, createGPUCompute, createGPUWithFallback, outputSpec, uniform } from './gpu.js';
+export { PipelineChain, DataPipelineChain } from './chains.js';
+export { buildShader, BUILT_IN_OPS, BUILT_IN_OP_NAMES, SPECIAL_OPS } from './shaders.js';
+export { runSpecial, runMatmul, buildMatmulShader, runReduce, getReduceBody,
+  runHistogram, runArgMaxMin, runScan } from './special.js';
+export { useGPU, useGPURun, useGPUMetrics, useGPUStatus } from './hooks.js';
+export { createGPUBinder, createGPUSignalBinder, createGPUStoreBinder } from './adapters.js';