kitcn 0.16.0 → 0.17.0

package/dist/plugins/index.js

@@ -1,3 +1,3 @@
-import { n as resolvePluginOptions, t as definePlugin } from "../middleware-Bg-PdtrI.js";
+import { n as resolvePluginOptions, t as definePlugin } from "../middleware-Cgrv2jIu.js";
 
 export { definePlugin, resolvePluginOptions };

package/dist/{procedure-caller-9m6NBxQu.js → procedure-caller-Rj6z3ai7.js}

@@ -1,5 +1,5 @@
 import { i as decodeWire, o as encodeWire } from "./transformer-C6pGVHqx.js";
-import { _ as CRPCError } from "./builder-DBgto1yn.js";
+import { _ as CRPCError } from "./builder-f4F_NRvK.js";
 import { z } from "zod";
 
 //#region src/server/env.ts

package/dist/{procedure-name-Cy1AxayA.d.ts → procedure-name-Bo5KMcqc.d.ts}

@@ -734,7 +734,12 @@ declare function createMiddlewareFactory<TDefaultContext, TMeta = object>(): <TC
 /** Internal definition storing procedure state */
 type ProcedureBuilderDef<TMeta = object> = {
   middlewares: AnyMiddleware[];
-  inputSchemas: Record<string, any>[];
+  /**
+   * Full `.input()` schemas, not their shapes: object-level checks
+   * (`.refine()`, `.superRefine()`, strict/catchall) only survive on the
+   * schema itself.
+   */
+  inputSchemas: z.ZodObject<any>[];
   outputSchema?: z.ZodTypeAny;
   meta?: TMeta;
   procedureName?: string;
@@ -764,7 +769,7 @@ declare class ProcedureBuilder<TBaseCtx, _TContext, TContextOverrides extends Un
   protected _meta(value: TMeta): ProcedureBuilderDef<TMeta>;
   /** Set server-only procedure name for middleware/logging */
   protected _name(value: string): ProcedureBuilderDef<TMeta>;
-  /** Merge all input schemas into one */
+  /** Merge every `.input()` shape - used to build the Convex arg validator */
   protected _getMergedInput(): Record<string, any> | undefined;
   protected _createFunction(handler: any, baseFunction: any, customFn: typeof zCustomQuery | typeof zCustomMutation | typeof zCustomAction, fnType: 'query' | 'mutation' | 'action'): Record<string, unknown>;
 }
@@ -1076,7 +1081,14 @@ type TokenResult = {
 type GetTokenFn = (siteUrl: string, headers: Headers, opts?: unknown) => Promise<TokenResult>;
 /** Auth options for server-side calls. */
 type AuthOptions = {
-  /** Function to extract auth token from request headers. */getToken: GetTokenFn; /** Custom function to detect UNAUTHORIZED errors. Default checks code property. */
+  /** Function to extract auth token from request headers. */getToken: GetTokenFn;
+  /**
+   * Custom function to detect UNAUTHORIZED errors.
+   * Set this to resolve those errors to `null` instead of throwing.
+   *
+   * Refreshing an expired cached token and retrying does not require this:
+   * that always falls back to `defaultIsUnauthorized`.
+   */
   isUnauthorized?: (error: unknown) => boolean;
 };
 type CreateCallerFactoryOptions<TApi> = {

package/dist/{query-context-ydn9kb6P.js → query-context-C90vNlc9.js}

@@ -23,6 +23,71 @@ function isFieldReference(value) {
 	return value && typeof value === "object" && value.__brand === "FieldReference";
 }
 /**
+* SQL `LIKE` semantics: `%` matches any run of characters, `_` matches exactly
+* one, everything else is literal. Wildcards work anywhere in the pattern, not
+* only at the ends.
+*
+* Matched with a single-backtrack scan rather than a compiled regex. A pattern
+* is caller data — anything interpolated into `` `%${query}%` `` reaches here —
+* and translating `%` to a regex quantifier makes `'%%%%%z'` backtrack
+* exponentially, which would burn the whole Convex function CPU budget on one
+* row. This scan remembers only the most recent `%`, so the worst case is
+* O(value * pattern) with no catastrophic case at all.
+*/
+function matchLikePattern(value, pattern, caseInsensitive) {
+	const target = Array.from(caseInsensitive ? value.toLowerCase() : value);
+	const source = Array.from(caseInsensitive ? pattern.toLowerCase() : pattern);
+	let valueIndex = 0;
+	let patternIndex = 0;
+	let wildcardPatternIndex = -1;
+	let wildcardValueIndex = 0;
+	while (valueIndex < target.length) {
+		const patternChar = patternIndex < source.length ? source[patternIndex] : void 0;
+		if (patternChar === "_" || patternChar === target[valueIndex]) {
+			valueIndex += 1;
+			patternIndex += 1;
+		} else if (patternChar === "%") {
+			wildcardPatternIndex = patternIndex;
+			wildcardValueIndex = valueIndex;
+			patternIndex += 1;
+		} else if (wildcardPatternIndex === -1) return false;
+		else {
+			wildcardValueIndex += 1;
+			valueIndex = wildcardValueIndex;
+			patternIndex = wildcardPatternIndex + 1;
+		}
+	}
+	while (patternIndex < source.length && source[patternIndex] === "%") patternIndex += 1;
+	return patternIndex === source.length;
+}
+/**
+* Structural equality matching Convex's own `q.eq`. Arrays, objects and bytes
+* are compared by content: reference identity would make every `eq`/`in` filter
+* on a `custom(v.array(...))` / `custom(v.object(...))` column match nothing.
+*/
+function filterValuesEqual(a, b) {
+	if (a === b) return true;
+	if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!(Array.isArray(a) && Array.isArray(b)) || a.length !== b.length) return false;
+		return a.every((item, index) => filterValuesEqual(item, b[index]));
+	}
+	if (a instanceof ArrayBuffer || b instanceof ArrayBuffer) {
+		if (!(a instanceof ArrayBuffer && b instanceof ArrayBuffer) || a.byteLength !== b.byteLength) return false;
+		const left = new Uint8Array(a);
+		const right = new Uint8Array(b);
+		return left.every((byte, index) => byte === right[index]);
+	}
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) return false;
+	return aKeys.every((key) => Object.hasOwn(b, key) && filterValuesEqual(a[key], b[key]));
+}
+/** `inArray`/`notInArray` membership using {@link filterValuesEqual}. */
+function filterValueInList(value, list) {
+	return list.some((candidate) => filterValuesEqual(candidate, value));
+}
+/**
 * Create a column wrapper
 * Used internally by query builder's _createColumnProxies
 */
@@ -1121,11 +1186,13 @@ var FlatMapStreamIterator = class {
 	#currentOuterItem = null;
 	#mapper;
 	#mappedIndexFields;
-	constructor(outerStream, mapper, mappedIndexFields) {
+	#emptyMappedKeyAllowed;
+	constructor(outerStream, mapper, mappedIndexFields, emptyMappedKeyAllowed) {
 		this.#outerIterator = outerStream.iterWithKeys()[Symbol.asyncIterator]();
 		this.#outerStream = outerStream;
 		this.#mapper = mapper;
 		this.#mappedIndexFields = mappedIndexFields;
+		this.#emptyMappedKeyAllowed = emptyMappedKeyAllowed;
 	}
 	singletonSkipInnerStream() {
 		const indexKey = this.#mappedIndexFields.map(() => null);
@@ -1136,7 +1203,7 @@ var FlatMapStreamIterator = class {
 		let innerStream;
 		if (t === null) innerStream = this.singletonSkipInnerStream();
 		else {
-			innerStream = await this.#mapper(t);
+			innerStream = await this.#mapper(t, indexKey);
 			if (!equalIndexFields(innerStream.getIndexFields(), this.#mappedIndexFields)) throw new Error(`FlatMapStream: inner stream has different index fields than expected: ${JSON.stringify(innerStream.getIndexFields())} vs ${JSON.stringify(this.#mappedIndexFields)}`);
 			if (innerStream.getOrder() !== this.#outerStream.getOrder()) throw new Error(`FlatMapStream: inner stream has different order than outer stream: ${innerStream.getOrder()} vs ${this.#outerStream.getOrder()}`);
 		}
@@ -1159,7 +1226,7 @@ var FlatMapStreamIterator = class {
 		}
 		const result = await this.#currentOuterItem.innerIterator.next();
 		if (result.done) {
-			if (this.#currentOuterItem.count > 0) this.#currentOuterItem = null;
+			if (this.#currentOuterItem.count > 0 || !this.#emptyMappedKeyAllowed(this.#currentOuterItem.indexKey)) this.#currentOuterItem = null;
 			else this.#currentOuterItem.innerIterator = this.singletonSkipInnerStream().iterWithKeys()[Symbol.asyncIterator]();
 			return await this.next();
 		}
@@ -1175,18 +1242,21 @@ var FlatMapStream = class FlatMapStream extends QueryStream {
 	#stream;
 	#mapper;
 	#mappedIndexFields;
-	constructor(stream, mapper, mappedIndexFields) {
+	#emptyMappedKeyAllowed;
+	constructor(stream, mapper, mappedIndexFields, emptyMappedKeyAllowed = () => true) {
 		super();
 		this.#stream = stream;
 		this.#mapper = mapper;
 		this.#mappedIndexFields = mappedIndexFields;
+		this.#emptyMappedKeyAllowed = emptyMappedKeyAllowed;
 	}
 	iterWithKeys() {
 		const outerStream = this.#stream;
 		const mapper = this.#mapper;
 		const mappedIndexFields = this.#mappedIndexFields;
+		const emptyMappedKeyAllowed = this.#emptyMappedKeyAllowed;
 		return { [Symbol.asyncIterator]() {
-			return new FlatMapStreamIterator(outerStream, mapper, mappedIndexFields);
+			return new FlatMapStreamIterator(outerStream, mapper, mappedIndexFields, emptyMappedKeyAllowed);
 		} };
 	}
 	getOrder() {
@@ -1210,15 +1280,34 @@ var FlatMapStream = class FlatMapStream extends QueryStream {
 			upperBound: outerUpperBound,
 			upperBoundInclusive: innerUpperBound.length === 0 ? indexBounds.upperBoundInclusive : true
 		};
-		const innerIndexBounds = {
-			lowerBound: innerLowerBound,
-			lowerBoundInclusive: innerLowerBound.length === 0 ? true : indexBounds.lowerBoundInclusive,
-			upperBound: innerUpperBound,
-			upperBoundInclusive: innerUpperBound.length === 0 ? true : indexBounds.upperBoundInclusive
+		const unrestricted = {
+			lowerBound: [],
+			lowerBoundInclusive: true,
+			upperBound: [],
+			upperBoundInclusive: true
 		};
-		return new FlatMapStream(this.#stream.narrow(outerIndexBounds), async (t) => {
-			return (await this.#mapper(t)).narrow(innerIndexBounds);
-		}, this.#mappedIndexFields);
+		const isBoundaryParent = (parentKey, bound) => bound.length === outerLength && compareKeys({
+			value: parentKey,
+			kind: "exact"
+		}, {
+			value: bound,
+			kind: "exact"
+		}) === 0;
+		const innerBoundsForParent = (parentKey) => {
+			const atLowerBound = innerLowerBound.length > 0 && isBoundaryParent(parentKey, outerLowerBound);
+			const atUpperBound = innerUpperBound.length > 0 && isBoundaryParent(parentKey, outerUpperBound);
+			if (!(atLowerBound || atUpperBound)) return unrestricted;
+			return {
+				lowerBound: atLowerBound ? innerLowerBound : unrestricted.lowerBound,
+				lowerBoundInclusive: atLowerBound ? indexBounds.lowerBoundInclusive : true,
+				upperBound: atUpperBound ? innerUpperBound : unrestricted.upperBound,
+				upperBoundInclusive: atUpperBound ? indexBounds.upperBoundInclusive : true
+			};
+		};
+		const emptyMappedIndexKey = this.#mappedIndexFields.map(() => null);
+		return new FlatMapStream(this.#stream.narrow(outerIndexBounds), async (t, parentKey) => {
+			return (await this.#mapper(t, parentKey)).narrow(innerBoundsForParent(parentKey));
+		}, this.#mappedIndexFields, (parentKey) => this.#emptyMappedKeyAllowed(parentKey) && indexKeyWithinBounds(emptyMappedIndexKey, innerBoundsForParent(parentKey)));
 	}
 };
 var SingletonStream = class SingletonStream extends QueryStream {
@@ -1264,25 +1353,37 @@ var SingletonStream = class SingletonStream extends QueryStream {
 		return this.#equalityIndexFilter;
 	}
 	narrow(indexBounds) {
-		const compareLowerBound = compareKeys({
-			value: indexBounds.lowerBound,
-			kind: indexBounds.lowerBoundInclusive ? "exact" : "successor"
-		}, {
-			value: this.#indexKey,
-			kind: "exact"
-		});
-		const compareUpperBound = compareKeys({
-			value: this.#indexKey,
-			kind: "exact"
-		}, {
-			value: indexBounds.upperBound,
-			kind: indexBounds.upperBoundInclusive ? "exact" : "predecessor"
-		});
-		if (compareLowerBound <= 0 && compareUpperBound <= 0) return new SingletonStream(this.#value, this.#order, this.#indexFields, this.#indexKey, this.#equalityIndexFilter);
+		if (indexKeyWithinBounds(this.#indexKey, indexBounds)) return new SingletonStream(this.#value, this.#order, this.#indexFields, this.#indexKey, this.#equalityIndexFilter);
 		return new EmptyStream(this.#order, this.#indexFields);
 	}
 };
 /**
+* True when `lowerBound <= indexKey <= upperBound`, honouring each bound's
+* inclusivity.
+*
+* Bounds are compared as `predecessor`/`successor` rather than `exact`, the
+* same convention `StreamQuery.narrow` uses. That is what lets a bound be a
+* prefix of the key — including the empty prefix that means unbounded — and it
+* agrees with `exact` whenever the two are the same length.
+*/
+function indexKeyWithinBounds(indexKey, indexBounds) {
+	const compareLowerBound = compareKeys({
+		value: indexBounds.lowerBound,
+		kind: indexBounds.lowerBoundInclusive ? "predecessor" : "successor"
+	}, {
+		value: indexKey,
+		kind: "exact"
+	});
+	const compareUpperBound = compareKeys({
+		value: indexKey,
+		kind: "exact"
+	}, {
+		value: indexBounds.upperBound,
+		kind: indexBounds.upperBoundInclusive ? "successor" : "predecessor"
+	});
+	return compareLowerBound <= 0 && compareUpperBound <= 0;
+}
+/**
 * This is a completely empty stream that yields no values, and in particular
 * does not count towards maxScan.
 * Compare to SingletonStream(null, ...), which yields no values but does count
@@ -1320,7 +1421,7 @@ var EmptyStream = class extends QueryStream {
 	}
 };
 function normalizeIndexFields(indexFields) {
-	if (!indexFields.includes("_creationTime") && (indexFields.length !== 1 || indexFields[0] !== "_id")) indexFields.push("_creationTime");
+	if (!indexFields.includes("_creationTime") && !indexFields.includes("_id")) indexFields.push("_creationTime");
 	if (!indexFields.includes("_id")) indexFields.push("_id");
 }
 function* getOrderingIndexFields(stream) {
@@ -1515,4 +1616,4 @@ async function getByIdWithOrmQueryFallback(ctx, tableName, id) {
 }
 
 //#endregion
-export { ne as A, inArray as C, like as D, isNull as E, notLike as F, or as I, startsWith as L, notBetween as M, notIlike as N, lt as O, notInArray as P, ilike as S, isNotNull as T, endsWith as _, mergedStream as a, gt as b, isUnsetToken as c, arrayContained as d, arrayContains as f, contains as g, column as h, getIndexFields as i, not as j, lte as k, unsetToken as l, between as m, EmptyStream as n, stream as o, arrayOverlaps as p, QueryStream as r, streamIndexRange as s, getByIdWithOrmQueryFallback as t, and as u, eq as v, isFieldReference as w, gte as x, fieldRef as y };
+export { like as A, or as B, gt as C, isFieldReference as D, inArray as E, not as F, notBetween as I, notIlike as L, lte as M, matchLikePattern as N, isNotNull as O, ne as P, notInArray as R, filterValuesEqual as S, ilike as T, startsWith as V, contains as _, indexKeyWithinBounds as a, fieldRef as b, streamIndexRange as c, and as d, arrayContained as f, column as g, between as h, getIndexFields as i, lt as j, isNull as k, isUnsetToken as l, arrayOverlaps as m, EmptyStream as n, mergedStream as o, arrayContains as p, QueryStream as r, stream as s, getByIdWithOrmQueryFallback as t, unsetToken as u, endsWith as v, gte as w, filterValueInList as x, eq as y, notLike as z };

package/dist/query-options-C_eBSIXG.js

@@ -0,0 +1,247 @@
+import { getFunctionName } from "convex/server";
+
+//#region src/crpc/http-types.ts
+/** HTTP client error */
+var HttpClientError = class extends Error {
+	name = "HttpClientError";
+	code;
+	status;
+	procedureName;
+	constructor(opts) {
+		super(opts.message ?? `${opts.code}: ${opts.procedureName}`);
+		this.code = opts.code;
+		this.status = opts.status;
+		this.procedureName = opts.procedureName;
+	}
+};
+/** Type guard for HttpClientError */
+const isHttpClientError = (error) => error instanceof HttpClientError;
+
+//#endregion
+//#region src/crpc/http-client.ts
+/**
+* HTTP Client Helpers
+*
+* Framework-agnostic utilities for executing HTTP requests
+* against Convex HTTP endpoints.
+*/
+/** Reserved keys that are not part of JSON body */
+const RESERVED_KEYS = new Set([
+	"params",
+	"searchParams",
+	"form",
+	"fetch",
+	"init",
+	"headers"
+]);
+/**
+* Replace URL path parameters with actual values.
+* e.g., '/users/:id' with { id: '123' } -> '/users/123'
+*/
+function replaceUrlParam(url, params) {
+	return url.replace(/:(\w+)/g, (_, key) => {
+		const value = params[key];
+		return value !== void 0 ? encodeURIComponent(value) : `:${key}`;
+	});
+}
+/**
+* Build URLSearchParams from query object.
+* Handles array values as multiple params with same key (like Hono).
+*/
+function buildSearchParams(query) {
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) if (Array.isArray(value)) for (const v of value) params.append(key, v);
+	else if (value !== void 0 && value !== null) params.append(key, value);
+	return params;
+}
+/**
+* Hono-style HTTP request executor.
+* Processes args in the same way as Hono's ClientRequestImpl.fetch().
+*/
+async function executeHttpRequest(opts) {
+	const { method, path } = opts.route;
+	const args = opts.args ?? {};
+	let rBody;
+	let cType;
+	if (args.form) {
+		const form = new FormData();
+		for (const [k, v] of Object.entries(args.form)) if (Array.isArray(v)) for (const v2 of v) form.append(k, v2);
+		else form.append(k, v);
+		rBody = form;
+	} else {
+		const jsonBody = {};
+		for (const [key, value] of Object.entries(args)) if (!RESERVED_KEYS.has(key) && value !== void 0) jsonBody[key] = value;
+		if (Object.keys(jsonBody).length > 0) {
+			rBody = JSON.stringify(opts.transformer.input.serialize(jsonBody));
+			cType = "application/json";
+		}
+	}
+	const argsClientOpts = {};
+	if (args.fetch) argsClientOpts.fetch = args.fetch;
+	if (args.init) argsClientOpts.init = args.init;
+	if (args.headers) argsClientOpts.headers = args.headers;
+	const mergedClientOpts = {
+		...opts.clientOpts,
+		...argsClientOpts
+	};
+	const resolvedBaseHeaders = typeof opts.baseHeaders === "function" ? await opts.baseHeaders() : opts.baseHeaders;
+	const headerValues = { ...typeof mergedClientOpts.headers === "function" ? await mergedClientOpts.headers() : mergedClientOpts.headers };
+	if (cType) headerValues["Content-Type"] = cType;
+	const finalHeaders = {};
+	if (resolvedBaseHeaders) {
+		for (const [key, value] of Object.entries(resolvedBaseHeaders)) if (value !== void 0) finalHeaders[key] = value;
+	}
+	Object.assign(finalHeaders, headerValues);
+	let url = opts.convexSiteUrl + path;
+	if (args.params) url = opts.convexSiteUrl + replaceUrlParam(path, args.params);
+	if (args.searchParams) {
+		const queryString = buildSearchParams(args.searchParams).toString();
+		if (queryString) url = `${url}?${queryString}`;
+	}
+	const methodUpperCase = method.toUpperCase();
+	const setBody = !(methodUpperCase === "GET" || methodUpperCase === "HEAD");
+	const response = await (mergedClientOpts.fetch ?? opts.baseFetch ?? globalThis.fetch)(url, {
+		body: setBody ? rBody : void 0,
+		method: methodUpperCase,
+		headers: finalHeaders,
+		...mergedClientOpts.init
+	});
+	if (!response.ok) {
+		const errorData = await response.json().catch(() => ({ error: {
+			code: "UNKNOWN",
+			message: response.statusText
+		} }));
+		const errorCode = errorData?.error?.code || "UNKNOWN";
+		const errorMessage = errorData?.error?.message || response.statusText;
+		throw new HttpClientError({
+			code: errorCode,
+			status: response.status,
+			procedureName: opts.procedureName,
+			message: errorMessage
+		});
+	}
+	if (response.headers.get("content-length") === "0" || response.status === 204) return;
+	if ((response.headers.get("content-type") || "").includes("application/json")) return opts.transformer.output.deserialize(await response.json());
+	return response.text();
+}
+
+//#endregion
+//#region src/crpc/query-options.ts
+/**
+* Query options factory for Convex query function subscriptions.
+* Requires `convexQueryClient.queryFn()` set as the default `queryFn` globally.
+*/
+function convexQuery(funcRef, args, meta, opts) {
+	const finalArgs = args ?? {};
+	const isSkip = finalArgs === "skip";
+	const funcName = getFunctionName(funcRef);
+	const [namespace, fnName] = funcName.split(":");
+	const authType = meta?.[namespace]?.[fnName]?.auth;
+	const skipUnauth = opts?.skipUnauth;
+	return {
+		queryKey: [
+			"convexQuery",
+			funcName,
+			isSkip ? "skip" : finalArgs
+		],
+		staleTime: Number.POSITIVE_INFINITY,
+		refetchInterval: false,
+		refetchOnMount: false,
+		refetchOnReconnect: false,
+		refetchOnWindowFocus: false,
+		...isSkip ? { enabled: false } : {},
+		meta: {
+			authType,
+			skipUnauth,
+			subscribe: true
+		}
+	};
+}
+/**
+* Query options factory for Convex action functions.
+* Actions are NOT reactive - they follow normal TanStack Query semantics.
+*
+* @example
+* ```ts
+* useQuery(convexAction(api.ai.generate, { prompt }))
+* ```
+*
+* @example With additional options (use spread):
+* ```ts
+* useQuery({
+*   ...convexAction(api.files.process, { fileId }),
+*   staleTime: 60_000
+* });
+* ```
+*/
+function convexAction(funcRef, args, meta, opts) {
+	const finalArgs = args ?? {};
+	const isSkip = finalArgs === "skip";
+	const funcName = getFunctionName(funcRef);
+	const [namespace, fnName] = funcName.split(":");
+	const authType = meta?.[namespace]?.[fnName]?.auth;
+	const skipUnauth = opts?.skipUnauth;
+	return {
+		queryKey: [
+			"convexAction",
+			funcName,
+			isSkip ? {} : finalArgs
+		],
+		staleTime: Number.POSITIVE_INFINITY,
+		refetchInterval: false,
+		refetchOnMount: false,
+		refetchOnReconnect: false,
+		refetchOnWindowFocus: false,
+		...isSkip ? { enabled: false } : {},
+		meta: {
+			authType,
+			skipUnauth,
+			subscribe: false
+		}
+	};
+}
+/**
+* Infinite query options factory for paginated Convex queries.
+* Server-safe (non-hook) - can be used in RSC.
+*
+* Uses flat { cursor, limit } input like tRPC.
+*/
+function convexInfiniteQueryOptions(funcRef, args, opts = {}, meta) {
+	const { limit, skipUnauth, enabled, ...queryOptions } = opts;
+	const finalArgs = args === "skip" ? {} : args;
+	const isSkip = args === "skip";
+	const funcName = getFunctionName(funcRef);
+	const [namespace, fnName] = funcName.split(":");
+	const authType = (meta?.[namespace]?.[fnName])?.auth;
+	const firstPageArgs = {
+		...finalArgs,
+		cursor: null,
+		limit
+	};
+	const finalEnabled = isSkip ? false : enabled;
+	return {
+		queryKey: [
+			"convexQuery",
+			funcName,
+			firstPageArgs
+		],
+		staleTime: Number.POSITIVE_INFINITY,
+		refetchInterval: false,
+		refetchOnMount: false,
+		refetchOnReconnect: false,
+		refetchOnWindowFocus: false,
+		...queryOptions,
+		...finalEnabled === void 0 ? {} : { enabled: finalEnabled },
+		meta: {
+			authType,
+			skipUnauth,
+			subscribe: true,
+			queryName: funcName,
+			args: finalArgs,
+			limit
+		}
+	};
+}
+
+//#endregion
+export { buildSearchParams as a, HttpClientError as c, RESERVED_KEYS as i, isHttpClientError as l, convexInfiniteQueryOptions as n, executeHttpRequest as o, convexQuery as r, replaceUrlParam as s, convexAction as t };

package/dist/ratelimit/index.d.ts

@@ -9,7 +9,7 @@ type Duration = number | DurationString;
 declare function toMs(duration: Duration): number;
 //#endregion
 //#region src/ratelimit/types.d.ts
-type RatelimitReason = 'timeout' | 'cacheBlock' | 'denyList';
+type RatelimitReason = 'timeout' | 'cacheBlock' | 'denyList' | 'requestTooLarge';
 type RatelimitResponse = {
   success: boolean;
   ok: boolean;
@@ -28,17 +28,25 @@ type RemainingResponse = {
 type DynamicLimitResponse = {
   dynamicLimit: number | null;
 };
-type RatelimitState = {
+type RatelimitStoredState = {
   value: number;
   ts: number;
   auxValue?: number;
   auxTs?: number;
 };
+type RatelimitShardState = {
+  shard: number;
+  state: RatelimitStoredState;
+};
+type RatelimitState = RatelimitStoredState & {
+  shards?: RatelimitShardState[];
+};
 type RatelimitSnapshot = {
   value: number;
   ts: number;
   shard: number;
   config: ResolvedAlgorithm;
+  state: RatelimitState;
 };
 type BaseAlgorithmOptions = {
   shards?: number;
@@ -151,12 +159,22 @@ declare function applyDynamicLimit(algorithm: ResolvedAlgorithm, dynamicLimit: n
 //#region src/ratelimit/core/calculate-rate-limit.d.ts
 type EvaluationResult = {
   state: RatelimitState;
-  retryAfter?: number;
-  remaining: number;
+  retryAfter?: number; /** Tokens left after this request, floored to `0`. */
+  remaining: number; /** Exact tokens left after this request. Negative when the request overdraws. */
+  remainingRaw: number;
   reset: number;
   limit: number;
 };
 declare function calculateRatelimit(state: RatelimitState | null, algorithm: ResolvedAlgorithm, now: number, count: number): EvaluationResult;
+/**
+ * Convert a {@link RatelimitSnapshot} back into the `RatelimitState` shape that
+ * {@link calculateRatelimit} consumes.
+ *
+ * Snapshot `value` is always "tokens left". Fixed window and token bucket store
+ * that directly, but sliding window state stores the used count, so it has to be
+ * inverted before it can be replayed.
+ */
+declare function snapshotToState(snapshot: RatelimitSnapshot): RatelimitState;
 //#endregion
 //#region src/ratelimit/plugin.d.ts
 type MaybePromise<T> = T | Promise<T>;
@@ -224,6 +242,7 @@ declare class Ratelimit {
   private readonly blockCache?;
   private readonly blockCacheSource?;
   private readonly checkCache;
+  private cacheGeneration;
   constructor(config: RatelimitConfig);
   limit(identifier: string, request?: LimitRequest): Promise<RatelimitResponse>;
   check(identifier: string, request?: CheckRequest): Promise<RatelimitResponse>;
@@ -246,9 +265,10 @@ declare class Ratelimit {
   };
   private withDb;
   private evaluate;
+  private blockKey;
+  private readShards;
   private evaluateCandidates;
   private resolveAlgorithm;
-  private rawLimit;
   private runWithTimeout;
   private timeoutResponse;
 }
@@ -265,4 +285,4 @@ declare const HOUR: number;
 declare const DAY: number;
 declare const WEEK: number;
 //#endregion
-export { type CheckRequest, type ConvexQueryBuilder, type ConvexRatelimitDbReader, type ConvexRatelimitDbWriter, DAY, type Duration, type DurationString, type DurationUnit, type DynamicLimitResponse, type FixedWindowAlgorithm, HOUR, type HookAPIOptions, type HookCheckValue, type LimitRequest, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, type RatelimitConfig, RatelimitPlugin, type RatelimitPluginOptions, type RatelimitReason, type RatelimitResponse, type RatelimitRow, type RatelimitSnapshot, type RatelimitState, type RemainingResponse, type ResolvedAlgorithm, SECOND, type SlidingWindowAlgorithm, type TokenBucketAlgorithm, WEEK, applyDynamicLimit, calculateRatelimit, fixedWindow, slidingWindow, toMs, tokenBucket };
+export { type CheckRequest, type ConvexQueryBuilder, type ConvexRatelimitDbReader, type ConvexRatelimitDbWriter, DAY, type Duration, type DurationString, type DurationUnit, type DynamicLimitResponse, type EvaluationResult, type FixedWindowAlgorithm, HOUR, type HookAPIOptions, type HookCheckValue, type LimitRequest, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, type RatelimitConfig, RatelimitPlugin, type RatelimitPluginOptions, type RatelimitReason, type RatelimitResponse, type RatelimitRow, type RatelimitShardState, type RatelimitSnapshot, type RatelimitState, type RatelimitStoredState, type RemainingResponse, type ResolvedAlgorithm, SECOND, type SlidingWindowAlgorithm, type TokenBucketAlgorithm, WEEK, applyDynamicLimit, calculateRatelimit, fixedWindow, slidingWindow, snapshotToState, toMs, tokenBucket };