@ubean/server 0.1.13 → 0.2.0

package/dist/single-flight-BJyhDLdU.d.ts

@@ -0,0 +1,422 @@
+import { Context, MiddlewareHandler } from "hono";
+import { UbeanEnv } from "@ubean/shared";
+//#region src/cors.d.ts
+interface CorsOptions {
+  origin?: string | string[] | boolean | ((origin: string, c: Context<UbeanEnv>) => boolean | string | undefined | Promise<boolean | string | undefined>);
+  allowMethods?: string[];
+  allowHeaders?: string[];
+  exposeHeaders?: string[];
+  credentials?: boolean;
+  maxAge?: number;
+  preflightContinue?: boolean;
+}
+declare function createCorsMiddleware(options?: CorsOptions): MiddlewareHandler<UbeanEnv>;
+declare function defineCors(options: CorsOptions): MiddlewareHandler<UbeanEnv>;
+//#endregion
+//#region src/rate-limit.d.ts
+interface RateLimitOptions {
+  maxRequests?: number;
+  windowMs?: number;
+  keyGenerator?: (c: Context<UbeanEnv>) => string;
+  handler?: (c: Context<UbeanEnv>, info: RateLimitInfo) => Response | Promise<Response>;
+  skip?: (c: Context<UbeanEnv>) => boolean | Promise<boolean>;
+  standardHeaders?: boolean;
+  legacyHeaders?: boolean;
+  store?: RateLimitStore;
+}
+interface RateLimitInfo {
+  limit: number;
+  remaining: number;
+  reset: number;
+  retryAfter: number;
+}
+interface RateLimitStoreEntry {
+  count: number;
+  resetAt: number;
+}
+interface RateLimitStore {
+  get(key: string): Promise<RateLimitStoreEntry | undefined>;
+  set(key: string, entry: RateLimitStoreEntry, ttlMs: number): Promise<void>;
+  increment(key: string, windowMs: number): Promise<RateLimitStoreEntry>;
+  reset(key: string): Promise<void>;
+}
+declare function createRateLimitMiddleware(options?: RateLimitOptions): MiddlewareHandler<UbeanEnv>;
+declare function defineRateLimit(options: RateLimitOptions): MiddlewareHandler<UbeanEnv>;
+declare function createMemoryRateLimitStore(): RateLimitStore & {
+  destroy(): void;
+};
+//#endregion
+//#region src/after.d.ts
+type AfterCallback = () => void | Promise<void>;
+/**
+ * 注册一个在响应发送后执行的回调
+ *
+ * @example
+ * ```typescript
+ * import { after } from 'ubean';
+ *
+ * export const POST = defineHandler(async (c) => {
+ *   const result = doWork();
+ *   after(() => {
+ *     // 这些不会阻塞响应
+ *     analytics.track('post_created', result);
+ *     invalidateCache('/posts');
+ *   });
+ *   return c.json(result);
+ * });
+ * ```
+ */
+declare function after(callback: AfterCallback): void;
+/**
+ * 创建 after() 中间件
+ *
+ * 在响应发送后执行所有通过 `after()` 注册的回调
+ */
+declare function createAfterMiddleware(): MiddlewareHandler<UbeanEnv>;
+/**
+ * 手动执行 after 回调(用于自定义中间件或测试)
+ */
+declare function flushAfterCallbacks(c: Context<UbeanEnv>): Promise<void>;
+/**
+ * 获取当前请求中注册的 after 回调数量(主要用于测试)
+ */
+declare function getAfterCallbackCount(c?: Context<UbeanEnv>): number;
+//#endregion
+//#region src/fetch-memo.d.ts
+/**
+ * 创建 fetch memoization 中间件
+ *
+ * 在请求作用域内包装 globalThis.fetch,对相同 GET URL 自动去重
+ */
+declare function createFetchMemoizationMiddleware(options?: {
+  /** 自定义哪些 URL 不参与 memoization */
+  exclude?: (url: string) => boolean;
+  /** 是否跳过非 GET 请求(默认 true,即非 GET 不 memoize) */
+  skipNonGet?: boolean;
+}): MiddlewareHandler<UbeanEnv>;
+/**
+ * 手动创建一个 memoized fetch 函数(不依赖中间件/AsyncLocalStorage)
+ *
+ * 适用于在非请求上下文中手动使用 memoization
+ */
+declare function createMemoizedFetch(options?: {
+  originalFetch?: typeof globalThis.fetch;
+  ttl?: number;
+}): {
+  fetch: typeof globalThis.fetch;
+  clear: () => void;
+  size: () => number;
+};
+/**
+ * fetch Data Cache 选项(对齐 Next.js `next` 字段)。
+ *
+ * 仅当 fetch 的 `init.next` 包含 `revalidate` 或 `tags` 时启用跨请求缓存;
+ * 无 `next` 选项或 `noStore: true` 时不缓存(默认行为不变)。
+ */
+interface FetchCacheOptions {
+  /** TTL(秒)。0 = 不缓存;`Infinity` / 未定义 = 永久缓存(直到被失效)。 */
+  revalidate?: number;
+  /** 关联标签列表(用于 `revalidateTag(tag)` 失效)。 */
+  tags?: string[];
+  /** 显式退出缓存(等价于 `revalidate: 0`)。 */
+  noStore?: boolean;
+}
+/** 持有 Next.js 风格 `next` 选项的 RequestInit 扩展。 */
+interface FetchInitWithNext extends RequestInit {
+  /** Next.js 风格的 fetch 缓存控制选项。 */
+  next?: FetchCacheOptions;
+}
+/** Data Cache 中间件选项。 */
+interface DataCacheMiddlewareOptions {
+  /**
+   * 是否为开发模式(默认 `process.env.NODE_ENV !== 'production'`)。
+   * dev 模式下默认不缓存(便于开发时看到最新数据),可通过 `forceDevCache` 强制启用。
+   */
+  dev?: boolean;
+  /** dev 模式下也启用缓存(用于测试)。 */
+  forceDevCache?: boolean;
+  /** 自定义 URL 排除规则(返回 true 的 URL 不缓存)。 */
+  exclude?: (url: string) => boolean;
+}
+/**
+ * 创建 fetch Data Cache 中间件(Task 4)。
+ *
+ * 在请求作用域内包装 `globalThis.fetch`,对带 `next: { revalidate, tags }` 选项的
+ * GET/HEAD 请求按 TTL 跨请求缓存响应。无 `next` 选项的请求走原始路径(默认行为不变)。
+ *
+ * 行为:
+ * - 仅缓存 2xx 响应(4xx/5xx 不缓存,允许后续重试)
+ * - dev 模式默认 no-cache(可通过 `forceDevCache` 强制启用,用于测试)
+ * - 与 `revalidateTag` / `revalidatePath` 集成,失效对应缓存条目
+ *
+ * @example
+ * ```ts
+ * import { createDataCacheMiddleware } from '@ubean/server';
+ * app.use('*', createDataCacheMiddleware());
+ *
+ * // 路由处理器中:
+ * const res = await fetch('https://api.example.com/data', {
+ *   next: { revalidate: 60, tags: ['data'] }
+ * });
+ * ```
+ */
+declare function createDataCacheMiddleware(options?: DataCacheMiddlewareOptions): MiddlewareHandler<UbeanEnv>;
+/**
+ * 失效所有带指定标签的 Data Cache 条目。返回删除数量。
+ *
+ * 用户通常无需直接调用 —— `cache-directive.ts` 的 `revalidateTag` 会自动调用此函数。
+ */
+declare function revalidateDataCacheTag(tag: string): Promise<number>;
+/**
+ * 失效缓存键匹配指定模式的 Data Cache 条目。返回删除数量。
+ *
+ * 用户通常无需直接调用 —— `cache-directive.ts` 的 `revalidatePath` 会自动调用此函数。
+ */
+declare function revalidateDataCachePath(pattern: string | RegExp): Promise<number>;
+/** 清空所有 fetch Data Cache 条目(主要用于测试)。 */
+declare function clearFetchDataCache(): void;
+/** 返回 Data Cache 当前条目数(主要用于测试)。 */
+declare function getDataCacheSize(): number;
+//#endregion
+//#region src/draft-mode.d.ts
+interface DraftModeOptions {
+  /** cookie 名称,默认 'ubean_draft' */
+  cookieName?: string;
+  /** 签名密钥(必填,用于防止 cookie 篡改) */
+  secret: string;
+  /** cookie 有效期(秒),默认 3600(1 小时) */
+  ttl?: number;
+  /** cookie 选项 */
+  cookie?: {
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+    domain?: string;
+  };
+  /** 跳过中间件的路径前缀 */
+  exclude?: string[];
+}
+interface DraftMode {
+  /** 是否已启用 draft mode */
+  readonly isEnabled: boolean;
+  /** 启用 draft mode(设置签名 cookie) */
+  enable: () => void;
+  /** 禁用 draft mode(清除 cookie) */
+  disable: () => void;
+}
+/**
+ * 创建 draft mode 中间件
+ *
+ * 中间件读取请求中的签名 cookie,验证签名与过期时间后在 context 上
+ * 标记 draft mode 状态。响应阶段根据 controller 的 pendingAction
+ * 设置或清除 cookie。
+ *
+ * @example
+ * ```typescript
+ * // 启用 draft mode(默认 1 小时有效)
+ * app.use('*', createDraftModeMiddleware({ secret: 'my-secret' }));
+ *
+ * // 自定义 cookie 名称与 TTL
+ * app.use('*', createDraftModeMiddleware({
+ *   secret: 'my-secret',
+ *   cookieName: 'preview',
+ *   ttl: 86400
+ * }));
+ * ```
+ */
+declare function createDraftModeMiddleware(options: DraftModeOptions): MiddlewareHandler<UbeanEnv>;
+/**
+ * 启用 draft mode(设置签名 cookie)
+ *
+ * 在路由处理函数中调用,中间件会在响应阶段设置 cookie。
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/preview/enable', c => {
+ *   enableDraftMode(c);
+ *   return c.json({ ok: true });
+ * });
+ * ```
+ */
+declare function enableDraftMode(c: Context<UbeanEnv>): void;
+/**
+ * 禁用 draft mode(清除 cookie)
+ *
+ * @example
+ * ```typescript
+ * app.get('/api/preview/disable', c => {
+ *   disableDraftMode(c);
+ *   return c.json({ ok: true });
+ * });
+ * ```
+ */
+declare function disableDraftMode(c: Context<UbeanEnv>): void;
+/**
+ * 检查 draft mode 是否已启用(从 context 读取)
+ *
+ * 未注册中间件时返回 false。
+ */
+declare function isDraftMode(c: Context<UbeanEnv>): boolean;
+/**
+ * 获取 draft mode 组合式 API
+ *
+ * 返回 `{ isEnabled, enable, disable }`,在路由处理函数中使用。
+ *
+ * @example
+ * ```typescript
+ * app.get('*', c => {
+ *   const draft = useDraftMode(c);
+ *   if (draft.isEnabled) {
+ *     // 返回草稿内容
+ *   }
+ *   return c.json({ draft: draft.isEnabled });
+ * });
+ * ```
+ */
+declare function useDraftMode(c: Context<UbeanEnv>): DraftMode;
+/**
+ * 定义 draft mode 中间件(别名,与 defineCsrf / defineCors 风格一致)
+ */
+declare function defineDraftMode(options: DraftModeOptions): MiddlewareHandler<UbeanEnv>;
+//#endregion
+//#region src/single-flight.d.ts
+/** 重新获取键 —— 字符串标识符,用于匹配 invalidate() 与 defineRevalidation() */
+type RevalidationKey = string;
+/**
+ * 重新获取上下文,传递给每个 revalidation fetcher。
+ */
+interface RevalidationContext {
+  /** 触发本次重新获取的键列表(invalidate 调用的键与该 entry 的键的交集) */
+  keys: RevalidationKey[];
+  /** Hono 上下文(用于读取请求信息、session 等) */
+  context: Context<UbeanEnv>;
+}
+/**
+ * Revalidation fetcher —— 返回需要打包进响应的重新获取数据。
+ *
+ * 返回值必须是一个扁平对象 `Record<string, unknown>`,其键是客户端缓存键,
+ * 值是重新获取的数据。多个 fetcher 的返回值会被合并到同一个 bundle 中。
+ */
+type RevalidationFetcher = (ctx: RevalidationContext) => Promise<Record<string, unknown>>;
+/**
+ * 已注册的 revalidation 条目。
+ */
+interface RevalidationEntry {
+  /** 该 fetcher 负责的重新获取键列表 */
+  keys: RevalidationKey[];
+  /** 重新获取处理器 */
+  fetcher: RevalidationFetcher;
+  /** 可选名称(用于调试) */
+  name?: string;
+}
+/**
+ * 单个 revalidation 结果条目。
+ */
+interface RevalidationResult {
+  /** 重新获取的数据(已合并) */
+  data: Record<string, unknown>;
+  /** 被重新获取的键 */
+  keys: RevalidationKey[];
+  /** 时间戳(ms) */
+  timestamp: number;
+  /** fetcher 执行中产生的错误(若有) */
+  errors: Array<{
+    keys: RevalidationKey[];
+    message: string;
+  }>;
+}
+/**
+ * Single-flight 中间件选项。
+ */
+interface SingleFlightOptions {
+  /** 标记响应包含 revalidation 数据的 header 名称 */
+  revalidationHeader?: string;
+  /** JSON 响应体中存放 revalidation 数据的字段名 */
+  revalidationField?: string;
+  /** 只处理这些 Content-Type 的响应(默认 application/json) */
+  contentTypes?: string[];
+  /** 跳过函数 —— 返回 true 则不处理该请求 */
+  skip?: (c: Context<UbeanEnv>) => boolean | Promise<boolean>;
+  /** revalidation fetcher 是否并行执行(默认 true) */
+  parallel?: boolean;
+}
+/**
+ * 注册一个 revalidation 依赖。
+ *
+ * @param keys 该 fetcher 负责的重新获取键列表
+ * @param fetcher 重新获取处理器,返回需要打包进响应的数据
+ * @param name 可选名称(用于调试)
+ *
+ * @example
+ * ```typescript
+ * defineRevalidation(['users', 'user-count'], async (ctx) => {
+ *   const [users, count] = await Promise.all([
+ *     db.query.users.findMany(),
+ *     db.select({ count: count() }).from(users)
+ *   ]);
+ *   return { users, 'user-count': count };
+ * });
+ * ```
+ */
+declare function defineRevalidation(keys: RevalidationKey[], fetcher: RevalidationFetcher, name?: string): RevalidationEntry;
+/**
+ * 取消注册一个 revalidation 条目。
+ */
+declare function unregisterRevalidation(entry: RevalidationEntry): boolean;
+/**
+ * 获取所有已注册的 revalidation 条目(只读副本,用于测试/调试)。
+ */
+declare function getRevalidationEntries(): RevalidationEntry[];
+/**
+ * 清空所有 revalidation 注册(主要用于测试)。
+ */
+declare function clearRevalidationRegistry(): void;
+/**
+ * 标记需要重新获取的依赖键。
+ *
+ * 必须在 single-flight 中间件作用域内(action 处理器中)调用,
+ * 否则给出开发警告。
+ *
+ * @example
+ * ```typescript
+ * export const deleteUser = defineAction(async (input) => {
+ *   await db.delete(users).where(eq(users.id, input.id));
+ *   invalidate(['users', `user:${input.id}`]);
+ *   return { ok: true };
+ * });
+ * ```
+ */
+declare function invalidate(keys: RevalidationKey[]): void;
+/**
+ * 标记单个键需要重新获取(`invalidate([key])` 的简写)。
+ */
+declare function invalidateKey(key: RevalidationKey): void;
+/**
+ * 获取当前请求中被 invalidate 的键(主要用于测试/调试)。
+ */
+declare function getInvalidatedKeys(c?: Context<UbeanEnv>): RevalidationKey[];
+/**
+ * 创建 single-flight mutations 中间件。
+ *
+ * 拦截 Server Action 响应,执行由 `invalidate()` 标记的 revalidation,
+ * 将结果打包进响应体,使客户端在单个 round-trip 内获得更新后的数据。
+ *
+ * @example
+ * ```typescript
+ * app.use('*', createSingleFlightMiddleware());
+ * ```
+ */
+declare function createSingleFlightMiddleware(options?: SingleFlightOptions): MiddlewareHandler<UbeanEnv>;
+/**
+ * 手动执行 revalidation(用于自定义中间件或测试)。
+ *
+ * 在中间件作用域外也可调用 —— 直接传入 invalidated 键与上下文。
+ */
+declare function runRevalidation(invalidatedKeys: RevalidationKey[], c: Context<UbeanEnv>, parallel?: boolean): Promise<RevalidationResult>;
+/**
+ * Single-flight 中间件别名(与 cors/rate-limit 的 define* 风格一致)。
+ */
+declare function defineSingleFlight(options?: SingleFlightOptions): MiddlewareHandler<UbeanEnv>;
+//#endregion
+export { createFetchMemoizationMiddleware as A, RateLimitOptions as B, isDraftMode as C, FetchInitWithNext as D, FetchCacheOptions as E, after as F, defineRateLimit as G, RateLimitStoreEntry as H, createAfterMiddleware as I, defineCors as J, CorsOptions as K, flushAfterCallbacks as L, getDataCacheSize as M, revalidateDataCachePath as N, clearFetchDataCache as O, revalidateDataCacheTag as P, getAfterCallbackCount as R, enableDraftMode as S, DataCacheMiddlewareOptions as T, createMemoryRateLimitStore as U, RateLimitStore as V, createRateLimitMiddleware as W, DraftMode as _, RevalidationResult as a, defineDraftMode as b, createSingleFlightMiddleware as c, getInvalidatedKeys as d, getRevalidationEntries as f, unregisterRevalidation as g, runRevalidation as h, RevalidationKey as i, createMemoizedFetch as j, createDataCacheMiddleware as k, defineRevalidation as l, invalidateKey as m, RevalidationEntry as n, SingleFlightOptions as o, invalidate as p, createCorsMiddleware as q, RevalidationFetcher as r, clearRevalidationRegistry as s, RevalidationContext as t, defineSingleFlight as u, DraftModeOptions as v, useDraftMode as w, disableDraftMode as x, createDraftModeMiddleware as y, RateLimitInfo as z };