@fluixi/reactive 1.0.0-alpha.83 → 1.0.0-alpha.85

package/dist/lib/store/api.d.ts

@@ -3,5 +3,38 @@ import type { Immutable, Store, StoreOptions } from './store.js';
 export type StoreHandle<T> = Immutable<T> & {
     set: Store<T>['set'];
 };
+/**
+ * A reactive store you read by property access and write with `.set()`.
+ *
+ * Tracking is per key and lazy: a signal is created for a key the first time something
+ * reads it, so an effect reading one field is untouched by a write to another. Nested
+ * objects and arrays are proxied on access, to whatever depth is reached.
+ *
+ * `options.equals` compares whole states, not individual keys, and `options.name` is
+ * what a devtools panel labels the store with.
+ *
+ * @example An object argument patches the keys it names and leaves the rest:
+ * ```ts
+ * const user = store({ name: 'Ada', role: 'admin' });
+ *
+ * effect(() => console.log(user.name));   // subscribes to `name` only
+ * user.set({ role: 'owner' });           // the effect does not re-run
+ * user.set({ name: 'Grace' });           // now it does
+ * ```
+ *
+ * @example A dot path writes deep without rebuilding the tree above it. Array indices
+ * are segments like any other:
+ * ```ts
+ * const state = store({ todos: [{ done: false }] });
+ * state.set('todos.0.done', true);
+ * state.set('todos.0.done', (done) => !done);   // or derive from the current value
+ * ```
+ *
+ * @example A `set` key of your own is unreachable through this form, because the setter
+ * occupies the name. `createStore` hands back a tuple and has no such collision:
+ * ```ts
+ * const [config, setConfig] = createStore({ set: 'a value' });
+ * ```
+ */
 export declare function store<T>(initialState: T, options?: StoreOptions<T>): StoreHandle<T>;
 //# sourceMappingURL=api.d.ts.map

package/dist/lib/store/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/lib/store/api.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjE,0DAA0D;AAC1D,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;CAAE,CAAC;AAErE,wBAAgB,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAUnF"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/lib/store/api.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjE,0DAA0D;AAC1D,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAUnF"}

package/dist/lib/store/api.js

@@ -1,23 +1,56 @@
 /**
- * `store` — `createStore` as one binding instead of a tuple.
+ * `store`: `createStore` as one binding instead of a tuple.
  *
  *   const user = store({ name: 'Ada' });
  *   user.name;                    // reads, and tracks that key
  *   user.set({ name: 'Grace' });  // writes
  *
- * It returns the reactive state itself, with `set` on it. That's the difference from
- * `signal`, and it's deliberate: `.get()` exists on a signal because a value has no
- * other way to be read, while a store is an object whose whole point is that property
- * access IS the read. Spelling it `user.get().name` would add a call to look uniform and
- * lose the thing that makes a store worth using.
+ * It returns the reactive state itself with `set` on it, which is where it parts from
+ * `signal`. A signal needs `.get()` because a value has no other way to be read. A
+ * store is an object, and property access is already the read, so `user.get().name`
+ * would add a call for the sake of looking uniform and lose the thing that makes a
+ * store worth using.
  *
- * Reads still subscribe per key, so an effect over `user.name` doesn't re-run when
+ * Reads still subscribe per key, so an effect over `user.name` does not re-run when
  * `user.role` changes.
  *
  * The one cost: a `set` key in your own state is shadowed by the setter. Reach for
- * `createStore` if you need that name — it is unchanged.
+ * `createStore` when you need that name, which is unchanged.
  */
 import { createStore } from './store.js';
+/**
+ * A reactive store you read by property access and write with `.set()`.
+ *
+ * Tracking is per key and lazy: a signal is created for a key the first time something
+ * reads it, so an effect reading one field is untouched by a write to another. Nested
+ * objects and arrays are proxied on access, to whatever depth is reached.
+ *
+ * `options.equals` compares whole states, not individual keys, and `options.name` is
+ * what a devtools panel labels the store with.
+ *
+ * @example An object argument patches the keys it names and leaves the rest:
+ * ```ts
+ * const user = store({ name: 'Ada', role: 'admin' });
+ *
+ * effect(() => console.log(user.name));   // subscribes to `name` only
+ * user.set({ role: 'owner' });           // the effect does not re-run
+ * user.set({ name: 'Grace' });           // now it does
+ * ```
+ *
+ * @example A dot path writes deep without rebuilding the tree above it. Array indices
+ * are segments like any other:
+ * ```ts
+ * const state = store({ todos: [{ done: false }] });
+ * state.set('todos.0.done', true);
+ * state.set('todos.0.done', (done) => !done);   // or derive from the current value
+ * ```
+ *
+ * @example A `set` key of your own is unreachable through this form, because the setter
+ * occupies the name. `createStore` hands back a tuple and has no such collision:
+ * ```ts
+ * const [config, setConfig] = createStore({ set: 'a value' });
+ * ```
+ */
 export function store(initialState, options) {
     const [state, set] = createStore(initialState, options);
     // A thin wrapper rather than assigning onto the state: the store proxy is the tracking