@blocksdiy/blocks-client-sdk 1.8.14 → 1.9.1

package/dist/ClientSdk.js

@@ -80,7 +80,7 @@ export class ClientSdk {
      */
     entity(entityConfig) {
         if (!this.entities.has(entityConfig.tableBlockId)) {
-            this.entities.set(entityConfig.tableBlockId, new Entity(entityConfig, { token: this.token }));
+            this.entities.set(entityConfig.tableBlockId, new Entity(entityConfig, { token: this.token, appId: this.appId }));
         }
         return this.entities.get(entityConfig.tableBlockId);
     }

package/dist/Entity.d.ts

@@ -58,9 +58,11 @@ export declare class Entity<EC extends EntityConfig = EntityConfig> {
      * Creates a new Entity instance
      * @param {EC} config - Configuration for the entity
      * @param {string} token - The token for the application
+     * @param {string} appId - The application id, sent as x-app-id on every request
      */
-    constructor(config: EC, { token }?: {
+    constructor(config: EC, { token, appId }?: {
         token?: string;
+        appId?: string;
     });
     /**
      * Retrieves a single entity by filters

package/dist/Entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Entity.d.ts","sourceRoot":"","sources":["../src/Entity.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,CAAC,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,YAAY,IAAI,CAAC,CAAC,cAAc,CAAC,CAAC;AAE9E;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,YAAY,IAAI,cAAc,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;AAE3F;;;;;;;;GAQG;AACH,qBAAa,MAAM,CAAC,EAAE,SAAS,YAAY,GAAG,YAAY;IACxD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAiB;IAEvC;;;;OAIG;gBACS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO;IAK1D;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAU1C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG;IAY5B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,IAAI,EAAE,qBAAqB,CAAC,EAAE,CAAC;IAU5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,UAAU,CAAC,IAAI,EAAE,qBAAqB,CAAC,EAAE,CAAC,EAAE;IAUlD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC;IAUvE;;;;;;;;;;;;;;;OAeG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM;IAS1B;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE;CAS/B"}
+{"version":3,"file":"Entity.d.ts","sourceRoot":"","sources":["../src/Entity.ts"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,CAAC,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,YAAY,IAAI,CAAC,CAAC,cAAc,CAAC,CAAC;AAE9E;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,YAAY,IAAI,cAAc,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;AAE3F;;;;;;;;GAQG;AACH,qBAAa,MAAM,CAAC,EAAE,SAAS,YAAY,GAAG,YAAY;IACxD,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAiB;IAEvC;;;;;OAKG;gBACS,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO;IAKjF;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAU1C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG;IAY5B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,MAAM,CAAC,IAAI,EAAE,qBAAqB,CAAC,EAAE,CAAC;IAU5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,UAAU,CAAC,IAAI,EAAE,qBAAqB,CAAC,EAAE,CAAC,EAAE;IAUlD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC;IAUvE;;;;;;;;;;;;;;;OAeG;IACG,SAAS,CAAC,EAAE,EAAE,MAAM;IAS1B;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE;CAS/B"}

package/dist/Entity.js

@@ -23,10 +23,11 @@ export class Entity {
      * Creates a new Entity instance
      * @param {EC} config - Configuration for the entity
      * @param {string} token - The token for the application
+     * @param {string} appId - The application id, sent as x-app-id on every request
      */
-    constructor(config, { token } = {}) {
+    constructor(config, { token, appId } = {}) {
         this.tableBlockId = config.tableBlockId;
-        this.dataApiService = new DataApiService({ token });
+        this.dataApiService = new DataApiService({ token, appId });
     }
     /**
      * Retrieves a single entity by filters

package/dist/EntityCache.d.ts

@@ -0,0 +1,162 @@
+import { QueryClient, QueryKey } from "@tanstack/react-query";
+export declare const ENTITIES_QUERY_KEY = "entities";
+/**
+ * Minimal shape of a server row required for cache reconciliation.
+ * Server rows always carry an id; updatedAt is used to discard out-of-order writes.
+ */
+export interface EntityCacheRow {
+    id: string | number;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
+export interface EntityWritePreparation {
+    /**
+     * Keys of table queries that must be (re-)invalidated after the cache write:
+     * queries with a fetch in flight (their response is of unknowable freshness) and
+     * queries already marked invalidated (writing to them would wrongly mark them fresh).
+     */
+    staleKeys: QueryKey[];
+}
+export type EntityQueriesSnapshot = [QueryKey, unknown][];
+export declare const entityTableKey: (tableBlockId: string) => QueryKey;
+/**
+ * Normalizes a mutation response into an array of cacheable rows.
+ *
+ * Server endpoints are inconsistent: create returns a single row, createMany returns
+ * an array, and the update endpoint returns an array of rows at runtime even though
+ * it is typed as a single entity. Anything we cannot recognize as row data is dropped,
+ * letting callers fall back to plain invalidation.
+ */
+export declare const normalizeRowsResult: (result: unknown) => EntityCacheRow[];
+export declare const sameId: (a: unknown, b: unknown) => boolean;
+/**
+ * Returns true when the incoming server row should replace the cached one.
+ * Rows updated concurrently can resolve out of order; updatedAt decides the winner.
+ * When timestamps are missing or unparsable we accept the incoming row (server data
+ * is more trustworthy than an undecidable comparison).
+ */
+export declare const isIncomingRowNewer: (existing: unknown, incoming: EntityCacheRow) => boolean;
+export declare const isListQueryKey: (queryKey: QueryKey, tableBlockId: string) => boolean;
+export declare const isUnfilteredListQueryKey: (queryKey: QueryKey, tableBlockId: string) => boolean;
+export declare const isFilteredListQueryKey: (queryKey: QueryKey, tableBlockId: string) => boolean;
+export declare const isOneQueryKey: (queryKey: QueryKey, tableBlockId: string) => boolean;
+/** Returns the id of a one-query keyed strictly by { id }, undefined for any other filter shape. */
+export declare const getOneQueryKeyId: (queryKey: QueryKey) => string | number | undefined;
+/**
+ * Writes canonical server rows into every cached query of the table.
+ *
+ * - Rows already present in a list (matched by id) are replaced when newer.
+ * - New rows are appended to unfiltered lists only (`appendNewToUnfilteredLists`),
+ *   matching the server's default `id ASC` ordering. Filtered lists never gain or
+ *   lose membership here - that is decided by `invalidateEntityQueriesAfterWrite`.
+ * - One-queries holding a row with the same id are replaced when newer; one-queries
+ *   keyed by `{ id }` that cached `null` are filled in with the row.
+ */
+export declare const applyEntityRowsUpserted: (queryClient: QueryClient, tableBlockId: string, rows: EntityCacheRow[], { appendNewToUnfilteredLists }: {
+    appendNewToUnfilteredLists: boolean;
+}) => void;
+/**
+ * Applies an optimistic partial patch to every cached copy of a row (lists and
+ * one-queries). The cached id and updatedAt always win over patch values: id so the
+ * row identity cannot change, and updatedAt so a caller-supplied timestamp (e.g. a
+ * whole row spread into the update payload, with a client clock ahead of the
+ * server) can never make `isIncomingRowNewer` reject the canonical server response.
+ */
+export declare const applyEntityRowPatch: (queryClient: QueryClient, tableBlockId: string, rowId: string | number, patch: Record<string, unknown>) => void;
+/**
+ * Removes rows from every cached list of the table and nulls out one-queries that
+ * held a deleted row. Removal by id is exact for filtered lists too - a deleted row
+ * can never re-match a filter.
+ */
+export declare const applyEntityRowsDeleted: (queryClient: QueryClient, tableBlockId: string, rowIds: (string | number)[]) => void;
+/**
+ * Seeds one-query cache entries for freshly written rows so a follow-up
+ * `useEntityGetOne(Entity, { id })` (or `useEntityGetOne(Entity, id)`) renders
+ * instantly without a fetch. Seeds both the raw id shape and the parseInt-normalized
+ * shape `useEntityGetOne` produces for string/number ids.
+ */
+export declare const seedEntityOneCaches: (queryClient: QueryClient, tableBlockId: string, rows: EntityCacheRow[]) => void;
+/**
+ * Whether the cache holds any query that direct row writes can keep fresh
+ * (unfiltered lists or one-queries). When none exist, fetching row data has nothing
+ * to update - filtered lists are refetched via invalidation regardless.
+ */
+export declare const hasDirectlyMaintainedEntityQueries: (queryClient: QueryClient, tableBlockId: string) => boolean;
+export declare const snapshotEntityQueries: (queryClient: QueryClient, tableBlockId: string) => EntityQueriesSnapshot;
+export declare const restoreEntityQueriesSnapshot: (queryClient: QueryClient, snapshot: EntityQueriesSnapshot) => void;
+/**
+ * Prepares the table cache for a direct write:
+ * - records which queries have a fetch in flight or are already invalidated (a
+ *   `setQueryData` write would mark them fresh, so they must be re-invalidated
+ *   afterwards via `invalidateEntityQueriesAfterWrite`),
+ * - cancels in-flight fetches of queries that already hold data, so a response
+ *   snapshotted before the mutation cannot overwrite the rows we are about to write.
+ *
+ * Fetches of queries without data (initial loads) are left running: cancelling them
+ * would strand the query in a non-fetching pending state.
+ */
+export declare const prepareEntityCacheWrite: (queryClient: QueryClient, tableBlockId: string) => Promise<EntityWritePreparation>;
+/**
+ * Single invalidation pass that re-syncs everything a direct cache write cannot
+ * decide on its own:
+ * - filtered lists (membership/order/limit semantics live on the server),
+ * - one-queries keyed by non-id filters (an update/create may change which row matches),
+ * - queries that had a fetch in flight while we wrote (their in-flight response is
+ *   of unknowable freshness and may carry an external change we cancelled).
+ *
+ * Unfiltered lists and id-keyed one-queries are NOT invalidated - they were fully
+ * reconciled from the server response, which is what saves the refetch round trips.
+ */
+export declare const invalidateEntityQueriesAfterWrite: (queryClient: QueryClient, tableBlockId: string, { staleKeys, filteredLists, nonIdOneQueries, deletedRowIds, }: {
+    staleKeys?: QueryKey[];
+    filteredLists?: boolean;
+    nonIdOneQueries?: boolean;
+    /**
+     * When set (delete flow), non-id one-queries are only invalidated if they cached
+     * one of these rows or currently hold null (which may be the optimistic removal
+     * of a deleted row, and another row may match the filter on the server).
+     */
+    deletedRowIds?: (string | number)[];
+}) => void;
+/** Full-table invalidation - the pre-optimistic behavior, kept as the safety fallback. */
+export declare const invalidateEntityTable: (queryClient: QueryClient, tableBlockId: string) => void;
+export interface EntityOptimisticContext {
+    snapshot: EntityQueriesSnapshot;
+    staleKeys: QueryKey[];
+}
+/**
+ * Optimistic phase of an update/delete mutation: cancel clobbering fetches, snapshot
+ * the table cache for rollback, then apply the optimistic change. Never throws - on
+ * any failure the optimistic change is rolled back and skipped, and the mutation
+ * proceeds (the success/error handlers still reconcile the cache).
+ */
+export declare const beginEntityOptimisticWrite: (queryClient: QueryClient, tableBlockId: string, applyOptimistic: () => void) => Promise<EntityOptimisticContext | undefined>;
+/**
+ * Error phase: restore the snapshot taken in `beginEntityOptimisticWrite`, then
+ * refetch the table since the server state is unknown after a failed request.
+ * `skipInvalidation` is for mutations rejected before any request was sent
+ * (e.g. client-side rate limiting) where the restored snapshot is already correct.
+ */
+export declare const rollbackEntityOptimisticWrite: (queryClient: QueryClient, tableBlockId: string, context: EntityOptimisticContext | undefined, { skipInvalidation }?: {
+    skipInvalidation?: boolean;
+}) => void;
+/**
+ * Success phase of a create/update mutation: writes the canonical rows returned by
+ * the server into the cache and invalidates only what a direct write cannot decide
+ * (filtered lists, non-id one-queries, queries that were mid-fetch). Falls back to
+ * full-table invalidation whenever the response is unusable or anything throws, so
+ * the worst case is exactly the previous always-refetch behavior.
+ */
+export declare const applyEntityCreateResult: (queryClient: QueryClient, tableBlockId: string, result: unknown, { appendNewToUnfilteredLists, extraStaleKeys, }: {
+    appendNewToUnfilteredLists: boolean;
+    extraStaleKeys?: QueryKey[];
+}) => Promise<void>;
+/**
+ * Success phase of a delete mutation: removes the rows from every cached query.
+ * Filtered lists are still refetched because server-side filters may involve
+ * limits/pagination that removal alone cannot reconcile.
+ */
+export declare const applyEntityDeleteResult: (queryClient: QueryClient, tableBlockId: string, rowIds: (string | number)[], { extraStaleKeys }?: {
+    extraStaleKeys?: QueryKey[];
+}) => Promise<void>;
+//# sourceMappingURL=EntityCache.d.ts.map

package/dist/EntityCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityCache.d.ts","sourceRoot":"","sources":["../src/EntityCache.ts"],"names":[],"mappings":"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"}

package/dist/EntityCache.js

@@ -0,0 +1,377 @@
+import { hashKey } from "@tanstack/react-query";
+export const ENTITIES_QUERY_KEY = "entities";
+const ONE_SEGMENT = "one";
+export const entityTableKey = (tableBlockId) => [ENTITIES_QUERY_KEY, tableBlockId];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isValidRow = (value) => isRecord(value) && (typeof value.id === "string" || typeof value.id === "number");
+/**
+ * Normalizes a mutation response into an array of cacheable rows.
+ *
+ * Server endpoints are inconsistent: create returns a single row, createMany returns
+ * an array, and the update endpoint returns an array of rows at runtime even though
+ * it is typed as a single entity. Anything we cannot recognize as row data is dropped,
+ * letting callers fall back to plain invalidation.
+ */
+export const normalizeRowsResult = (result) => {
+    if (Array.isArray(result)) {
+        return result.filter(isValidRow);
+    }
+    return isValidRow(result) ? [result] : [];
+};
+export const sameId = (a, b) => (typeof a === "string" || typeof a === "number") &&
+    (typeof b === "string" || typeof b === "number") &&
+    String(a) === String(b);
+/**
+ * Returns true when the incoming server row should replace the cached one.
+ * Rows updated concurrently can resolve out of order; updatedAt decides the winner.
+ * When timestamps are missing or unparsable we accept the incoming row (server data
+ * is more trustworthy than an undecidable comparison).
+ */
+export const isIncomingRowNewer = (existing, incoming) => {
+    if (!isRecord(existing) || typeof existing.updatedAt !== "string" || typeof incoming.updatedAt !== "string") {
+        return true;
+    }
+    const existingTime = Date.parse(existing.updatedAt);
+    const incomingTime = Date.parse(incoming.updatedAt);
+    if (Number.isNaN(existingTime) || Number.isNaN(incomingTime)) {
+        return true;
+    }
+    return incomingTime >= existingTime;
+};
+/* Query key classification.
+ * List queries:   [ENTITIES_QUERY_KEY, tableBlockId, filters?]            (length 3, filters may be undefined)
+ * One queries:    [ENTITIES_QUERY_KEY, tableBlockId, "one", filters]      (length 4)
+ */
+const isTableKey = (queryKey, tableBlockId) => Array.isArray(queryKey) && queryKey[0] === ENTITIES_QUERY_KEY && queryKey[1] === tableBlockId;
+export const isListQueryKey = (queryKey, tableBlockId) => isTableKey(queryKey, tableBlockId) && queryKey.length === 3 && queryKey[2] !== ONE_SEGMENT;
+export const isUnfilteredListQueryKey = (queryKey, tableBlockId) => isListQueryKey(queryKey, tableBlockId) && queryKey[2] == null;
+export const isFilteredListQueryKey = (queryKey, tableBlockId) => isListQueryKey(queryKey, tableBlockId) && queryKey[2] != null;
+export const isOneQueryKey = (queryKey, tableBlockId) => isTableKey(queryKey, tableBlockId) && queryKey.length === 4 && queryKey[2] === ONE_SEGMENT;
+/** Returns the id of a one-query keyed strictly by { id }, undefined for any other filter shape. */
+export const getOneQueryKeyId = (queryKey) => {
+    const filters = queryKey[3];
+    if (!isRecord(filters)) {
+        return undefined;
+    }
+    const keys = Object.keys(filters);
+    if (keys.length !== 1 || keys[0] !== "id") {
+        return undefined;
+    }
+    const id = filters.id;
+    return typeof id === "string" || typeof id === "number" ? id : undefined;
+};
+const updateListData = (oldData, transform) => {
+    if (!Array.isArray(oldData)) {
+        // Bail out (undefined keeps the cache untouched) instead of corrupting non-list data.
+        return undefined;
+    }
+    return transform(oldData);
+};
+/**
+ * Writes canonical server rows into every cached query of the table.
+ *
+ * - Rows already present in a list (matched by id) are replaced when newer.
+ * - New rows are appended to unfiltered lists only (`appendNewToUnfilteredLists`),
+ *   matching the server's default `id ASC` ordering. Filtered lists never gain or
+ *   lose membership here - that is decided by `invalidateEntityQueriesAfterWrite`.
+ * - One-queries holding a row with the same id are replaced when newer; one-queries
+ *   keyed by `{ id }` that cached `null` are filled in with the row.
+ */
+export const applyEntityRowsUpserted = (queryClient, tableBlockId, rows, { appendNewToUnfilteredLists }) => {
+    if (rows.length === 0) {
+        return;
+    }
+    queryClient.setQueriesData({
+        queryKey: entityTableKey(tableBlockId),
+        predicate: (query) => isListQueryKey(query.queryKey, tableBlockId),
+    }, (oldData) => updateListData(oldData, (oldRows) => {
+        let changed = false;
+        const nextRows = oldRows.map((oldRow) => {
+            if (!isValidRow(oldRow)) {
+                return oldRow;
+            }
+            const incoming = rows.find((row) => sameId(row.id, oldRow.id));
+            if (!incoming || !isIncomingRowNewer(oldRow, incoming)) {
+                return oldRow;
+            }
+            changed = true;
+            return incoming;
+        });
+        return changed ? nextRows : undefined;
+    }));
+    if (appendNewToUnfilteredLists) {
+        queryClient.setQueriesData({
+            queryKey: entityTableKey(tableBlockId),
+            predicate: (query) => isUnfilteredListQueryKey(query.queryKey, tableBlockId),
+        }, (oldData) => updateListData(oldData, (oldRows) => {
+            const missingRows = rows.filter((row) => !oldRows.some((oldRow) => isValidRow(oldRow) && sameId(oldRow.id, row.id)));
+            return missingRows.length > 0 ? [...oldRows, ...missingRows] : undefined;
+        }));
+    }
+    queryClient
+        .getQueryCache()
+        .findAll({
+        queryKey: entityTableKey(tableBlockId),
+        predicate: (query) => isOneQueryKey(query.queryKey, tableBlockId),
+    })
+        .forEach((query) => {
+        queryClient.setQueryData(query.queryKey, (oldData) => {
+            if (isValidRow(oldData)) {
+                const incoming = rows.find((row) => sameId(row.id, oldData.id));
+                return incoming && isIncomingRowNewer(oldData, incoming) ? incoming : undefined;
+            }
+            if (oldData === null) {
+                const keyId = getOneQueryKeyId(query.queryKey);
+                const incoming = keyId === undefined ? undefined : rows.find((row) => sameId(row.id, keyId));
+                return incoming ?? undefined;
+            }
+            return undefined;
+        });
+    });
+};
+/**
+ * Applies an optimistic partial patch to every cached copy of a row (lists and
+ * one-queries). The cached id and updatedAt always win over patch values: id so the
+ * row identity cannot change, and updatedAt so a caller-supplied timestamp (e.g. a
+ * whole row spread into the update payload, with a client clock ahead of the
+ * server) can never make `isIncomingRowNewer` reject the canonical server response.
+ */
+export const applyEntityRowPatch = (queryClient, tableBlockId, rowId, patch) => {
+    const mergePatch = (row) => ({
+        ...row,
+        ...patch,
+        id: row.id,
+        updatedAt: row.updatedAt,
+    });
+    queryClient.setQueriesData({
+        queryKey: entityTableKey(tableBlockId),
+        predicate: (query) => isListQueryKey(query.queryKey, tableBlockId),
+    }, (oldData) => updateListData(oldData, (oldRows) => {
+        const hasMatch = oldRows.some((row) => isValidRow(row) && sameId(row.id, rowId));
+        if (!hasMatch) {
+            return undefined;
+        }
+        return oldRows.map((row) => (isValidRow(row) && sameId(row.id, rowId) ? mergePatch(row) : row));
+    }));
+    queryClient.setQueriesData({
+        queryKey: entityTableKey(tableBlockId),
+        predicate: (query) => isOneQueryKey(query.queryKey, tableBlockId),
+    }, (oldData) => (isValidRow(oldData) && sameId(oldData.id, rowId) ? mergePatch(oldData) : undefined));
+};
+/**
+ * Removes rows from every cached list of the table and nulls out one-queries that
+ * held a deleted row. Removal by id is exact for filtered lists too - a deleted row
+ * can never re-match a filter.
+ */
+export const applyEntityRowsDeleted = (queryClient, tableBlockId, rowIds) => {
+    if (rowIds.length === 0) {
+        return;
+    }
+    const isDeleted = (id) => rowIds.some((rowId) => sameId(rowId, id));
+    queryClient.setQueriesData({
+        queryKey: entityTableKey(tableBlockId),
+        predicate: (query) => isListQueryKey(query.queryKey, tableBlockId),
+    }, (oldData) => updateListData(oldData, (oldRows) => {
+        const nextRows = oldRows.filter((row) => !(isValidRow(row) && isDeleted(row.id)));
+        return nextRows.length !== oldRows.length ? nextRows : undefined;
+    }));
+    queryClient.setQueriesData({
+        queryKey: entityTableKey(tableBlockId),
+        predicate: (query) => isOneQueryKey(query.queryKey, tableBlockId),
+    }, (oldData) => {
+        if (isValidRow(oldData) && isDeleted(oldData.id)) {
+            return null;
+        }
+        return undefined;
+    });
+};
+/**
+ * Seeds one-query cache entries for freshly written rows so a follow-up
+ * `useEntityGetOne(Entity, { id })` (or `useEntityGetOne(Entity, id)`) renders
+ * instantly without a fetch. Seeds both the raw id shape and the parseInt-normalized
+ * shape `useEntityGetOne` produces for string/number ids.
+ */
+export const seedEntityOneCaches = (queryClient, tableBlockId, rows) => {
+    rows.forEach((row) => {
+        const idVariants = new Set([row.id]);
+        const numericId = typeof row.id === "string" && /^\d+$/.test(row.id) ? parseInt(row.id, 10) : row.id;
+        idVariants.add(numericId);
+        idVariants.forEach((id) => {
+            queryClient.setQueryData([ENTITIES_QUERY_KEY, tableBlockId, ONE_SEGMENT, { id }], (oldData) => oldData === undefined || oldData === null || (isValidRow(oldData) && isIncomingRowNewer(oldData, row))
+                ? row
+                : undefined);
+        });
+    });
+};
+/**
+ * Whether the cache holds any query that direct row writes can keep fresh
+ * (unfiltered lists or one-queries). When none exist, fetching row data has nothing
+ * to update - filtered lists are refetched via invalidation regardless.
+ */
+export const hasDirectlyMaintainedEntityQueries = (queryClient, tableBlockId) => queryClient.getQueryCache().findAll({
+    queryKey: entityTableKey(tableBlockId),
+    predicate: (query) => isUnfilteredListQueryKey(query.queryKey, tableBlockId) || isOneQueryKey(query.queryKey, tableBlockId),
+}).length > 0;
+export const snapshotEntityQueries = (queryClient, tableBlockId) => queryClient.getQueriesData({ queryKey: entityTableKey(tableBlockId) });
+export const restoreEntityQueriesSnapshot = (queryClient, snapshot) => {
+    snapshot.forEach(([queryKey, data]) => {
+        if (data !== undefined) {
+            queryClient.setQueryData(queryKey, data);
+        }
+    });
+};
+/**
+ * Prepares the table cache for a direct write:
+ * - records which queries have a fetch in flight or are already invalidated (a
+ *   `setQueryData` write would mark them fresh, so they must be re-invalidated
+ *   afterwards via `invalidateEntityQueriesAfterWrite`),
+ * - cancels in-flight fetches of queries that already hold data, so a response
+ *   snapshotted before the mutation cannot overwrite the rows we are about to write.
+ *
+ * Fetches of queries without data (initial loads) are left running: cancelling them
+ * would strand the query in a non-fetching pending state.
+ */
+export const prepareEntityCacheWrite = async (queryClient, tableBlockId) => {
+    const tableKey = entityTableKey(tableBlockId);
+    const staleKeys = queryClient
+        .getQueryCache()
+        .findAll({
+        queryKey: tableKey,
+        predicate: (query) => query.state.fetchStatus === "fetching" || query.state.isInvalidated,
+    })
+        .map((query) => query.queryKey);
+    await queryClient.cancelQueries({
+        queryKey: tableKey,
+        predicate: (query) => query.state.data !== undefined,
+    });
+    return { staleKeys };
+};
+/**
+ * Single invalidation pass that re-syncs everything a direct cache write cannot
+ * decide on its own:
+ * - filtered lists (membership/order/limit semantics live on the server),
+ * - one-queries keyed by non-id filters (an update/create may change which row matches),
+ * - queries that had a fetch in flight while we wrote (their in-flight response is
+ *   of unknowable freshness and may carry an external change we cancelled).
+ *
+ * Unfiltered lists and id-keyed one-queries are NOT invalidated - they were fully
+ * reconciled from the server response, which is what saves the refetch round trips.
+ */
+export const invalidateEntityQueriesAfterWrite = (queryClient, tableBlockId, { staleKeys = [], filteredLists = false, nonIdOneQueries = false, deletedRowIds, }) => {
+    const staleHashes = new Set(staleKeys.map((queryKey) => hashKey(queryKey)));
+    void queryClient.invalidateQueries({
+        queryKey: entityTableKey(tableBlockId),
+        predicate: (query) => {
+            if (staleHashes.has(hashKey(query.queryKey))) {
+                return true;
+            }
+            if (filteredLists && isFilteredListQueryKey(query.queryKey, tableBlockId)) {
+                return true;
+            }
+            if (nonIdOneQueries &&
+                isOneQueryKey(query.queryKey, tableBlockId) &&
+                getOneQueryKeyId(query.queryKey) === undefined) {
+                if (!deletedRowIds) {
+                    return true;
+                }
+                const data = query.state.data;
+                return data === null || (isValidRow(data) && deletedRowIds.some((rowId) => sameId(rowId, data.id)));
+            }
+            return false;
+        },
+    });
+};
+/** Full-table invalidation - the pre-optimistic behavior, kept as the safety fallback. */
+export const invalidateEntityTable = (queryClient, tableBlockId) => {
+    void queryClient.invalidateQueries({ queryKey: entityTableKey(tableBlockId) });
+};
+/**
+ * Optimistic phase of an update/delete mutation: cancel clobbering fetches, snapshot
+ * the table cache for rollback, then apply the optimistic change. Never throws - on
+ * any failure the optimistic change is rolled back and skipped, and the mutation
+ * proceeds (the success/error handlers still reconcile the cache).
+ */
+export const beginEntityOptimisticWrite = async (queryClient, tableBlockId, applyOptimistic) => {
+    try {
+        const { staleKeys } = await prepareEntityCacheWrite(queryClient, tableBlockId);
+        const snapshot = snapshotEntityQueries(queryClient, tableBlockId);
+        try {
+            applyOptimistic();
+        }
+        catch {
+            // A partially applied optimistic change must not linger in the cache.
+            restoreEntityQueriesSnapshot(queryClient, snapshot);
+        }
+        return { snapshot, staleKeys };
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Error phase: restore the snapshot taken in `beginEntityOptimisticWrite`, then
+ * refetch the table since the server state is unknown after a failed request.
+ * `skipInvalidation` is for mutations rejected before any request was sent
+ * (e.g. client-side rate limiting) where the restored snapshot is already correct.
+ */
+export const rollbackEntityOptimisticWrite = (queryClient, tableBlockId, context, { skipInvalidation = false } = {}) => {
+    try {
+        if (context) {
+            restoreEntityQueriesSnapshot(queryClient, context.snapshot);
+        }
+    }
+    catch {
+        invalidateEntityTable(queryClient, tableBlockId);
+        return;
+    }
+    if (!skipInvalidation) {
+        invalidateEntityTable(queryClient, tableBlockId);
+    }
+};
+/**
+ * Success phase of a create/update mutation: writes the canonical rows returned by
+ * the server into the cache and invalidates only what a direct write cannot decide
+ * (filtered lists, non-id one-queries, queries that were mid-fetch). Falls back to
+ * full-table invalidation whenever the response is unusable or anything throws, so
+ * the worst case is exactly the previous always-refetch behavior.
+ */
+export const applyEntityCreateResult = async (queryClient, tableBlockId, result, { appendNewToUnfilteredLists, extraStaleKeys = [], }) => {
+    try {
+        const rows = normalizeRowsResult(result);
+        if (rows.length === 0) {
+            invalidateEntityTable(queryClient, tableBlockId);
+            return;
+        }
+        const { staleKeys } = await prepareEntityCacheWrite(queryClient, tableBlockId);
+        applyEntityRowsUpserted(queryClient, tableBlockId, rows, { appendNewToUnfilteredLists });
+        seedEntityOneCaches(queryClient, tableBlockId, rows);
+        invalidateEntityQueriesAfterWrite(queryClient, tableBlockId, {
+            staleKeys: [...extraStaleKeys, ...staleKeys],
+            filteredLists: true,
+            nonIdOneQueries: true,
+        });
+    }
+    catch {
+        invalidateEntityTable(queryClient, tableBlockId);
+    }
+};
+/**
+ * Success phase of a delete mutation: removes the rows from every cached query.
+ * Filtered lists are still refetched because server-side filters may involve
+ * limits/pagination that removal alone cannot reconcile.
+ */
+export const applyEntityDeleteResult = async (queryClient, tableBlockId, rowIds, { extraStaleKeys = [] } = {}) => {
+    try {
+        const { staleKeys } = await prepareEntityCacheWrite(queryClient, tableBlockId);
+        applyEntityRowsDeleted(queryClient, tableBlockId, rowIds);
+        invalidateEntityQueriesAfterWrite(queryClient, tableBlockId, {
+            staleKeys: [...extraStaleKeys, ...staleKeys],
+            filteredLists: true,
+            nonIdOneQueries: true,
+            deletedRowIds: rowIds,
+        });
+    }
+    catch {
+        invalidateEntityTable(queryClient, tableBlockId);
+    }
+};

package/dist/EntityLiveSync.d.ts

@@ -0,0 +1,57 @@
+import { QueryClient } from "@tanstack/react-query";
+export type EntityDataOperation = "insert" | "update" | "delete";
+/** Fetches the current server rows for the given ids (typically `findMany({ id: ids })`). */
+export type EntityRowsByIdsFetcher = (tableBlockId: string, ids: (string | number)[]) => Promise<unknown>;
+export interface EntityDataEventPayload {
+    table?: string;
+    affectedRowsData?: {
+        id?: unknown;
+    }[];
+}
+export interface EntityLiveSyncOptions {
+    queryClient: QueryClient;
+    fetchRowsByIds: EntityRowsByIdsFetcher;
+    /** How long to coalesce a burst of events for the same table before syncing once. */
+    batchDelayMs?: number;
+    /** Above this many affected rows, refetching the queries is cheaper than fetching rows one batch. */
+    maxRowFetchCount?: number;
+}
+/**
+ * Pulls the canonical state of specific rows from the server and reconciles the
+ * cache with it - the "fetch a little data instead of refetching everything" path.
+ *
+ * - `deleteIds` are removed from every cached query without any fetch.
+ * - `insertIds`/`updateIds` are fetched in a single by-id request; the returned rows
+ *   are written into every cached query (insert-origin rows are appended to
+ *   unfiltered lists, update-origin rows are only replaced in place).
+ * - The fetch is skipped entirely when the cache holds no unfiltered lists or
+ *   one-queries - there would be nothing for the row data to update.
+ * - Requested ids the server no longer returns are treated as deleted (the by-id
+ *   fetch runs through the same pipeline and policies as lists, so a missing row is
+ *   either gone or was never visible to this session in the first place).
+ * - Filtered lists and non-id one-queries are still invalidated, since membership
+ *   can only be decided server-side.
+ *
+ * Any failure falls back to invalidating the whole table, so the worst case is the
+ * previous refetch-everything behavior.
+ */
+export declare const syncEntityRowsFromServer: (queryClient: QueryClient, tableBlockId: string, fetchRowsByIds: EntityRowsByIdsFetcher, { insertIds, updateIds, deleteIds, }: {
+    insertIds?: (string | number)[];
+    updateIds?: (string | number)[];
+    deleteIds?: (string | number)[];
+}) => Promise<void>;
+/**
+ * Turns websocket data events into minimal cache syncs.
+ *
+ * Events for the same table are coalesced for `batchDelayMs` and then processed in
+ * one pass: one small by-id fetch for inserted/updated rows, zero fetches for
+ * deletes, instead of invalidating (and refetching) every query of the table.
+ * Events without row ids and oversized batches keep the old full-invalidation
+ * behavior.
+ */
+export declare const createEntityLiveSync: ({ queryClient, fetchRowsByIds, batchDelayMs, maxRowFetchCount, }: EntityLiveSyncOptions) => {
+    handleDataEvent: (operation: EntityDataOperation, payload: EntityDataEventPayload) => void;
+    dispose: () => void;
+};
+export type EntityLiveSync = ReturnType<typeof createEntityLiveSync>;
+//# sourceMappingURL=EntityLiveSync.d.ts.map

package/dist/EntityLiveSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityLiveSync.d.ts","sourceRoot":"","sources":["../src/EntityLiveSync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAapD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjE,6FAA6F;AAC7F,MAAM,MAAM,sBAAsB,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE1G,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,WAAW,CAAC;IACzB,cAAc,EAAE,sBAAsB,CAAC;IACvC,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAiBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,GACnC,aAAa,WAAW,EACxB,cAAc,MAAM,EACpB,gBAAgB,sBAAsB,EACtC,sCAIG;IACD,SAAS,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CACjC,KACA,OAAO,CAAC,IAAI,CA6Cd,CAAC;AAkBF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,GAAI,kEAKlC,qBAAqB;iCA4Ec,mBAAmB,WAAW,sBAAsB,KAAG,IAAI;mBA2B3E,IAAI;CAiBzB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/EntityLiveSync.js

@@ -0,0 +1,182 @@
+import { applyEntityRowsDeleted, applyEntityRowsUpserted, hasDirectlyMaintainedEntityQueries, invalidateEntityQueriesAfterWrite, invalidateEntityTable, normalizeRowsResult, prepareEntityCacheWrite, sameId, } from "./EntityCache.js";
+const DEFAULT_BATCH_DELAY_MS = 150;
+const DEFAULT_MAX_ROW_FETCH_COUNT = 100;
+const isIdValue = (value) => (typeof value === "string" && value.length > 0) || (typeof value === "number" && Number.isFinite(value));
+const extractEventRowIds = (payload) => (payload.affectedRowsData ?? []).map((row) => row?.id).filter(isIdValue);
+const dedupeIds = (ids) => {
+    const byKey = new Map();
+    ids.forEach((id) => byKey.set(String(id), id));
+    return [...byKey.values()];
+};
+/**
+ * Pulls the canonical state of specific rows from the server and reconciles the
+ * cache with it - the "fetch a little data instead of refetching everything" path.
+ *
+ * - `deleteIds` are removed from every cached query without any fetch.
+ * - `insertIds`/`updateIds` are fetched in a single by-id request; the returned rows
+ *   are written into every cached query (insert-origin rows are appended to
+ *   unfiltered lists, update-origin rows are only replaced in place).
+ * - The fetch is skipped entirely when the cache holds no unfiltered lists or
+ *   one-queries - there would be nothing for the row data to update.
+ * - Requested ids the server no longer returns are treated as deleted (the by-id
+ *   fetch runs through the same pipeline and policies as lists, so a missing row is
+ *   either gone or was never visible to this session in the first place).
+ * - Filtered lists and non-id one-queries are still invalidated, since membership
+ *   can only be decided server-side.
+ *
+ * Any failure falls back to invalidating the whole table, so the worst case is the
+ * previous refetch-everything behavior.
+ */
+export const syncEntityRowsFromServer = async (queryClient, tableBlockId, fetchRowsByIds, { insertIds = [], updateIds = [], deleteIds = [], }) => {
+    try {
+        const { staleKeys } = await prepareEntityCacheWrite(queryClient, tableBlockId);
+        if (deleteIds.length > 0) {
+            applyEntityRowsDeleted(queryClient, tableBlockId, deleteIds);
+        }
+        // A row that was also deleted in the same batch is gone - no point fetching it.
+        const wantedIds = dedupeIds([...insertIds, ...updateIds].filter((id) => !deleteIds.some((deletedId) => sameId(deletedId, id))));
+        let missingIds = [];
+        // Only fetch row data when the cache holds queries that direct writes can keep
+        // fresh - otherwise the invalidation below already covers everything cached.
+        if (wantedIds.length > 0 && hasDirectlyMaintainedEntityQueries(queryClient, tableBlockId)) {
+            const fetched = normalizeRowsResult(await fetchRowsByIds(tableBlockId, wantedIds));
+            // Only trust rows we actually asked for, in case the fetcher over-returns.
+            const rows = fetched.filter((row) => wantedIds.some((id) => sameId(id, row.id)));
+            const insertRows = rows.filter((row) => insertIds.some((id) => sameId(id, row.id)));
+            const updateRows = rows.filter((row) => !insertRows.includes(row));
+            applyEntityRowsUpserted(queryClient, tableBlockId, updateRows, { appendNewToUnfilteredLists: false });
+            applyEntityRowsUpserted(queryClient, tableBlockId, insertRows, { appendNewToUnfilteredLists: true });
+            // Ids the server did not return are gone (deleted or no longer accessible):
+            // the by-id fetch runs through the same query pipeline and policies as lists.
+            missingIds = wantedIds.filter((id) => !rows.some((row) => sameId(row.id, id)));
+            if (missingIds.length > 0) {
+                applyEntityRowsDeleted(queryClient, tableBlockId, missingIds);
+            }
+        }
+        const allDeletedIds = [...deleteIds, ...missingIds];
+        invalidateEntityQueriesAfterWrite(queryClient, tableBlockId, {
+            staleKeys,
+            filteredLists: true,
+            nonIdOneQueries: true,
+            deletedRowIds: wantedIds.length === 0 && allDeletedIds.length > 0 ? allDeletedIds : undefined,
+        });
+    }
+    catch {
+        invalidateEntityTable(queryClient, tableBlockId);
+    }
+};
+/**
+ * Turns websocket data events into minimal cache syncs.
+ *
+ * Events for the same table are coalesced for `batchDelayMs` and then processed in
+ * one pass: one small by-id fetch for inserted/updated rows, zero fetches for
+ * deletes, instead of invalidating (and refetching) every query of the table.
+ * Events without row ids and oversized batches keep the old full-invalidation
+ * behavior.
+ */
+export const createEntityLiveSync = ({ queryClient, fetchRowsByIds, batchDelayMs = DEFAULT_BATCH_DELAY_MS, maxRowFetchCount = DEFAULT_MAX_ROW_FETCH_COUNT, }) => {
+    const tables = new Map();
+    let disposed = false;
+    const getOrCreateState = (table) => {
+        const existing = tables.get(table);
+        if (existing) {
+            return existing;
+        }
+        const created = {
+            insertIds: new Map(),
+            updateIds: new Map(),
+            deleteIds: new Map(),
+            fullInvalidate: false,
+            flushing: false,
+        };
+        tables.set(table, created);
+        return created;
+    };
+    const hasPendingEvents = (state) => state.fullInvalidate || state.insertIds.size > 0 || state.updateIds.size > 0 || state.deleteIds.size > 0;
+    const takeBatch = (state) => {
+        const batch = {
+            insertIds: [...state.insertIds.values()],
+            updateIds: [...state.updateIds.values()],
+            deleteIds: [...state.deleteIds.values()],
+            fullInvalidate: state.fullInvalidate,
+        };
+        state.insertIds = new Map();
+        state.updateIds = new Map();
+        state.deleteIds = new Map();
+        state.fullInvalidate = false;
+        return batch;
+    };
+    const scheduleFlush = (table, state) => {
+        state.timer = setTimeout(() => {
+            void flush(table);
+        }, batchDelayMs);
+    };
+    const flush = async (table) => {
+        const state = tables.get(table);
+        if (!state || state.flushing) {
+            return;
+        }
+        state.timer = undefined;
+        state.flushing = true;
+        const batch = takeBatch(state);
+        try {
+            const rowFetchCount = batch.insertIds.length + batch.updateIds.length;
+            if (batch.fullInvalidate || rowFetchCount > maxRowFetchCount) {
+                invalidateEntityTable(queryClient, table);
+            }
+            else {
+                await syncEntityRowsFromServer(queryClient, table, fetchRowsByIds, batch);
+            }
+        }
+        catch {
+            invalidateEntityTable(queryClient, table);
+        }
+        finally {
+            state.flushing = false;
+            if (disposed || !hasPendingEvents(state)) {
+                tables.delete(table);
+            }
+            else {
+                // Events arrived while we were syncing - process them in the next window.
+                scheduleFlush(table, state);
+            }
+        }
+    };
+    const handleDataEvent = (operation, payload) => {
+        if (disposed) {
+            return;
+        }
+        const table = payload?.table;
+        if (!table) {
+            return;
+        }
+        const state = getOrCreateState(table);
+        const ids = extractEventRowIds(payload);
+        if (ids.length === 0) {
+            // No row ids in the event - we cannot sync selectively.
+            state.fullInvalidate = true;
+        }
+        else {
+            const target = operation === "insert" ? state.insertIds : operation === "update" ? state.updateIds : state.deleteIds;
+            ids.forEach((id) => target.set(String(id), id));
+        }
+        if (!state.timer && !state.flushing) {
+            scheduleFlush(table, state);
+        }
+    };
+    const dispose = () => {
+        disposed = true;
+        tables.forEach((state, table) => {
+            if (state.timer) {
+                clearTimeout(state.timer);
+                state.timer = undefined;
+            }
+            // Pending events cannot be synced during teardown - fall back to marking stale.
+            if (hasPendingEvents(state)) {
+                invalidateEntityTable(queryClient, table);
+            }
+        });
+        tables.clear();
+    };
+    return { handleDataEvent, dispose };
+};

package/dist/ReactClientSdk.d.ts

@@ -86,12 +86,12 @@ export declare const useClient: () => ReactClientSdk;
  * @returns {EntityType<E>[] | undefined} returns.data - The fetched entities
  * @returns {boolean} returns.isLoading - Whether the query is loading
  * @returns {Error | null} returns.error - Any error that occurred
- * @returns {Function} returns.refetch - Function to manually refetch the data
+ * @returns {Function} returns.refetch - Intentional no-op kept for API compatibility; returns the current state without fetching. Data is kept fresh automatically (mutation cache writes + websocket live sync), so manual refetching is unsupported.
  * @returns {boolean} returns.isError - Whether the query resulted in an error
  * @returns {boolean} returns.isFetched - Whether the query has been fetched
  * @returns {boolean} returns.isFetching - Whether the query is currently fetching
  * @returns {boolean} returns.isSuccess - Whether the query was successful
- * @returns {string} returns.status - Current status of the query: 'idle', 'loading', 'success', 'error', or 'pending'
+ * @returns {string} returns.status - Current status of the query: 'pending', 'error', or 'success'
  * @example
  * ```tsx
  * import { ItemEntity } from '@/product-types';
@@ -121,7 +121,7 @@ export declare const useEntityGetAll: <E extends EntityConfig>(entityConfig: E,
     isFetched: boolean;
     isFetching: boolean;
     isSuccess: boolean;
-    status: "idle" | "loading" | "success" | "error" | "pending";
+    status: "pending" | "error" | "success";
 };
 /**
  * Hook to fetch a single entity by filters
@@ -139,12 +139,12 @@ export declare const useEntityGetAll: <E extends EntityConfig>(entityConfig: E,
  * @returns {EntityType<EC> | undefined | null} returns.data - The fetched entity
  * @returns {boolean} returns.isLoading - Whether the query is loading
  * @returns {Error | null} returns.error - Any error that occurred
- * @returns {Function} returns.refetch - Function to manually refetch the data
+ * @returns {Function} returns.refetch - Intentional no-op kept for API compatibility; returns the current state without fetching. Data is kept fresh automatically (mutation cache writes + websocket live sync), so manual refetching is unsupported.
  * @returns {boolean} returns.isError - Whether the query resulted in an error
  * @returns {boolean} returns.isFetched - Whether the query has been fetched
  * @returns {boolean} returns.isFetching - Whether the query is currently fetching
  * @returns {boolean} returns.isSuccess - Whether the query was successful
- * @returns {string} returns.status - Current status of the query: 'idle', 'loading', 'success', 'error', or 'pending'
+ * @returns {string} returns.status - Current status of the query: 'pending', 'error', or 'success'
  * @example
  * ```tsx
  * import { UserEntity } from '@/product-types';
@@ -171,13 +171,15 @@ export declare const useEntityGetOne: <EC extends EntityConfig = EntityConfig>(e
     isFetched: boolean;
     isFetching: boolean;
     isSuccess: boolean;
-    status: "idle" | "loading" | "success" | "error" | "pending";
+    status: "pending" | "error" | "success";
 };
 /**
  * Hook to create a new entity
  *
  * Creates a new entity instance in the data store.
  * EntityTypeOnlyMutable<EC> represents the writable properties of the entity.
+ * The created entity returned by the server is written directly into the query cache,
+ * so `useEntityGetAll`/`useEntityGetOne` consumers update instantly without refetching.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type
@@ -226,7 +228,8 @@ export declare const useEntityCreate: <EC extends EntityConfig = EntityConfig>(e
  * Creates multiple entity instances in the data store in one batch operation.
  * This is more efficient than calling useEntityCreate multiple times when you need
  * to create several entities at once. EntityTypeOnlyMutable<EC> represents the
- * writable properties of the entity.
+ * writable properties of the entity. The created entities returned by the server are
+ * written directly into the query cache, so consumers update without refetching.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type
@@ -269,6 +272,8 @@ export declare const useEntityCreateMany: <EC extends EntityConfig = EntityConfi
  *
  * Updates an existing entity with the provided partial data.
  * Only the properties included in the data object will be updated.
+ * The change is applied to the query cache optimistically (and rolled back on error),
+ * then confirmed with the canonical row returned by the server - no refetch needed.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type
@@ -310,7 +315,8 @@ export declare const useEntityUpdate: <EC extends EntityConfig = EntityConfig>(e
  * Hook to delete an entity
  *
  * Permanently removes an entity from the data store by its ID.
- * Automatically invalidates relevant queries after deletion.
+ * The row is removed from the query cache optimistically (and restored on error),
+ * so dependent queries update instantly without refetching.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type
@@ -347,7 +353,8 @@ export declare const useEntityDelete: <EC extends EntityConfig = EntityConfig>(e
  * Hook to delete multiple entities at once
  *
  * Permanently removes multiple entities from the data store by their IDs.
- * Automatically invalidates relevant queries after deletion.
+ * The rows are removed from the query cache optimistically (and restored on error),
+ * so dependent queries update instantly without refetching.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type

package/dist/ReactClientSdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReactClientSdk.d.ts","sourceRoot":"","sources":["../src/ReactClientSdk.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,qBAAa,cAAe,SAAQ,SAAS;CAAG;AAsChD,oBAAY,iBAAiB;IAC3B,eAAe,oBAAoB;IACnC,eAAe,oBAAoB;IACnC,eAAe,oBAAoB;CACpC;AA+ID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,cAAc,GAAI,gDAK5B;IACD,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvC,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,KAAK,IAAI,CAAC;CAChE,gCAuDA,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,sBAOrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,YAAY,EACpD,cAAc,CAAC,EACf,UAAU,GAAG,EACb,eAAc;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9B,eAAe,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;CAC9B,KACL;IACD,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;CAuB9D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,eAAe,GAAI,EAAE,SAAS,YAAY,GAAG,YAAY,EACpE,cAAc,EAAE,EAChB,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC5B,eAAc;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;CAChC,KACL;IACD,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,GAAG,SAAS,GAAG,IAAI,CAAC;IACxC,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;CA6B9D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,eAAe,GAAI,EAAE,SAAS,YAAY,GAAG,YAAY,EACpE,cAAc,EAAE,KACf;IACD,cAAc,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,qBAAqB,CAAC,EAAE,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3F,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CA0BrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,mBAAmB,GAAI,EAAE,SAAS,YAAY,GAAG,YAAY,EACxE,cAAc,EAAE,KACf;IACD,kBAAkB,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QAAE,IAAI,EAAE,qBAAqB,CAAC,EAAE,CAAC,EAAE,CAAA;KAAE,KAAK,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACnG,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CA0BrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,eAAe,GAAI,EAAE,SAAS,YAAY,GAAG,YAAY,EACpE,cAAc,EAAE,KACf;IACD,cAAc,EAAE,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC,CAAA;KAAE,KAAK,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IACpH,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CA2BrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,eAAe,GAAI,EAAE,SAAS,YAAY,GAAG,YAAY,EACpE,cAAc,EAAE,KACf;IACD,cAAc,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CA2BrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,mBAAmB,GAAI,EAAE,SAAS,YAAY,GAAG,YAAY,EACxE,cAAc,EAAE,KACf;IACD,kBAAkB,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE;QAAE,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CA4BrB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AACH,eAAO,MAAM,gBAAgB,GAAI,EAAE,SAAS,YAAY,GAAG,YAAY,EAAE,cAAc,EAAE;;;;;;;;CAiExF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,GAAI,GAAG,SAAS,eAAe,GAAG,eAAe,EAAE,iBAAiB,GAAG,yCAG/F,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,QAAQ,GAAI,EAAE,SAAS,WAAW,GAAG,WAAW,EAAE,aAAa,EAAE,gCAG7E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,aAAa,QAAO;IAC/B,cAAc,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;CAyB1B,CAAC;AAEF;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,OAAO,kCASnB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,YAAY,QAAO;IAC9B,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvC,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,KAAK,IAAI,CAAC;CAIhE,CAAC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,eAAO,MAAM,iBAAiB,GAAI,cAAa;IAAE,OAAO,CAAC,EAAE,iBAAiB,CAAA;CAAO;;gBAWtC,MAAM;cAAQ,MAAM;;;;;CAwBhE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,gBAAgB;+BAOP;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE;;;;CAmBtC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,cAAc,cAG1B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,EAAE,SAAS,UAAU,GAAG,UAAU,EAAE,YAAY,EAAE,2BAS/E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,EAAE,SAAS,UAAU,GAAG,UAAU,EAAE,YAAY,EAAE,WAI5E,CAAC"}
+{"version":3,"file":"ReactClientSdk.d.ts","sourceRoot":"","sources":["../src/ReactClientSdk.tsx"],"names":[],"mappings":"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"}

package/dist/ReactClientSdk.jsx

@@ -5,10 +5,13 @@ import { useAiStreamChunks } from "@blocksdiy/react-common/useAiStreamChunks";
 import { QueryClient, QueryClientProvider, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { ClientSdk } from "./ClientSdk.js";
+import { applyEntityCreateResult, applyEntityDeleteResult, applyEntityRowPatch, applyEntityRowsDeleted, beginEntityOptimisticWrite, ENTITIES_QUERY_KEY, rollbackEntityOptimisticWrite, } from "./EntityCache.js";
+import { createEntityLiveSync } from "./EntityLiveSync.js";
 export class ReactClientSdk extends ClientSdk {
 }
-const ENTITIES_QUERY_KEY = "entities";
 const CURRENT_USER_QUERY_KEY = "currentUser";
+// Avoids redundant refetches on quick remounts and window focus flaps without meaningfully delaying anything.
+const ENTITIES_STALE_TIME = 5_000;
 const ClientContext = createContext(null);
 const ThemeModeContext = createContext({
     themeMode: "system",
@@ -157,7 +160,17 @@ const useEntityRowMutationRateLimiting = (entityConfig, functionName) => {
  * ```
  */
 export const ClientProvider = ({ client, children, themeMode, setThemeMode, }) => {
-    const [queryClient] = useState(() => new QueryClient());
+    const [queryClient] = useState(() => new QueryClient({
+        defaultOptions: {
+            queries: {
+                staleTime: ENTITIES_STALE_TIME,
+                // TEMP: disable React Query's default refetch-on-window-focus so switching
+                // browser tabs never triggers fetches. Remove this line to restore the
+                // default focus revalidation (refetch stale queries on refocus).
+                refetchOnWindowFocus: false,
+            },
+        },
+    }));
     const user = client.getUser();
     const userIdInNumber = useMemo(() => {
         if (user?.id) {
@@ -171,22 +184,25 @@ export const ClientProvider = ({ client, children, themeMode, setThemeMode, }) =
     }, [user?.id]);
     useWebsockets({ userId: userIdInNumber, token: client.token });
     useWebsocketsAppSubscribe({ appId: client.appId });
-    const dataChangeCallback = useCallback(async (data) => {
-        queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, data.table] });
-        data.affectRows?.forEach((row) => {
-            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, data.table, "one", { id: row.id }] });
-        });
-    }, [queryClient]);
+    // Websocket events update cache for specific rows after external changes
     useEffect(() => {
-        websocketsService.listen(AppDataEventTypes.APP_DATA_INSERT, dataChangeCallback);
-        websocketsService.listen(AppDataEventTypes.APP_DATA_UPDATE, dataChangeCallback);
-        websocketsService.listen(AppDataEventTypes.APP_DATA_DELETE, dataChangeCallback);
+        const liveSync = createEntityLiveSync({
+            queryClient,
+            fetchRowsByIds: (tableBlockId, ids) => client.entity({ tableBlockId, instanceType: {} }).findMany({ id: ids }),
+        });
+        const onInsert = async (data) => liveSync.handleDataEvent("insert", data);
+        const onUpdate = async (data) => liveSync.handleDataEvent("update", data);
+        const onDelete = async (data) => liveSync.handleDataEvent("delete", data);
+        websocketsService.listen(AppDataEventTypes.APP_DATA_INSERT, onInsert);
+        websocketsService.listen(AppDataEventTypes.APP_DATA_UPDATE, onUpdate);
+        websocketsService.listen(AppDataEventTypes.APP_DATA_DELETE, onDelete);
         return () => {
-            websocketsService.unlisten(AppDataEventTypes.APP_DATA_INSERT, dataChangeCallback);
-            websocketsService.unlisten(AppDataEventTypes.APP_DATA_UPDATE, dataChangeCallback);
-            websocketsService.unlisten(AppDataEventTypes.APP_DATA_DELETE, dataChangeCallback);
+            websocketsService.unlisten(AppDataEventTypes.APP_DATA_INSERT, onInsert);
+            websocketsService.unlisten(AppDataEventTypes.APP_DATA_UPDATE, onUpdate);
+            websocketsService.unlisten(AppDataEventTypes.APP_DATA_DELETE, onDelete);
+            liveSync.dispose();
         };
-    }, [dataChangeCallback]);
+    }, [queryClient, client]);
     return (<ClientContext value={client}>
       <ThemeModeContext value={{ themeMode, setThemeMode }}>
         {/* <QueryClientProvider client={queryClient}>
@@ -244,12 +260,12 @@ export const useClient = () => {
  * @returns {EntityType<E>[] | undefined} returns.data - The fetched entities
  * @returns {boolean} returns.isLoading - Whether the query is loading
  * @returns {Error | null} returns.error - Any error that occurred
- * @returns {Function} returns.refetch - Function to manually refetch the data
+ * @returns {Function} returns.refetch - Intentional no-op kept for API compatibility; returns the current state without fetching. Data is kept fresh automatically (mutation cache writes + websocket live sync), so manual refetching is unsupported.
  * @returns {boolean} returns.isError - Whether the query resulted in an error
  * @returns {boolean} returns.isFetched - Whether the query has been fetched
  * @returns {boolean} returns.isFetching - Whether the query is currently fetching
  * @returns {boolean} returns.isSuccess - Whether the query was successful
- * @returns {string} returns.status - Current status of the query: 'idle', 'loading', 'success', 'error', or 'pending'
+ * @returns {string} returns.status - Current status of the query: 'pending', 'error', or 'success'
  * @example
  * ```tsx
  * import { ItemEntity } from '@/product-types';
@@ -280,6 +296,8 @@ export const useEntityGetAll = (entityConfig, filters, queryOptions = {}) => {
         data,
         isLoading,
         error,
+        // Deliberately NOT React Query's refetch: app code must not be able to force
+        // refetches - the cache stays fresh via mutation writes and websocket live sync.
         refetch: () => ({ data, isLoading, error, isError, isFetched, isFetching, isSuccess, status }),
         isError,
         isFetched,
@@ -304,12 +322,12 @@ export const useEntityGetAll = (entityConfig, filters, queryOptions = {}) => {
  * @returns {EntityType<EC> | undefined | null} returns.data - The fetched entity
  * @returns {boolean} returns.isLoading - Whether the query is loading
  * @returns {Error | null} returns.error - Any error that occurred
- * @returns {Function} returns.refetch - Function to manually refetch the data
+ * @returns {Function} returns.refetch - Intentional no-op kept for API compatibility; returns the current state without fetching. Data is kept fresh automatically (mutation cache writes + websocket live sync), so manual refetching is unsupported.
  * @returns {boolean} returns.isError - Whether the query resulted in an error
  * @returns {boolean} returns.isFetched - Whether the query has been fetched
  * @returns {boolean} returns.isFetching - Whether the query is currently fetching
  * @returns {boolean} returns.isSuccess - Whether the query was successful
- * @returns {string} returns.status - Current status of the query: 'idle', 'loading', 'success', 'error', or 'pending'
+ * @returns {string} returns.status - Current status of the query: 'pending', 'error', or 'success'
  * @example
  * ```tsx
  * import { UserEntity } from '@/product-types';
@@ -344,6 +362,8 @@ export const useEntityGetOne = (entityConfig, filters, queryOptions = {}) => {
         data,
         isLoading,
         error,
+        // Deliberately NOT React Query's refetch: app code must not be able to force
+        // refetches - the cache stays fresh via mutation writes and websocket live sync.
         refetch: () => ({ data, isLoading, error, isError, isFetched, isFetching, isSuccess, status }),
         isError,
         isFetched,
@@ -357,6 +377,8 @@ export const useEntityGetOne = (entityConfig, filters, queryOptions = {}) => {
  *
  * Creates a new entity instance in the data store.
  * EntityTypeOnlyMutable<EC> represents the writable properties of the entity.
+ * The created entity returned by the server is written directly into the query cache,
+ * so `useEntityGetAll`/`useEntityGetOne` consumers update instantly without refetching.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type
@@ -401,9 +423,11 @@ export const useEntityCreate = (entityConfig) => {
             validateExceededMaxCount({ data });
             return client.entity(entityConfig).create(data);
         },
-        onSuccess: () => {
-            // Invalidate the list so we refetch it with the newly created item
-            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
+        onSuccess: async (result) => {
+            // The server returns the canonical created row, so write it into the cache
+            await applyEntityCreateResult(queryClient, entityConfig.tableBlockId, result, {
+                appendNewToUnfilteredLists: true,
+            });
         },
     });
     if (error instanceof FatalAppError) {
@@ -417,7 +441,8 @@ export const useEntityCreate = (entityConfig) => {
  * Creates multiple entity instances in the data store in one batch operation.
  * This is more efficient than calling useEntityCreate multiple times when you need
  * to create several entities at once. EntityTypeOnlyMutable<EC> represents the
- * writable properties of the entity.
+ * writable properties of the entity. The created entities returned by the server are
+ * written directly into the query cache, so consumers update without refetching.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type
@@ -457,9 +482,11 @@ export const useEntityCreateMany = (entityConfig) => {
             validateExceededMaxCount({ data });
             return client.entity(entityConfig).createMany(data);
         },
-        onSuccess: () => {
-            // Invalidate the list so we refetch it with the newly created item
-            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
+        onSuccess: async (result) => {
+            // The server returns the canonical created rows, so write them into the cache
+            await applyEntityCreateResult(queryClient, entityConfig.tableBlockId, result, {
+                appendNewToUnfilteredLists: true,
+            });
         },
     });
     if (error instanceof FatalAppError) {
@@ -472,6 +499,8 @@ export const useEntityCreateMany = (entityConfig) => {
  *
  * Updates an existing entity with the provided partial data.
  * Only the properties included in the data object will be updated.
+ * The change is applied to the query cache optimistically (and rolled back on error),
+ * then confirmed with the canonical row returned by the server - no refetch needed.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type
@@ -506,14 +535,28 @@ export const useEntityUpdate = (entityConfig) => {
     const queryClient = useQueryClient();
     const { validateExceededMaxCount } = useEntityRowMutationRateLimiting(entityConfig, "useEntityUpdate");
     const { mutateAsync: updateFunction, isPending: isLoading, error, } = useMutation({
+        onMutate: ({ id, data }) => 
+        // Optimistically patch every cached copy of the row for instant UI feedback.
+        beginEntityOptimisticWrite(queryClient, entityConfig.tableBlockId, () => {
+            applyEntityRowPatch(queryClient, entityConfig.tableBlockId, id, data);
+        }),
         mutationFn: ({ id, data }) => {
             validateExceededMaxCount({ rowId: id, data });
             return client.entity(entityConfig).updateOne(id, data);
         },
-        onSuccess: (_result, { id }) => {
-            // Invalidate both the list and the specific item's query
-            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
-            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId, "one", { id }] });
+        onSuccess: async (result, _variables, context) => {
+            // Replace the optimistic patch with the canonical updated row from the server
+            await applyEntityCreateResult(queryClient, entityConfig.tableBlockId, result, {
+                appendNewToUnfilteredLists: false,
+                extraStaleKeys: context?.staleKeys,
+            });
+        },
+        onError: (mutationError, _variables, context) => {
+            rollbackEntityOptimisticWrite(queryClient, entityConfig.tableBlockId, context, {
+                // Rate-limit rejections happen before the request is sent, so the restored
+                // snapshot is already the correct server state.
+                skipInvalidation: mutationError instanceof FatalAppError,
+            });
         },
     });
     if (error instanceof FatalAppError) {
@@ -525,7 +568,8 @@ export const useEntityUpdate = (entityConfig) => {
  * Hook to delete an entity
  *
  * Permanently removes an entity from the data store by its ID.
- * Automatically invalidates relevant queries after deletion.
+ * The row is removed from the query cache optimistically (and restored on error),
+ * so dependent queries update instantly without refetching.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type
@@ -556,14 +600,25 @@ export const useEntityDelete = (entityConfig) => {
     const queryClient = useQueryClient();
     const { validateExceededMaxCount } = useEntityRowMutationRateLimiting(entityConfig, "useEntityDelete");
     const { mutateAsync: deleteFunction, isPending: isLoading, error, } = useMutation({
+        onMutate: ({ id }) => 
+        // Optimistically remove the row from every cached query for instant UI feedback.
+        beginEntityOptimisticWrite(queryClient, entityConfig.tableBlockId, () => {
+            applyEntityRowsDeleted(queryClient, entityConfig.tableBlockId, [id]);
+        }),
         mutationFn: ({ id }) => {
             validateExceededMaxCount({ rowId: id });
             return client.entity(entityConfig).deleteOne(id);
         },
-        onSuccess: (_result, { id }) => {
-            // Invalidate both the list and the specific item's query
-            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
-            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId, "one", { id }] });
+        onSuccess: async (_result, { id }, context) => {
+            // Confirm the removal directly in the cache instead of refetching every query.
+            await applyEntityDeleteResult(queryClient, entityConfig.tableBlockId, [id], {
+                extraStaleKeys: context?.staleKeys,
+            });
+        },
+        onError: (mutationError, _variables, context) => {
+            rollbackEntityOptimisticWrite(queryClient, entityConfig.tableBlockId, context, {
+                skipInvalidation: mutationError instanceof FatalAppError,
+            });
         },
     });
     if (error instanceof FatalAppError) {
@@ -575,7 +630,8 @@ export const useEntityDelete = (entityConfig) => {
  * Hook to delete multiple entities at once
  *
  * Permanently removes multiple entities from the data store by their IDs.
- * Automatically invalidates relevant queries after deletion.
+ * The rows are removed from the query cache optimistically (and restored on error),
+ * so dependent queries update instantly without refetching.
  *
  * @template EC - Entity configuration type
  * @param {EC} entityConfig - Configuration for the entity type
@@ -606,14 +662,24 @@ export const useEntityDeleteMany = (entityConfig) => {
     const queryClient = useQueryClient();
     const { validateExceededMaxCount } = useEntityMutationRateLimiting(entityConfig, "useEntityDeleteMany");
     const { mutateAsync: deleteManyFunction, isPending: isLoading, error, } = useMutation({
+        onMutate: ({ ids }) => 
+        // Optimistically remove the rows from every cached query for instant UI feedback.
+        beginEntityOptimisticWrite(queryClient, entityConfig.tableBlockId, () => {
+            applyEntityRowsDeleted(queryClient, entityConfig.tableBlockId, ids);
+        }),
         mutationFn: ({ ids }) => {
             validateExceededMaxCount({ data: ids });
             return client.entity(entityConfig).deleteMany(ids);
         },
-        onSuccess: (_result, { ids }) => {
-            queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId] });
-            ids.forEach((id) => {
-                queryClient.invalidateQueries({ queryKey: [ENTITIES_QUERY_KEY, entityConfig.tableBlockId, "one", { id }] });
+        onSuccess: async (_result, { ids }, context) => {
+            // Confirm the removal directly in the cache instead of refetching every query.
+            await applyEntityDeleteResult(queryClient, entityConfig.tableBlockId, ids, {
+                extraStaleKeys: context?.staleKeys,
+            });
+        },
+        onError: (mutationError, _variables, context) => {
+            rollbackEntityOptimisticWrite(queryClient, entityConfig.tableBlockId, context, {
+                skipInvalidation: mutationError instanceof FatalAppError,
             });
         },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blocksdiy/blocks-client-sdk",
-  "version": "1.8.14",
+  "version": "1.9.1",
   "type": "module",
   "description": "Blocks client sdk",
   "keywords": [],
@@ -46,9 +46,9 @@
     ]
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.90.21",
-    "@blocksdiy/blocks-client-api": "1.12.0",
-    "@blocksdiy/react-common": "1.30.2"
+    "@tanstack/react-query": "^5.101.0",
+    "@blocksdiy/blocks-client-api": "1.13.0",
+    "@blocksdiy/react-common": "1.31.0"
   },
   "devDependencies": {
     "tsc-alias": "^1.8.10",