@nadrif/thread 0.1.0

package/src/config/adapters.js

@@ -0,0 +1,188 @@
+/**
+ * @file State manager adapter registry for the thread config system.
+ *
+ * Maps a state manager name (e.g. `'zustand'`, `'redux'`) to the
+ * appropriate adapter constructors for threads and GPU.
+ *
+ * ## How adapters work
+ *
+ * Adapters bridge thread's thread/pool/GPU instances to your state manager.
+ * They follow a consistent pattern:
+ *
+ * ```
+ * adapter(threadOrGpu, store, action, options) → { run, destroy }
+ * ```
+ *
+ * - `run(...args)` — execute the task **and** push the result to the store
+ * - `destroy()` — clean up event listeners
+ *
+ * Different state managers have different update patterns:
+ *
+ * | Type | Pattern | Used by |
+ * |------|---------|---------|
+ * | `action` | Call a store action by name: `store.getAction('setData')(result)` | Zustand |
+ * | `signal` | Write to a signal's `.value` property: `signal.value = result` | Preact Signals |
+ * | `setter` | Call a setter callback: `setter(result)` | Redux, Jotai, MobX, vanilla |
+ *
+ * ## Why some adapters are the same
+ *
+ * Redux, Jotai, MobX, and vanilla JS all use the same adapter
+ * (`createStoreBinder`) because they all accept a generic setter callback.
+ * The difference is in how you *create* the store, not in how thread
+ * pushes results to it.
+ *
+ * @example
+ * ```js
+ * // All of these use the same adapter under the hood:
+ * import { getAdapter } from './config/adapters.js';
+ *
+ * const reduxAdapter = getAdapter('redux');
+ * const jotaiAdapter = getAdapter('jotai');
+ * const mobxAdapter = getAdapter('mobx');
+ *
+ * // reduxAdapter.thread === jotaiAdapter.thread === mobxAdapter.thread
+ * // They're all `createStoreBinder`
+ * ```
+ *
+ * @module config/adapters
+ */
+
+import {
+  createZustandBinder,
+  createSignalBinder,
+  createStoreBinder,
+} from '../adapters.js';
+
+import {
+  createGPUBinder,
+  createGPUSignalBinder,
+  createGPUStoreBinder,
+} from '../gpu/adapters.js';
+
+// ---------------------------------------------------------------------------
+// Adapter map
+// ---------------------------------------------------------------------------
+
+/**
+ * Mapping of state manager names to their adapter constructors.
+ *
+ * Each entry provides:
+ * - `thread`: adapter constructor for thread/pool binding
+ * - `gpu`: adapter constructor for GPU binding
+ * - `type`: hint about the update pattern (`'action'` | `'signal'` | `'setter'`)
+ *
+ * @type {Record<string, { thread: Function, gpu: Function, type: string }>}
+ * @private
+ */
+const ADAPTER_MAP = {
+  zustand: {
+    thread: createZustandBinder,
+    gpu: createGPUBinder,
+    type: 'action',
+  },
+  signals: {
+    thread: createSignalBinder,
+    gpu: createGPUSignalBinder,
+    type: 'signal',
+  },
+  redux: {
+    thread: createStoreBinder,
+    gpu: createGPUStoreBinder,
+    type: 'setter',
+  },
+  jotai: {
+    thread: createStoreBinder,
+    gpu: createGPUStoreBinder,
+    type: 'setter',
+  },
+  mobx: {
+    thread: createStoreBinder,
+    gpu: createGPUStoreBinder,
+    type: 'setter',
+  },
+  vanilla: {
+    thread: createStoreBinder,
+    gpu: createGPUStoreBinder,
+    type: 'setter',
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Get adapter constructors for a given state manager.
+ *
+ * Returns the thread and GPU adapter constructors, plus a type hint
+ * that tells you how the adapter works.
+ *
+ * @param {string} stateManager
+ *   State manager name.  Must be one of the values in {@link STATE_MANAGERS}.
+ * @param {Function|null} [customAdapter=null]
+ *   Optional custom adapter factory.  If provided, it is used for both
+ *   thread and GPU adapters, overriding the registry lookup.
+ *
+ * @returns {{ thread: Function, gpu: Function, type: string }}
+ *   Adapter constructors and type hint.
+ *
+ * @example
+ * ```js
+ * import { getAdapter } from './config/adapters.js';
+ *
+ * // Get Zustand adapters
+ * const { thread, gpu, type } = getAdapter('zustand');
+ * console.log(type); // 'action'
+ *
+ * // Use the thread adapter
+ * const binder = thread(myThread, useStore, 'setData', {
+ *   errorAction: 'setError',
+ * });
+ *
+ * // Now every thread.run() result is pushed to the store
+ * await binder.run('some data');
+ * ```
+ *
+ * @example
+ * ```js
+ * // Get Redux adapters (generic setter pattern)
+ * const { thread, type } = getAdapter('redux');
+ * console.log(type); // 'setter'
+ *
+ * // The adapter works with any setter function:
+ * const binder = thread(myThread, (result) => {
+ *   dispatch({ type: 'SET_DATA', payload: result });
+ * });
+ * ```
+ *
+ * @example
+ * ```js
+ * // Custom adapter
+ * const myAdapter = (instance, store, action) => ({
+ *   run: async (...args) => {
+ *     const result = await instance.run(...args);
+ *     store.dispatch({ type: action, payload: result });
+ *   },
+ *   destroy: () => {},
+ * });
+ *
+ * const { thread } = getAdapter('custom', myAdapter);
+ * ```
+ */
+export function getAdapter(stateManager, customAdapter = null) {
+  if (typeof customAdapter === 'function') {
+    return { thread: customAdapter, gpu: customAdapter, type: 'custom' };
+  }
+
+  const entry = ADAPTER_MAP[stateManager];
+
+  if (!entry) {
+    console.warn(
+      `[thread] Unknown stateManager: "${stateManager}". Falling back to "vanilla". ` +
+      `Valid options: ${Object.keys(ADAPTER_MAP).join(', ')}`
+    );
+    return ADAPTER_MAP.vanilla;
+  }
+
+  return entry;
+}

package/src/config/define.js

@@ -0,0 +1,171 @@
+/**
+ * @file Configuration helper for the thread library.
+ *
+ * Provides the `defineConfig()` function — the recommended way to create
+ * a `thread.config.js` file.  It validates the config, warns on unknown
+ * keys (catching typos), applies sensible defaults for omitted fields,
+ * and returns a frozen (immutable) config object.
+ *
+ * ## Why `defineConfig()`?
+ *
+ * You *could* write `export default { ... }` directly, but `defineConfig()`
+ * gives you:
+ *
+ * - **Typo detection** — unknown keys trigger a console warning
+ * - **Automatic defaults** — omit any field and it falls back to a sensible value
+ * - **Immutability** — the returned config is frozen, preventing accidental mutation
+ * - **Validation** — invalid enum values (e.g. `framework: ' angular'`) warn and
+ *   fall back to the default
+ *
+ * ## How it works
+ *
+ * 1. The user creates `thread.config.js` in their project root
+ * 2. They `import { defineConfig } from 'thread/config'` and call it
+ * 3. At library load time, thread reads the file, parses the config object,
+ *    and applies it globally
+ * 4. All hooks and adapters use the resolved config to pick the right
+ *    framework and state manager
+ *
+ * @example
+ * ```js
+ * // thread.config.js — in your project root
+ * import { defineConfig } from 'thread/config';
+ *
+ * export default defineConfig({
+ *   // Pick your UI framework — hooks are auto-resolved
+ *   framework: 'react',
+ *
+ *   // Pick your state manager — adapter shortcuts are auto-selected
+ *   stateManager: 'zustand',
+ *
+ *   // GPU compute defaults (used by all GPUCompute instances)
+ *   gpu: {
+ *     workgroupSize: 256,
+ *     powerPreference: 'high-performance',
+ *   },
+ *
+ *   // Thread defaults
+ *   thread: { timeout: 10_000 },
+ *
+ *   // Pool defaults
+ *   pool: { autoRestart: true, enableStealing: true },
+ *
+ *   // Development options
+ *   dev: { log: true, metrics: true },
+ * });
+ * ```
+ *
+ * @example
+ * ```js
+ * // Minimal config — everything else uses defaults
+ * import { defineConfig } from 'thread/config';
+ *
+ * export default defineConfig({
+ *   framework: 'svelte',
+ *   stateManager: 'signals',
+ * });
+ * ```
+ *
+ * @example
+ * ```js
+ * // Custom framework with your own hooks
+ * import { defineConfig } from 'thread/config';
+ *
+ * export default defineConfig({
+ *   framework: 'custom',
+ *   customHookSource: async () => {
+ *     const mod = await import('my-framework/hooks');
+ *     return {
+ *       useState: mod.useState,
+ *       useEffect: mod.useEffect,
+ *       useRef: mod.useRef,
+ *       useCallback: mod.useCallback,
+ *       useMemo: mod.useMemo,
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @module config/define
+ */
+
+import { mergeWithDefaults, validateConfig } from './schema.js';
+
+// ---------------------------------------------------------------------------
+// defineConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Define a thread configuration object.
+ *
+ * Returns a **frozen** (immutable) config with all defaults applied.
+ * Unknown top-level keys produce a console warning — this helps catch
+ * typos like `framwork` instead of `framework`.
+ *
+ * Invalid values (e.g. `framework: 'Angular'` with wrong casing) are
+ * replaced with the default and a warning is logged.  This keeps the
+ * library functional even with a partially incorrect config.
+ *
+ * @param {Record<string, any>} [config={}]
+ *   User configuration.  All fields are optional.  See {@link threadConfig}
+ *   for the full schema.
+ *
+ * @returns {Readonly<import('../types.js').threadConfig>}
+ *   Fully resolved, frozen configuration object.  Contains the user's
+ *   values where valid, and built-in defaults everywhere else.
+ *
+ * @throws {TypeError} Never — invalid inputs are handled gracefully with
+ *   warnings and fallbacks.
+ *
+ * @see {@link threadConfig} for the full type definition.
+ * @see {@link DEFAULTS} for the default values.
+ * @see {@link FRAMEWORKS} for the list of supported frameworks.
+ * @see {@link STATE_MANAGERS} for the list of supported state managers.
+ *
+ * @example
+ * ```js
+ * import { defineConfig } from 'thread/config';
+ *
+ * export default defineConfig({
+ *   framework: 'react',
+ *   gpu: { powerPreference: 'low-power' },
+ *   dev: { log: true },
+ * });
+ *
+ * // Result:
+ * // {
+ * //   framework: 'react',
+ * //   stateManager: 'zustand',       ← default
+ * //   customHookSource: null,        ← default
+ * //   customAdapter: null,            ← default
+ * //   gpu: { workgroupSize: 256, maxBufferSize: 268435456, ... },
+ * //   thread: { timeout: 30000 },     ← default
+ * //   pool: { autoRestart: true },    ← default
+ * //   dev: { log: true, metrics: false, warnOnLongTask: 0 },
+ * // }
+ * ```
+ *
+ * @example
+ * ```js
+ * // TypeScript — the return type is threadConfig
+ * import { defineConfig } from 'thread/config';
+ * import type { threadConfig } from 'thread/types';
+ *
+ * const config: threadConfig = defineConfig({
+ *   framework: 'vue',
+ *   stateManager: 'redux',
+ * });
+ * ```
+ */
+export function defineConfig(config = {}) {
+  if (config !== null && typeof config !== 'object') {
+    console.warn('[thread] defineConfig() expected an object, got:', typeof config);
+    return Object.freeze(mergeWithDefaults({}));
+  }
+
+  validateConfig(config);
+
+  const resolved = mergeWithDefaults(config);
+
+  return Object.freeze(resolved);
+}

package/src/config/env.js

@@ -0,0 +1,218 @@
+/**
+ * @file Cross-environment config loading for the thread library.
+ *
+ * Loads `thread.config.js` from the project root across different runtimes:
+ * - **Node.js / Bun** — `fs.readFileSync` (synchronous, works with top-level await)
+ * - **Deno** — `Deno.readTextFileSync`
+ * - **Browser** — Skips file loading (config must be set programmatically)
+ * - **Edge** — Skips file loading
+ *
+ * @module config/env
+ */
+
+import { env } from '../env.js';
+
+// ---------------------------------------------------------------------------
+// Config file loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt to load `thread.config.js` from the project root.
+ *
+ * Uses the appropriate file system API for the current runtime.
+ * Returns `null` if the file doesn't exist or can't be read.
+ *
+ * @param {string} [filename='thread.config.js'] - Config filename to look for.
+ * @returns {Record<string, any>|null} Parsed config object, or `null`.
+ *
+ * @example
+ * ```js
+ * const file = loadConfigFile();
+ * if (file) {
+ *   console.log('Loaded config:', file);
+ * } else {
+ *   console.log('No config file found — using defaults');
+ * }
+ * ```
+ */
+export function loadConfigFile(filename = 'thread.config.js') {
+  // --- Node.js / Bun ---
+  if (env.isNode || env.isBun) {
+    return _loadNodeConfig(filename);
+  }
+
+  // --- Deno ---
+  if (env.isDeno) {
+    return _loadDenoConfig(filename);
+  }
+
+  // --- Browser / Edge ---
+  // Config must be set programmatically via setConfig()
+  return null;
+}
+
+/**
+ * @private
+ */
+function _loadNodeConfig(filename) {
+  try {
+    const fs = env.requireModule('node:fs');
+    const path = env.requireModule('node:path');
+    if (!fs || !path) return null;
+
+    const cwd = env.getCwd();
+    const configPath = path.resolve(cwd, filename);
+
+    if (!fs.existsSync(configPath)) return null;
+
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    return _parseConfig(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @private
+ */
+function _loadDenoConfig(filename) {
+  try {
+    if (typeof Deno === 'undefined' || typeof Deno.readTextFileSync !== 'function') {
+      return null;
+    }
+
+    const cwd = env.getCwd();
+    const configPath = `${cwd}/${filename}`;
+
+    // Check if file exists
+    try { Deno.statSync(configPath); } catch { return null; }
+
+    const raw = Deno.readTextFileSync(configPath);
+    return _parseConfig(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse a config file string into an object.
+ *
+ * Strips `import` and `export default` statements, then evaluates
+ * the remaining object literal.
+ *
+ * @param {string} raw - Raw file contents.
+ * @returns {Record<string, any>|null} Parsed object, or `null` on failure.
+ * @private
+ */
+function _parseConfig(raw) {
+  try {
+    // Strip ESM syntax
+    const cleaned = raw
+      .replace(/^import\s+.*$/gm, '')
+      .replace(/^export\s+default\s+/, '')
+      .replace(/^export\s+\{[^}]*\};?\s*$/gm, '')
+      .trim();
+
+    if (!cleaned) return null;
+
+    // Evaluate the config object
+    const fn = new Function(`return (${cleaned})`);
+    const result = fn();
+
+    // Handle defineConfig() return value (frozen object)
+    if (result && typeof result === 'object' && typeof result[Symbol.iterator] === 'function') {
+      return Object.fromEntries(
+        Object.entries(result).filter(([k]) => k !== 'then')
+      );
+    }
+
+    return result && typeof result === 'object' ? result : null;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Programmatic config storage (for browser/edge environments)
+// ---------------------------------------------------------------------------
+
+/** @type {Record<string, any>|null} Programmatic config override. */
+let _programmaticConfig = null;
+
+/**
+ * Set the configuration programmatically.
+ *
+ * Use this in browser/edge environments where file system access
+ * is not available.  This overrides any `thread.config.js` file.
+ *
+ * @param {Record<string, any>} config - Configuration object.
+ *
+ * @example
+ * ```js
+ * import { setProgrammaticConfig } from './config/env.js';
+ *
+ * setProgrammaticConfig({
+ *   framework: 'react',
+ *   stateManager: 'zustand',
+ *   gpu: { workgroupSize: 512 },
+ * });
+ * ```
+ */
+export function setProgrammaticConfig(config) {
+  _programmaticConfig = config && typeof config === 'object' ? { ...config } : null;
+}
+
+/**
+ * Get the programmatic config override (if set).
+ *
+ * @returns {Record<string, any>|null} The programmatic config, or `null`.
+ */
+export function getProgrammaticConfig() {
+  return _programmaticConfig;
+}
+
+/**
+ * Clear the programmatic config override.
+ */
+export function clearProgrammaticConfig() {
+  _programmaticConfig = null;
+}
+
+/**
+ * Load config with programmatic override support.
+ *
+ * Priority: programmatic config > file-based config > defaults.
+ *
+ * @param {string} [filename='thread.config.js'] - Config filename.
+ * @returns {Record<string, any>|null} Loaded config, or `null`.
+ *
+ * @example
+ * ```js
+ * // In a browser environment
+ * import { loadConfigWithOverride } from './config/env.js';
+ *
+ * // User sets config programmatically
+ * setProgrammaticConfig({ framework: 'svelte' });
+ *
+ * // Config loader uses programmatic override
+ * const config = loadConfigWithOverride();
+ * console.log(config.framework); // 'svelte'
+ * ```
+ */
+export function loadConfigWithOverride(filename = 'thread.config.js') {
+  // Priority: programmatic > file
+  if (_programmaticConfig) return _programmaticConfig;
+  return loadConfigFile(filename);
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export default {
+  loadConfigFile,
+  setProgrammaticConfig,
+  getProgrammaticConfig,
+  clearProgrammaticConfig,
+  loadConfigWithOverride,
+};