sibujs 3.4.0 → 4.0.0

package/dist/performance.d.cts

@@ -1,5 +1,5 @@
-import { T as TrustedHTML } from './ssr-D62yFwuw.cjs';
-export { t as trustHTML } from './ssr-D62yFwuw.cjs';
+import { T as TrustedHTML } from './ssr-BiPRdZ6n.cjs';
+export { t as trustHTML } from './ssr-BiPRdZ6n.cjs';
 
 declare const Priority: {
     readonly IMMEDIATE: 0;
@@ -283,7 +283,7 @@ interface NormalizedStoreActions<T> {
  * const bobs = users.select(u => u.name.startsWith("B"));
  * ```
  */
-declare function normalizedStore<T extends Record<string, unknown>>(schema: NormalizedSchema): NormalizedStoreActions<T>;
+declare function normalizedStore<T extends object>(schema: NormalizedSchema): NormalizedStoreActions<T>;
 /** A map of entity type names to their flat entity tables */
 type NormalizedEntities = Record<string, Record<string, unknown>>;
 /** Result of normalizing nested data */
@@ -328,7 +328,7 @@ interface NormalizeResult {
  * // entities.comment["c1"] === { id: "c1", text: "Great!" }
  * ```
  */
-declare function normalize<T extends Record<string, unknown>>(data: T | T[], schema: NormalizedSchema): NormalizeResult;
+declare function normalize<T extends object>(data: T | T[], schema: NormalizedSchema): NormalizeResult;
 /**
  * denormalize reconstructs a nested object from a flat normalized entities
  * map, resolving relation references back to their full objects.
@@ -345,7 +345,7 @@ declare function normalize<T extends Record<string, unknown>>(data: T | T[], sch
  * // post.comments is an array of full comment objects
  * ```
  */
-declare function denormalize<T extends Record<string, unknown>>(id: string, entities: NormalizedEntities, schema: NormalizedSchema): T | undefined;
+declare function denormalize<T extends object>(id: string, entities: NormalizedEntities, schema: NormalizedSchema): T | undefined;
 
 /**
  * Advanced runtime chunk loading with caching strategies for SibuJS.
@@ -371,6 +371,44 @@ interface ChunkConfig {
 }
 /**
  * Central registry for managing dynamic chunks with caching and lifecycle callbacks.
+ *
+ * INVALIDATION IS A PUBLICATION BARRIER
+ * ------------------------------------
+ * `invalidate(id)` and `clear()` used to delete cache entries and leave the
+ * `pending` map untouched, so an in-flight load that started *before* the
+ * invalidation still ran its `.then` afterwards and wrote the now-stale value
+ * back into the cache. The sequence
+ *
+ *     load("a") starts → clear() → old load resolves → cache.set("a", stale)
+ *
+ * left `has("a") === true` holding data the caller had explicitly discarded.
+ * The same load also ran `pending.delete(id)` unconditionally, so a *newer*
+ * pending entry for the same id was removed by its predecessor's settlement.
+ * And because the stale promise stayed in `pending`, a `load(id, freshLoader)`
+ * issued after the invalidation deduplicated against it: the new loader was
+ * never called and the caller received the stale value.
+ *
+ * OWNERSHIP IS THE PENDING ENTRY ITSELF. Each load creates an entry object and
+ * installs it in `pending`; that object *is* the load's claim on the key.
+ * `invalidate(id)` removes the key's entry and `clear()` removes all of them,
+ * which revokes the claim without needing a generation counter or any map that
+ * grows over time. On settlement a load re-reads `pending.get(id)` and only
+ * publishes or cleans up when it finds its own entry still there.
+ *
+ * Work started before an invalidation still resolves or rejects normally *for
+ * its original caller* — it simply cannot touch shared state any more. Nothing
+ * is cancelled: the loader API takes no abort signal, so no cancellation is
+ * claimed here.
+ *
+ * LIFECYCLE CALLBACKS ARE OBSERVERS
+ * ---------------------------------
+ * `onLoadStart` / `onLoadEnd` / `onLoadError` used to run inside the operation's
+ * control flow. `onLoadStart` ran before the loader, so a throwing one stopped
+ * the load from ever starting; `onLoadEnd` ran inside the `.then`, so a throwing
+ * one converted a cached success into a rejection *and* then delivered the
+ * observer's own error to `onLoadError`, leaving the caller told "failed" while
+ * the cache held the value. Every callback now runs through `notify`, which
+ * contains and reports the failure without letting it reach the operation.
  */
 declare function createChunkRegistry(config?: ChunkConfig): {
     load: <T>(id: string, loader: () => Promise<T>) => Promise<T>;
@@ -391,15 +429,25 @@ declare function createChunkRegistry(config?: ChunkConfig): {
      */
     get<T>(id: string): T | undefined;
     /**
-     * Invalidate a cached chunk.
+     * Invalidate a cached chunk, and supersede any load still in flight for it.
+     *
+     * In-flight work is not cancelled — the loader API takes no abort signal, so
+     * claiming cancellation would be a lie. It is *superseded*: it still settles
+     * for whoever called `load()`, but it can no longer write to the cache, and
+     * a subsequent `load(id, …)` starts fresh work rather than adopting it.
      */
     invalidate(id: string): void;
     /**
-     * Clear all cached chunks.
+     * Clear all cached chunks, and supersede every load still in flight.
+     *
+     * Same barrier as `invalidate`, applied to every key at once.
      */
     clear(): void;
     /**
      * Get cache statistics.
+     *
+     * Describes currently OWNED state: superseded loads are already absent from
+     * `pending`, so the counts never include work whose result will be discarded.
      */
     stats(): {
         size: number;

package/dist/performance.d.ts

@@ -1,5 +1,5 @@
-import { T as TrustedHTML } from './ssr-D62yFwuw.js';
-export { t as trustHTML } from './ssr-D62yFwuw.js';
+import { T as TrustedHTML } from './ssr-BiPRdZ6n.js';
+export { t as trustHTML } from './ssr-BiPRdZ6n.js';
 
 declare const Priority: {
     readonly IMMEDIATE: 0;
@@ -283,7 +283,7 @@ interface NormalizedStoreActions<T> {
  * const bobs = users.select(u => u.name.startsWith("B"));
  * ```
  */
-declare function normalizedStore<T extends Record<string, unknown>>(schema: NormalizedSchema): NormalizedStoreActions<T>;
+declare function normalizedStore<T extends object>(schema: NormalizedSchema): NormalizedStoreActions<T>;
 /** A map of entity type names to their flat entity tables */
 type NormalizedEntities = Record<string, Record<string, unknown>>;
 /** Result of normalizing nested data */
@@ -328,7 +328,7 @@ interface NormalizeResult {
  * // entities.comment["c1"] === { id: "c1", text: "Great!" }
  * ```
  */
-declare function normalize<T extends Record<string, unknown>>(data: T | T[], schema: NormalizedSchema): NormalizeResult;
+declare function normalize<T extends object>(data: T | T[], schema: NormalizedSchema): NormalizeResult;
 /**
  * denormalize reconstructs a nested object from a flat normalized entities
  * map, resolving relation references back to their full objects.
@@ -345,7 +345,7 @@ declare function normalize<T extends Record<string, unknown>>(data: T | T[], sch
  * // post.comments is an array of full comment objects
  * ```
  */
-declare function denormalize<T extends Record<string, unknown>>(id: string, entities: NormalizedEntities, schema: NormalizedSchema): T | undefined;
+declare function denormalize<T extends object>(id: string, entities: NormalizedEntities, schema: NormalizedSchema): T | undefined;
 
 /**
  * Advanced runtime chunk loading with caching strategies for SibuJS.
@@ -371,6 +371,44 @@ interface ChunkConfig {
 }
 /**
  * Central registry for managing dynamic chunks with caching and lifecycle callbacks.
+ *
+ * INVALIDATION IS A PUBLICATION BARRIER
+ * ------------------------------------
+ * `invalidate(id)` and `clear()` used to delete cache entries and leave the
+ * `pending` map untouched, so an in-flight load that started *before* the
+ * invalidation still ran its `.then` afterwards and wrote the now-stale value
+ * back into the cache. The sequence
+ *
+ *     load("a") starts → clear() → old load resolves → cache.set("a", stale)
+ *
+ * left `has("a") === true` holding data the caller had explicitly discarded.
+ * The same load also ran `pending.delete(id)` unconditionally, so a *newer*
+ * pending entry for the same id was removed by its predecessor's settlement.
+ * And because the stale promise stayed in `pending`, a `load(id, freshLoader)`
+ * issued after the invalidation deduplicated against it: the new loader was
+ * never called and the caller received the stale value.
+ *
+ * OWNERSHIP IS THE PENDING ENTRY ITSELF. Each load creates an entry object and
+ * installs it in `pending`; that object *is* the load's claim on the key.
+ * `invalidate(id)` removes the key's entry and `clear()` removes all of them,
+ * which revokes the claim without needing a generation counter or any map that
+ * grows over time. On settlement a load re-reads `pending.get(id)` and only
+ * publishes or cleans up when it finds its own entry still there.
+ *
+ * Work started before an invalidation still resolves or rejects normally *for
+ * its original caller* — it simply cannot touch shared state any more. Nothing
+ * is cancelled: the loader API takes no abort signal, so no cancellation is
+ * claimed here.
+ *
+ * LIFECYCLE CALLBACKS ARE OBSERVERS
+ * ---------------------------------
+ * `onLoadStart` / `onLoadEnd` / `onLoadError` used to run inside the operation's
+ * control flow. `onLoadStart` ran before the loader, so a throwing one stopped
+ * the load from ever starting; `onLoadEnd` ran inside the `.then`, so a throwing
+ * one converted a cached success into a rejection *and* then delivered the
+ * observer's own error to `onLoadError`, leaving the caller told "failed" while
+ * the cache held the value. Every callback now runs through `notify`, which
+ * contains and reports the failure without letting it reach the operation.
  */
 declare function createChunkRegistry(config?: ChunkConfig): {
     load: <T>(id: string, loader: () => Promise<T>) => Promise<T>;
@@ -391,15 +429,25 @@ declare function createChunkRegistry(config?: ChunkConfig): {
      */
     get<T>(id: string): T | undefined;
     /**
-     * Invalidate a cached chunk.
+     * Invalidate a cached chunk, and supersede any load still in flight for it.
+     *
+     * In-flight work is not cancelled — the loader API takes no abort signal, so
+     * claiming cancellation would be a lie. It is *superseded*: it still settles
+     * for whoever called `load()`, but it can no longer write to the cache, and
+     * a subsequent `load(id, …)` starts fresh work rather than adopting it.
      */
     invalidate(id: string): void;
     /**
-     * Clear all cached chunks.
+     * Clear all cached chunks, and supersede every load still in flight.
+     *
+     * Same barrier as `invalidate`, applied to every key at once.
      */
     clear(): void;
     /**
      * Get cache statistics.
+     *
+     * Describes currently OWNED state: superseded loads are already absent from
+     * `pending`, so the counts never include work whose result will be discarded.
      */
     stats(): {
         size: number;

package/dist/performance.js

@@ -33,18 +33,18 @@ import {
   transitionState,
   uniqueId,
   yieldToMain
-} from "./chunk-JCO7AHNU.js";
+} from "./chunk-3EKJK5FZ.js";
 import {
   trustHTML
-} from "./chunk-EX77FXTT.js";
+} from "./chunk-HYCCIYNS.js";
+import "./chunk-5INI7D2L.js";
 import "./chunk-7ZHH77QA.js";
-import "./chunk-L3GAGWCC.js";
-import "./chunk-BUKYCWHX.js";
-import "./chunk-S3NFJO6L.js";
-import "./chunk-5VGSK6D2.js";
-import "./chunk-KZBEVFXZ.js";
-import "./chunk-OOUQUCNN.js";
-import "./chunk-COY6PUD2.js";
+import "./chunk-PBQEW5VW.js";
+import "./chunk-TIRZCERI.js";
+import "./chunk-DHDZ7IVN.js";
+import "./chunk-W55YHPEP.js";
+import "./chunk-ACBT6UZS.js";
+import "./chunk-VPP2FONR.js";
 export {
   DOMPool,
   Features,