@solidjs/signals 0.11.0 → 0.11.2

package/README.md

@@ -1,5 +1,255 @@
 # @solidjs/signals
 
-Standalone Reactive implementation to serve as the basis of future (post 1.x) versions of SolidJS. This package aims to be core for Signals library made with rendering in mind so it may have more features and opinions than common Signals libraries, but are still necessary core to accomplish the type of capabilities we intend.
+The reactive core that powers [SolidJS 2.0](https://github.com/solidjs/solid). This is a standalone signals library designed for rendering — it includes first-class support for async, transitions, optimistic updates, and deeply reactive stores that go beyond what general-purpose signals libraries offer.
 
-This is not ready for production and should be considered pre-alpha. This package is completely experimental and every release may be breaking. It is also not tuned for performance as of yet as we are still focusing on capability.
+> **Status:** Beta — this package is the reactive foundation of SolidJS 2.0 Beta. The API is stabilizing but may still have breaking changes before a final release.
+
+## Installation
+
+```bash
+npm install @solidjs/signals
+# or
+pnpm add @solidjs/signals
+```
+
+## Overview
+
+`@solidjs/signals` is a push-pull hybrid reactive system. Signals hold values, computeds derive from them, and effects run side effects — all connected through an automatic dependency graph. Updates are **batched** and flushed asynchronously via microtask, giving you consistent state without glitches.
+
+```typescript
+import { createEffect, createMemo, createRoot, createSignal, flush } from "@solidjs/signals";
+
+createRoot(() => {
+  const [count, setCount] = createSignal(0);
+  const doubled = createMemo(() => count() * 2);
+
+  createEffect(
+    () => doubled(),
+    value => {
+      console.log("Doubled:", value);
+    }
+  );
+
+  setCount(5);
+  flush(); // "Doubled: 10"
+});
+```
+
+### Batched Updates
+
+Signal writes are batched — reads after a write won't reflect the new value until `flush()` runs. This prevents glitches and unnecessary recomputation.
+
+```typescript
+const [a, setA] = createSignal(1);
+const [b, setB] = createSignal(2);
+
+setA(10);
+setB(20);
+// Neither has updated yet — both writes are batched
+flush(); // Now both update and downstream effects run once
+```
+
+## Core Primitives
+
+### Signals
+
+```typescript
+const [value, setValue] = createSignal(initialValue, options?);
+```
+
+Reactive state with a getter/setter pair. Supports custom equality via `options.equals`.
+
+### Memos
+
+```typescript
+const derived = createMemo(() => expensive(signal()));
+```
+
+Read-only derived values that cache their result and only recompute when dependencies change. Supports async compute functions — return a `Promise` or `AsyncIterable` and downstream consumers will wait automatically.
+
+### Effects
+
+```typescript
+// Two-phase: compute tracks dependencies, effect runs side effects
+createEffect(
+  () => count(),
+  value => {
+    console.log(value);
+  }
+);
+
+// Render-phase effect (runs before user effects)
+createRenderEffect(
+  () => count(),
+  value => {
+    updateDOM(value);
+  }
+);
+```
+
+Effects split tracking from execution. `createEffect` and `createRenderEffect` take a compute function (for tracking) and an effect function (for side effects).
+
+### Writable Memos
+
+Pass a function to `createSignal` to get a writable derived value — a memo you can also set:
+
+```typescript
+const [value, setValue] = createSignal(prev => transform(source(), prev), initialValue);
+```
+
+## Async
+
+Computeds can return promises or async iterables. The reactive graph handles this automatically — previous values are held in place until the async work resolves, so downstream consumers never see an inconsistent state.
+
+```typescript
+const data = createMemo(async () => {
+  const response = await fetch(`/api/items?q=${query()}`);
+  return response.json();
+});
+
+// Check async state
+isPending(data); // true while loading
+latest(data); // last resolved value
+```
+
+Use `action()` to coordinate async workflows with the reactive graph:
+
+```typescript
+const save = action(function* (item) {
+  yield fetch("/api/save", { method: "POST", body: JSON.stringify(item) });
+});
+```
+
+## Optimistic Updates
+
+Optimistic signals show an immediate value while async work is pending, then automatically revert when it settles:
+
+```typescript
+const [optimisticCount, setOptimisticCount] = createOptimistic(0);
+
+// Immediate UI update — reverts when the async work resolves
+setOptimisticCount(count + 1);
+```
+
+Also available for stores via `createOptimisticStore()`.
+
+## Stores
+
+Proxy-based deeply reactive objects with per-property tracking:
+
+```typescript
+import { createStore, reconcile } from "@solidjs/signals";
+
+const [store, setStore] = createStore({ todos: [], filter: "all" });
+
+// Setter takes a mutating callback — mutations are intercepted by the proxy
+setStore(s => {
+  s.filter = "active";
+});
+setStore(s => {
+  s.todos.push({ text: "New", done: false });
+});
+setStore(s => {
+  s.todos[0].done = true;
+});
+
+// Reconcile from server data
+setStore(s => {
+  reconcile(serverTodos, "id")(s.todos);
+});
+```
+
+### Projections
+
+Derived stores that transform data reactively:
+
+```typescript
+import { createProjection } from "@solidjs/signals";
+
+const filtered = createProjection(
+  draft => {
+    draft.items = store.todos.filter(t => !t.done);
+  },
+  { items: [] }
+);
+```
+
+## Boundaries
+
+Intercept async loading and error states in the reactive graph:
+
+```typescript
+import { createErrorBoundary, createLoadBoundary } from "@solidjs/signals";
+
+createErrorBoundary(
+  () => riskyComputation(),
+  (error, reset) => handleError(error)
+);
+
+createLoadBoundary(
+  () => asyncContent(),
+  () => showFallback()
+);
+```
+
+## Ownership & Context
+
+All reactive nodes exist within an **owner** tree that handles disposal and context propagation:
+
+```typescript
+import { createContext, createRoot, getContext, onCleanup, setContext } from "@solidjs/signals";
+
+const ThemeContext = createContext("light");
+
+createRoot(dispose => {
+  setContext(ThemeContext, "dark");
+
+  createEffect(
+    () => getContext(ThemeContext),
+    theme => {
+      console.log("Theme:", theme);
+    }
+  );
+
+  onCleanup(() => console.log("Disposed"));
+
+  // Call dispose() to tear down the tree
+});
+```
+
+## Utilities
+
+| Function                 | Description                                                        |
+| ------------------------ | ------------------------------------------------------------------ |
+| `flush()`                | Process all pending updates                                        |
+| `untrack(fn)`            | Run `fn` without tracking dependencies                             |
+| `isPending(accessor)`    | Check if an async accessor is loading                              |
+| `latest(accessor)`       | Get the last resolved value of an async accessor                   |
+| `refresh(accessor)`      | Re-trigger an async computation                                    |
+| `isRefreshing(accessor)` | Check if an async accessor is refreshing                           |
+| `resolve(fn)`            | Returns a promise that resolves when a reactive expression settles |
+| `mapArray(list, mapFn)`  | Reactive array mapping with keyed reconciliation                   |
+| `repeat(count, mapFn)`   | Reactive repeat based on a reactive count                          |
+| `onSettled(fn)`          | Run a callback after the current flush cycle completes             |
+| `snapshot(store)`        | Returns a non-reactive copy of a store, preserving unmodified references |
+| `reconcile(value, key)`  | Returns a diffing function for updating stores from new data       |
+| `merge(...sources)`      | Reactively merges multiple objects/stores, last source wins        |
+| `omit(props, ...keys)`   | Creates a reactive view of an object with specified keys removed   |
+| `deep(store)`            | Tracks all nested changes on a store                               |
+| `storePath(...path)`     | Path-based setter for stores as an alternative to mutating callbacks |
+
+## Development
+
+```bash
+pnpm install
+pnpm build          # Rollup build (dev/prod/node outputs)
+pnpm test           # Run tests
+pnpm test:watch     # Watch mode
+pnpm test:gc        # Tests with GC exposed
+pnpm bench          # Benchmarks
+pnpm format         # Prettier + import sorting
+```
+
+## License
+
+MIT

package/dist/dev.js

@@ -34,6 +34,7 @@ const REACTIVE_ZOMBIE = 1 << 5;
 const REACTIVE_DISPOSED = 1 << 6;
 const REACTIVE_OPTIMISTIC_DIRTY = 1 << 7;
 const REACTIVE_SNAPSHOT_STALE = 1 << 8;
+const REACTIVE_LAZY = 1 << 9;
 const STATUS_PENDING = 1 << 0;
 const STATUS_ERROR = 1 << 1;
 const STATUS_UNINITIALIZED = 1 << 2;
@@ -392,7 +393,7 @@ function finalizePureQueue(completingTransition = null, incomplete = false) {
         n._pendingValue = NOT_PENDING;
         if (n._type && n._type !== EFFECT_TRACKED) n._modified = true;
       }
-      n._statusFlags &= ~STATUS_UNINITIALIZED;
+      if (!(n._statusFlags & STATUS_PENDING)) n._statusFlags &= ~STATUS_UNINITIALIZED;
       if (n._fn) GlobalQueue._dispose(n, false, true);
     }
     pendingNodes.length = 0;
@@ -1237,7 +1238,7 @@ function computed(fn, initialValue, options) {
     _parent: context,
     _nextSibling: null,
     _firstChild: null,
-    _flags: REACTIVE_NONE,
+    _flags: options?.lazy ? REACTIVE_LAZY : REACTIVE_NONE,
     _statusFlags: STATUS_UNINITIALIZED,
     _time: clock,
     _pendingValue: NOT_PENDING,
@@ -1369,10 +1370,20 @@ function read(el) {
   let c = context;
   if (c?._root) c = c._parentComputed;
   if (refreshing && el._fn) recompute(el);
+  if (el._flags & REACTIVE_LAZY) {
+    el._flags &= ~REACTIVE_LAZY;
+    recompute(el, true);
+  }
+  const owner = el._firewall || el;
+  if (strictRead && owner._statusFlags & STATUS_PENDING) {
+    throw new Error(
+      `Reading a pending async value in ${strictRead}. ` +
+        `Async values must be read within a tracking scope (JSX, computations, effects).`
+    );
+  }
   if (c && tracking) {
     if (el._fn && el._flags & REACTIVE_DISPOSED) recompute(el);
     link(el, c);
-    const owner = el._firewall || el;
     if (owner._fn) {
       const isZombie = el._flags & REACTIVE_ZOMBIE;
       if (owner._height >= (isZombie ? zombieQueue._min : dirtyQueue._min)) {
@@ -1386,25 +1397,21 @@ function read(el) {
       }
     }
   }
-  const asyncCompute = el._firewall || el;
-  if (asyncCompute._statusFlags & STATUS_PENDING) {
-    if (
-      c &&
-      !(stale && asyncCompute._transition && activeTransition !== asyncCompute._transition)
-    ) {
+  if (owner._statusFlags & STATUS_PENDING) {
+    if (c && !(stale && owner._transition && activeTransition !== owner._transition)) {
       if (currentOptimisticLane) {
-        const pendingLane = asyncCompute._optimisticLane;
+        const pendingLane = owner._optimisticLane;
         const lane = findLane(currentOptimisticLane);
-        if (pendingLane && findLane(pendingLane) === lane && !hasActiveOverride(asyncCompute)) {
+        if (pendingLane && findLane(pendingLane) === lane && !hasActiveOverride(owner)) {
           if (!tracking) link(el, c);
-          throw asyncCompute._error;
+          throw owner._error;
         }
       } else {
         if (!tracking) link(el, c);
-        throw asyncCompute._error;
+        throw owner._error;
       }
-    } else if (!c && asyncCompute._statusFlags & STATUS_UNINITIALIZED) {
-      throw asyncCompute._error;
+    } else if (!c && owner._statusFlags & STATUS_UNINITIALIZED) {
+      throw owner._error;
     }
   }
   if (el._fn && el._statusFlags & STATUS_ERROR) {
@@ -1424,7 +1431,8 @@ function read(el) {
   }
   if (strictRead && !tracking)
     console.warn(
-      `Untracked reactive read in ${strictRead}. This value won't update — use untrack() if intentional.`
+      `Reactive value read at the top level of ${strictRead} will not update. ` +
+        `Move it into a tracking scope (JSX, computations, effects).`
     );
   return !c ||
     currentOptimisticLane !== null ||
@@ -1445,7 +1453,8 @@ function setSignal(el, v) {
       ? el._value
       : el._pendingValue;
   if (typeof v === "function") v = v(currentValue);
-  const valueChanged = !el._equals || !el._equals(currentValue, v);
+  const valueChanged =
+    !el._equals || !el._equals(currentValue, v) || !!(el._statusFlags & STATUS_UNINITIALIZED);
   if (!valueChanged) {
     if (isOptimistic && el._pendingValue !== NOT_PENDING && el._fn) {
       insertSubs(el, true);
@@ -2143,7 +2152,8 @@ const storeTraps = {
     }
     if (strictRead && !tracking && typeof property === "string")
       console.warn(
-        `Untracked reactive read in ${strictRead}. This value won't update — use untrack() if intentional.`
+        `Reactive value read at the top level of ${strictRead} will not update. ` +
+          `Move it into a tracking scope (JSX, computations, effects).`
       );
     return isWrappable(value) ? wrap(value, target) : value;
   },