kitcn 0.0.1 → 0.12.1

package/dist/query-context-CFZqIvD7.d.ts

@@ -0,0 +1,42 @@
+import { DocumentByName, GenericQueryCtx, TableNamesInDataModel } from "convex/server";
+
+//#region src/orm/query-context.d.ts
+type InferCtxDataModel<TCtx extends GenericQueryCtx<any>> = TCtx extends GenericQueryCtx<infer DataModel> ? DataModel : never;
+type DocByCtx<TCtx extends GenericQueryCtx<any>, TableName extends TableNamesInDataModel<InferCtxDataModel<TCtx>>> = DocumentByName<InferCtxDataModel<TCtx>, TableName>;
+type QueryCtxWithOptionalOrmQueryTable<TCtx extends GenericQueryCtx<any>, TableName extends TableNamesInDataModel<InferCtxDataModel<TCtx>>> = TCtx & {
+  orm?: {
+    query?: { [K in TableName]?: {
+      findFirst?: (...args: any[]) => unknown;
+    } };
+  };
+};
+type QueryCtxWithOrmQueryTable<TCtx extends GenericQueryCtx<any>, TableName extends TableNamesInDataModel<InferCtxDataModel<TCtx>>> = TCtx & {
+  orm: {
+    query: { [K in TableName]-?: {
+      findFirst: (...args: any[]) => unknown;
+    } };
+  };
+};
+type OrmQueryByCtx<TCtx extends GenericQueryCtx<any>> = TCtx extends {
+  orm: {
+    query: infer TQuery;
+  };
+} ? TQuery : never;
+type OrmQueryEntryByCtx<TCtx extends GenericQueryCtx<any>, TableName extends TableNamesInDataModel<InferCtxDataModel<TCtx>>> = TableName extends keyof OrmQueryByCtx<TCtx> ? NonNullable<OrmQueryByCtx<TCtx>[TableName]> : never;
+type HasOrmFindFirstByCtx<TCtx extends GenericQueryCtx<any>, TableName extends TableNamesInDataModel<InferCtxDataModel<TCtx>>> = [OrmQueryEntryByCtx<TCtx, TableName>] extends [never] ? false : OrmQueryEntryByCtx<TCtx, TableName> extends {
+  findFirst: (...args: any[]) => unknown;
+} ? true : false;
+type QueryCtxWithPreferredOrmQueryTable<TCtx extends GenericQueryCtx<any>, TableName extends TableNamesInDataModel<InferCtxDataModel<TCtx>>> = TCtx extends {
+  orm: unknown;
+} ? HasOrmFindFirstByCtx<TCtx, TableName> extends true ? TCtx : never : TCtx;
+type OrmQueryRowByCtx<TCtx extends GenericQueryCtx<any>, TableName extends TableNamesInDataModel<InferCtxDataModel<TCtx>>> = OrmQueryEntryByCtx<TCtx, TableName> extends {
+  _: {
+    baseResult: infer TResult;
+  };
+} ? TResult : never;
+type LookupByIdResultByCtx<TCtx extends GenericQueryCtx<any>, TableName extends TableNamesInDataModel<InferCtxDataModel<TCtx>>> = (TCtx extends {
+  orm: unknown;
+} ? OrmQueryRowByCtx<TCtx, TableName> : DocByCtx<TCtx, TableName>) | null;
+declare function getByIdWithOrmQueryFallback<TCtx extends GenericQueryCtx<any>, TableName extends TableNamesInDataModel<InferCtxDataModel<TCtx>>>(ctx: QueryCtxWithPreferredOrmQueryTable<TCtx, TableName>, tableName: TableName, id: DocByCtx<TCtx, TableName>['_id']): Promise<LookupByIdResultByCtx<TCtx, TableName>>;
+//#endregion
+export { QueryCtxWithPreferredOrmQueryTable as a, QueryCtxWithOrmQueryTable as i, LookupByIdResultByCtx as n, getByIdWithOrmQueryFallback as o, QueryCtxWithOptionalOrmQueryTable as r, DocByCtx as t };

package/dist/query-options-Dw7cOyXl.js

@@ -0,0 +1,121 @@
+import { getFunctionName } from "convex/server";
+
+//#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 = enabled === false || isSkip ? false : void 0;
+	return {
+		queryKey: [
+			"convexQuery",
+			funcName,
+			firstPageArgs
+		],
+		staleTime: Number.POSITIVE_INFINITY,
+		refetchInterval: false,
+		refetchOnMount: false,
+		refetchOnReconnect: false,
+		refetchOnWindowFocus: false,
+		...queryOptions,
+		...finalEnabled === false ? { enabled: false } : {},
+		meta: {
+			authType,
+			skipUnauth,
+			subscribe: true,
+			queryName: funcName,
+			args: finalArgs,
+			limit
+		}
+	};
+}
+
+//#endregion
+export { convexInfiniteQueryOptions as n, convexQuery as r, convexAction as t };

package/dist/ratelimit/index.d.ts

@@ -0,0 +1,269 @@
+import { o as MiddlewareBuilder } from "../types-DEJpkIhw.js";
+import { t as Plugin } from "../middleware-BUybuv9n.js";
+import * as convex_server0 from "convex/server";
+
+//#region src/ratelimit/duration.d.ts
+type DurationUnit = 'ms' | 's' | 'm' | 'h' | 'd';
+type DurationString = `${number} ${DurationUnit}` | `${number}${DurationUnit}`;
+type Duration = number | DurationString;
+declare function toMs(duration: Duration): number;
+//#endregion
+//#region src/ratelimit/types.d.ts
+type RatelimitReason = 'timeout' | 'cacheBlock' | 'denyList';
+type RatelimitResponse = {
+  success: boolean;
+  ok: boolean;
+  limit: number;
+  remaining: number;
+  reset: number;
+  pending: Promise<unknown>;
+  reason?: RatelimitReason;
+  deniedValue?: string;
+};
+type RemainingResponse = {
+  remaining: number;
+  reset: number;
+  limit: number;
+};
+type DynamicLimitResponse = {
+  dynamicLimit: number | null;
+};
+type RatelimitState = {
+  value: number;
+  ts: number;
+  auxValue?: number;
+  auxTs?: number;
+};
+type RatelimitSnapshot = {
+  value: number;
+  ts: number;
+  shard: number;
+  config: ResolvedAlgorithm;
+};
+type BaseAlgorithmOptions = {
+  shards?: number;
+  maxReserved?: number;
+};
+type FixedWindowAlgorithm = {
+  kind: 'fixedWindow';
+  limit: number;
+  window: number;
+  capacity: number;
+  start?: number;
+  maxReserved?: number;
+  shards: number;
+};
+type SlidingWindowAlgorithm = {
+  kind: 'slidingWindow';
+  limit: number;
+  window: number;
+  maxReserved?: number;
+  shards: number;
+};
+type TokenBucketAlgorithm = {
+  kind: 'tokenBucket';
+  refillRate: number;
+  interval: number;
+  maxTokens: number;
+  maxReserved?: number;
+  shards: number;
+};
+type ResolvedAlgorithm = FixedWindowAlgorithm | SlidingWindowAlgorithm | TokenBucketAlgorithm;
+type AlgorithmOptions = BaseAlgorithmOptions & {
+  capacity?: number;
+  start?: number;
+};
+type LimitRequest = {
+  rate?: number;
+  count?: number;
+  reserve?: boolean;
+  ip?: string;
+  userAgent?: string;
+  country?: string;
+  geo?: unknown;
+};
+type CheckRequest = Omit<LimitRequest, 'reserve'> & {
+  reserve?: boolean;
+};
+type FailureMode = 'closed' | 'open';
+type ProtectionLists = {
+  identifiers?: readonly string[];
+  ips?: readonly string[];
+  userAgents?: readonly string[];
+  countries?: readonly string[];
+};
+type RatelimitConfig = {
+  db?: ConvexRatelimitDbReader | ConvexRatelimitDbWriter;
+  limiter: ResolvedAlgorithm;
+  prefix?: string;
+  dynamicLimits?: boolean;
+  ephemeralCache?: Map<string, number> | false;
+  timeout?: number;
+  failureMode?: FailureMode;
+  enableProtection?: boolean;
+  denyListThreshold?: number;
+  denyList?: ProtectionLists;
+};
+type RatelimitRow = {
+  _id: string;
+  _creationTime?: number;
+  name: string;
+  key?: string;
+  shard: number;
+  value: number;
+  ts: number;
+  auxValue?: number;
+  auxTs?: number;
+};
+type ConvexQueryBuilder = {
+  withIndex: (name: any, cb: any) => {
+    unique: () => Promise<any>;
+    collect: () => Promise<any[]>;
+  };
+};
+type ConvexRatelimitDbReader = {
+  query: (tableName: string) => ConvexQueryBuilder;
+};
+type ConvexRatelimitDbWriter = ConvexRatelimitDbReader & {
+  insert: (...args: any[]) => Promise<any>;
+  patch: (...args: any[]) => Promise<void>;
+  delete: (...args: any[]) => Promise<void>;
+};
+type HookAPIOptions = {
+  identifier?: string | ((ctx: unknown, fromClient?: string) => string | Promise<string>);
+  sampleShards?: number;
+};
+type HookCheckValue = {
+  value: number;
+  ts: number;
+  config: ResolvedAlgorithm;
+  shard: number;
+  ok: boolean;
+  retryAt?: number;
+};
+//#endregion
+//#region src/ratelimit/core/algorithms.d.ts
+declare function fixedWindow(limit: number, window: Duration, options?: AlgorithmOptions): FixedWindowAlgorithm;
+declare function slidingWindow(limit: number, window: Duration, options?: AlgorithmOptions): SlidingWindowAlgorithm;
+declare function tokenBucket(refillRate: number, interval: Duration, maxTokens: number, options?: AlgorithmOptions): TokenBucketAlgorithm;
+declare function applyDynamicLimit(algorithm: ResolvedAlgorithm, dynamicLimit: number | null): ResolvedAlgorithm;
+//#endregion
+//#region src/ratelimit/core/calculate-rate-limit.d.ts
+type EvaluationResult = {
+  state: RatelimitState;
+  retryAfter?: number;
+  remaining: number;
+  reset: number;
+  limit: number;
+};
+declare function calculateRatelimit(state: RatelimitState | null, algorithm: ResolvedAlgorithm, now: number, count: number): EvaluationResult;
+//#endregion
+//#region src/ratelimit/plugin.d.ts
+type MaybePromise<T> = T | Promise<T>;
+type RatelimitBuckets = Record<string, Record<string, ResolvedAlgorithm>>;
+type BucketName<TBuckets extends RatelimitBuckets> = Extract<keyof TBuckets, string>;
+type TierName<TBuckets extends RatelimitBuckets> = Extract<keyof TBuckets[BucketName<TBuckets>], string>;
+type RatelimitResolvedArgs<TCtx, TMeta extends object, TUser, TBuckets extends RatelimitBuckets> = {
+  ctx: TCtx;
+  meta: TMeta;
+  user: TUser;
+  bucket: BucketName<TBuckets>;
+  tier: TierName<TBuckets>;
+  identifier: string;
+};
+type RatelimitPluginOptions<TCtx = unknown, TMeta extends object = object, TUser = unknown, TBuckets extends RatelimitBuckets = RatelimitBuckets> = {
+  buckets: TBuckets;
+  getBucket: (args: {
+    ctx: TCtx;
+    meta: TMeta;
+  }) => MaybePromise<BucketName<TBuckets>>;
+  getUser: (args: {
+    ctx: TCtx;
+    meta: TMeta;
+  }) => MaybePromise<TUser>;
+  getIdentifier: (args: {
+    ctx: TCtx;
+    meta: TMeta;
+    user: TUser;
+    bucket: BucketName<TBuckets>;
+  }) => MaybePromise<string>;
+  getTier: (user: TUser) => MaybePromise<TierName<TBuckets>>;
+  getSignals: (args: RatelimitResolvedArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<LimitRequest | undefined>;
+  prefix?: string | ((args: RatelimitResolvedArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<string>);
+  failureMode?: 'closed' | 'open';
+  enableProtection?: boolean;
+  denyListThreshold?: number;
+  message?: string | ((args: RatelimitResolvedArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<string>);
+};
+type AnyRatelimitPluginOptions = RatelimitPluginOptions<any, any, any, any>;
+declare const RatelimitPlugin: Plugin<"ratelimit", AnyRatelimitPluginOptions, AnyRatelimitPluginOptions, unknown, Omit<{
+  middleware: () => MiddlewareBuilder<any, any, {
+    api: Record<string, unknown> & Record<"ratelimit", AnyRatelimitPluginOptions>;
+  } | {
+    [x: string]: any;
+    [x: number]: any;
+    [x: symbol]: any;
+    api: Record<string, unknown> & Record<"ratelimit", AnyRatelimitPluginOptions>;
+  }, unknown>;
+}, "middleware">>;
+//#endregion
+//#region src/ratelimit/ratelimit.d.ts
+declare class Ratelimit {
+  private readonly config;
+  static fixedWindow: typeof fixedWindow;
+  static slidingWindow: typeof slidingWindow;
+  static tokenBucket: typeof tokenBucket;
+  private readonly store;
+  private readonly prefix;
+  private readonly timeout;
+  private readonly dynamicLimits;
+  private readonly failureMode;
+  private readonly enableProtection;
+  private readonly denyListThreshold;
+  private readonly denyList?;
+  private readonly limiter;
+  private readonly blockCache?;
+  private readonly blockCacheSource?;
+  private readonly checkCache;
+  constructor(config: RatelimitConfig);
+  limit(identifier: string, request?: LimitRequest): Promise<RatelimitResponse>;
+  check(identifier: string, request?: CheckRequest): Promise<RatelimitResponse>;
+  blockUntilReady(identifier: string, timeoutMs: number): Promise<RatelimitResponse>;
+  resetUsedTokens(identifier: string): Promise<void>;
+  getRemaining(identifier: string): Promise<RemainingResponse>;
+  getValue(identifier: string, options?: {
+    sampleShards?: number;
+  }): Promise<RatelimitSnapshot>;
+  setDynamicLimit(options: {
+    limit: number | false;
+  }): Promise<void>;
+  getDynamicLimit(): Promise<DynamicLimitResponse>;
+  hookAPI(options?: HookAPIOptions): {
+    getRatelimit: convex_server0.RegisteredQuery<"public", {
+      identifier?: string | undefined;
+      sampleShards?: number | undefined;
+    }, Promise<RatelimitSnapshot>>;
+    getServerTime: convex_server0.RegisteredMutation<"public", {}, Promise<number>>;
+  };
+  private withDb;
+  private evaluate;
+  private evaluateCandidates;
+  private resolveAlgorithm;
+  private rawLimit;
+  private runWithTimeout;
+  private timeoutResponse;
+}
+//#endregion
+//#region src/ratelimit/store/convex-store.d.ts
+declare const RATE_LIMIT_STATE_TABLE = "ratelimitState";
+declare const RATE_LIMIT_DYNAMIC_TABLE = "ratelimitDynamicLimit";
+declare const RATE_LIMIT_HIT_TABLE = "ratelimitProtectionHit";
+//#endregion
+//#region src/ratelimit/index.d.ts
+declare const SECOND = 1000;
+declare const MINUTE: number;
+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 };