sibujs 3.4.0 → 4.0.0

package/dist/patterns.d.cts

@@ -1,6 +1,6 @@
-export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as compose, d as createGuard, e as createSlots, f as defineComponent, g as defineSlottedComponent, h as defineStrictComponent, v as validateProps, i as validators, w as withBoundary, j as withDefaults, k as withProps, l as withWrapper } from './contracts-ey_Qh8ef.cjs';
+export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as compose, d as createGuard, e as createSlots, f as defineComponent, g as defineSlottedComponent, h as defineStrictComponent, v as validateProps, i as validators, w as withBoundary, j as withDefaults, k as withProps, l as withWrapper } from './contracts-Hg6ITAEF.cjs';
 
-interface MachineConfig<S extends string, E extends string, C extends Record<string, unknown> = Record<string, unknown>> {
+interface MachineConfig<S extends string, E extends string, C extends object = Record<string, unknown>> {
     initial: S;
     context?: C;
     states: {
@@ -17,7 +17,7 @@ interface MachineConfig<S extends string, E extends string, C extends Record<str
         };
     };
 }
-interface MachineReturn<S extends string, E extends string, C extends Record<string, unknown>> {
+interface MachineReturn<S extends string, E extends string, C extends object> {
     state: () => S;
     context: () => C;
     send: (event: E) => void;
@@ -27,7 +27,7 @@ interface MachineReturn<S extends string, E extends string, C extends Record<str
 /**
  * machine creates a finite state machine with states, events, guards, and actions.
  */
-declare function machine<S extends string, E extends string, C extends Record<string, unknown> = Record<string, unknown>>(config: MachineConfig<S, E, C>): MachineReturn<S, E, C>;
+declare function machine<S extends string, E extends string, C extends object = Record<string, unknown>>(config: MachineConfig<S, E, C>): MachineReturn<S, E, C>;
 
 /**
  * Creates a reactive state that automatically persists to localStorage
@@ -102,9 +102,18 @@ declare function persisted<T>(key: string, initial: T, options?: PersistOptions<
  *
  * Returns a named object with `value`, `pending`, and `update`.
  *
- * Concurrent safety: each operation is tagged with a version counter.
- * A failing operation only reverts if no newer operation has started since,
- * preventing stale snapshots from overwriting fresher optimistic state.
+ * CONCURRENCY MODEL — last writer wins, deliberately.
+ *
+ * A scalar has exactly one logical row, so "which operation owns the value" and
+ * "which operation started last" are the same question. Each operation is tagged
+ * with a version counter and only settles the value if no newer operation has
+ * started since. That is a coherent model here precisely because there is
+ * nothing to be disjoint with.
+ *
+ * `optimisticList` deliberately does NOT share this design: an array has many
+ * independent rows, so a global version counter cannot tell "a newer operation
+ * changed the row I am about to revert" from "a newer operation changed a
+ * completely different row". See the note above `optimisticList`.
  *
  * @example
  * ```ts
@@ -124,9 +133,32 @@ declare function optimistic<T>(initialValue: T): {
 /**
  * optimisticList provides optimistic updates for array state.
  *
- * Uses functional updates (setItems(current => ...)) for the success path
- * to avoid losing changes made by concurrent operations. The failure path
- * uses a version guard so stale reverts don't overwrite newer state.
+ * CONCURRENCY MODEL — per-row claim chains ordered by invocation.
+ *
+ * Every operation gets an id when it is invoked, and every row it touches gets
+ * a claim at that id's position in the row's stack. The newest claim is what
+ * `items()` shows. On settlement an operation touches only its own claim:
+ *
+ *   - a failed `add` withdraws exactly the row it inserted, and marks it so a
+ *     concurrent failed `remove` cannot reinstate it;
+ *   - a successful `add` resolves its own claim; if a later operation has
+ *     claimed the row since, that newer claim stays on top;
+ *   - a failed `remove` makes its rows visible again, in their correct relative
+ *     order and carrying whatever value they hold NOW;
+ *   - a successful `remove` retires its rows; each record is dropped as soon as
+ *     its last holder settles;
+ *   - a failed `update` drops its claim, revealing whatever is beneath it;
+ *   - a successful `update` resolves its claim in place, which becomes visible
+ *     only once no newer claim sits above it.
+ *
+ * Operations on disjoint rows are completely independent. Where two operations
+ * touch the same row the later one is visible — including when the later one
+ * was started by a reactive subscriber, by the outer operation's own predicate,
+ * or by one of its patch's property getters.
+ *
+ * `pending()` is true while any operation is unsettled and becomes false exactly
+ * when the last one settles, in any settlement order. It is always published in
+ * the same batch as `items()`, so a subscriber never sees one without the other.
  *
  * @example
  * ```ts
@@ -170,7 +202,22 @@ declare function timeline<T>(initial: T, maxHistory?: number): TimeTravelReturn<
 
 type Middleware<S> = (state: S, action: string, payload: unknown, next: () => void) => void;
 type Selector<S, R> = (state: S) => R;
-interface GlobalStore<S extends Record<string, unknown>, A extends Record<string, (state: S, payload?: unknown) => Partial<S>>> {
+/**
+ * Action-map constraint.
+ *
+ * `(state: S, payload?: unknown)` looks permissive but is the opposite: it
+ * requires every action to ACCEPT any `unknown` payload, so a typed action such
+ * as `add: (state, amount: number) => ...` is not assignable, and
+ * `Parameters<A[K]>[1]` — which `dispatch` already uses to type its payload —
+ * collapses to `unknown` for every action. The constraint therefore defeated the
+ * per-action payload typing the rest of this file is built around.
+ *
+ * A `never[]` rest parameter accepts any concrete parameter list while keeping
+ * `Parameters<A[K]>` intact, so `dispatch("add", 5)` is checked against the
+ * action's real signature. (TYPE-007)
+ */
+type StoreActionMap<S> = Record<string, (state: S, ...args: never[]) => Partial<S>>;
+interface GlobalStore<S extends object, A extends StoreActionMap<S>> {
     getState: () => S;
     select: <R>(selector: Selector<S, R>) => () => R;
     dispatch: <K extends keyof A>(action: K, payload?: Parameters<A[K]>[1]) => void;
@@ -181,10 +228,10 @@ interface GlobalStore<S extends Record<string, unknown>, A extends Record<string
  * globalStore creates a centralized state management store
  * with actions, selectors, and middleware support.
  */
-declare function globalStore<S extends Record<string, unknown>, A extends Record<string, (state: S, payload?: unknown) => Partial<S>>>(config: {
+declare function globalStore<S extends object, A extends StoreActionMap<S>>(config: {
     state: S;
     actions: A;
     middleware?: Middleware<S>[];
 }): GlobalStore<S, A>;
 
-export { type GlobalStore, type MachineConfig, type MachineReturn, type Middleware, type PersistOptions, type Selector, type TimeTravelReturn, globalStore, machine, optimistic, optimisticList, persisted, timeline };
+export { type GlobalStore, type MachineConfig, type MachineReturn, type Middleware, type PersistOptions, type Selector, type StoreActionMap, type TimeTravelReturn, globalStore, machine, optimistic, optimisticList, persisted, timeline };

package/dist/patterns.d.ts

@@ -1,6 +1,6 @@
-export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as compose, d as createGuard, e as createSlots, f as defineComponent, g as defineSlottedComponent, h as defineStrictComponent, v as validateProps, i as validators, w as withBoundary, j as withDefaults, k as withProps, l as withWrapper } from './contracts-ey_Qh8ef.js';
+export { C as ComponentProps, P as PropDef, a as PropSchema, R as RenderProp, V as Validator, b as assertType, c as compose, d as createGuard, e as createSlots, f as defineComponent, g as defineSlottedComponent, h as defineStrictComponent, v as validateProps, i as validators, w as withBoundary, j as withDefaults, k as withProps, l as withWrapper } from './contracts-Hg6ITAEF.js';
 
-interface MachineConfig<S extends string, E extends string, C extends Record<string, unknown> = Record<string, unknown>> {
+interface MachineConfig<S extends string, E extends string, C extends object = Record<string, unknown>> {
     initial: S;
     context?: C;
     states: {
@@ -17,7 +17,7 @@ interface MachineConfig<S extends string, E extends string, C extends Record<str
         };
     };
 }
-interface MachineReturn<S extends string, E extends string, C extends Record<string, unknown>> {
+interface MachineReturn<S extends string, E extends string, C extends object> {
     state: () => S;
     context: () => C;
     send: (event: E) => void;
@@ -27,7 +27,7 @@ interface MachineReturn<S extends string, E extends string, C extends Record<str
 /**
  * machine creates a finite state machine with states, events, guards, and actions.
  */
-declare function machine<S extends string, E extends string, C extends Record<string, unknown> = Record<string, unknown>>(config: MachineConfig<S, E, C>): MachineReturn<S, E, C>;
+declare function machine<S extends string, E extends string, C extends object = Record<string, unknown>>(config: MachineConfig<S, E, C>): MachineReturn<S, E, C>;
 
 /**
  * Creates a reactive state that automatically persists to localStorage
@@ -102,9 +102,18 @@ declare function persisted<T>(key: string, initial: T, options?: PersistOptions<
  *
  * Returns a named object with `value`, `pending`, and `update`.
  *
- * Concurrent safety: each operation is tagged with a version counter.
- * A failing operation only reverts if no newer operation has started since,
- * preventing stale snapshots from overwriting fresher optimistic state.
+ * CONCURRENCY MODEL — last writer wins, deliberately.
+ *
+ * A scalar has exactly one logical row, so "which operation owns the value" and
+ * "which operation started last" are the same question. Each operation is tagged
+ * with a version counter and only settles the value if no newer operation has
+ * started since. That is a coherent model here precisely because there is
+ * nothing to be disjoint with.
+ *
+ * `optimisticList` deliberately does NOT share this design: an array has many
+ * independent rows, so a global version counter cannot tell "a newer operation
+ * changed the row I am about to revert" from "a newer operation changed a
+ * completely different row". See the note above `optimisticList`.
  *
  * @example
  * ```ts
@@ -124,9 +133,32 @@ declare function optimistic<T>(initialValue: T): {
 /**
  * optimisticList provides optimistic updates for array state.
  *
- * Uses functional updates (setItems(current => ...)) for the success path
- * to avoid losing changes made by concurrent operations. The failure path
- * uses a version guard so stale reverts don't overwrite newer state.
+ * CONCURRENCY MODEL — per-row claim chains ordered by invocation.
+ *
+ * Every operation gets an id when it is invoked, and every row it touches gets
+ * a claim at that id's position in the row's stack. The newest claim is what
+ * `items()` shows. On settlement an operation touches only its own claim:
+ *
+ *   - a failed `add` withdraws exactly the row it inserted, and marks it so a
+ *     concurrent failed `remove` cannot reinstate it;
+ *   - a successful `add` resolves its own claim; if a later operation has
+ *     claimed the row since, that newer claim stays on top;
+ *   - a failed `remove` makes its rows visible again, in their correct relative
+ *     order and carrying whatever value they hold NOW;
+ *   - a successful `remove` retires its rows; each record is dropped as soon as
+ *     its last holder settles;
+ *   - a failed `update` drops its claim, revealing whatever is beneath it;
+ *   - a successful `update` resolves its claim in place, which becomes visible
+ *     only once no newer claim sits above it.
+ *
+ * Operations on disjoint rows are completely independent. Where two operations
+ * touch the same row the later one is visible — including when the later one
+ * was started by a reactive subscriber, by the outer operation's own predicate,
+ * or by one of its patch's property getters.
+ *
+ * `pending()` is true while any operation is unsettled and becomes false exactly
+ * when the last one settles, in any settlement order. It is always published in
+ * the same batch as `items()`, so a subscriber never sees one without the other.
  *
  * @example
  * ```ts
@@ -170,7 +202,22 @@ declare function timeline<T>(initial: T, maxHistory?: number): TimeTravelReturn<
 
 type Middleware<S> = (state: S, action: string, payload: unknown, next: () => void) => void;
 type Selector<S, R> = (state: S) => R;
-interface GlobalStore<S extends Record<string, unknown>, A extends Record<string, (state: S, payload?: unknown) => Partial<S>>> {
+/**
+ * Action-map constraint.
+ *
+ * `(state: S, payload?: unknown)` looks permissive but is the opposite: it
+ * requires every action to ACCEPT any `unknown` payload, so a typed action such
+ * as `add: (state, amount: number) => ...` is not assignable, and
+ * `Parameters<A[K]>[1]` — which `dispatch` already uses to type its payload —
+ * collapses to `unknown` for every action. The constraint therefore defeated the
+ * per-action payload typing the rest of this file is built around.
+ *
+ * A `never[]` rest parameter accepts any concrete parameter list while keeping
+ * `Parameters<A[K]>` intact, so `dispatch("add", 5)` is checked against the
+ * action's real signature. (TYPE-007)
+ */
+type StoreActionMap<S> = Record<string, (state: S, ...args: never[]) => Partial<S>>;
+interface GlobalStore<S extends object, A extends StoreActionMap<S>> {
     getState: () => S;
     select: <R>(selector: Selector<S, R>) => () => R;
     dispatch: <K extends keyof A>(action: K, payload?: Parameters<A[K]>[1]) => void;
@@ -181,10 +228,10 @@ interface GlobalStore<S extends Record<string, unknown>, A extends Record<string
  * globalStore creates a centralized state management store
  * with actions, selectors, and middleware support.
  */
-declare function globalStore<S extends Record<string, unknown>, A extends Record<string, (state: S, payload?: unknown) => Partial<S>>>(config: {
+declare function globalStore<S extends object, A extends StoreActionMap<S>>(config: {
     state: S;
     actions: A;
     middleware?: Middleware<S>[];
 }): GlobalStore<S, A>;
 
-export { type GlobalStore, type MachineConfig, type MachineReturn, type Middleware, type PersistOptions, type Selector, type TimeTravelReturn, globalStore, machine, optimistic, optimisticList, persisted, timeline };
+export { type GlobalStore, type MachineConfig, type MachineReturn, type Middleware, type PersistOptions, type Selector, type StoreActionMap, type TimeTravelReturn, globalStore, machine, optimistic, optimisticList, persisted, timeline };

package/dist/patterns.js

@@ -5,7 +5,7 @@ import {
   optimisticList,
   persisted,
   timeline
-} from "./chunk-CEBWDD63.js";
+} from "./chunk-WOOMUJFT.js";
 import {
   RenderProp,
   assertType,
@@ -23,12 +23,12 @@ import {
   withWrapper
 } from "./chunk-VJE6DDYM.js";
 import "./chunk-H3SRKIYX.js";
-import "./chunk-ITWCTZYH.js";
-import "./chunk-BUKYCWHX.js";
-import "./chunk-S3NFJO6L.js";
-import "./chunk-KZBEVFXZ.js";
-import "./chunk-OOUQUCNN.js";
-import "./chunk-COY6PUD2.js";
+import "./chunk-Z2CE42DB.js";
+import "./chunk-PBQEW5VW.js";
+import "./chunk-TIRZCERI.js";
+import "./chunk-W55YHPEP.js";
+import "./chunk-ACBT6UZS.js";
+import "./chunk-VPP2FONR.js";
 export {
   RenderProp,
   assertType,