stitchkit 0.37.0 → 0.39.0

package/dist/index.js

@@ -14,20 +14,16 @@ import {
   isStitchErrorCode,
   notFound,
   paginatedSchema,
+  parseTrailingWildcard,
   rateLimited,
   unauthorized
-} from "./index-g3jrbd0z.js";
+} from "./index-xax049k6.js";
 import {
   isRecord,
   mapObject,
   typedEntries
 } from "./index-809wc1tt.js";
 
-// src/internal/http-input.ts
-function inputIsQuery(method) {
-  return method === "GET" || method === "DELETE";
-}
-
 // src/browser/client-multipart.ts
 function isFileDescriptor(value) {
   return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
@@ -47,6 +43,170 @@ function appendFormFields(formData, values, skipKeys) {
   }
 }
 
+// src/internal/http-input.ts
+function inputIsQuery(method) {
+  return method === "GET" || method === "DELETE";
+}
+
+// src/browser/client-url.ts
+function isParamArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" || typeof item === "number");
+}
+function collectQueryParams(args, endpoint) {
+  const params = {};
+  let hasParams = false;
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || value === null)
+      continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isParamArray(value)) {
+      params[key] = value;
+      hasParams = true;
+      continue;
+    }
+    const what = Array.isArray(value) ? "an array with non-primitive items" : typeof value === "object" ? "a nested object" : `a ${typeof value}`;
+    throw new Error(`${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
+  }
+  return hasParams ? params : undefined;
+}
+function hasStringKeys(args, keys) {
+  for (const key of keys) {
+    if (typeof args[key] !== "string")
+      return false;
+  }
+  return true;
+}
+function resolvePathPrefix(config, args) {
+  if (!config?.pathPrefix)
+    return "";
+  if (typeof config.pathPrefix === "string")
+    return config.pathPrefix;
+  const keys = config.stripPrefixKeys ?? [];
+  if (!hasStringKeys(args, keys)) {
+    const missing = keys.find((key) => typeof args[key] !== "string");
+    throw new Error(`Missing path prefix key: ${missing}`);
+  }
+  return config.pathPrefix(args);
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function decodePathSegment(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+function createClientRouteMatcher(endpoint, contractPrefix, config) {
+  if (typeof config?.pathPrefix === "function" && (!config.stripPrefixKeys || config.stripPrefixKeys.length === 0)) {
+    throw new Error("Dynamic pathPrefix matchers require stripPrefixKeys");
+  }
+  const markerByKey = {};
+  for (const [index, key] of (config?.stripPrefixKeys ?? []).entries()) {
+    markerByKey[key] = `__stitch_scope_${index}__`;
+  }
+  const pathPrefix = resolvePathPrefix(config, markerByKey);
+  const route = [pathPrefix, contractPrefix, endpoint.path === "/" ? "" : endpoint.path].filter(Boolean).join("/");
+  const patternSegments = route.split("/").filter(Boolean);
+  const wildcard = patternSegments.at(-1)?.startsWith("*") === true;
+  const fixedCount = wildcard ? patternSegments.length - 1 : patternSegments.length;
+  const markers = Object.values(markerByKey);
+  return (pathname) => {
+    const actualSegments = pathname.split("/").filter(Boolean).map(decodePathSegment);
+    if (wildcard ? actualSegments.length < fixedCount : actualSegments.length !== fixedCount) {
+      return false;
+    }
+    for (let index = 0;index < fixedCount; index += 1) {
+      const pattern = patternSegments[index];
+      const actual = actualSegments[index];
+      if (!pattern || actual === undefined)
+        return false;
+      if (pattern.startsWith(":"))
+        continue;
+      let source = escapeRegex(pattern);
+      for (const marker of markers) {
+        source = source.replaceAll(escapeRegex(marker), "[^/]+");
+      }
+      if (!new RegExp(`^${source}$`).test(actual))
+        return false;
+    }
+    return true;
+  };
+}
+function extractParamNames(path) {
+  const matches = path.match(/:(\w+)/g);
+  const names = matches ? matches.map((match) => match.slice(1)) : [];
+  const wildcard = parseTrailingWildcard(path);
+  if (wildcard)
+    names.push(wildcard.name);
+  return names;
+}
+function fillPathParams(path, args) {
+  const wildcard = parseTrailingWildcard(path);
+  let filled = path.replace(/:(\w+)/g, (_, key) => {
+    const value = args[key];
+    if (value === undefined || value === null) {
+      throw new Error(`Missing path param: ${key}`);
+    }
+    return encodeURIComponent(String(value));
+  });
+  if (!wildcard)
+    return filled;
+  const wildcardValue = args[wildcard.name];
+  if (wildcardValue === undefined || wildcardValue === null) {
+    throw new Error(`Missing path param: ${wildcard.name}`);
+  }
+  const remainder = String(wildcardValue).split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  filled = `${filled.slice(0, -(wildcard.name.length + 1))}${remainder}`;
+  return filled;
+}
+function stripConsumedArgs(args, path, scopeKeys) {
+  const consumed = new Set(scopeKeys);
+  for (const name of extractParamNames(path))
+    consumed.add(name);
+  const remaining = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (!consumed.has(key) && value !== undefined)
+      remaining[key] = value;
+  }
+  return remaining;
+}
+function appendQuery(relativeUrl, params) {
+  if (!params)
+    return relativeUrl;
+  const search = new URLSearchParams;
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      for (const item of value)
+        search.append(key, String(item));
+    } else {
+      search.set(key, String(value));
+    }
+  }
+  return search.size > 0 ? `${relativeUrl}?${search}` : relativeUrl;
+}
+function planClientRequest(endpoint, contractPrefix, args, config) {
+  let pathPrefix = resolvePathPrefix(config, args);
+  if (pathPrefix && !pathPrefix.endsWith("/"))
+    pathPrefix += "/";
+  if (pathPrefix.startsWith("/"))
+    pathPrefix = pathPrefix.slice(1);
+  const endpointPath = endpoint.path === "/" ? "" : endpoint.path;
+  let relativeUrl = fillPathParams(`${pathPrefix}${contractPrefix}${endpointPath}`, args);
+  if (relativeUrl.endsWith("/"))
+    relativeUrl = relativeUrl.slice(0, -1);
+  const remainingArgs = stripConsumedArgs(args, endpoint.path, config?.stripPrefixKeys ?? []);
+  if (inputIsQuery(endpoint.method)) {
+    relativeUrl = appendQuery(relativeUrl, collectQueryParams(remainingArgs, endpoint));
+  }
+  return { relativeUrl, remainingArgs };
+}
+function joinClientBaseUrl(baseUrl, relativeUrl) {
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const path = relativeUrl.startsWith("/") ? relativeUrl : `/${relativeUrl}`;
+  return `${base}${path}`;
+}
+
 // src/browser/http.ts
 import ky, { isHTTPError } from "ky";
 
@@ -121,7 +281,7 @@ function createHttpClient(config) {
   let ssrCookies = null;
   let isLoggedOut = false;
   const listeners = new Set;
-  const authEndpoints = config.authEndpoints ?? ["/auth/"];
+  const suppressUnauthorizedFor = config.suppressUnauthorizedFor ?? [];
   const parseError = config.parseError ?? parseApiErrorBody;
   function emit(event) {
     for (const fn of listeners) {
@@ -160,7 +320,7 @@ function createHttpClient(config) {
         async ({ request: request2, response }) => {
           if (response.status === 401) {
             const url = new URL(request2.url).pathname;
-            if (!isLoggedOut && !authEndpoints.some((path) => url.startsWith(path))) {
+            if (!isLoggedOut && !suppressUnauthorizedFor.some((matches) => matches(url))) {
               isLoggedOut = true;
               emit({ type: "unauthorized" });
             }
@@ -228,7 +388,9 @@ function createHttpClient(config) {
     }
   }
   return {
+    baseUrl: config.baseUrl,
     get: (url, options) => request("get", url, undefined, options),
+    head: (url, options) => request("head", url, undefined, options),
     post: (url, data, options) => request("post", url, data, options),
     put: (url, data, options) => request("put", url, data, options),
     patch: (url, data, options) => request("patch", url, data, options),
@@ -267,24 +429,24 @@ function withOutput(endpoint, result) {
     return result;
   return result.then((value) => value === undefined ? undefined : schema.parse(value));
 }
-function isParamArray(value) {
-  return Array.isArray(value) && value.every((v) => typeof v === "string" || typeof v === "number");
-}
-function collectQueryParams(args, skipKeys, endpoint) {
-  const params = {};
-  let hasParams = false;
-  for (const [key, value] of Object.entries(args)) {
-    if (skipKeys.has(key) || value === undefined || value === null)
+function contractEndpointMatchers(contract, endpointNames, contractConfig) {
+  const selected = endpointNames ? new Set(endpointNames) : null;
+  const matchers = [];
+  for (const [key, endpoint] of typedEntries(contract.endpoints)) {
+    if (selected && !selected.has(key))
       continue;
-    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isParamArray(value)) {
-      params[key] = value;
-      hasParams = true;
+    if (endpoint.expose && !endpoint.expose.includes("HTTP")) {
+      if (selected) {
+        throw new Error(`Cannot create an HTTP route matcher for non-HTTP endpoint: ${String(key)}`);
+      }
       continue;
     }
-    const what = Array.isArray(value) ? "an array with non-primitive items" : typeof value === "object" ? "a nested object" : `a ${typeof value}`;
-    throw new Error(`${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
+    matchers.push(createClientRouteMatcher(endpoint, contract.meta.prefix, contractConfig));
   }
-  return hasParams ? params : undefined;
+  if (selected && matchers.length !== selected.size) {
+    throw new Error("Cannot create an HTTP route matcher for an unknown endpoint");
+  }
+  return matchers;
 }
 function createClient(contract, configOrClient, contractConfig) {
   const client = {};
@@ -296,8 +458,34 @@ function createClient(contract, configOrClient, contractConfig) {
   }
   return client;
 }
-function createClients(contracts, http) {
-  return mapObject(contracts, (_key, contract) => createClient(contract, http));
+function createClients(contracts, configOrClient, contractConfig) {
+  return mapObject(contracts, (_key, contract) => createClient(contract, configOrClient, contractConfig));
+}
+function createScopedClients(contracts, configOrClient, scopeConfigs) {
+  const registry = {};
+  for (const [namespace, value] of Object.entries(contracts)) {
+    const list = Array.isArray(value) ? value : [value];
+    const client = {};
+    for (const contract of list) {
+      const scope = contract.meta.scope;
+      if (!scope) {
+        throw new Error(`Contract in client namespace "${namespace}" has no scope`);
+      }
+      const scopeConfig = Object.entries(scopeConfigs).find(([configuredScope]) => configuredScope === scope)?.[1];
+      if (!scopeConfig) {
+        throw new Error(`Missing client config for scope: ${scope}`);
+      }
+      const scoped = createClient(contract, configOrClient, scopeConfig);
+      for (const [methodName, method] of Object.entries(scoped)) {
+        if (Object.hasOwn(client, methodName)) {
+          throw new Error(`Client namespace "${namespace}" has duplicate method: ${methodName}`);
+        }
+        client[methodName] = method;
+      }
+    }
+    registry[namespace] = client;
+  }
+  return registry;
 }
 function isHttpAdapter(value) {
   return typeof value === "object" && "get" in value && typeof value.get === "function";
@@ -307,90 +495,41 @@ function setClientMethod(target, key, method) {
 }
 function createHttpMethod(endpoint, prefix, client, config) {
   const httpMethod = endpoint.method.toLowerCase();
-  const isGet = httpMethod === "get";
-  const paramNames = extractParamNames(endpoint.path);
-  const prefixKeys = new Set([...config?.stripPrefixKeys ?? [], ...paramNames]);
   return (...args) => {
     const firstArg = args[0] ?? {};
-    let pathPrefixStr = "";
-    if (config?.pathPrefix) {
-      pathPrefixStr = typeof config.pathPrefix === "function" ? config.pathPrefix(firstArg) : config.pathPrefix;
-      if (pathPrefixStr && !pathPrefixStr.endsWith("/"))
-        pathPrefixStr += "/";
-    }
-    let url = `${pathPrefixStr}${prefix}${endpoint.path}`;
-    for (const name of paramNames) {
-      const value = firstArg[name];
-      if (value === undefined || value === null) {
-        throw new Error(`Missing path param: ${name}`);
-      }
-      url = url.replace(`:${name}`, encodeURIComponent(String(value)));
-    }
-    if (url.endsWith("/"))
-      url = url.slice(0, -1);
+    const plan = planClientRequest(endpoint, prefix, firstArg, config);
     if (endpoint.multipart) {
       const file = firstArg[endpoint.multipart];
       if (!isMultipartFile(file)) {
         throw new Error(`Missing multipart file field: ${endpoint.multipart}`);
       }
-      if (httpMethod === "get" || httpMethod === "delete") {
+      if (httpMethod === "get" || httpMethod === "head" || httpMethod === "delete") {
         throw new Error(`Multipart endpoint ${endpoint.method} ${endpoint.path} must be POST / PUT / PATCH`);
       }
       const formData = new FormData;
       appendMultipartFile(formData, endpoint.multipart, file);
-      appendFormFields(formData, firstArg, new Set([...prefixKeys, endpoint.multipart]));
-      return withOutput(endpoint, client[httpMethod](url, formData, withTimeout(undefined, endpoint)));
+      appendFormFields(formData, plan.remainingArgs, new Set([endpoint.multipart]));
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, formData, withTimeout(undefined, endpoint)));
     }
-    if (isGet) {
-      const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return withOutput(endpoint, client.get(url, withTimeout(params ? { params } : undefined, endpoint)));
+    if (httpMethod === "get" || httpMethod === "head") {
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, withTimeout(undefined, endpoint)));
     }
     if (httpMethod === "delete") {
-      const params = collectQueryParams(firstArg, prefixKeys, endpoint);
-      return withOutput(endpoint, client.delete(url, withTimeout(params ? { params } : undefined, endpoint)));
+      return withOutput(endpoint, client.delete(plan.relativeUrl, withTimeout(undefined, endpoint)));
     }
-    const payload = {};
-    for (const [key, value] of Object.entries(firstArg)) {
-      if (!prefixKeys.has(key) && value !== undefined) {
-        payload[key] = value;
-      }
-    }
-    return withOutput(endpoint, client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint)));
+    return withOutput(endpoint, client[httpMethod](plan.relativeUrl, Object.keys(plan.remainingArgs).length > 0 ? plan.remainingArgs : undefined, withTimeout(undefined, endpoint)));
   };
 }
 function createFetchMethod(endpoint, prefix, config, contractConfig) {
-  const prefixKeys = new Set(contractConfig?.stripPrefixKeys ?? []);
   return async (args) => {
-    let pathPrefixStr = "";
-    if (contractConfig?.pathPrefix) {
-      pathPrefixStr = typeof contractConfig.pathPrefix === "function" ? contractConfig.pathPrefix(args ?? {}) : contractConfig.pathPrefix;
-      if (pathPrefixStr && !pathPrefixStr.endsWith("/"))
-        pathPrefixStr += "/";
-    }
-    let url = buildFetchUrl(config.baseUrl, prefix, endpoint.path, args, pathPrefixStr);
+    const plan = planClientRequest(endpoint, prefix, args ?? {}, contractConfig);
+    const url = joinClientBaseUrl(config.baseUrl, plan.relativeUrl);
     const headers = {
       Accept: "application/json",
       ...typeof config.headers === "function" ? config.headers() : config.headers
     };
     const signal = endpoint.timeout !== undefined ? AbortSignal.timeout(endpoint.timeout) : undefined;
-    const isQuery = inputIsQuery(endpoint.method);
-    const hasBody = !isQuery && !endpoint.multipart && endpoint.input && args;
-    if (isQuery && args) {
-      const remaining = stripParams(args, endpoint.path, prefixKeys);
-      const params = collectQueryParams(remaining, new Set, endpoint);
-      if (params) {
-        const searchParams = new URLSearchParams;
-        for (const [k, v] of Object.entries(params)) {
-          if (Array.isArray(v)) {
-            for (const item of v)
-              searchParams.append(k, String(item));
-          } else {
-            searchParams.set(k, String(v));
-          }
-        }
-        url += `?${searchParams}`;
-      }
-    }
+    const hasBody = endpoint.method !== "GET" && endpoint.method !== "HEAD" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && args;
     if (hasBody)
       headers["Content-Type"] = "application/json";
     if (endpoint.multipart && args) {
@@ -400,7 +539,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       }
       const formData = new FormData;
       appendMultipartFile(formData, endpoint.multipart, file);
-      appendFormFields(formData, stripParams(args, endpoint.path, prefixKeys), new Set([endpoint.multipart]));
+      appendFormFields(formData, plan.remainingArgs, new Set([endpoint.multipart]));
       const res2 = await fetch(url, {
         method: endpoint.method,
         headers,
@@ -424,7 +563,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       credentials: config.credentials,
       signal,
       ...hasBody && {
-        body: JSON.stringify(stripParams(hasBody, endpoint.path, prefixKeys))
+        body: JSON.stringify(plan.remainingArgs)
       }
     });
     if (!res.ok) {
@@ -447,35 +586,24 @@ async function throwForErrorResponse(res, config, fallbackBody) {
   }
   throw new ApiError("HTTP_ERROR", res.status, { body });
 }
-function extractParamNames(path) {
-  const matches = path.match(/:(\w+)/g);
-  return matches ? matches.map((m) => m.slice(1)) : [];
-}
-function buildFetchUrl(baseUrl, prefix, path, args, pathPrefix = "") {
-  let fullPath = `/${pathPrefix}${prefix}${path === "/" ? "" : path}`;
-  if (args) {
-    fullPath = fullPath.replace(/:(\w+)/g, (_, key) => {
-      const val = args[key];
-      if (val === undefined || val === null) {
-        throw new Error(`Missing path param: ${key}`);
+function createUrlBuilder(contract, source, contractConfig) {
+  const builder = {};
+  for (const [key, endpoint] of typedEntries(contract.endpoints)) {
+    if (endpoint.expose && !endpoint.expose.includes("HTTP"))
+      continue;
+    setClientMethod(builder, key, (args) => {
+      const plan = planClientRequest(endpoint, contract.meta.prefix, args ?? {}, contractConfig);
+      if (endpoint.method !== "GET" && endpoint.method !== "DELETE" && Object.keys(plan.remainingArgs).length > 0) {
+        const fields = Object.keys(plan.remainingArgs).join(", ");
+        throw new Error(`URL builder for ${endpoint.method} ${endpoint.path} received non-URL fields: ${fields}`);
       }
-      return encodeURIComponent(String(val));
+      return joinClientBaseUrl(source.baseUrl, plan.relativeUrl);
     });
   }
-  return `${baseUrl}${fullPath}`;
+  return builder;
 }
-function stripParams(args, path, extra) {
-  const skip = new Set(extra);
-  for (const match of path.matchAll(/:(\w+)/g)) {
-    if (match[1])
-      skip.add(match[1]);
-  }
-  const result = {};
-  for (const [k, v] of Object.entries(args)) {
-    if (!skip.has(k))
-      result[k] = v;
-  }
-  return result;
+function createUrlBuilders(contracts, source, contractConfig) {
+  return mapObject(contracts, (_key, contract) => createUrlBuilder(contract, source, contractConfig));
 }
 // src/retained.ts
 function createRetainedTopics() {
@@ -683,13 +811,17 @@ export {
   defineErrors,
   defineContract,
   decodeCursor,
+  createUrlBuilders,
+  createUrlBuilder,
   createTraceContext,
   createSocketIOClient,
+  createScopedClients,
   createRetainedTopics,
   createHttpClient,
   createContractFactory,
   createClients,
   createClient,
+  contractEndpointMatchers,
   conflict,
   childSpan,
   badRequest,

package/dist/internal/route-pattern.d.ts

@@ -0,0 +1,7 @@
+export interface TrailingWildcard {
+    name: string;
+    segmentIndex: number;
+}
+/** Parse and validate the route's single named terminal wildcard, if present. */
+export declare function parseTrailingWildcard(path: string): TrailingWildcard | null;
+//# sourceMappingURL=route-pattern.d.ts.map

package/dist/internal/route-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-pattern.d.ts","sourceRoot":"","sources":["../../src/internal/route-pattern.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CA2C3E"}

package/dist/node.js

@@ -3,8 +3,8 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-4pvtq6h2.js";
-import"./index-czmqks7r.js";
+} from "./index-7rbzbnnf.js";
+import"./index-6jypn22c.js";
 import"./index-x3fcszf8.js";
 import {
   AppError,
@@ -15,7 +15,7 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-e497hxcy.js";
+} from "./index-fyfk537k.js";
 // src/server/node.ts
 import { serve } from "srvx";
 async function serveNode(config) {

package/dist/observability/index.js

@@ -16,7 +16,7 @@ import {
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-e497hxcy.js";
+} from "../index-fyfk537k.js";
 
 // src/observability/sanitize.ts
 var DEFAULT_SENSITIVE_KEYS = /(password|passwd|pwd|secret|token|apikey|api[-_ ]?key|auth|authorization|bearer|session|cookie|init[-_ ]?data|credential|private[-_ ]?key)/i;

package/dist/react/entity-cache.d.ts

@@ -1,54 +1,68 @@
 /**
- * Declarative CRUD cache handlers for `createCacheBridge` — the created /
- * updated / deleted socket events of one entity, patched into its list and
- * detail queries. Every project hand-rolls this same updater; this builds it
- * from a small config.
- *
- * It patches stitchkit's own `Paginated<T>` list envelope (plain or a TanStack
- * `InfiniteData` of it) and the entity's detail query. It does **not** flatten
- * pages or expose a `useAllX` surface — flattening stays in the component (a
- * deliberate boundary): this only keeps the cache correct.
- *
- * ```ts
- * const handlers = createEntityCacheHandlers<Widget>({
- *   getId: (w) => w.id,
- *   listKey: ['widgets'],
- *   detailKey: (id) => ['widgets', id],
- * });
- * createCacheBridge({ socket, queryClient, handlers: {
- *   widgetCreated: handlers.created,
- *   widgetUpdated: handlers.updated,
- *   widgetDeleted: handlers.deleted,
- * }});
- * ```
+ * Declarative CRUD cache handlers for `createCacheBridge`. One config projects
+ * a full event entity into the cached list item and patches plain, paginated or
+ * infinite TanStack Query data without changing its envelope metadata.
  */
 import type { QueryKey } from '@tanstack/react-query';
 import type { CacheBridgeHandler } from './cache-bridge';
-/** The `deleted` event may carry the whole entity or just its id. */
-export type DeletedPayload<T> = T | {
+/** The `deleted` event may carry the whole entity or only its id. */
+export type DeletedPayload<TData> = TData | {
     id: string;
 };
+/** Typed event passed to dynamic list/detail query-key selectors. */
+export type EntityCacheEvent<TData> = {
+    type: 'created';
+    entity: TData;
+    id: string;
+} | {
+    type: 'updated';
+    entity: TData;
+    id: string;
+} | {
+    type: 'deleted';
+    payload: DeletedPayload<TData>;
+    id: string;
+};
+/** A static cache key/prefix or an event-aware key factory. */
+export type EntityCacheKey<TData> = QueryKey | ((event: EntityCacheEvent<TData>) => QueryKey);
+export type EntityCacheListShape = 'array' | 'paginated' | 'infinite-array' | 'infinite-paginated';
+/** List envelope, scoped key and explicit CRUD policies. */
+export interface EntityCacheListConfig<TData, TListItem> {
+    /** Static query-key prefix or an event-aware scoped key factory. */
+    key: EntityCacheKey<TData>;
+    /** Edge/page used for a create or an inserted missing update. */
+    createAt: 'start' | 'end';
+    /** Explicit behavior when an update's id is absent from every cached page. */
+    updateMissing: 'skip' | 'insert';
+    /** Backend-equivalent ordering for each affected logical item array. */
+    compare?: (left: TListItem, right: TListItem) => number;
+    /** Cached data envelope; no runtime shape inference is performed. */
+    shape: EntityCacheListShape;
+}
 /** Config for `createEntityCacheHandlers`. */
-export interface EntityCacheConfig<T> {
-    /** Read the entity's id — the identity used to match, replace and remove. */
-    getId: (entity: T) => string;
-    /** Read the id from a `deleted` payload (entity or `{ id }`). Default `getId` / `.id`. */
-    getDeletedId?: (payload: DeletedPayload<T>) => string;
-    /** Query key (or prefix) of the list(s) to patch — matched by partial equality. */
-    listKey: QueryKey;
-    /** Build the detail query key for an id. Omit to skip detail-cache updates. */
-    detailKey?: (id: string) => QueryKey;
+export interface EntityCacheConfig<TData, TListItem = TData> {
+    /** Canonical id from a full created/updated entity. */
+    getId: (entity: TData) => string;
+    /** Canonical id from the projected item stored in list caches. */
+    getListItemId: (item: TListItem) => string;
+    /** Project a full mutation entity into the list cache's item type. */
+    toListItem: (entity: TData) => TListItem;
+    /** Read a deleted id. Default: a string `.id`, otherwise `getId(payload)`. */
+    getDeletedId?: (payload: DeletedPayload<TData>) => string;
+    /** List envelope, key/prefix, insertion policy and optional ordering. */
+    list: EntityCacheListConfig<TData, TListItem>;
+    /** Static detail key or event-aware key factory. Omit to skip detail updates. */
+    detailKey?: EntityCacheKey<TData>;
 }
-/** The three handlers to wire onto a `createCacheBridge` `handlers` map. */
-export interface EntityCacheHandlers<T> {
-    created: CacheBridgeHandler<T>;
-    updated: CacheBridgeHandler<T>;
-    deleted: CacheBridgeHandler<DeletedPayload<T>>;
+/** The three handlers to wire onto a `createCacheBridge` handlers map. */
+export interface EntityCacheHandlers<TData> {
+    created: CacheBridgeHandler<TData>;
+    updated: CacheBridgeHandler<TData>;
+    deleted: CacheBridgeHandler<DeletedPayload<TData>>;
 }
 /**
- * Build created / updated / deleted cache handlers for one entity. Each skips a
- * stale socket echo of a change the client just made (`ctx.isFresh`), keyed on
- * the entity's detail key when available, else the list key.
+ * Build created/updated/deleted cache handlers over one declared list shape.
+ * Every event resolves its own scoped keys and applies the same fresh-echo gate.
  */
-export declare function createEntityCacheHandlers<T>(config: EntityCacheConfig<T>): EntityCacheHandlers<T>;
+export declare function createEntityCacheHandlers<TData, TListItem = TData>(config: EntityCacheConfig<TData, TListItem>): EntityCacheHandlers<TData>;
 //# sourceMappingURL=entity-cache.d.ts.map

package/dist/react/entity-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-cache.d.ts","sourceRoot":"","sources":["../../src/react/entity-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGpE,OAAO,KAAK,EAAsB,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAK7E,qEAAqE;AACrE,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,CAAC,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,6EAA6E;IAC7E,KAAK,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAAC;IAC7B,0FAA0F;IAC1F,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IACtD,mFAAmF;IACnF,OAAO,EAAE,QAAQ,CAAC;IAClB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,QAAQ,CAAC;CACtC;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAC/B,OAAO,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;CAChD;AAyBD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EACzC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC3B,mBAAmB,CAAC,CAAC,CAAC,CAuCxB"}
+{"version":3,"file":"entity-cache.d.ts","sourceRoot":"","sources":["../../src/react/entity-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAgB,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGpE,OAAO,KAAK,EAAsB,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,qEAAqE;AACrE,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,CAAC,KAAK,IAC9B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,+DAA+D;AAC/D,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI,QAAQ,GAAG,CAAC,CAAC,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAC5B,OAAO,GACP,WAAW,GACX,gBAAgB,GAChB,oBAAoB,CAAC;AAEzB,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB,CAAC,KAAK,EAAE,SAAS;IACrD,oEAAoE;IACpE,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,EAAE,OAAO,GAAG,KAAK,CAAC;IAC1B,8EAA8E;IAC9E,aAAa,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,MAAM,CAAC;IACxD,qEAAqE;IACrE,KAAK,EAAE,oBAAoB,CAAC;CAC7B;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK;IACzD,uDAAuD;IACvD,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,MAAM,CAAC;IACjC,kEAAkE;IAClE,aAAa,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC;IAC3C,sEAAsE;IACtE,UAAU,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,SAAS,CAAC;IACzC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC;IAC1D,yEAAyE;IACzE,IAAI,EAAE,qBAAqB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC9C,iFAAiF;IACjF,SAAS,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;CACnC;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB,CAAC,KAAK;IACxC,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,EAAE,kBAAkB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;CACpD;AAiJD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,EAChE,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,GAC1C,mBAAmB,CAAC,KAAK,CAAC,CAkD5B"}

package/dist/react.d.ts

@@ -1,4 +1,4 @@
 export { type CacheBridge, type CacheBridgeConfig, type CacheBridgeContext, type CacheBridgeHandler, type CacheBridgeHandlers, type CacheBridgeSocket, createCacheBridge, } from './react/cache-bridge';
 export { type CursorQueryConfig, createCursorQuery } from './react/cursor-query';
-export { createEntityCacheHandlers, type DeletedPayload, type EntityCacheConfig, type EntityCacheHandlers, } from './react/entity-cache';
+export { createEntityCacheHandlers, type DeletedPayload, type EntityCacheConfig, type EntityCacheEvent, type EntityCacheHandlers, type EntityCacheKey, type EntityCacheListConfig, type EntityCacheListShape, } from './react/entity-cache';
 //# sourceMappingURL=react.d.ts.map