@granularjs/core 1.0.0

package/src/core/reactivity/observe.js

@@ -0,0 +1,421 @@
+import { isSignal, readSignal, subscribeSignal, setSignal, signal } from './signal.js';
+import { isObservableArray } from '../collections/observable-array.js';
+import { createStateFromAdapter, isState, isStatePath, readState, readStateFromRoot, subscribeState, setStateValue } from './state.js';
+
+function freezeValue(value) {
+  if (!value || typeof value !== 'object') return value;
+  try {
+    return Object.freeze(value);
+  } catch {
+    return value;
+  }
+}
+
+function normalizeTargets(targets) {
+  if (targets.length === 1 && Array.isArray(targets[0]) && !isObservableArray(targets[0])) return targets[0];
+  return targets;
+}
+
+function readTargetValue(target) {
+  if (isState(target) || isStatePath(target)) return readState(target);
+  if (isSignal(target)) return readSignal(target);
+  if (isObservableArray(target)) return target;
+  return undefined;
+}
+
+function subscribeAfterTarget(target, fn) {
+  if (isState(target) || isStatePath(target)) {
+    return subscribeState(target, (next, prev) => fn(freezeValue(next), freezeValue(prev), null));
+  }
+  if (isSignal(target)) {
+    return subscribeSignal(target, (next, prev) => fn(freezeValue(next), freezeValue(prev), null));
+  }
+  if (isObservableArray(target)) {
+    return target.after().any((patch, ctx) => {
+      const prevLen = ctx?.prevLength ?? target.length;
+      const nextLen = ctx?.nextLength ?? target.length;
+      const { next, prev } = makeArraySnapshots(target, patch, ctx, 'after');
+      fn(next, prev, { patch, prevLength: prevLen, nextLength: nextLen, array: target });
+    });
+  }
+  throw new Error('after(x).change: unsupported target');
+}
+
+function subscribeBeforeTarget(target, fn) {
+  if (isState(target) || isStatePath(target)) {
+    return target.before?.((prevRoot, nextRoot) => {
+      const prev = readStateFromRoot(target, prevRoot);
+      const next = nextRoot !== undefined ? readStateFromRoot(target, nextRoot) : prev;
+      if (next === prev) return true;
+      const res = fn(freezeValue(next), freezeValue(prev), null);
+      return res !== false;
+    });
+  }
+  if (isSignal(target)) {
+    return target.before((prev, next) => fn(freezeValue(next), freezeValue(prev), null));
+  }
+  if (isObservableArray(target)) {
+    return target.before().any((patch, ctx) => {
+      const prevLen = target.length;
+      const nextLen = ctx?.nextLength ?? prevLen;
+      const { next, prev } = makeArraySnapshots(target, patch, ctx, 'before');
+      const res = fn(next, prev, { patch, prevLength: prevLen, nextLength: nextLen, array: target });
+      return res !== false;
+    });
+  }
+  throw new Error('before(x).change: unsupported target');
+}
+
+function createComputedState() {
+  const rootSignal = signal(undefined);
+  const adapter = {
+    kind: 'computed',
+    get: () => readSignal(rootSignal),
+    set: () => {
+      throw new Error('Computed values are read-only.');
+    },
+    subscribe: (fn) => subscribeSignal(rootSignal, fn),
+    before: undefined,
+  };
+  const proxy = createStateFromAdapter(adapter);
+  const setValue = (next) => setSignal(rootSignal, next, true);
+  return { value: proxy, setValue };
+}
+
+function applyPatch(baseArray, patch, ctx) {
+  if (!Array.isArray(baseArray)) return [];
+  const out = baseArray.slice();
+  if (!patch || !patch.type) return out;
+  if (patch.type === 'insert') {
+    out.splice(patch.index, 0, ...(patch.items || []));
+    return out;
+  }
+  if (patch.type === 'remove') {
+    out.splice(patch.index, patch.count || 0);
+    return out;
+  }
+  if (patch.type === 'set') {
+    out[patch.index] = patch.value;
+    return out;
+  }
+  if (patch.type === 'reset') {
+    return Array.isArray(patch.items) ? patch.items.slice() : [];
+  }
+  return out;
+}
+
+function applyInversePatch(baseArray, patch, ctx) {
+  if (!Array.isArray(baseArray)) return [];
+  const out = baseArray.slice();
+  if (!patch || !patch.type) return out;
+  if (patch.type === 'insert') {
+    out.splice(patch.index, (patch.items || []).length);
+    return out;
+  }
+  if (patch.type === 'remove') {
+    const items = patch.items || [];
+    out.splice(patch.index, 0, ...items);
+    return out;
+  }
+  if (patch.type === 'set') {
+    out[patch.index] = patch.prev;
+    return out;
+  }
+  if (patch.type === 'reset') {
+    return Array.isArray(patch.prevItems) ? patch.prevItems.slice() : [];
+  }
+  return out;
+}
+
+function makeArraySnapshots(target, patch, ctx, phase) {
+  const cached = { prev: null, next: null };
+  const prev = () => {
+    if (cached.prev) return cached.prev;
+    cached.prev = phase === 'after' ? applyInversePatch(target, patch, ctx) : target.slice();
+    return cached.prev;
+  };
+  const next = () => {
+    if (cached.next) return cached.next;
+    cached.next = phase === 'after' ? target.slice() : applyPatch(target, patch, ctx);
+    return cached.next;
+  };
+  return { prev, next };
+}
+
+function valueForTarget(target) {
+  if (isObservableArray(target)) return () => target.slice();
+  return readTargetValue(target);
+}
+
+export function after(...targets) {
+  const list = normalizeTargets(targets);
+  if (!list.length) {
+    throw new Error('after(...targets): at least one target is required');
+  }
+  return {
+    change(fn) {
+      const unsubs = list.map((target) =>
+        subscribeAfterTarget(target, (next, prev, ctx) => fn(next, prev, ctx))
+      );
+      return () => {
+        for (const unsub of unsubs) {
+          if (typeof unsub === 'function') unsub();
+        }
+      };
+    },
+    compute(fn, options = {}) {
+      const { value, setValue } = createComputedState();
+      let runId = 0;
+      let lastHash = undefined;
+      let lastValue = undefined;
+      let scheduled = null;
+      let disposed = false;
+      let lastValues = list.map(valueForTarget);
+      const equals = typeof options.equals === 'function' ? options.equals : Object.is;
+      const handleError = (err) => {
+        if (typeof options.onError === 'function') {
+          options.onError(err);
+          return;
+        }
+        if (typeof console !== 'undefined' && typeof console.error === 'function') {
+          console.error(err);
+        }
+      };
+      const computeNow = (nextValues, prevValues, ctxs) => {
+        if (disposed) return;
+        const current = ++runId;
+        const args = nextValues;
+        if (typeof options.hash === 'function') {
+          let nextHash = undefined;
+          try {
+            nextHash = list.length === 1 ? options.hash(args[0], prevValues[0], ctxs[0]) : options.hash(args, prevValues, ctxs);
+          } catch (err) {
+            handleError(err);
+            return;
+          }
+          if (nextHash === lastHash) return;
+          lastHash = nextHash;
+        }
+        let result;
+        try {
+          result = list.length === 1 ? fn(args[0], prevValues[0], ctxs[0]) : fn(args, prevValues, ctxs);
+        } catch (err) {
+          handleError(err);
+          return;
+        }
+        if (result && typeof result.then === 'function') {
+          result
+            .then((next) => {
+              if (current !== runId || disposed) return;
+              if (equals(lastValue, next)) return;
+              lastValue = next;
+              setValue(next);
+            })
+            .catch((err) => handleError(err));
+          return;
+        }
+        if (equals(lastValue, result)) return;
+        lastValue = result;
+        setValue(result);
+      };
+      const scheduleRun = (nextValues, prevValues, ctxs) => {
+        if (disposed) return;
+        const delay = Math.max(0, options.debounce ?? 0);
+        if (!delay) {
+          computeNow(nextValues, prevValues, ctxs);
+          return;
+        }
+        if (scheduled) clearTimeout(scheduled);
+        scheduled = setTimeout(() => {
+          scheduled = null;
+          computeNow(nextValues, prevValues, ctxs);
+        }, delay);
+      };
+      scheduleRun(lastValues, lastValues, list.map(() => null));
+      const unsubs = list.map((target, index) =>
+        subscribeAfterTarget(target, (next, prev, ctx) => {
+          const nextValues = list.map(valueForTarget);
+          nextValues[index] = next;
+          const prevValues = lastValues.slice();
+          prevValues[index] = prev;
+          lastValues = nextValues;
+          const ctxs = list.map(() => null);
+          ctxs[index] = ctx;
+          scheduleRun(nextValues, prevValues, ctxs);
+        })
+      );
+      Object.defineProperty(value, 'dispose', {
+        value: () => {
+          disposed = true;
+          runId++;
+          if (scheduled) clearTimeout(scheduled);
+          for (const unsub of unsubs) {
+            if (typeof unsub === 'function') unsub();
+          }
+        },
+        enumerable: false,
+      });
+      return value;
+    },
+  };
+}
+
+export function before(...targets) {
+  const list = normalizeTargets(targets);
+  if (!list.length) {
+    throw new Error('before(...targets): at least one target is required');
+  }
+  return {
+    change(fn) {
+      const unsubs = list.map((target) =>
+        subscribeBeforeTarget(target, (next, prev, ctx) => fn(next, prev, ctx))
+      );
+      return () => {
+        for (const unsub of unsubs) {
+          if (typeof unsub === 'function') unsub();
+        }
+      };
+    },
+    compute(fn, options = {}) {
+      const { value, setValue } = createComputedState();
+      let runId = 0;
+      let lastHash = undefined;
+      let lastValue = undefined;
+      let scheduled = null;
+      let disposed = false;
+      const equals = typeof options.equals === 'function' ? options.equals : Object.is;
+      const handleError = (err) => {
+        if (typeof options.onError === 'function') {
+          options.onError(err);
+          return;
+        }
+        if (typeof console !== 'undefined' && typeof console.error === 'function') {
+          console.error(err);
+        }
+      };
+      const computeNow = (nextValues, prevValues, ctxs) => {
+        if (disposed) return;
+        const current = ++runId;
+        if (typeof options.hash === 'function') {
+          let nextHash = undefined;
+          try {
+            nextHash =
+              list.length === 1
+                ? options.hash(nextValues[0], prevValues[0], ctxs[0])
+                : options.hash(nextValues, prevValues, ctxs);
+          } catch (err) {
+            handleError(err);
+            return;
+          }
+          if (nextHash === lastHash) return;
+          lastHash = nextHash;
+        }
+        let result;
+        try {
+          result =
+            list.length === 1
+              ? fn(nextValues[0], prevValues[0], ctxs[0])
+              : fn(nextValues, prevValues, ctxs);
+        } catch (err) {
+          handleError(err);
+          return;
+        }
+        if (result && typeof result.then === 'function') {
+          result
+            .then((next) => {
+              if (current !== runId || disposed) return;
+              if (equals(lastValue, next)) return;
+              lastValue = next;
+              setValue(next);
+            })
+            .catch((err) => handleError(err));
+          return;
+        }
+        if (equals(lastValue, result)) return;
+        lastValue = result;
+        setValue(result);
+      };
+      const scheduleRun = (nextValues, prevValues, ctxs) => {
+        if (disposed) return;
+        const delay = Math.max(0, options.debounce ?? 0);
+        if (!delay) {
+          computeNow(nextValues, prevValues, ctxs);
+          return;
+        }
+        if (scheduled) clearTimeout(scheduled);
+        scheduled = setTimeout(() => {
+          scheduled = null;
+          computeNow(nextValues, prevValues, ctxs);
+        }, delay);
+      };
+      const unsubs = list.map((target, index) =>
+        subscribeBeforeTarget(target, (next, prev, ctx) => {
+          const currentValues = list.map(valueForTarget);
+          const nextValues = currentValues.slice();
+          nextValues[index] = next;
+          const prevValues = currentValues.slice();
+          prevValues[index] = prev;
+          const ctxs = list.map(() => null);
+          ctxs[index] = ctx;
+          scheduleRun(nextValues, prevValues, ctxs);
+        })
+      );
+      Object.defineProperty(value, 'dispose', {
+        value: () => {
+          disposed = true;
+          runId++;
+          if (scheduled) clearTimeout(scheduled);
+          for (const unsub of unsubs) {
+            if (typeof unsub === 'function') unsub();
+          }
+        },
+        enumerable: false,
+      });
+      return value;
+    },
+  };
+}
+
+export function set(target, value) {
+  if (isState(target) || isStatePath(target)) {
+    setStateValue(target, value);
+    return;
+  }
+  if (isSignal(target)) {
+    setSignal(target, value);
+    return;
+  }
+  if (isObservableArray(target)) {
+    if (typeof target.reset !== 'function') {
+      throw new Error('set(array, value): observableArray must implement reset');
+    }
+    target.reset(value);
+    return;
+  }
+  throw new Error('set(target, value): unsupported target');
+}
+
+function resolveValue(value) {
+  return typeof value === 'function' ? value() : value;
+}
+
+export function subscribe(target, selector, listener, equalityFn) {
+  if (typeof selector !== 'function') {
+    throw new Error('subscribe(target, selector, listener?): selector must be a function');
+  }
+  if (listener === undefined) {
+    return after(target).compute((next) => selector(resolveValue(next)));
+  }
+  if (typeof listener !== 'function') {
+    throw new Error('subscribe(target, selector, listener): listener must be a function');
+  }
+  const eq = typeof equalityFn === 'function' ? equalityFn : Object.is;
+  let prevSelected = selector(resolveValue(readTargetValue(target)));
+  return after(target).change((next) => {
+    const nextSelected = selector(resolveValue(next));
+    if (eq(prevSelected, nextSelected)) return;
+    const p = prevSelected;
+    prevSelected = nextSelected;
+    listener(nextSelected, p);
+  });
+}

package/src/core/reactivity/persist.js

@@ -0,0 +1,180 @@
+import { isState, isStatePath, readState, setStateValue } from './state.js';
+import { after } from './observe.js';
+
+function isStoreLike(value) {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    typeof value.getState === 'function' &&
+    typeof value.setState === 'function' &&
+    typeof value.subscribe === 'function'
+  );
+}
+
+function isStateLike(value) {
+  return isState(value) || isStatePath(value);
+}
+
+function getAtPath(obj, path) {
+  let cur = obj;
+  for (const key of path) {
+    if (!cur) return undefined;
+    cur = cur[key];
+  }
+  return cur;
+}
+
+function setAtPath(obj, path, value) {
+  if (!path.length) return value;
+  const root = Array.isArray(obj) ? obj.slice() : { ...(obj || {}) };
+  let cur = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    const next = cur[key];
+    const cloned = Array.isArray(next) ? next.slice() : { ...(next || {}) };
+    cur[key] = cloned;
+    cur = cloned;
+  }
+  cur[path[path.length - 1]] = value;
+  return root;
+}
+
+function normalizePaths(paths) {
+  if (!paths || !paths.length) return null;
+  return paths.map((p) => String(p).split('.').map((s) => s.trim()).filter(Boolean));
+}
+
+function pickPaths(value, pathList) {
+  if (!pathList) return value;
+  let next = value;
+  for (const path of pathList) {
+    const v = getAtPath(value, path);
+    next = setAtPath(next, path, v);
+  }
+  return next;
+}
+
+function defaultSerialize(value) {
+  return JSON.stringify(value, (_key, v) => {
+    if (typeof v === 'function') return undefined;
+    if (typeof v === 'symbol') return undefined;
+    return v;
+  });
+}
+
+function defaultDeserialize(text) {
+  return JSON.parse(text);
+}
+
+function readSnapshot(target, pathList) {
+  if (isStateLike(target)) return pickPaths(readState(target), pathList);
+  if (isStoreLike(target)) return pickPaths(target.getState(), pathList);
+  throw new Error('persist(target): unsupported target');
+}
+
+function applySnapshot(target, snapshot) {
+  if (isStateLike(target)) {
+    setStateValue(target, snapshot);
+    return;
+  }
+  if (isStoreLike(target)) {
+    target.setState(snapshot, true);
+    return;
+  }
+  throw new Error('persist(target): unsupported target');
+}
+
+function subscribeChanges(target, fn) {
+  if (isStateLike(target)) return after(target).change(fn);
+  if (isStoreLike(target)) return target.subscribe(fn);
+  throw new Error('persist(target): unsupported target');
+}
+
+function safeStorage(storage) {
+  try {
+    if (!storage || typeof storage.getItem !== 'function') return null;
+    return storage;
+  } catch {
+    return null;
+  }
+}
+
+export function persist(target, options = {}) {
+  const key = options.key;
+  if (!key) throw new Error('persist(target): options.key is required');
+
+  const storage = safeStorage(options.storage ?? (typeof localStorage !== 'undefined' ? localStorage : null));
+  const pathList = normalizePaths(options.paths);
+  const serialize = options.serialize || defaultSerialize;
+  const deserialize = options.deserialize || defaultDeserialize;
+  const version = options.version ?? 1;
+  const migrate = options.migrate || null;
+  const reconcile = options.reconcile || null;
+  const throttleMs = Math.max(0, options.throttle ?? 0);
+
+  if (storage) {
+    const raw = storage.getItem(key);
+    if (raw != null) {
+      let payload = null;
+      try {
+        payload = deserialize(raw);
+      } catch {
+        payload = null;
+      }
+      if (payload != null) {
+        let data = payload;
+        let v = null;
+        if (payload && typeof payload === 'object' && 'data' in payload && 'v' in payload) {
+          data = payload.data;
+          v = payload.v;
+        }
+        if (v != null && v !== version && typeof migrate === 'function') {
+          data = migrate(data, v);
+        }
+        if (typeof reconcile === 'function') {
+          data = reconcile(data);
+        }
+        if (data !== undefined) {
+          applySnapshot(target, data);
+        }
+      }
+    }
+  }
+
+  let scheduled = false;
+  let lastTimer = null;
+
+  const write = () => {
+    scheduled = false;
+    const snapshot = readSnapshot(target, pathList);
+    const payload = { v: version, data: snapshot };
+    try {
+      storage?.setItem?.(key, serialize(payload));
+    } catch {
+      return;
+    }
+  };
+
+  const scheduleWrite = () => {
+    if (!storage) return;
+    if (throttleMs <= 0) {
+      write();
+      return;
+    }
+    if (scheduled) return;
+    scheduled = true;
+    lastTimer = setTimeout(write, throttleMs);
+  };
+
+  const unsubscribe = subscribeChanges(target, scheduleWrite);
+
+  Object.defineProperty(target, 'persistDispose', {
+    value: () => {
+      if (lastTimer) clearTimeout(lastTimer);
+      if (typeof unsubscribe === 'function') unsubscribe();
+    },
+    enumerable: false,
+  });
+
+  return target;
+}

package/src/core/reactivity/resolve.js

@@ -0,0 +1,8 @@
+import { isSignal, readSignal } from './signal.js';
+import { isState, isStatePath, readState } from './state.js';
+
+export function resolve(value) {
+  if (isSignal(value)) return readSignal(value);
+  if (isState(value) || isStatePath(value)) return readState(value);
+  return value;
+}

package/src/core/reactivity/signal.js

@@ -0,0 +1,97 @@
+const SIGNAL = Symbol('zb.signal');
+const SIGNAL_MAP = Symbol('zb.signal.map');
+
+function isObject(value) {
+  return value !== null && typeof value === 'object';
+}
+
+export function signal(initial) {
+  const state = {
+    [SIGNAL]: true,
+    value: initial,
+    subs: new Set(),
+    before: new Set(),
+  };
+
+  const notify = (prev) => {
+    for (const fn of state.subs) fn(state.value, prev);
+  };
+
+  const api = {
+    get() {
+      return state.value;
+    },
+    set(next, force = false) {
+      const prev = state.value;
+      if (!force && prev === next) return true;
+      for (const fn of state.before) {
+        const res = fn(prev, next);
+        if (res === false) return false;
+      }
+      state.value = next;
+      notify(prev);
+      return true;
+    },
+    subscribe(fn) {
+      state.subs.add(fn);
+      return () => state.subs.delete(fn);
+    },
+    before(fn) {
+      state.before.add(fn);
+      return () => state.before.delete(fn);
+    },
+  };
+
+  const proxy = new Proxy(api, {
+    get(_target, prop) {
+      if (prop === SIGNAL) return true;
+      if (prop === 'value') return state.value;
+      if (prop === 'get') return api.get;
+      if (prop === 'set') return api.set;
+      if (prop === 'subscribe') return api.subscribe;
+      if (prop === 'before') return api.before;
+      if (prop === Symbol.toPrimitive) return () => state.value;
+      if (prop === 'valueOf') return () => state.value;
+      if (prop === 'toString') return () => String(state.value);
+
+      const value = state.value;
+      if (Array.isArray(value) && prop === 'map') {
+        return (fn) => {
+          const out = value.map(fn);
+          Object.defineProperty(out, SIGNAL_MAP, { value: { signal: proxy, mapFn: fn } });
+          return out;
+        };
+      }
+
+      if (isObject(value)) {
+        const v = value[prop];
+        if (typeof v === 'function') return v.bind(value);
+        return v;
+      }
+      return undefined;
+    },
+  });
+
+  return proxy;
+}
+
+export function isSignal(value) {
+  return !!value && value[SIGNAL] === true;
+}
+
+export function subscribeSignal(sig, fn) {
+  return sig?.subscribe?.(fn);
+}
+
+export function readSignal(sig) {
+  return sig?.get?.();
+}
+
+export function setSignal(sig, next, force = false) {
+  return sig?.set?.(next, force);
+}
+
+export function getMappedArrayMeta(value) {
+  if (!Array.isArray(value)) return null;
+  return value[SIGNAL_MAP] || null;
+}