sibujs 4.6.0 → 4.8.0

package/dist/data.d.ts

@@ -57,6 +57,43 @@ declare function calculateDelay(attempt: number, strategy: "exponential" | "line
  */
 declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions, onRetry?: (error: unknown, attempt: number, delay: number) => void, signal?: AbortSignal): Promise<T>;
 
+/**
+ * Structural sharing for the data layer.
+ *
+ * A refetch almost always produces a brand-new object graph, even when the
+ * server sent back exactly what it sent last time. Committing that graph to a
+ * signal notifies every subscriber — signals compare with `Object.is` — so a
+ * background refresh that changed nothing still re-ran every binding reading
+ * the data, and a `when(() => q.data(), …)` or a `() => q.data() && Form()`
+ * child rebuilt its subtree and threw away whatever the user was typing.
+ *
+ * `replaceEqualDeep(prev, next)` reconciles the new graph against the old one:
+ *
+ * - deeply equal → returns `prev` itself, so the signal write is a no-op and
+ *   nothing is notified;
+ * - partially equal → returns a new container in which every unchanged
+ *   subtree is the OLD reference, so an `each()` keyed by reference, a
+ *   `derived` over one branch, or an `equals`-less signal holding a sub-object
+ *   stays stable while only the changed path gets fresh identities.
+ *
+ * Only plain objects (prototype `Object.prototype` or `null`) and arrays are
+ * reconciled. Everything else — Date, Map, Set, class instances — is opaque
+ * and compared by identity: its enumerable keys say nothing about its state,
+ * and rebuilding it as a plain object would change its type.
+ *
+ * Internal to the data layer; not re-exported from `data.ts`.
+ */
+/**
+ * The public knob shared by `query()` and `resource()`.
+ *
+ * - `true` (default) — reconcile with {@link replaceEqualDeep}.
+ * - `false` — commit every result as-is (a fresh reference notifies).
+ * - a function — custom reconciliation. It receives the previously committed
+ *   value and the new one and returns what to commit; returning `prev` means
+ *   "unchanged" and notifies nobody.
+ */
+type StructuralSharingOption<T> = boolean | ((prev: T, next: T) => T);
+
 /**
  * ## Callback semantics
  *
@@ -118,8 +155,52 @@ interface QueryOptions<T> {
     onError?: (error: Error) => void;
     /** Called on fetch settle (success or error) */
     onSettled?: () => void;
-    /** Transform fetched data before returning to consumers. Cache stores raw data. */
+    /**
+     * Transform fetched data before returning to consumers. Cache stores raw data.
+     *
+     * Runs in this observer's own reactive computation: it re-runs when the
+     * cached value changes, and when a signal it reads changes — without
+     * re-running the key effect, so such a signal never triggers a refetch. It
+     * runs once per fetch that changed the data, and its output is structurally
+     * shared against this observer's previous output for the same key, so an
+     * identical refetch notifies nobody.
+     */
     select?: (data: T) => T;
+    /**
+     * Keep data referentially stable across refetches. Default: `true`.
+     *
+     * Every refetch — `refetchInterval`, window focus, reconnect,
+     * `invalidateQueries` — produces a new object graph even when the server
+     * returned the same thing. With structural sharing on, the new result is
+     * reconciled against the previous value of the same key: if it is deeply
+     * equal the previous reference is kept and `data` subscribers are not
+     * notified at all; if only part of it changed, every unchanged nested object
+     * or array keeps its old reference, so `each()` rows and deriveds over
+     * untouched branches stay put. Only plain objects and arrays are compared —
+     * Date, Map, Set and class instances compare by identity. Cyclic data is
+     * safe: the containers on a cycle are taken as-is.
+     *
+     * Every observer of a key using the default holds the SAME reference.
+     *
+     * `setQueryData()` is an explicit write, not a fetch: when it hands over a
+     * new top-level reference, observers always receive a new top-level
+     * reference and are notified — even if every child is unchanged, as after
+     * `prev.items.push(x); return { ...prev }`. Unchanged nested subtrees are
+     * still reused beneath it.
+     *
+     * The option applies to this observer only; observers of one key may use
+     * different settings.
+     *
+     * - `false` commits every result as-is (each refetch notifies).
+     * - A function `(prev, next) => T` replaces the default reconciliation;
+     *   `prev` is this observer's previous value for the same key. Return `prev`
+     *   to report "unchanged" (ignored for an explicit write of a new
+     *   reference). It must not throw — if it does, the error is reported and
+     *   `next` is committed unshared.
+     *
+     * Also applied to this observer's `select` output.
+     */
+    structuralSharing?: StructuralSharingOption<T>;
 }
 interface QueryResult<T> {
     /** Reactive getter for the cached data */
@@ -143,9 +224,20 @@ declare function query<T>(key: string | (() => string), fetcher: (ctx: {
 }) => Promise<T>, options?: QueryOptions<T>): QueryResult<T>;
 /** Invalidate queries matching a key or predicate, triggering refetch for active subscribers */
 declare function invalidateQueries(keyOrPredicate: string | ((key: string) => boolean)): void;
-/** Get cached data for a query key */
+/**
+ * Get cached data for a query key — the same reference every observer using
+ * the default `structuralSharing` holds.
+ */
 declare function getQueryData<T>(key: string): T | undefined;
-/** Set cached data for a query key, notifying subscribers */
+/**
+ * Set cached data for a query key, notifying subscribers.
+ *
+ * An explicit write: a value (or updater result) that is a new top-level
+ * reference reaches every observer as a new top-level reference, even when it
+ * is deeply equal to the previous value — so `prev.items.push(x); return
+ * { ...prev }` is never dropped. Unchanged nested subtrees are still reused.
+ * Returning `prev` itself changes nothing.
+ */
 declare function setQueryData<T>(key: string, data: T | ((prev: T | undefined) => T)): void;
 /** Clear the entire query cache */
 declare function clearQueryCache(): void;
@@ -354,6 +446,30 @@ interface ResourceOptions<T> {
     onError?: (error: Error) => void;
     /** Called on fetch settle (success or error) */
     onSettled?: () => void;
+    /**
+     * Keep data referentially stable across refetches. Default: `true`.
+     *
+     * Each fetched result — from `refetch()` or a source change — is
+     * reconciled against the value already held: a deeply equal result keeps
+     * the previous reference and notifies nobody, and a partially changed one
+     * reuses every unchanged nested object or array. Only plain objects and
+     * arrays are compared; Date, Map, Set and class instances compare by
+     * identity. Cyclic data is safe: the containers on a cycle are taken as-is.
+     * Same contract as `QueryOptions.structuralSharing`.
+     *
+     * `mutate()` is an explicit write, not a fetch: when it hands over a new
+     * top-level reference, `data` always becomes a new top-level reference and
+     * notifies — even if every child is unchanged, as after
+     * `prev.items.push(x); return { ...prev }`. Unchanged nested subtrees are
+     * still reused beneath it.
+     *
+     * - `false` commits every result as-is.
+     * - A function `(prev, next) => T` replaces the default reconciliation;
+     *   return `prev` to report "unchanged" (ignored for a `mutate()` of a new
+     *   reference). If it throws, the error is reported and `next` is committed
+     *   unshared.
+     */
+    structuralSharing?: StructuralSharingOption<T>;
 }
 interface Resource<T> {
     /** Reactive getter for the fetched data */

package/dist/data.js

@@ -22,14 +22,14 @@ import {
   throttle,
   withLoader,
   withRetry
-} from "./chunk-PK6FK2G2.js";
-import "./chunk-QE4TTDU3.js";
-import "./chunk-2INLLLMZ.js";
+} from "./chunk-UCNP3HVM.js";
+import "./chunk-KJ3UKABJ.js";
 import "./chunk-7ZHH77QA.js";
-import "./chunk-XC4MEKGA.js";
+import "./chunk-V3LHZSU5.js";
+import "./chunk-EXXSN3BW.js";
 import "./chunk-7XHATCIH.js";
-import "./chunk-D33YTSX5.js";
-import "./chunk-5Q4R7HCL.js";
+import "./chunk-DSID757X.js";
+import "./chunk-TQQUN4WR.js";
 import "./chunk-NYNYSPK7.js";
 export {
   __resetQueryCache,

package/dist/devtools.cjs

@@ -844,7 +844,7 @@ function forEachSubscriber(signal2, visit) {
 }
 
 // src/reactivity/track.ts
-var _runtimeVersion = true ? "4.6.0" : "dev";
+var _runtimeVersion = true ? "4.8.0" : "dev";
 var REGISTRY_KEY = /* @__PURE__ */ Symbol.for("sibujs.reactive.v1");
 function resolveReactiveApi() {
   const g = globalThis;
@@ -950,6 +950,14 @@ var batch = API2.batch;
 var enqueueBatchedSignal = API2.enqueueBatchedSignal;
 var isBatching = API2.isBatching;
 
+// src/core/devtoolsHook.ts
+function emitDevtools(hook, event, payload) {
+  try {
+    hook.emit(event, payload);
+  } catch {
+  }
+}
+
 // src/core/signals/signal.ts
 var _g = globalThis;
 function signal(initial, options) {
@@ -983,7 +991,7 @@ function signal(initial, options) {
       state2.__v++;
       if (DEV) {
         const hook = _g.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
-        if (hook) hook.emit("signal:update", { signal: state2, name: debugName, oldValue: prev, newValue });
+        if (hook) emitDevtools(hook, "signal:update", { signal: state2, name: debugName, oldValue: prev, newValue });
       }
       if (!enqueueBatchedSignal(state2)) {
         notifySubscribers2(state2);
@@ -997,7 +1005,7 @@ function signal(initial, options) {
       state2.value = newValue;
       state2.__v++;
       const hook = _g.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
-      if (hook) hook.emit("signal:update", { signal: state2, name: debugName, oldValue: prev, newValue });
+      if (hook) emitDevtools(hook, "signal:update", { signal: state2, name: debugName, oldValue: prev, newValue });
       if (!enqueueBatchedSignal(state2)) {
         notifySubscribers2(state2);
       }
@@ -1016,7 +1024,7 @@ function signal(initial, options) {
   }
   if (DEV) {
     const hook = _g.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
-    if (hook) hook.emit("signal:create", { signal: state2, name: debugName, getter: get, initial });
+    if (hook) emitDevtools(hook, "signal:create", { signal: state2, name: debugName, getter: get, initial });
   }
   return [get, set];
 }
@@ -2164,12 +2172,17 @@ function effect(effectFn, options) {
   try {
     retrack2(ctx.bodyFn, ctx.subscriber);
     if (ctx.rerunPending) drainReruns(ctx);
+  } catch (err) {
+    ctx.disposed = true;
+    if (ctx.userCleanups.length > 0) flushUserCleanups(ctx);
+    cleanup2(ctx.subscriber);
+    throw err;
   } finally {
     ctx.running = false;
     ctx.rerunPending = false;
   }
   const hook = _g2.__SIBU_DEVTOOLS_GLOBAL_HOOK__;
-  if (hook) hook.emit("effect:create", { effectFn });
+  if (hook) emitDevtools(hook, "effect:create", { effectFn });
   return () => disposeEffect(ctx);
 }
 

package/dist/devtools.js

@@ -35,13 +35,13 @@ import {
   trackCleanup,
   walkDependencyGraph,
   withErrorTracking
-} from "./chunk-7NCARGJW.js";
-import "./chunk-2INLLLMZ.js";
+} from "./chunk-44MTL7ED.js";
 import "./chunk-7ZHH77QA.js";
-import "./chunk-XC4MEKGA.js";
+import "./chunk-V3LHZSU5.js";
+import "./chunk-EXXSN3BW.js";
 import "./chunk-7XHATCIH.js";
-import "./chunk-D33YTSX5.js";
-import "./chunk-5Q4R7HCL.js";
+import "./chunk-DSID757X.js";
+import "./chunk-TQQUN4WR.js";
 import {
   isDev
 } from "./chunk-NYNYSPK7.js";