sibujs 1.4.0 → 2.0.0

package/dist/patterns.d.cts

@@ -1,4 +1,4 @@
-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-xo5ckdRP.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-ey_Qh8ef.cjs';
 
 interface MachineConfig<S extends string, E extends string, C extends Record<string, unknown> = Record<string, unknown>> {
     initial: S;
@@ -71,48 +71,81 @@ interface PersistOptions<T = unknown> {
      *  - use XOR with a static key — trivially reversible
      *  - roll your own cipher — nearly always broken
      *
+     * **Sync only:** because `persisted()` exposes synchronous getters and
+     * setters, both `encrypt` and `decrypt` must be SYNCHRONOUS. Async
+     * crypto (e.g. `crypto.subtle.encrypt`) is NOT supported here — derive
+     * keys ahead of time and use a sync wrapper, or pre/post-process the
+     * value yourself before/after `setValue`.
+     *
      * @example
      * ```ts
+     * // Pre-derived key + sync wrapper
      * persisted("token", "", {
-     *   encrypt: async (v) => aesGcmEncrypt(v, await getKey()),
-     *   decrypt: async (v) => aesGcmDecrypt(v, await getKey()),
+     *   encrypt: (v) => syncAesGcmEncrypt(v, derivedKey),
+     *   decrypt: (v) => syncAesGcmDecrypt(v, derivedKey),
      * });
      * ```
-     *
-     * Note that because localStorage is synchronous, any real AES-GCM
-     * flow needs pre-derived keys and is inherently best-effort.
      */
     encrypt?: (value: string) => string;
-    /** Decrypt the stored value before deserialization. Required if `encrypt` is set. */
+    /** Decrypt the stored value before deserialization. Required if `encrypt` is set.
+     *  Must be synchronous — see `encrypt` docs. */
     decrypt?: (value: string) => string;
 }
 declare function persisted<T>(key: string, initial: T, options?: PersistOptions<T>): [() => T, (next: T | ((prev: T) => T)) => void];
 
-interface OptimisticAction<T> {
-    optimisticValue: T;
-    revert: T;
-}
 /**
  * optimistic provides optimistic UI updates that can be reverted on failure.
  * The value updates immediately, then reverts if the async operation fails.
  *
- * Note: concurrent optimistic updates on the same value are inherently
- * ambiguous. If multiple operations are in flight, a failed revert restores
- * the value captured before that specific operation started.
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const likes = optimistic(42);
+ *
+ * button(
+ *   { on: { click: () => likes.update(likes.value() + 1, () => api.like()) } },
+ *   () => `${likes.value()} ${likes.pending() ? "(saving…)" : ""}`,
+ * );
+ * ```
  */
-declare function optimistic<T>(initialValue: T): [() => T, (optimisticValue: T, asyncAction: () => Promise<T>) => Promise<void>];
+declare function optimistic<T>(initialValue: T): {
+    value: () => T;
+    pending: () => boolean;
+    update: (optimisticValue: T, asyncAction: () => Promise<T>) => Promise<void>;
+};
 /**
  * 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
- * reverts to a snapshot taken before the operation started.
+ * uses a version guard so stale reverts don't overwrite newer state.
+ *
+ * @example
+ * ```ts
+ * const todos = optimisticList<Todo>([]);
+ *
+ * todos.add(
+ *   { id: tempId(), text: "New" },
+ *   async () => api.createTodo("New"),
+ * );
+ *
+ * div([
+ *   () => todos.pending() ? span("Saving…") : null,
+ *   each(() => todos.items(), (t) => div(t().text), { key: (t) => t.id }),
+ * ]);
+ * ```
  */
 declare function optimisticList<T>(initialValue: T[]): {
     items: () => T[];
-    addOptimistic: (item: T, asyncAction: () => Promise<T>) => Promise<void>;
-    removeOptimistic: (predicate: (item: T) => boolean, asyncAction: () => Promise<void>) => Promise<void>;
-    updateOptimistic: (predicate: (item: T) => boolean, update: Partial<T>, asyncAction: () => Promise<T>) => Promise<void>;
+    pending: () => boolean;
+    add: (item: T, asyncAction: () => Promise<T>) => Promise<void>;
+    remove: (predicate: (item: T) => boolean, asyncAction: () => Promise<void>) => Promise<void>;
+    update: (predicate: (item: T) => boolean, patch: Partial<T>, asyncAction: () => Promise<T>) => Promise<void>;
 };
 
 interface TimeTravelReturn<T> {
@@ -151,4 +184,4 @@ declare function globalStore<S extends Record<string, unknown>, A extends Record
     middleware?: Middleware<S>[];
 }): GlobalStore<S, A>;
 
-export { type GlobalStore, type MachineConfig, type MachineReturn, type Middleware, type OptimisticAction, 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 TimeTravelReturn, globalStore, machine, optimistic, optimisticList, persisted, timeline };

package/dist/patterns.d.ts

@@ -1,4 +1,4 @@
-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-xo5ckdRP.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-ey_Qh8ef.js';
 
 interface MachineConfig<S extends string, E extends string, C extends Record<string, unknown> = Record<string, unknown>> {
     initial: S;
@@ -71,48 +71,81 @@ interface PersistOptions<T = unknown> {
      *  - use XOR with a static key — trivially reversible
      *  - roll your own cipher — nearly always broken
      *
+     * **Sync only:** because `persisted()` exposes synchronous getters and
+     * setters, both `encrypt` and `decrypt` must be SYNCHRONOUS. Async
+     * crypto (e.g. `crypto.subtle.encrypt`) is NOT supported here — derive
+     * keys ahead of time and use a sync wrapper, or pre/post-process the
+     * value yourself before/after `setValue`.
+     *
      * @example
      * ```ts
+     * // Pre-derived key + sync wrapper
      * persisted("token", "", {
-     *   encrypt: async (v) => aesGcmEncrypt(v, await getKey()),
-     *   decrypt: async (v) => aesGcmDecrypt(v, await getKey()),
+     *   encrypt: (v) => syncAesGcmEncrypt(v, derivedKey),
+     *   decrypt: (v) => syncAesGcmDecrypt(v, derivedKey),
      * });
      * ```
-     *
-     * Note that because localStorage is synchronous, any real AES-GCM
-     * flow needs pre-derived keys and is inherently best-effort.
      */
     encrypt?: (value: string) => string;
-    /** Decrypt the stored value before deserialization. Required if `encrypt` is set. */
+    /** Decrypt the stored value before deserialization. Required if `encrypt` is set.
+     *  Must be synchronous — see `encrypt` docs. */
     decrypt?: (value: string) => string;
 }
 declare function persisted<T>(key: string, initial: T, options?: PersistOptions<T>): [() => T, (next: T | ((prev: T) => T)) => void];
 
-interface OptimisticAction<T> {
-    optimisticValue: T;
-    revert: T;
-}
 /**
  * optimistic provides optimistic UI updates that can be reverted on failure.
  * The value updates immediately, then reverts if the async operation fails.
  *
- * Note: concurrent optimistic updates on the same value are inherently
- * ambiguous. If multiple operations are in flight, a failed revert restores
- * the value captured before that specific operation started.
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const likes = optimistic(42);
+ *
+ * button(
+ *   { on: { click: () => likes.update(likes.value() + 1, () => api.like()) } },
+ *   () => `${likes.value()} ${likes.pending() ? "(saving…)" : ""}`,
+ * );
+ * ```
  */
-declare function optimistic<T>(initialValue: T): [() => T, (optimisticValue: T, asyncAction: () => Promise<T>) => Promise<void>];
+declare function optimistic<T>(initialValue: T): {
+    value: () => T;
+    pending: () => boolean;
+    update: (optimisticValue: T, asyncAction: () => Promise<T>) => Promise<void>;
+};
 /**
  * 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
- * reverts to a snapshot taken before the operation started.
+ * uses a version guard so stale reverts don't overwrite newer state.
+ *
+ * @example
+ * ```ts
+ * const todos = optimisticList<Todo>([]);
+ *
+ * todos.add(
+ *   { id: tempId(), text: "New" },
+ *   async () => api.createTodo("New"),
+ * );
+ *
+ * div([
+ *   () => todos.pending() ? span("Saving…") : null,
+ *   each(() => todos.items(), (t) => div(t().text), { key: (t) => t.id }),
+ * ]);
+ * ```
  */
 declare function optimisticList<T>(initialValue: T[]): {
     items: () => T[];
-    addOptimistic: (item: T, asyncAction: () => Promise<T>) => Promise<void>;
-    removeOptimistic: (predicate: (item: T) => boolean, asyncAction: () => Promise<void>) => Promise<void>;
-    updateOptimistic: (predicate: (item: T) => boolean, update: Partial<T>, asyncAction: () => Promise<T>) => Promise<void>;
+    pending: () => boolean;
+    add: (item: T, asyncAction: () => Promise<T>) => Promise<void>;
+    remove: (predicate: (item: T) => boolean, asyncAction: () => Promise<void>) => Promise<void>;
+    update: (predicate: (item: T) => boolean, patch: Partial<T>, asyncAction: () => Promise<T>) => Promise<void>;
 };
 
 interface TimeTravelReturn<T> {
@@ -151,4 +184,4 @@ declare function globalStore<S extends Record<string, unknown>, A extends Record
     middleware?: Middleware<S>[];
 }): GlobalStore<S, A>;
 
-export { type GlobalStore, type MachineConfig, type MachineReturn, type Middleware, type OptimisticAction, 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 TimeTravelReturn, globalStore, machine, optimistic, optimisticList, persisted, timeline };

package/dist/patterns.js

@@ -5,7 +5,7 @@ import {
   optimisticList,
   persisted,
   timeline
-} from "./chunk-ZWKZCBO6.js";
+} from "./chunk-3LR7GLWQ.js";
 import {
   RenderProp,
   assertType,
@@ -22,12 +22,12 @@ import {
   withProps,
   withWrapper
 } from "./chunk-CNZ35WI2.js";
-import "./chunk-NEKUBFPT.js";
-import "./chunk-CHF5OHIA.js";
-import "./chunk-EUZND3CB.js";
-import "./chunk-WZSPOOER.js";
-import "./chunk-ZD6OAMTH.js";
-import "./chunk-5X6PP2UK.js";
+import "./chunk-54EDRCEF.js";
+import "./chunk-HB24TBAF.js";
+import "./chunk-2RA7SHDA.js";
+import "./chunk-CC65Y57T.js";
+import "./chunk-VLPPXTYG.js";
+import "./chunk-LMLD24FC.js";
 export {
   RenderProp,
   assertType,