@retreon/cells 0.1.0 → 0.1.1-2025-06-19.ef01c21

package/README.md

@@ -125,19 +125,6 @@ batch((swap) => {
 });
 ```
 
-### `watch(signal, handler)`
-
-Subscribes to changes in a signal. Returns a cleanup function. For formulas, watches all transitive dependencies.
-
-```ts
-const dispose = watch(total, () => {
-  console.log('Total updated:', get(total));
-});
-
-// Later: stop watching
-dispose();
-```
-
 ### `untracked(fn)`
 
 Executes a function without tracking any signal dependencies. When called inside a formula computation, any signals read within the untracked function will not be registered as dependencies.
@@ -164,3 +151,29 @@ const visited = visitDependencies(receipt, (sig) => {
 });
 // Logs: "Found formula", "Found cell", "Found cell", "Found source"
 ```
+
+> [!WARNING]
+> This API does not evaluate formulas. If the formula hasn't been re-evaluated since dependencies changed, this API may return stale data.
+
+### `watch(signal, handler)`
+
+Subscribes to changes in a signal. Returns a cleanup and renewal function. For formulas, watches all transitive dependencies.
+
+```ts
+const [dispose, renew] = watch(total, () => {
+  console.log('Total updated:', renew());
+});
+
+// Later: stop watching
+dispose();
+```
+
+This is a low-level function that prioritizes power over simplicity. It's easy to misuse.
+
+- **dispose:** Stops watching for changes.
+- **renew:** Re-evaluates the expression and watches the new dependency set.
+
+> [!WARNING]
+> Careful attention is required when watching formulas. `watch()` does not invoke formulas automatically unless you call `renew()`. This means `watch()` may be watching stale dependencies.
+>
+> It's recommended to call `renew()` inside the watch handler (re-evaluating any formulas) to ensure you're always observing the correct dependencies.

package/dist/cells.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});let f=0;function d(){return++f}const y=(t,e)=>{t.w.add(e)},u=(t,e)=>{t.w.delete(e)},W=t=>({t:"c",c:t,v:f,w:new Set});let c=null,o=!1;const b=t=>{c&&F(c,t)},k=(t,e)=>{const n=c;c=t;try{return e()}finally{c=n}},C=t=>{const e=o;o=!0;try{return t()}finally{o=e}},D=t=>{const e=c;c=null;try{return t()}finally{c=e}},E=t=>({t:"f",f:t,c:void 0,v:-1,d:new Map,x:!1}),F=(t,e)=>{t.d.set(e,e.v)},V=t=>{if(t.x)return!0;if(t.v===f)return!1;for(const[e,n]of t.d)if(e.t==="s"&&e.x||e.v!==n)return!0;return t.v===-1},v=t=>{if(!V(t))return t.c;t.d.clear(),t.x=!1;const e=k(t,t.f);for(const n of t.d.keys())if(n.t==="s"&&n.x||n.t==="f"&&n.x){t.x=!0;break}return t.c=e,t.v=f,e},z=t=>(t.x&&o&&h(t),t.x?(0,t.r)():(t.p||(t.c=t.r(),t.p=!0),t.c)),h=t=>{t.x&&t.s&&(t.x=!1,t.d=t.s(()=>{t.c=void 0,t.p=!1,t.v=d();for(const e of t.w)e.c()}))},M=(t,e)=>{t.w.add(e),t.w.size===1&&h(t)},x=(t,e)=>{t.w.delete(e),t.w.size===0&&(t.x=!0,t.d&&(t.d(),t.d=void 0),t.c=void 0,t.p=!1)},N=(t,e)=>({t:"s",r:t,s:e,c:void 0,v:f,w:new Set,x:!0,p:!1,d:void 0}),T=t=>(b(t),t.t==="c"?t.c:t.t==="f"?v(t):z(t));function w(t,e){const n=new Set;function r(i){if(!n.has(i)&&(n.add(i),e==null||e(i),i.t==="f")){v(i);for(const[p]of i.d)r(p)}}return r(t),n}const j=(t,e)=>({s:t,c:e,d:new Set}),S=(t,e=!0)=>{const n=C(()=>w(t.s));n.forEach(r=>{t.d.has(r)||(r.t==="c"?y(r,t):r.t==="s"&&M(r,t))}),t.d.forEach(r=>{n.has(r)||(r.t==="c"?u(r,t):r.t==="s"&&x(r,t))}),t.d=n,e&&(0,t.c)()},B=t=>{t.d.forEach(e=>{e.t==="c"?u(e,t):e.t==="s"&&x(e,t)}),t.d.clear()},I=(t,e)=>{const n=j(t,e);return S(n,!1),()=>B(n)};let s=!1;const a=new Set;function O(t){if(s){t(l);return}s=!0,a.clear();try{t(l);for(const e of a)S(e)}finally{s=!1,a.clear()}}function l(t,e){if(!s)throw new Error("Cell mutations must occur within a batch()");if(t.c!==e){t.c=e,t.v=d();for(const n of t.w)a.add(n)}}exports.batch=O;exports.cell=W;exports.formula=E;exports.get=T;exports.source=N;exports.untracked=D;exports.visitDependencies=w;exports.watch=I;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});let o=0;function h(){return++o}const b=(t,e)=>{t.w.add(e)},w=(t,e)=>{t.w.delete(e)},k=t=>({t:"c",c:t,v:o,w:new Set});let c=null,i=!1;const C=t=>{c&&V(c,t)},D=(t,e)=>{const n=c;c=t;try{return e()}finally{c=n}},x=t=>{const e=i;i=!0;try{return t()}finally{i=e}},E=t=>{const e=c;c=null;try{return t()}finally{c=e}},F=t=>({t:"f",f:t,c:void 0,v:-1,d:new Map,x:!1}),V=(t,e)=>{t.d.set(e,e.v)},T=t=>{if(t.x)return!0;if(t.v===o)return!1;for(const[e,n]of t.d)if(e.t==="s"&&e.x||e.v!==n)return!0;return t.v===-1},z=t=>{if(!T(t))return t.c;t.d.clear(),t.x=!1;const e=D(t,t.f);for(const n of t.d.keys())if(n.t==="s"&&n.x||n.t==="f"&&n.x){t.x=!0;break}return t.c=e,t.v=o,e},d={};function S(t,e){const n=new Set;function r(s){if(!n.has(s)&&(n.add(s),e==null||e(s),s.t==="f"))for(const[u]of s.d)r(u)}return r(t),n}const y=t=>(C(t),t.t==="c"?t.c:t.t==="f"?z(t):A(t)),M=(t,e)=>({s:t,c:e,d:new Set}),l=(t,e=!0)=>{const n=x(()=>S(t.s));n.forEach(r=>{t.d.has(r)||(r.t==="c"?b(r,t):r.t==="s"&&B(r,t))}),t.d.forEach(r=>{n.has(r)||(r.t==="c"?w(r,t):r.t==="s"&&p(r,t))}),t.d=n,e&&(0,t.c)()},N=t=>{t.d.forEach(e=>{e.t==="c"?w(e,t):e.t==="s"&&p(e,t)}),t.d.clear()},j=(t,e)=>{const n=M(t,e);return l(n,!1),[()=>N(n),()=>{const u=x(()=>y(t));return l(n,!1),u}]},A=t=>(t.x&&i&&W(t),t.x?(0,t.r)():(t.c===d&&(t.c=t.r()),t.c)),W=t=>{t.x&&t.s&&(t.x=!1,t.d=t.s(()=>{t.c=d,t.v=h();for(const e of t.w)l(e)}))},B=(t,e)=>{t.w.add(e),t.w.size===1&&W(t)},p=(t,e)=>{t.w.delete(e),t.w.size===0&&(t.x=!0,t.d&&(t.d(),t.d=void 0),t.c=d)},I=(t,e)=>({t:"s",r:t,s:e,c:d,v:o,w:new Set,x:!0,d:void 0});let f=!1;const a=new Set;function L(t){if(f)return t(v);f=!0,a.clear();try{const e=t(v);for(const n of a)l(n);return e}finally{f=!1,a.clear()}}function v(t,e){if(!f)throw new Error("Cell mutations must occur within a batch()");if(t.c!==e){t.c=e,t.v=h();for(const n of t.w)a.add(n)}}exports.batch=L;exports.cell=k;exports.formula=F;exports.get=y;exports.source=I;exports.untracked=E;exports.visitDependencies=S;exports.watch=j;

package/dist/cells.d.ts

@@ -9,19 +9,22 @@ declare type BaseSignal = Signal<unknown>;
  * - No intermediate inconsistent states are observable
  *
  * @param fn - Function that receives a swap function for updating cells
+ * @returns The return value of the provided function
  *
  * @example
  * ```typescript
  * const x = cell(1);
  * const y = cell(2);
  *
- * batch((swap) => {
+ * const result = batch((swap) => {
  *   swap(x, 10);
  *   swap(y, 20);
+ *   return 'updated';
  * });
+ * // result === 'updated'
  * ```
  */
-export declare function batch(fn: (swap: SwapFunction) => void): void;
+export declare function batch<T>(fn: (swap: SwapFunction) => T): T;
 
 export declare interface Cell<T> {
     /** Type */
@@ -130,9 +133,7 @@ export declare interface Source<T> {
     /** Disposer for the subscription */
     d?: Disposer;
     /** Cached value */
-    c: T | undefined;
-    /** Whether the cache is primed */
-    p: boolean;
+    c: T | typeof STALE;
     /** Volatile flag */
     x: boolean;
     /** Version */
@@ -171,6 +172,9 @@ export declare interface Source<T> {
  */
 export declare const source: <T>(read: () => T, subscribe?: (onChange: () => void) => () => void) => Source<T>;
 
+/** Sentinel value indicating cache is empty. */
+declare const STALE: {};
+
 export declare type SwapFunction = <T>(cell: Cell<T>, newValue: T) => void;
 
 /**
@@ -227,14 +231,14 @@ export declare function visitDependencies<T>(signal: Signal<T>, visitor?: (signa
  *
  * @param signal - The signal to watch
  * @param onChange - Function to call when the signal changes
- * @returns A disposer function that stops watching when called
+ * @returns A tuple of [dispose, renew] functions
  *
  * @example
  * ```typescript
  * const count = cell(0);
  *
- * const dispose = watch(count, () => {
- *   console.log('Count changed to:', get(count));
+ * const [dispose, renew] = watch(count, () => {
+ *   console.log('Count changed to:', renew());
  * });
  *
  * batch((swap) => {
@@ -244,7 +248,7 @@ export declare function visitDependencies<T>(signal: Signal<T>, visitor?: (signa
  * dispose(); // Stop watching
  * ```
  */
-export declare const watch: <T>(signal: Signal<T>, onChange: ChangeHandler) => Disposer;
+export declare const watch: <T>(signal: Signal<T>, onChange: ChangeHandler) => [dispose: Disposer, renew: () => T];
 
 declare interface Watcher<T> {
     /** Signal */

package/dist/cells.js

@@ -1,21 +1,21 @@
-let f = 0;
-function l() {
-  return ++f;
+let o = 0;
+function x() {
+  return ++o;
 }
-const S = (t, e) => {
+const W = (t, e) => {
   t.w.add(e);
-}, u = (t, e) => {
+}, h = (t, e) => {
   t.w.delete(e);
-}, N = (t) => ({
+}, A = (t) => ({
   t: "c",
   c: t,
-  v: f,
+  v: o,
   w: /* @__PURE__ */ new Set()
 });
-let c = null, o = !1;
-const y = (t) => {
+let c = null, i = !1;
+const p = (t) => {
   c && k(c, t);
-}, W = (t, e) => {
+}, C = (t, e) => {
   const n = c;
   c = t;
   try {
@@ -23,13 +23,13 @@ const y = (t) => {
   } finally {
     c = n;
   }
-}, C = (t) => {
-  const e = o;
-  o = !0;
+}, w = (t) => {
+  const e = i;
+  i = !0;
   try {
     return t();
   } finally {
-    o = e;
+    i = e;
   }
 }, B = (t) => {
   const e = c;
@@ -51,108 +51,107 @@ const y = (t) => {
 }, D = (t) => {
   if (t.x)
     return !0;
-  if (t.v === f)
+  if (t.v === o)
     return !1;
   for (const [e, n] of t.d)
     if (e.t === "s" && e.x || e.v !== n)
       return !0;
   return t.v === -1;
-}, v = (t) => {
+}, E = (t) => {
   if (!D(t))
     return t.c;
   t.d.clear(), t.x = !1;
-  const e = W(t, t.f);
+  const e = C(t, t.f);
   for (const n of t.d.keys())
     if (n.t === "s" && n.x || n.t === "f" && n.x) {
       t.x = !0;
       break;
     }
-  return t.c = e, t.v = f, e;
-}, b = (t) => (t.x && o && x(t), t.x ? (0, t.r)() : (t.p || (t.c = t.r(), t.p = !0), t.c)), x = (t) => {
-  t.x && t.s && (t.x = !1, t.d = t.s(() => {
-    t.c = void 0, t.p = !1, t.v = l();
-    for (const e of t.w)
-      e.c();
-  }));
-}, E = (t, e) => {
-  t.w.add(e), t.w.size === 1 && x(t);
-}, h = (t, e) => {
-  t.w.delete(e), t.w.size === 0 && (t.x = !0, t.d && (t.d(), t.d = void 0), t.c = void 0, t.p = !1);
-}, M = (t, e) => ({
-  t: "s",
-  r: t,
-  s: e,
-  c: void 0,
-  v: f,
-  w: /* @__PURE__ */ new Set(),
-  x: !0,
-  p: !1,
-  d: void 0
-}), T = (t) => (y(t), t.t === "c" ? t.c : t.t === "f" ? v(t) : b(t));
-function F(t, e) {
+  return t.c = e, t.v = o, e;
+}, l = {};
+function b(t, e) {
   const n = /* @__PURE__ */ new Set();
-  function r(i) {
-    if (!n.has(i) && (n.add(i), e == null || e(i), i.t === "f")) {
-      v(i);
-      for (const [p] of i.d)
-        r(p);
-    }
+  function r(s) {
+    if (!n.has(s) && (n.add(s), e == null || e(s), s.t === "f"))
+      for (const [u] of s.d)
+        r(u);
   }
   return r(t), n;
 }
-const V = (t, e) => ({
+const F = (t) => (p(t), t.t === "c" ? t.c : t.t === "f" ? E(t) : N(t)), V = (t, e) => ({
   s: t,
   c: e,
   d: /* @__PURE__ */ new Set()
-}), w = (t, e = !0) => {
-  const n = C(
-    () => F(t.s)
+}), d = (t, e = !0) => {
+  const n = w(
+    () => b(t.s)
   );
   n.forEach((r) => {
-    t.d.has(r) || (r.t === "c" ? S(r, t) : r.t === "s" && E(r, t));
+    t.d.has(r) || (r.t === "c" ? W(r, t) : r.t === "s" && T(r, t));
   }), t.d.forEach((r) => {
-    n.has(r) || (r.t === "c" ? u(r, t) : r.t === "s" && h(r, t));
+    n.has(r) || (r.t === "c" ? h(r, t) : r.t === "s" && y(r, t));
   }), t.d = n, e && (0, t.c)();
 }, z = (t) => {
   t.d.forEach((e) => {
-    e.t === "c" ? u(e, t) : e.t === "s" && h(e, t);
+    e.t === "c" ? h(e, t) : e.t === "s" && y(e, t);
   }), t.d.clear();
-}, j = (t, e) => {
+}, L = (t, e) => {
   const n = V(t, e);
-  return w(n, !1), () => z(n);
-};
-let s = !1;
+  return d(n, !1), [() => z(n), () => {
+    const u = w(() => F(t));
+    return d(n, !1), u;
+  }];
+}, N = (t) => (t.x && i && S(t), t.x ? (0, t.r)() : (t.c === l && (t.c = t.r()), t.c)), S = (t) => {
+  t.x && t.s && (t.x = !1, t.d = t.s(() => {
+    t.c = l, t.v = x();
+    for (const e of t.w)
+      d(e);
+  }));
+}, T = (t, e) => {
+  t.w.add(e), t.w.size === 1 && S(t);
+}, y = (t, e) => {
+  t.w.delete(e), t.w.size === 0 && (t.x = !0, t.d && (t.d(), t.d = void 0), t.c = l);
+}, M = (t, e) => ({
+  t: "s",
+  r: t,
+  s: e,
+  c: l,
+  v: o,
+  w: /* @__PURE__ */ new Set(),
+  x: !0,
+  d: void 0
+});
+let f = !1;
 const a = /* @__PURE__ */ new Set();
-function q(t) {
-  if (s) {
-    t(d);
-    return;
-  }
-  s = !0, a.clear();
+function j(t) {
+  if (f)
+    return t(v);
+  f = !0, a.clear();
   try {
-    t(d);
-    for (const e of a)
-      w(e);
+    const e = t(v);
+    for (const n of a)
+      d(n);
+    return e;
   } finally {
-    s = !1, a.clear();
+    f = !1, a.clear();
   }
 }
-function d(t, e) {
-  if (!s)
+function v(t, e) {
+  if (!f)
     throw new Error("Cell mutations must occur within a batch()");
   if (t.c !== e) {
-    t.c = e, t.v = l();
+    t.c = e, t.v = x();
     for (const n of t.w)
       a.add(n);
   }
 }
 export {
-  q as batch,
-  N as cell,
+  j as batch,
+  A as cell,
   I as formula,
-  T as get,
+  F as get,
   M as source,
   B as untracked,
-  F as visitDependencies,
-  j as watch
+  b as visitDependencies,
+  L as watch
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@retreon/cells",
-  "version": "0.1.0",
+  "version": "0.1.1-2025-06-19.ef01c21",
   "description": "A minimal spreadsheet engine",
   "author": "Jesse Gibson <JesseTheGibson@gmail.com>",
   "license": "MIT",