Skip to content

Commit 82721ee

Browse files
claudeGabbeV
andcommitted
feat(signals,solid): seedless derived stores; seeds are a complete T again
createStore(fn), createProjection(fn) and createOptimisticStore(fn) accept a derive that takes no draft and answers a complete value (sync, promise, or an async iterable of complete snapshots). Plain-object roots only; arrays keep their `[]` seed. The root starts as an empty record, an unobservable draft like any seed (A25, D-30), so hydration replay and the setter's draft work as they do with a `{}` seed today. `seedLoadingValue` is not offered without a seed. Pass `undefined` for the seed to reach the options. With the seedless form in place, a seed is a complete T again: the reason #3258 was reverted (async stores that need the options slot had to invent a T) is covered by `createStore(fn, undefined, options)`. Types from Gabriel's #3194 exploration (NoArray, the return-only overload). Co-Authored-By: Gabriel Valfridsson <[email protected]> Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01JJ7QVVnmnQrdvYP548mWWc
1 parent fb8558c commit 82721ee

15 files changed

Lines changed: 367 additions & 44 deletions
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
"@solidjs/signals": patch
3+
"solid-js": patch
4+
---
5+
6+
Derived stores no longer need a seed (#3194). `createStore(fn)`, `createProjection(fn)` and `createOptimisticStore(fn)` accept a derive that takes no draft and answers a complete value — sync, a promise, or an async iterable whose every yield is a complete snapshot. The root is a plain object (an array keeps its `[]` seed); pass `undefined` for the seed to reach the options, e.g. `createStore(fetchUser, undefined, { key: "email" })`. Until the first answer lands the store is unreadable, as with any seed (A25); `seedLoadingValue` needs a seed and is not offered on the seedless form.
7+
8+
With the seedless form available, a seed is a complete `T` again (#3258's requirement, reverted then because async stores that needed the options slot had to invent one). A `{}` seed on a return-form derive is now a type error: drop it. A mutating derive that builds its object from an empty seed needs `{} as T`.

‎packages/signals/docs/RULES-DERIVED.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -246,7 +246,7 @@ Effect-phase code that runs after the frame is decided reads the frame as it sta
246246

247247
**From:** F-9, F-1. **Scenarios:** S-36, S-37.
248248

249-
Pending is per node — per store key: a held write to a plain store pends exactly the touched keys; a derived store's leaves report the derive's new-question refetch like any async memo, in both forms, and a quiet re-ask (`refresh(store)`) is quiet on them too. A derived store's landing resumes the frame that asked it: when a consumer of its leaves goes async, the landed leaves are held with that frame and read stale and pending until it reveals (signal parity); an untouched sibling key is final. A derived store's seed is a draft for the derive, never an observable value: until the first resolution (first yield for a generator) every outside read — tracked, untracked, `in`, enumeration — throws `NotReadyError` (DEV in a component body: `PENDING_ASYNC_UNTRACKED_READ`); write-path reads see it. `loadingValue` / `seedLoadingValue` promote a first value to commit #0: reads serve it, no boundary trips, no hold starts or extends, `isPending` is `false` on every axis until the first real landing — a hydration invariant (the server always answers `false`) — after which the node is an ordinary memo.
249+
Pending is per node — per store key: a held write to a plain store pends exactly the touched keys; a derived store's leaves report the derive's new-question refetch like any async memo, in both forms, and a quiet re-ask (`refresh(store)`) is quiet on them too. A derived store's landing resumes the frame that asked it: when a consumer of its leaves goes async, the landed leaves are held with that frame and read stale and pending until it reveals (signal parity); an untouched sibling key is final. A derived store's seed is a draft for the derive, never an observable value: until the first resolution (first yield for a generator) every outside read — tracked, untracked, `in`, enumeration — throws `NotReadyError` (DEV in a component body: `PENDING_ASYNC_UNTRACKED_READ`); write-path reads see it. A seedless derived store (`createStore(fn)` with a derive that takes no draft) starts from an empty record, the same unobservable draft. `loadingValue` / `seedLoadingValue` promote a first value to commit #0: reads serve it, no boundary trips, no hold starts or extends, `isPending` is `false` on every axis until the first real landing — a hydration invariant (the server always answers `false`) — after which the node is an ordinary memo.
250250

251251
**Collapses:** [A9](./SPEC-ASYNC-SEMANTICS.md#a9-store-leaves-behind-a-firewall-report-the-firewalls-new-question-refetch), [A22](./SPEC-ASYNC-SEMANTICS.md#a22-pending-is-per-node-store-wide-only-for-the-firewalls-own-work) (amended 2026-10-03), [A25](./SPEC-ASYNC-SEMANTICS.md#a25-a-derived-stores-seed-is-a-draft-never-an-observable-value), [A27](./SPEC-ASYNC-SEMANTICS.md#a27-the-commit-0-loading-window-is-loading-class-and-verdict-quiet), the L2 stores ruling (statement 7), OS-R30–R36, PJ-R23/R30/R31. **Status:** standing; one adoption shape pinned `it.fails` (`adoption-unchanged-key-read-3706.test.ts`, a row first read after the adoption).
252252

‎packages/signals/docs/RULES-INDEX.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
6969
| A22 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:229` | store.ts×1 | createProjection.draft-lifetime-3585.test.ts×1 spec-async-semantics.test.ts×1 visibility-oracle-store.states.ts×1 | [ruled, amended in place 2026-07-08] Pending is per-node; store-wide only for the firewall's own work — **Pending is per-node: store-wide verdicts exist only as the firewall's own in-flight work (A9) … |
7070
| A23 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:239` | — | spec-async-semantics.test.ts×1 | [ruled 2026-07-08] The `isPending` probe is reads-only — **The `isPending` probe is reads-only — the thunk's return value is never inspected.** `isPending(() => store)` reads nothing and reports `fals… |
7171
| A24 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:157` | affects.ts×2 constants.ts×1 lanes.ts×2 types.ts×1 verdict.ts×3 affects.ts×1 optimistic.ts×1 | body-end-supersession-visibility.test.ts×1 optimistic-undefined-override.test.ts×1 reveal-gating-contract.test.ts×1 spec-async-semantics.test.ts×3 kanban-a17-fixture.test.ts×1 signal-store-twins-qd.test.ts×1 visibility-oracle-store.states.ts×4 visibility-oracle.states.ts×5 visibility-oracle.test.ts×1 | [ruled 2026-07-13] Question-scoped pending: pending iff a value change is in flight or an `affects()` mark is live — (**ruled 2026-07-13** — supersedes A20/A21; the converged model from the #2844/#272… |
72-
| A25 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:309` | projection.ts×1 | derived-presence-async-3726.test.ts×2 uninitialized-visibility.test.ts×3 visibility-oracle-store.states.ts×7 visibility-oracle-store.test.ts×1 | [ruled 2026-07-16] A derived store's seed is a draft, never an observable value — (**ruled 2026-07-16**, #2897) **A derived store's seed is a draft, never an observable value.** The seed exists for th… |
72+
| A25 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:309` | projection.ts×2 | derived-presence-async-3726.test.ts×2 seedless-derived-store.test.ts×1 uninitialized-visibility.test.ts×3 visibility-oracle-store.states.ts×7 visibility-oracle-store.test.ts×1 | [ruled 2026-07-16] A derived store's seed is a draft, never an observable value — (**ruled 2026-07-16**, #2897) **A derived store's seed is a draft, never an observable value.** The seed exists for th… |
7373
| A26 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:111` | — | action-await-contract.test.ts×2 fuzz-findings-l2.test.ts×1 posture-store-parity.test.ts×2 visibility-oracle-store.states.ts×2 visibility-oracle.states.ts×1 visibility-oracle.test.ts×1 | [ruled 2026-07-17] An ambient transaction window is one flush; parking is flush-driven — (**ruled 2026-07-17**, #2913; **enforcement hardened 2026-08-31**, #3141 — parking is flush-driven, and a trans… |
7474
| A27 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:301` | — | loading-value.test.ts×2 visibility-oracle.states.ts×18 visibility-oracle.test.ts×1 | [ruled 2026-08-10] The commit-#0 loading window is loading-class and verdict-quiet — (**ruled 2026-08-10**) **The commit-#0 loading window is loading-class and verdict-quiet.** A node born committed v… |
7575
| A28 | ruled, mechanism landed | `docs/SPEC-ASYNC-SEMANTICS.md:95` | constants.ts×1 core.ts×12 lanes.ts×2 scheduler.ts×3 types.ts×1 verdict.ts×2 store.ts×4 | createOptimistic.test.ts×5 fuzz-findings-l2.test.ts×6 held-derivation-not-a-proposal-3612.test.ts×1 issue-3800-repro.test.ts×1 latest-held-till-flush.test.ts×1 posture-store-parity.test.ts×5 question-scoped-pending.test.ts×3 snapshot-derived-store-rows.test.ts×1 createOptimisticStore.test.ts×10 optimistic-draft-visibility-3665.test.ts×5 optimistic-list-mutation-matrix.harness.ts×1 optimistic-list-mutation-matrix.test.ts×2 shallow.test.ts×1 woken-transaction-adopts-staged-bump.test.ts×1 treeshake.test.ts×2 verdict-contract.test.ts×1 visibility-oracle-store.states.ts×8 visibility-oracle.states.ts×8 | [ruled, mechanism landed 2026-09-15] A write becomes visible at flush — to every channel — (**ruled 2026-09-08**; supersedes the #2922 mid-tick pull) **A write becomes visible at flush — to every chan… |

‎packages/signals/src/store/index.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
* return on later steps (plan sec. 31.5).
55
*/
66
export type {
7+
NoArray,
78
NoFn,
89
NotWrappable,
910
ProjectionOptions,
@@ -34,6 +35,7 @@ import {
3435
snapshot as snapshotStore
3536
} from "./store.js";
3637
import type {
38+
NoArray,
3739
NoFn,
3840
ProjectionOptions,
3941
ProjectionStoreReturn,
@@ -77,14 +79,25 @@ export type { SourceKind } from "./utils.js";
7779
* Create a reactive store: a proxy over plain data with fine-grained
7880
* subscriptions per read path, written through its setter's draft — or, in
7981
* the derived form, a projection with a setter.
82+
*
83+
* The derived form comes in two shapes. Seedless, `createStore(fn)`: `fn`
84+
* takes no draft and every answer is a complete `T` (plain-object roots only;
85+
* pass `undefined` for the seed to reach the options). Seeded,
86+
* `createStore(fn, seed)`: the seed is a complete `T` the derive drafts
87+
* against — `[]` for an array.
8088
*/
8189
export function createStore<T extends object = {}>(
8290
initialValue: NoFn<T>,
8391
options?: StoreOptions
8492
): StoreReturn<T>;
93+
export function createStore<T extends object = {}>(
94+
fn: (() => T | Promise<T> | AsyncIterable<T>) & NoArray<T>,
95+
seed?: null,
96+
options?: Omit<ProjectionOptions, "seedLoadingValue">
97+
): ProjectionStoreReturn<T>;
8598
export function createStore<T extends object = {}>(
8699
fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
87-
seed: Partial<T> | Store<NoFn<T>>,
100+
seed: NoFn<T> | Store<NoFn<T>>,
88101
options?: ProjectionOptions
89102
): ProjectionStoreReturn<T>;
90103
export function createStore(first: any, second?: any, third?: any): any {

‎packages/signals/src/store/optimistic.ts‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ import {
6666
$TRACK,
6767
isWrappable,
6868
markRawIngest,
69+
type NoArray,
6970
type NoFn,
7071
type ProjectionOptions,
7172
type Store,
@@ -614,19 +615,26 @@ export function createOptimisticStore<T extends object = {}>(
614615
initialValue: NoFn<T> | Store<NoFn<T>>,
615616
options?: StoreOptions
616617
): [get: Store<T>, set: StoreSetter<T>];
618+
export function createOptimisticStore<T extends object = {}>(
619+
fn: (() => T | Promise<T> | AsyncIterable<T>) & NoArray<T>,
620+
seed?: null,
621+
options?: Omit<ProjectionOptions, "seedLoadingValue">
622+
): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
617623
export function createOptimisticStore<T extends object = {}>(
618624
fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
619-
seed: Partial<T> | Store<NoFn<T>>,
625+
seed: NoFn<T> | Store<NoFn<T>>,
620626
options?: ProjectionOptions
621627
): [get: Refreshable<Store<T>>, set: StoreSetter<T>];
622628
export function createOptimisticStore<T extends object = {}>(
623629
first: T | ((store: T) => void | T | Promise<void | T> | AsyncIterable<void | T>),
624-
second?: Partial<T> | NoFn<T> | Store<NoFn<T>> | StoreOptions,
630+
second?: NoFn<T> | Store<NoFn<T>> | StoreOptions | null,
625631
third?: ProjectionOptions
626632
): [get: Store<T>, set: StoreSetter<T>] {
627633
const derived = typeof first === "function";
628634
const options = (derived ? third : second) as ProjectionOptions | undefined;
629-
const initialValue = (derived ? second : first) as T;
635+
// Seedless derived form: the root starts as an empty record (see
636+
// createProjectionInternal).
637+
const initialValue = (derived ? second || {} : first) as T;
630638
const keyOption = options?.key === undefined ? "id" : options.key;
631639
const fam: StoreFamily = {
632640
map: new WeakMap(),

‎packages/signals/src/store/projection.ts‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ import {
4040
isWrappable,
4141
markRawIngest,
4242
setWriteOverride,
43+
type NoArray,
4344
type NoFn,
4445
type ProjectionOptions,
4546
type Store
@@ -302,9 +303,12 @@ export function runProjectionComputed<T extends object>(
302303

303304
function createProjectionInternal<T extends object = {}>(
304305
fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
305-
seed: Partial<T>,
306+
seed: T | null | undefined,
306307
options?: ProjectionOptions
307308
) {
309+
// Seedless (`fn` takes no draft): the root starts as an empty record. It is
310+
// a draft like any seed, never observable before the first landing (A25).
311+
seed ||= {} as T;
308312
const keyOption = options?.key === undefined ? "id" : options.key;
309313
const fam: StoreFamily = {
310314
map: new WeakMap(),
@@ -350,9 +354,19 @@ function createProjectionInternal<T extends object = {}>(
350354
* firewall). `fn` may be async or an async iterator; the seed is a draft,
351355
* never an observable value, until the first landing (A25).
352356
*/
357+
export function createProjection<T extends object = {}>(
358+
fn: (() => T | Promise<T> | AsyncIterable<T>) & NoArray<T>,
359+
seed?: null,
360+
options?: Omit<ProjectionOptions, "seedLoadingValue">
361+
): Refreshable<Store<T>>;
362+
export function createProjection<T extends object = {}>(
363+
fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
364+
seed: NoFn<T> | Store<NoFn<T>>,
365+
options?: ProjectionOptions
366+
): Refreshable<Store<T>>;
353367
export function createProjection<T extends object = {}>(
354368
fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
355-
seed: Partial<T> | Store<NoFn<T>>,
369+
seed?: T | null,
356370
options?: ProjectionOptions
357371
): Refreshable<Store<T>> {
358372
return createProjectionInternal(fn, seed, options).store;
@@ -361,7 +375,7 @@ export function createProjection<T extends object = {}>(
361375
/** `createStore(fn, seed, options)`: a projection with a user setter. */
362376
export function createStoreDerived<T extends object = {}>(
363377
fn: (draft: T) => void | T | Promise<void | T> | AsyncIterable<void | T>,
364-
seed: Partial<T> | Store<NoFn<T>>,
378+
seed: T | null | undefined,
365379
options?: ProjectionOptions
366380
): [Refreshable<Store<T>>, (f: (draft: T) => T | void) => void] {
367381
const { store } = createProjectionInternal(fn, seed, options);

‎packages/signals/src/store/types.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,9 @@ export interface ProjectionOptions extends StoreOptions {
6767
}
6868

6969
export type NoFn<T> = T extends Function ? never : T;
70+
/** Rejects array roots on the seedless derived form: a store's root shape is
71+
* fixed when it is created, and `[]` is already a complete seed for an array. */
72+
export type NoArray<T> = Extract<T, readonly unknown[]> extends never ? unknown : never;
7073

7174
/** Brand keys the proxy answers directly (never user data). */
7275
export const $TRACK = Symbol(__DEV__ ? "STORE_TRACK" : 0),

‎packages/signals/tests/store/createProjection.test.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -518,7 +518,7 @@ describe("projection over a store — chained backing (#2941)", () => {
518518
proj = createProjection(() => {
519519
derive();
520520
return store;
521-
}, {}) as { a: number };
521+
}) as { a: number };
522522
createEffect(
523523
() => proj.a,
524524
v => {
@@ -547,7 +547,7 @@ describe("projection over a store — chained backing (#2941)", () => {
547547
const dispose = createRoot(dispose => {
548548
const [store, set] = createStore({ top: "t1", nest: { deep: "d1" } });
549549
setStore = set;
550-
const proj = createProjection(() => store, {}) as typeof store;
550+
const proj = createProjection(() => store) as typeof store;
551551
createEffect(
552552
() => proj.top,
553553
v => {
@@ -587,7 +587,7 @@ describe("projection over a store — chained backing (#2941)", () => {
587587
const proj = createProjection(() => {
588588
const m = mode();
589589
return m === "a" ? a : m === "b" ? b : { v: "plain" };
590-
}, {}) as { v: string };
590+
}) as { v: string };
591591
createEffect(
592592
() => proj.v,
593593
v => {
@@ -676,7 +676,7 @@ describe("projection over a store — chained backing (#2941)", () => {
676676
const dispose = createRoot(dispose => {
677677
const [store, set] = createStore({ a: 1, nest: { b: 2 } });
678678
setStore = set;
679-
proj = createProjection(() => store, {});
679+
proj = createProjection(() => store);
680680
return dispose;
681681
});
682682
flush();

‎packages/signals/tests/store/projection-transition-isolation.test.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ describe("projection transition isolation", () => {
4141
const [count, setCount] = createSignal(0);
4242
let p!: { a?: number };
4343
const dispose = createRoot(d => {
44-
p = createProjection(() => ({ a: count() }), {});
44+
p = createProjection(() => ({ a: count() }));
4545
return d;
4646
});
4747
flush();
@@ -72,7 +72,7 @@ describe("projection transition isolation", () => {
7272
const seen: (number | undefined)[] = [];
7373
let p!: { a?: number };
7474
const dispose = createRoot(d => {
75-
p = createProjection(() => ({ a: count() }), {});
75+
p = createProjection(() => ({ a: count() }));
7676
createEffect(
7777
() => p.a,
7878
v => {
@@ -103,7 +103,7 @@ describe("projection transition isolation", () => {
103103
let p!: { a?: number };
104104
let m!: () => number;
105105
const dispose = createRoot(d => {
106-
p = createProjection(() => ({ a: count() }), {});
106+
p = createProjection(() => ({ a: count() }));
107107
m = createMemo(() => count());
108108
return d;
109109
});
@@ -134,7 +134,7 @@ describe("projection transition isolation", () => {
134134
const [count, setCount] = createSignal(0);
135135
let p!: { a?: number };
136136
const dispose = createRoot(d => {
137-
p = createProjection(() => ({ a: count() }), {});
137+
p = createProjection(() => ({ a: count() }));
138138
return d;
139139
});
140140
flush();

0 commit comments

Comments
 (0)