janux 0.1.0

package/src/signals/index.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { batch, computed, effect, signal, untrack } from './index';
+
+describe('signals', () => {
+  it('reads and writes values', () => {
+    const count = signal(0);
+
+    count.value = 2;
+    expect(count.value).toBe(2);
+    expect(count.peek()).toBe(2);
+  });
+
+  it('re-runs effects on change and supports cleanup', () => {
+    const count = signal(0);
+    const cleanup = mock(() => {});
+    const runs = mock(() => {});
+    const dispose = effect(() => {
+      runs();
+      count.value;
+
+      return cleanup;
+    });
+
+    count.value = 1;
+    expect(runs).toHaveBeenCalledTimes(2);
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    dispose();
+    count.value = 2;
+    expect(runs).toHaveBeenCalledTimes(2);
+    expect(cleanup).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not notify on same value (Object.is)', () => {
+    const count = signal(1);
+    const runs = mock(() => {});
+
+    effect(() => {
+      runs();
+      count.value;
+    });
+    count.value = 1;
+    expect(runs).toHaveBeenCalledTimes(1);
+  });
+
+  it('derives computed values reactively', () => {
+    const qty = signal(2);
+    const price = signal(100);
+    const total = computed(() => qty.value * price.value);
+
+    expect(total.value).toBe(200);
+    qty.value = 3;
+    expect(total.value).toBe(300);
+  });
+
+  it('tracks dynamic dependencies only', () => {
+    const flag = signal(true);
+    const a = signal('a');
+    const b = signal('b');
+    const runs = mock(() => {});
+
+    effect(() => {
+      runs();
+      flag.value ? a.value : b.value;
+    });
+    b.value = 'B';
+    expect(runs).toHaveBeenCalledTimes(1);
+    flag.value = false;
+    b.value = 'BB';
+    expect(runs).toHaveBeenCalledTimes(3);
+  });
+
+  it('batches multiple writes into one notification', () => {
+    const a = signal(1);
+    const b = signal(2);
+    const runs = mock(() => {});
+
+    effect(() => {
+      runs();
+      a.value + b.value;
+    });
+    batch(() => {
+      a.value = 10;
+      b.value = 20;
+    });
+    expect(runs).toHaveBeenCalledTimes(2);
+  });
+
+  it('untrack reads without subscribing', () => {
+    const a = signal(1);
+    const runs = mock(() => {});
+
+    effect(() => {
+      runs();
+      untrack(() => a.value);
+    });
+    a.value = 2;
+    expect(runs).toHaveBeenCalledTimes(1);
+  });
+});

package/src/signals/index.ts

@@ -0,0 +1,129 @@
+type Cleanup = (() => void) | undefined;
+
+interface Runner {
+  run: () => void;
+  deps: Set<Set<Runner>>;
+}
+
+export interface Sig<T> {
+  value: T;
+  peek(): T;
+}
+
+export interface ReadonlySig<T> {
+  readonly value: T;
+  peek(): T;
+  dispose(): void;
+}
+
+let active: Runner | null = null;
+let batching: Set<Runner> | null = null;
+
+function track(subs: Set<Runner>): void {
+  if (active === null) return;
+
+  subs.add(active);
+  active.deps.add(subs);
+}
+
+function notify(subs: Set<Runner>): void {
+  const runners = [...subs];
+
+  if (batching !== null) {
+    runners.forEach((runner) => batching!.add(runner));
+
+    return;
+  }
+  runners.forEach((runner) => runner.run());
+}
+
+function detach(runner: Runner): void {
+  runner.deps.forEach((subs) => subs.delete(runner));
+  runner.deps.clear();
+}
+
+export function signal<T>(initial: T): Sig<T> {
+  const subs = new Set<Runner>();
+  let current = initial;
+
+  return {
+    get value(): T {
+      track(subs);
+
+      return current;
+    },
+    set value(next: T) {
+      if (Object.is(next, current)) return;
+      current = next;
+      notify(subs);
+    },
+    peek: () => current,
+  };
+}
+
+function runTracked(runner: Runner, fn: () => Cleanup): Cleanup {
+  const previous = active;
+
+  detach(runner);
+  active = runner;
+  try {
+    return fn();
+  } finally {
+    active = previous;
+  }
+}
+
+export function effect(fn: () => Cleanup | void): () => void {
+  let cleanup: Cleanup;
+  const runner: Runner = { deps: new Set(), run: () => {} };
+
+  runner.run = function runEffect() {
+    cleanup?.();
+    cleanup = runTracked(runner, fn as () => Cleanup) ?? undefined;
+  };
+  runner.run();
+
+  return function dispose() {
+    cleanup?.();
+    detach(runner);
+  };
+}
+
+export function computed<T>(fn: () => T): ReadonlySig<T> {
+  const out = signal<T>(undefined as T);
+  const dispose = effect(() => {
+    out.value = fn();
+  });
+
+  return {
+    get value(): T {
+      return out.value;
+    },
+    peek: () => out.peek(),
+    dispose,
+  };
+}
+
+export function batch<T>(fn: () => T): T {
+  if (batching !== null) return fn();
+  batching = new Set();
+  try {
+    return fn();
+  } finally {
+    const queued = batching;
+
+    batching = null;
+    queued.forEach((runner) => runner.run());
+  }
+}
+
+export function untrack<T>(fn: () => T): T {
+  const previous = active;
+
+  active = null;
+  try {
+    return fn();
+  } finally {
+    active = previous;
+  }
+}

package/src/state/mutation-gate.ts

@@ -0,0 +1,20 @@
+let mutationDepth = 0;
+
+/** Runs `fn` with state mutations enabled (used by intent/effect/event runners). */
+export function allowMutations<T>(fn: () => T): T {
+  mutationDepth += 1;
+  try {
+    return fn();
+  } finally {
+    mutationDepth -= 1;
+  }
+}
+
+export function assertMutable(path: string): void {
+  if (mutationDepth > 0) return;
+
+  throw new Error(
+    `Janux: illegal mutation of "${path}" outside an intent, effect or event handler. ` +
+      'State can only change inside declared run() bodies (RFC §4.4).',
+  );
+}

package/src/state/reactive-state.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { effect } from '../signals';
+import { allowMutations } from './mutation-gate';
+import { createReactiveState } from './reactive-state';
+
+const initial = () => ({
+  items: [{ id: 'a', qty: 1 }],
+  coupon: null as string | null,
+});
+
+describe('reactive state', () => {
+  it('reads initial data through the proxy', () => {
+    const state = createReactiveState(initial());
+
+    expect(state.proxy.items[0]!.qty).toBe(1);
+    expect(state.proxy.coupon).toBe(null);
+  });
+
+  it('throws on mutation outside a run context', () => {
+    const state = createReactiveState(initial());
+
+    expect(() => {
+      state.proxy.coupon = 'SAVE10';
+    }).toThrow(/illegal mutation of "coupon"/);
+    expect(() => state.proxy.items.push({ id: 'b', qty: 2 })).toThrow(/illegal mutation/);
+  });
+
+  it('mutates inside allowMutations and notifies path readers', () => {
+    const state = createReactiveState(initial());
+    const runs = mock(() => {});
+
+    effect(() => {
+      runs();
+      state.proxy.items[0]!.qty;
+    });
+    allowMutations(() => {
+      state.proxy.items[0]!.qty = 5;
+    });
+    expect(runs).toHaveBeenCalledTimes(2);
+    expect(state.snapshot().items[0]!.qty).toBe(5);
+  });
+
+  it('notifies list readers on push and filter-reassign', () => {
+    const state = createReactiveState(initial());
+    const lengths: number[] = [];
+
+    effect(() => {
+      lengths.push(state.proxy.items.length);
+    });
+    allowMutations(() => {
+      state.proxy.items.push({ id: 'b', qty: 2 });
+    });
+    allowMutations(() => {
+      state.proxy.items = state.proxy.items.filter((item) => item.id === 'b');
+    });
+    expect(lengths).toEqual([1, 2, 1]);
+    expect(state.snapshot().items).toEqual([{ id: 'b', qty: 2 }]);
+  });
+
+  it('does not notify readers of untouched sibling paths', () => {
+    const state = createReactiveState(initial());
+    const runs = mock(() => {});
+
+    effect(() => {
+      runs();
+      state.proxy.coupon;
+    });
+    allowMutations(() => {
+      state.proxy.items[0]!.qty = 9;
+    });
+    expect(runs).toHaveBeenCalledTimes(1);
+  });
+
+  it('snapshot is plain data detached from the proxy', () => {
+    const state = createReactiveState(initial());
+    const snap = state.snapshot();
+
+    snap.items[0]!.qty = 99;
+    expect(state.proxy.items[0]!.qty).toBe(1);
+    expect(JSON.parse(JSON.stringify(snap)).items[0].qty).toBe(99);
+  });
+
+});

package/src/state/reactive-state.ts

@@ -0,0 +1,139 @@
+import { batch, signal, untrack, type Sig } from '../signals';
+import { assertMutable } from './mutation-gate';
+
+const MUTATING_ARRAY_METHODS = new Set([
+  'push',
+  'pop',
+  'shift',
+  'unshift',
+  'splice',
+  'sort',
+  'reverse',
+  'fill',
+  'copyWithin',
+]);
+
+export interface ReactiveState<T extends object = Record<string, unknown>> {
+  proxy: T;
+  snapshot(): T;
+}
+
+function isPlainContainer(value: unknown): value is object {
+  return typeof value === 'object' && value !== null;
+}
+
+/** Deep-clones through proxies into plain JSON data (state is JSON-safe by schema). */
+function plainify<T>(value: T): T {
+  if (Array.isArray(value)) return untrack(() => value.map(plainify)) as T;
+  if (isPlainContainer(value)) return untrack(() => plainObject(value)) as T;
+
+  return value;
+}
+
+function plainObject(value: object): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(value).map(([key, v]) => [key, plainify(v)]));
+}
+
+export function createReactiveState<T extends object>(initial: T): ReactiveState<T> {
+  const versions = new Map<string, Sig<number>>();
+  let data = structuredClone(initial);
+
+  const versionOf = (path: string): Sig<number> => {
+    const existing = versions.get(path);
+
+    if (existing) return existing;
+    const created = signal(0);
+
+    versions.set(path, created);
+
+    return created;
+  };
+
+  const bump = (path: string): void => {
+    versionOf(path).value += 1;
+  };
+
+  const bumpDescendants = (path: string): void => {
+    const prefix = path === '' ? '' : `${path}.`;
+
+    [...versions.keys()].filter((key) => key !== path && key.startsWith(prefix)).forEach(bump);
+  };
+
+  const bumpAncestors = (path: string): void => {
+    const parts = path.split('.').slice(0, -1);
+
+    parts.forEach((_, index) => bump(parts.slice(0, index + 1).join('.')));
+    bump('');
+  };
+
+  const touch = (path: string): void => {
+    batch(() => {
+      bump(path);
+      bumpDescendants(path);
+      bumpAncestors(path);
+    });
+  };
+
+  const childPath = (path: string, key: string): string => (path === '' ? key : `${path}.${key}`);
+
+  const wrapArrayMethod = (target: unknown[], path: string, method: string) => {
+    return (...args: unknown[]) => {
+      assertMutable(path);
+      const result = (target as any)[method](...args.map(plainify));
+
+      touch(path);
+
+      return result;
+    };
+  };
+
+  const proxyFor = (target: object, path: string): object => {
+    return new Proxy(target, {
+      get: (raw, key) => readTrap(raw, path, key),
+      set: (raw, key, value) => writeTrap(raw, path, key, value),
+      deleteProperty: (raw, key) => deleteTrap(raw, path, key),
+    });
+  };
+
+  const readTrap = (raw: object, path: string, key: string | symbol): unknown => {
+    if (typeof key === 'symbol') return Reflect.get(raw, key);
+    if (Array.isArray(raw) && MUTATING_ARRAY_METHODS.has(key)) {
+      return wrapArrayMethod(raw as unknown[], path, key);
+    }
+    const value = Reflect.get(raw, key);
+
+    if (typeof value === 'function') return value.bind(proxyFor(raw, path));
+    versionOf(childPath(path, key)).value;
+
+    return isPlainContainer(value) ? proxyFor(value, childPath(path, key)) : value;
+  };
+
+  const writeTrap = (raw: object, path: string, key: string | symbol, value: unknown): boolean => {
+    if (typeof key === 'symbol') return Reflect.set(raw, key, value);
+    const target = childPath(path, key);
+
+    assertMutable(target);
+    Reflect.set(raw, key, plainify(value));
+    touch(target);
+
+    return true;
+  };
+
+  const deleteTrap = (raw: object, path: string, key: string | symbol): boolean => {
+    if (typeof key === 'symbol') return Reflect.deleteProperty(raw, key);
+    const target = childPath(path, key);
+
+    assertMutable(target);
+    Reflect.deleteProperty(raw, key);
+    touch(target);
+
+    return true;
+  };
+
+  return {
+    get proxy(): T {
+      return proxyFor(data, '') as T;
+    },
+    snapshot: () => structuredClone(data),
+  };
+}