stitchkit 0.17.0 → 0.19.0

package/dist/{index-yv93m4yr.js → index-ynnh9x6h.js}

@@ -1,12 +1,14 @@
 import {
+  base64UrlToBytes,
+  bytesToBase64Url,
   forbidden,
   unauthorized
-} from "./index-ktn76xz0.js";
+} from "./index-ng2v2ts4.js";
 import {
   isRecord,
   isUnsafeKey,
   safeJsonParse
-} from "./index-tm7dqzxc.js";
+} from "./index-c7nyw0yt.js";
 
 // src/server/middleware/cookies.ts
 function parseCookies(header) {
@@ -62,14 +64,6 @@ function defineCookie(config) {
 
 // src/server/middleware/auth.ts
 var MAX_TOKEN_BYTES = 8192;
-function decodeBase64Url(segment) {
-  if (!/^[A-Za-z0-9_-]*$/.test(segment) || segment.length % 4 === 1) {
-    throw new Error("invalid base64url segment");
-  }
-  const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, "=");
-  return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
-}
 async function verifyJwt(token, secret, options = {}) {
   if (!secret)
     throw new Error("verifyJwt: a non-empty secret is required");
@@ -83,9 +77,9 @@ async function verifyJwt(token, secret, options = {}) {
   let signature;
   try {
     const decoder = new TextDecoder;
-    header = JSON.parse(decoder.decode(decodeBase64Url(headerB64)));
-    payloadRaw = safeJsonParse(decoder.decode(decodeBase64Url(payloadB64)));
-    signature = decodeBase64Url(signatureB64);
+    header = JSON.parse(decoder.decode(base64UrlToBytes(headerB64)));
+    payloadRaw = safeJsonParse(decoder.decode(base64UrlToBytes(payloadB64)));
+    signature = base64UrlToBytes(signatureB64);
   } catch {
     throw unauthorized("Malformed token");
   }
@@ -125,12 +119,6 @@ async function verifyJwt(token, secret, options = {}) {
   }
   return payload;
 }
-function encodeBase64Url(bytes) {
-  let binary = "";
-  for (const byte of bytes)
-    binary += String.fromCharCode(byte);
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
 async function signJwt(payload, secret, options = {}) {
   if (!secret)
     throw new Error("signJwt: a non-empty secret is required");
@@ -144,12 +132,12 @@ async function signJwt(payload, secret, options = {}) {
     ...options.subject !== undefined && { sub: options.subject }
   };
   const encoder = new TextEncoder;
-  const headerB64 = encodeBase64Url(encoder.encode(JSON.stringify({ alg: "HS256", typ: "JWT" })));
-  const payloadB64 = encodeBase64Url(encoder.encode(JSON.stringify(claims)));
+  const headerB64 = bytesToBase64Url(encoder.encode(JSON.stringify({ alg: "HS256", typ: "JWT" })));
+  const payloadB64 = bytesToBase64Url(encoder.encode(JSON.stringify(claims)));
   const signingInput = `${headerB64}.${payloadB64}`;
   const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
   const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(signingInput));
-  const signatureB64 = encodeBase64Url(new Uint8Array(signature));
+  const signatureB64 = bytesToBase64Url(new Uint8Array(signature));
   return `${signingInput}.${signatureB64}`;
 }
 function extractToken(req, cookieName) {
@@ -197,15 +185,9 @@ function createBearerResolver(config) {
 }
 
 // src/server/middleware/pkce.ts
-function base64UrlEncode(bytes) {
-  let binary = "";
-  for (const byte of bytes)
-    binary += String.fromCharCode(byte);
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
 async function deriveCodeChallenge(verifier) {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
-  return base64UrlEncode(new Uint8Array(digest));
+  return bytesToBase64Url(new Uint8Array(digest));
 }
 async function verifyPkce(verifier, challenge) {
   if (!verifier || !challenge)

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export type { SocketEventMap, SocketIOClient, SocketIOClientConfig, } from './br
 export { createSocketIOClient } from './browser/socket-io';
 export { type ParseSSEOptions, parseSSE } from './browser/stream';
 export * from './contract';
+export { childSpan, createTraceContext, formatTraceparent, parseTraceparent, type TraceContext, } from './observability/trace';
 export { createRetainedTopics, type RetainedTopics } from './retained';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,YAAY,EACZ,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAClE,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,YAAY,EACZ,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,cAAc,EACd,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAClE,cAAc,YAAY,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -5,8 +5,10 @@ import {
   appError,
   badRequest,
   conflict,
+  createContractFactory,
   decodeCursor,
   defineContract,
+  defineErrors,
   encodeCursor,
   forbidden,
   isStitchErrorCode,
@@ -14,32 +16,58 @@ import {
   paginatedSchema,
   rateLimited,
   unauthorized
-} from "./index-yzac2zbh.js";
+} from "./index-x62gnfsk.js";
+import {
+  isRecord,
+  mapObject,
+  typedEntries
+} from "./index-809wc1tt.js";
 
 // src/internal/http-input.ts
 function inputIsQuery(method) {
   return method === "GET" || method === "DELETE";
 }
 
-// src/internal/typed.ts
-function typedEntries(value) {
-  return Object.entries(value);
+// src/browser/http.ts
+import ky, { isHTTPError } from "ky";
+
+// src/observability/trace.ts
+var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;
+function randomHex(bytes) {
+  const arr = new Uint8Array(bytes);
+  crypto.getRandomValues(arr);
+  let hex = "";
+  for (const byte of arr)
+    hex += byte.toString(16).padStart(2, "0");
+  return hex;
 }
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function createTraceContext() {
+  return { traceId: randomHex(16), spanId: randomHex(8) };
 }
-function mapObject(source, mapper) {
-  const result = {};
-  for (const [key, value] of typedEntries(source)) {
-    const mapped = mapper(key, value);
-    if (mapped !== undefined)
-      result[key] = mapped;
-  }
-  return result;
+function parseTraceparent(header) {
+  if (!header)
+    return null;
+  const match = TRACEPARENT_RE.exec(header.trim());
+  if (!match?.[1] || !match[2])
+    return null;
+  const traceId = match[1].toLowerCase();
+  const parentSpanId = match[2].toLowerCase();
+  if (/^0+$/.test(traceId) || /^0+$/.test(parentSpanId))
+    return null;
+  return { traceId, spanId: randomHex(8), parentSpanId };
+}
+function formatTraceparent(ctx) {
+  return `00-${ctx.traceId}-${ctx.spanId}-01`;
+}
+function childSpan(parent) {
+  return {
+    traceId: parent.traceId,
+    spanId: randomHex(8),
+    parentSpanId: parent.spanId
+  };
 }
 
 // src/browser/http.ts
-import ky, { isHTTPError } from "ky";
 class ApiError extends Error {
   code;
   status;
@@ -104,6 +132,9 @@ function createHttpClient(config) {
               request2.headers.set(key, value);
             }
           }
+          if (config.trace && !request2.headers.has("traceparent")) {
+            request2.headers.set("traceparent", formatTraceparent(createTraceContext()));
+          }
         }
       ],
       afterResponse: [
@@ -203,10 +234,16 @@ function withTimeout(options, timeout) {
     return options;
   return { ...options, timeout };
 }
+function withOutput(endpoint, result) {
+  const schema = endpoint.output;
+  if (!schema)
+    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) {
+function collectQueryParams(args, skipKeys, endpoint) {
   const params = {};
   let hasParams = false;
   for (const [key, value] of Object.entries(args)) {
@@ -215,7 +252,10 @@ function collectQueryParams(args, skipKeys) {
     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;
 }
@@ -266,18 +306,21 @@ function createHttpMethod(endpoint, prefix, client, config) {
       if (!isMultipartFile(file)) {
         throw new Error(`Missing multipart file field: ${endpoint.multipart}`);
       }
+      if (httpMethod === "get" || 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 client.post(url, formData, withTimeout(undefined, endpoint.timeout));
+      return withOutput(endpoint, client[httpMethod](url, formData, withTimeout(undefined, endpoint.timeout)));
     }
     if (isGet) {
-      const params = collectQueryParams(firstArg, prefixKeys);
-      return client.get(url, withTimeout(params ? { params } : undefined, endpoint.timeout));
+      const params = collectQueryParams(firstArg, prefixKeys, endpoint);
+      return withOutput(endpoint, client.get(url, withTimeout(params ? { params } : undefined, endpoint.timeout)));
     }
     if (httpMethod === "delete") {
-      const params = collectQueryParams(firstArg, prefixKeys);
-      return client.delete(url, withTimeout(params ? { params } : undefined, endpoint.timeout));
+      const params = collectQueryParams(firstArg, prefixKeys, endpoint);
+      return withOutput(endpoint, client.delete(url, withTimeout(params ? { params } : undefined, endpoint.timeout)));
     }
     const payload = {};
     for (const [key, value] of Object.entries(firstArg)) {
@@ -285,7 +328,7 @@ function createHttpMethod(endpoint, prefix, client, config) {
         payload[key] = value;
       }
     }
-    return client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint.timeout));
+    return withOutput(endpoint, client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint.timeout)));
   };
 }
 function createFetchMethod(endpoint, prefix, config, contractConfig) {
@@ -302,23 +345,24 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       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 searchParams = new URLSearchParams;
-      for (const [k, v] of Object.entries(remaining)) {
-        if (v === undefined || v === null)
-          continue;
-        if (isParamArray(v)) {
-          for (const item of v)
-            searchParams.append(k, String(item));
-        } else if (typeof v !== "object") {
-          searchParams.set(k, String(v));
+      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));
+          }
         }
-      }
-      if (searchParams.size > 0)
         url += `?${searchParams}`;
+      }
     }
     if (hasBody)
       headers["Content-Type"] = "application/json";
@@ -334,7 +378,8 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
         method: endpoint.method,
         headers,
         credentials: config.credentials,
-        body: formData
+        body: formData,
+        signal
       });
       if (!res2.ok) {
         await throwForErrorResponse(res2, config, null);
@@ -348,6 +393,7 @@ function createFetchMethod(endpoint, prefix, config, contractConfig) {
       method: endpoint.method,
       headers,
       credentials: config.credentials,
+      signal,
       ...hasBody && {
         body: JSON.stringify(stripParams(hasBody, endpoint.path, prefixKeys))
       }
@@ -417,9 +463,6 @@ function stripParams(args, path, extra) {
   }
   return result;
 }
-// src/browser/socket-io.ts
-import { io } from "socket.io-client";
-
 // src/retained.ts
 function createRetainedTopics() {
   const last = {};
@@ -447,6 +490,17 @@ function createRetainedTopics() {
 }
 
 // src/browser/socket-io.ts
+var SOCKET_IO_CLIENT = "socket.io-client";
+var ioLoader = null;
+function loadIo() {
+  if (!ioLoader) {
+    ioLoader = import(SOCKET_IO_CLIENT).then((mod) => mod.io, (cause) => {
+      ioLoader = null;
+      throw new Error('stitchkit: createSocketIOClient needs the "socket.io-client" peer — install it (e.g. `bun add socket.io-client`).', { cause });
+    });
+  }
+  return ioLoader;
+}
 function toIoAuth(auth) {
   if (typeof auth !== "function")
     return auth;
@@ -456,6 +510,7 @@ function toIoAuth(auth) {
 }
 function createSocketIOClient(config) {
   let socket = null;
+  let desiredConnected = false;
   let reconnectTimer = null;
   const serverDisconnectDelay = config.reconnectOnServerDisconnect ?? 1000;
   const connectionListeners = new Set;
@@ -473,50 +528,57 @@ function createSocketIOClient(config) {
       reconnectTimer = null;
     }
   }
+  function openSocket(io) {
+    if (!desiredConnected || socket)
+      return;
+    socket = io(config.url, {
+      path: config.path ?? "/socket.io/",
+      withCredentials: config.withCredentials ?? true,
+      auth: toIoAuth(config.auth),
+      ...config.query && { query: config.query },
+      ...config.extraHeaders && { extraHeaders: config.extraHeaders },
+      transports: config.transports ?? ["websocket", "polling"],
+      autoConnect: false,
+      reconnection: true,
+      reconnectionAttempts: config.reconnectionAttempts ?? Infinity,
+      reconnectionDelay: config.reconnectionDelay ?? 1000,
+      reconnectionDelayMax: config.reconnectionDelayMax ?? 5000,
+      timeout: config.timeout ?? 20000
+    });
+    socket.on("connect", () => notifyConnection(true));
+    socket.on("disconnect", (reason) => {
+      notifyConnection(false, reason);
+      if (reason === "io server disconnect" && serverDisconnectDelay !== false) {
+        const current = socket;
+        clearReconnectTimer();
+        reconnectTimer = setTimeout(() => {
+          reconnectTimer = null;
+          if (socket === current && current && !current.connected)
+            current.connect();
+        }, serverDisconnectDelay);
+      }
+    });
+    if (retained) {
+      for (const name of retainNames) {
+        socket.on(name, (payload) => retained.record(name, payload));
+      }
+    }
+    for (const attach of subscriptions)
+      attach(socket);
+    socket.connect();
+  }
   return {
     get connected() {
       return socket?.connected ?? false;
     },
     connect() {
-      if (socket)
+      if (socket || desiredConnected)
         return;
-      socket = io(config.url, {
-        path: config.path ?? "/socket.io/",
-        withCredentials: config.withCredentials ?? true,
-        auth: toIoAuth(config.auth),
-        ...config.query && { query: config.query },
-        ...config.extraHeaders && { extraHeaders: config.extraHeaders },
-        transports: config.transports ?? ["websocket", "polling"],
-        autoConnect: false,
-        reconnection: true,
-        reconnectionAttempts: config.reconnectionAttempts ?? Infinity,
-        reconnectionDelay: config.reconnectionDelay ?? 1000,
-        reconnectionDelayMax: config.reconnectionDelayMax ?? 5000,
-        timeout: config.timeout ?? 20000
-      });
-      socket.on("connect", () => notifyConnection(true));
-      socket.on("disconnect", (reason) => {
-        notifyConnection(false, reason);
-        if (reason === "io server disconnect" && serverDisconnectDelay !== false) {
-          const current = socket;
-          clearReconnectTimer();
-          reconnectTimer = setTimeout(() => {
-            reconnectTimer = null;
-            if (socket === current && current && !current.connected)
-              current.connect();
-          }, serverDisconnectDelay);
-        }
-      });
-      if (retained) {
-        for (const name of retainNames) {
-          socket.on(name, (payload) => retained.record(name, payload));
-        }
-      }
-      for (const attach of subscriptions)
-        attach(socket);
-      socket.connect();
+      desiredConnected = true;
+      loadIo().then(openSocket);
     },
     disconnect() {
+      desiredConnected = false;
       clearReconnectTimer();
       if (!socket)
         return;
@@ -596,20 +658,26 @@ async function* parseSSE(response, options) {
 export {
   unauthorized,
   rateLimited,
+  parseTraceparent,
   parseSSE,
   paginatedSchema,
   notFound,
   isStitchErrorCode,
+  formatTraceparent,
   forbidden,
   encodeCursor,
+  defineErrors,
   defineContract,
   decodeCursor,
+  createTraceContext,
   createSocketIOClient,
   createRetainedTopics,
   createHttpClient,
+  createContractFactory,
   createClients,
   createClient,
   conflict,
+  childSpan,
   badRequest,
   appError,
   STITCH_ERROR_STATUS,

package/dist/internal/base64url.d.ts

@@ -0,0 +1,16 @@
+/**
+ * base64url over raw bytes — the one codec shared by cursor pagination, JWT
+ * segments, OAuth-token minting and PKCE. `btoa`/`atob` based (not Node
+ * `Buffer`), so it works identically in the server, the browser and the typed
+ * client. Kept byte-level: string callers compose with `TextEncoder` /
+ * `TextDecoder` themselves (pagination round-trips UTF-8; JWT/PKCE are binary).
+ */
+/** Encode raw bytes as an unpadded base64url string. */
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+/**
+ * Decode a base64url string to bytes. A character outside the alphabet, or a
+ * length that no base64 string can have (`% 4 === 1`), is malformed — reject it
+ * before `atob` rather than emit silent garbage.
+ */
+export declare function base64UrlToBytes(segment: string): Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=base64url.d.ts.map

package/dist/internal/base64url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64url.d.ts","sourceRoot":"","sources":["../../src/internal/base64url.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAI1D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAOzE"}

package/dist/node.js

@@ -3,7 +3,8 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-6k6y7wat.js";
+} from "./index-wpbn133x.js";
+import"./index-tje0q6gp.js";
 import {
   AppError,
   appError,
@@ -13,9 +14,10 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-ktn76xz0.js";
-import"./index-fwqnkc90.js";
-import"./index-tm7dqzxc.js";
+} from "./index-ng2v2ts4.js";
+import"./index-dzx781tm.js";
+import"./index-khwedj16.js";
+import"./index-c7nyw0yt.js";
 // src/server/node.ts
 import { serve } from "srvx";
 async function serveNode(config) {

package/dist/observability/index.js

@@ -1,23 +1,25 @@
 import {
-  childSpan,
-  createTraceContext,
-  formatTraceparent,
   getRequestContext,
   getTraceId,
   getUserId,
-  parseTraceparent,
-  resolveTraceContext,
   runWithRequestContext,
   setRequestDimensions,
   setRequestEndpoint,
   setRequestError,
   setRequestUser,
   wrapInRequestContext
-} from "../index-fwqnkc90.js";
+} from "../index-dzx781tm.js";
+import {
+  childSpan,
+  createTraceContext,
+  formatTraceparent,
+  parseTraceparent,
+  resolveTraceContext
+} from "../index-khwedj16.js";
 import {
   isRecord,
   isUnsafeKey
-} from "../index-tm7dqzxc.js";
+} from "../index-c7nyw0yt.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

@@ -0,0 +1,54 @@
+/**
+ * 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,
+ * }});
+ * ```
+ */
+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 | {
+    id: string;
+};
+/** 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;
+}
+/** The three handlers to wire onto a `createCacheBridge` `handlers` map. */
+export interface EntityCacheHandlers<T> {
+    created: CacheBridgeHandler<T>;
+    updated: CacheBridgeHandler<T>;
+    deleted: CacheBridgeHandler<DeletedPayload<T>>;
+}
+/**
+ * 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.
+ */
+export declare function createEntityCacheHandlers<T>(config: EntityCacheConfig<T>): EntityCacheHandlers<T>;
+//# sourceMappingURL=entity-cache.d.ts.map

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

@@ -0,0 +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"}

package/dist/react.d.ts

@@ -1,3 +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';
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EACL,yBAAyB,EACzB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAC"}