@ubean/routes 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soybean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+import { ScannedApiRoute, ScannedLayout, ScannedMiddleware, ScannedPageRoute } from "@ubean/scan";
+import { ComposedHandler, GenericSchema, Input, IsrRule, IsrRule as IsrRule$1, RouteMeta, RouteMeta as RouteMeta$1, RouteRule, RouteRule as RouteRule$1, Span, SpanAttributes, SpanContext, SpanEndOptions, SpanEvent, SpanOptions, SpanStatus, UbeanBindings, UbeanContext, UbeanEnv, UbeanEnv as UbeanEnv$1, UbeanHandler, UbeanMiddleware, UbeanMiddleware as UbeanMiddleware$1, UbeanVariables } from "@ubean/shared";
+import { Context, Hono, MiddlewareHandler, Next } from "hono";
+import { H, HandlerResponse, Input as Input$1 } from "hono/types";
+import { FetchAdapter } from "@soybeanjs/fetch";
+//#region src/handler.d.ts
+interface MiddlewareChain extends Array<MiddlewareHandler> {
+  __routeMeta?: RouteMeta$1;
+}
+declare function defineHandler<I extends Input$1 = {}, R extends HandlerResponse<any> = any>(handler1: H<UbeanEnv$1, any, I, R>): [H<UbeanEnv$1, any, I, R>];
+declare function defineHandler<I extends Input$1 = {}, I2 extends Input$1 = I, R extends HandlerResponse<any> = any, R2 extends HandlerResponse<any> = any>(handler1: H<UbeanEnv$1, any, I, R>, handler2: H<UbeanEnv$1, any, I & I2, R2>): [H<UbeanEnv$1, any, I, R>, H<UbeanEnv$1, any, I & I2, R2>];
+declare function defineHandler<I extends Input$1 = {}, I2 extends Input$1 = I, I3 extends Input$1 = I & I2, R extends HandlerResponse<any> = any, R2 extends HandlerResponse<any> = any, R3 extends HandlerResponse<any> = any>(handler1: H<UbeanEnv$1, any, I, R>, handler2: H<UbeanEnv$1, any, I2, R2>, handler3: H<UbeanEnv$1, any, I3, R3>): [H<UbeanEnv$1, any, I, R>, H<UbeanEnv$1, any, I2, R2>, H<UbeanEnv$1, any, I3, R3>];
+declare function defineHandler<I extends Input$1 = {}, I2 extends Input$1 = I, I3 extends Input$1 = I & I2, I4 extends Input$1 = I & I2 & I3, R extends HandlerResponse<any> = any, R2 extends HandlerResponse<any> = any, R3 extends HandlerResponse<any> = any, R4 extends HandlerResponse<any> = any>(handler1: H<UbeanEnv$1, any, I, R>, handler2: H<UbeanEnv$1, any, I2, R2>, handler3: H<UbeanEnv$1, any, I3, R3>, handler4: H<UbeanEnv$1, any, I4, R4>): [H<UbeanEnv$1, any, I, R>, H<UbeanEnv$1, any, I2, R2>, H<UbeanEnv$1, any, I3, R3>, H<UbeanEnv$1, any, I4, R4>];
+declare function defineHandler<I extends Input$1 = {}, I2 extends Input$1 = I, I3 extends Input$1 = I & I2, I4 extends Input$1 = I & I2 & I3, I5 extends Input$1 = I & I2 & I3 & I4, R extends HandlerResponse<any> = any, R2 extends HandlerResponse<any> = any, R3 extends HandlerResponse<any> = any, R4 extends HandlerResponse<any> = any, R5 extends HandlerResponse<any> = any>(handler1: H<UbeanEnv$1, any, I, R>, handler2: H<UbeanEnv$1, any, I2, R2>, handler3: H<UbeanEnv$1, any, I3, R3>, handler4: H<UbeanEnv$1, any, I4, R4>, handler5: H<UbeanEnv$1, any, I5, R5>): [H<UbeanEnv$1, any, I, R>, H<UbeanEnv$1, any, I2, R2>, H<UbeanEnv$1, any, I3, R3>, H<UbeanEnv$1, any, I4, R4>, H<UbeanEnv$1, any, I5, R5>];
+declare function isHandlerChain(obj: unknown): obj is MiddlewareChain;
+declare function extractRouteMeta(handlers: MiddlewareHandler[]): RouteMeta$1;
+declare function defineHandlerMeta(meta: Partial<RouteMeta$1>): (_c: Context<UbeanEnv$1>, next: Next) => Promise<void>;
+declare function defineMiddleware(handler: MiddlewareHandler<UbeanEnv$1>): MiddlewareHandler<UbeanEnv$1>;
+//#endregion
+//#region src/server-router.d.ts
+interface CompiledRoute {
+  method: string;
+  path: string;
+  id: string;
+  filePath: string;
+  meta?: Record<string, unknown>;
+}
+interface CompiledMiddleware {
+  path: string;
+  filePath: string;
+  order: number;
+  global: boolean;
+}
+interface CompiledPage {
+  name: string;
+  path: string;
+  filePath: string;
+  layout?: string | string[] | false;
+  reuseTarget?: string;
+}
+interface CompiledLayout {
+  name: string;
+  filePath: string;
+  isDefault: boolean;
+}
+declare class UbeanRouter {
+  private apiContext;
+  private middlewares;
+  private pages;
+  private layouts;
+  constructor();
+  addApiRoute(route: ScannedApiRoute): void;
+  addMiddleware(mw: ScannedMiddleware): void;
+  addPage(page: ScannedPageRoute): void;
+  addLayout(layout: ScannedLayout): void;
+  matchApi(method: string, path: string): CompiledRoute | undefined;
+  getMiddlewares(): CompiledMiddleware[];
+  getPages(): CompiledPage[];
+  getPage(name: string): CompiledPage | undefined;
+  getLayout(name: string): CompiledLayout | undefined;
+  getDefaultLayout(): CompiledLayout | undefined;
+  getLayouts(): CompiledLayout[];
+  getPageRouteNames(): string[];
+}
+declare function useRouter(): UbeanRouter;
+/**
+ * 创建服务端 rou3 router 实例(无参数)。
+ *
+ * 命名说明:与 `@ubean/client` 的 `createUbeanRouter`(Vue Router 工厂,
+ * 接受 options)曾是同名冲突,服务端版本改名 `createServerRouter` 彻底消歧。
+ */
+declare function createServerRouter(): UbeanRouter;
+//#endregion
+//#region src/isr.d.ts
+/**
+ * ISR 缓存条目(内部表示,与 @ubean/server 的 CacheEntry 结构兼容)。
+ */
+interface IsrCacheEntryInternal {
+  body: ArrayBuffer;
+  headers: Record<string, string>;
+  status: number;
+  statusText: string;
+  createdAt: number;
+  expiresAt: number;
+}
+/**
+ * ISR 缓存存储接口。与 `@ubean/server` 的 `CacheStore` 结构兼容 ——
+ * 调用方注入任何满足此形状的实例即可(无需真正依赖 @ubean/server)。
+ */
+interface IsrCacheStore {
+  get(key: string): Promise<IsrCacheEntryInternal | undefined>;
+  set(key: string, entry: Omit<IsrCacheEntryInternal, 'createdAt' | 'expiresAt'>, ttl: number): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  clear(): Promise<void>;
+  /** 返回 entry(无论是否过期)。不实现时退化为 `get`(SWR 自动降级为同步重新生成) */
+  peek?(key: string): Promise<IsrCacheEntryInternal | undefined>;
+}
+interface IsrCacheEntry {
+  html: string;
+  status: number;
+  headers: Record<string, string>;
+}
+interface IsrServeOptions {
+  /** 当前请求的路径名(用于构建 cache key) */
+  pathname: string;
+  /** ISR 规则(已规范化) */
+  rule: IsrRule$1;
+  /** 渲染函数:同步重新生成时调用 */
+  render: () => Promise<{
+    html: string;
+    status?: number;
+    headers?: Record<string, string>;
+  }>;
+  /** cache store(必传 —— 由调用方通过 RegisterOptions.cacheStore 注入) */
+  store: IsrCacheStore;
+}
+declare function buildIsrCacheKey(pathname: string): string;
+/**
+ * 读取缓存的 ISR entry(仅未过期)。
+ */
+declare function getIsrCache(store: IsrCacheStore, pathname: string): Promise<IsrCacheEntry | undefined>;
+/**
+ * 读取缓存的 ISR entry(即使已过期,用于 SWR)。
+ * 后端不支持 `peek` 时退化为 `get`(无 SWR)。
+ */
+declare function getStaleIsrCache(store: IsrCacheStore, pathname: string): Promise<IsrCacheEntry | undefined>;
+/**
+ * 写入 ISR 缓存。
+ */
+declare function setIsrCache(store: IsrCacheStore, pathname: string, entry: IsrCacheEntry, ttl: number): Promise<void>;
+/**
+ * 失效指定路径的 ISR 缓存。需要调用方提供 store(避免本包依赖全局单例)。
+ */
+declare function invalidateIsrCache(store: IsrCacheStore, pathname: string): Promise<boolean>;
+/**
+ * 失效所有匹配模式的 ISR 缓存。仅对内存存储有效(读取底层 Map)。
+ */
+declare function invalidateIsrCachePattern(store: IsrCacheStore, pattern: RegExp): Promise<number>;
+/**
+ * 判断 entry 是否已过期。配合 `getStaleIsrCache` 用于 SWR 判定。
+ * 仅内存存储可用 —— 其他后端在 `getStaleIsrCache` 已退化为 `get`(永远 fresh),
+ * 不会进入此分支。
+ */
+declare function isIsrEntryStale(pathname: string, store: IsrCacheStore): boolean;
+/**
+ * ISR 主入口:检查缓存 → 命中则返回,未命中/过期则调用 render 重新生成。
+ *
+ * 返回 `Response` 表示 ISR 处理完成(直接返回给客户端),
+ * 返回 `undefined` 表示无 ISR 规则或调用方应自行处理(由 `serveIsr` 内部逻辑决定)。
+ *
+ * 实现说明:使用 `peek`(若可用)而非 `get` 来读取缓存,避免 `get` 在
+ * 过期时删除 entry 导致 SWR 无法读取旧内容。后端不支持 `peek` 时退化为 `get`
+ * (SWR 自动降级为同步重新生成)。
+ */
+declare function serveIsr(_c: Context<UbeanEnv$1>, options: IsrServeOptions): Promise<Response | undefined>;
+/**
+ * 从 context 读取匹配到的 routeRule,提取 ISR 规则。
+ * 返回 `undefined` 表示该路由未启用 ISR。
+ */
+declare function getIsrRuleFromContext(c: Context<UbeanEnv$1>): IsrRule$1 | undefined;
+//#endregion
+//#region src/router.d.ts
+/**
+ * Structural type for the route registrar app.
+ *
+ * Avoids a hard dependency on `@ubean/app` (T2-6). The actual `UbeanApp`
+ * returned by `createUbeanApp()` satisfies this interface because it
+ * extends `Hono<UbeanEnv>` and adds a `hooks` property from `hookable`.
+ */
+interface RouteRegistrar {
+  on(method: string, path: string, ...handlers: MiddlewareHandler[]): void;
+  on(methods: string[], path: string, ...handlers: MiddlewareHandler[]): void;
+  get(path: string, ...handlers: MiddlewareHandler[]): void;
+  post(path: string, ...handlers: MiddlewareHandler[]): void;
+  hooks: {
+    callHook(name: string, ...args: any[]): Promise<void>;
+  };
+}
+interface RegisterOptions {
+  routes: ScannedApiRoute[];
+  middleware: ScannedMiddleware[];
+  pages: ScannedPageRoute[];
+  layouts?: ScannedLayout[];
+  routeLoaders: Record<string, () => Promise<Record<string, unknown>>>;
+  middlewareLoaders: Record<string, () => Promise<{
+    default?: UbeanMiddleware$1;
+  }>>;
+  pageRenderer?: unknown;
+  pageAssetTags?: unknown;
+  pageLoaders?: Record<string, () => Promise<any>>;
+  i18nConfig?: {
+    strategy?: 'prefix' | 'prefix_except_default' | 'prefix_and_default' | 'no_prefix';
+    defaultLocale?: string;
+    locales?: string[];
+  };
+  /**
+   * 不进行 SSR 的路由模式列表(glob)。
+   * 匹配的页面将跳过服务端渲染,返回客户端渲染 shell。
+   */
+  ssrExclude?: string[];
+  /**
+   * 启用流式 SSR。当为 `true` 且 pageRenderer 提供 `renderToStream` 时,
+   * 页面响应将以 `ReadableStream` 形式分块输出(头部先发送,app HTML 边渲染边输出),
+   * 显著改善 TTFB/LCP。回退:renderer 不支持流式时自动降级为缓冲渲染。
+   */
+  streaming?: boolean;
+  /**
+   * 爬虫降级(P9-24 / Task 6 流式 metadata):当 `streaming` 启用且检测到
+   * 爬虫/社交预览 UA(Facebook OG、Twitter、Slack 等)时,自动降级为缓冲渲染,
+   * 保证动态 `<head>` metadata 出现在初始响应中(社交爬虫只解析初始 `<head>`,
+   * 不会执行流式尾部的 metadata 注入)。默认 `true`(仅在 streaming 启用时生效)。
+   */
+  botFallback?: boolean;
+  /**
+   * `pages/404.vue` 自动检测的 404 页面。
+   * 注册为 Vue Router catch-all 路由的兜底,同时注册 Hono 的 `GET *` 兜底处理器。
+   */
+  notFoundPage?: ScannedPageRoute;
+  /**
+   * ISR 缓存存储(P9-03)。与 `@ubean/server` 的 `CacheStore` 结构兼容。
+   * 启用 `routeRules[*].isr` 时必须传入,否则 ISR 规则被忽略。
+   */
+  cacheStore?: IsrCacheStore;
+  /**
+   * Pre-rendered no-FOUC color-mode script (from `getColorModeScript`).
+   * Injected as the first child of `<head>` in every SSR/prerendered HTML
+   * response so the correct theme class is set before first paint.
+   * `transformIndexHtml` only runs in dev — SSG/prerender bypasses it, so
+   * the script must be injected here to cover production HTML.
+   */
+  colorModeScript?: string;
+}
+/**
+ * Sort page routes so catch-all routes (`/**:slug`, converted to Hono `*`)
+ * are registered last. Hono's RegExpRouter matches in registration order,
+ * so a catch-all registered before a specific path (e.g. `/`) would swallow
+ * it. File-system sort order puts `[...slug].vue` before `index.vue`
+ * (`[` < `i`), which is wrong for Hono — this sort corrects it.
+ *
+ * Stable: non-catch-all pages keep their original relative order.
+ */
+declare function sortPagesForRegistration<T extends {
+  route: string;
+}>(pages: readonly T[]): T[];
+declare function registerApiRoutes(app: RouteRegistrar, options: RegisterOptions): Promise<void>;
+declare function registerPageRoutes(app: RouteRegistrar, options: RegisterOptions): Promise<void>;
+declare function registerRoutes(app: RouteRegistrar, options: RegisterOptions): Promise<void>;
+declare function createRouteLoader(importMetaGlob: Record<string, () => Promise<any>>): {
+  [k: string]: () => Promise<any>;
+};
+//#endregion
+//#region src/route-rules.d.ts
+interface CompiledRouteRule {
+  pattern: RegExp;
+  rule: RouteRule$1;
+  /** 原始路径模式(用于路径特异性计算) */
+  path: string;
+}
+declare function compileRouteRules(rules: Record<string, RouteRule$1>): CompiledRouteRule[];
+/**
+ * 规范化 `isr` 字段为 `IsrRule` 对象形式。
+ * `number` → `{ ttl: n }`,`undefined` → `undefined`。
+ */
+declare function normalizeIsrRule(isr: RouteRule$1['isr']): IsrRule$1 | undefined;
+declare function matchRouteRules(path: string, compiledRules: CompiledRouteRule[]): RouteRule$1;
+declare function createRouteRulesMiddleware(rules: Record<string, RouteRule$1>): (c: Context, next: Next) => Promise<(Response & import("hono").TypedResponse<undefined, 301 | 302 | 303 | 307 | 308, "redirect">) | undefined>;
+//#endregion
+//#region src/internal-fetch.d.ts
+interface InternalFetchOptions {
+  baseURL?: string;
+  headers?: Record<string, string>;
+  credentials?: 'include' | 'omit' | 'same-origin';
+  forwardHeaders?: string[];
+}
+type AppFetcher = (request: Request) => Response | Promise<Response>;
+declare function setInternalFetcher(fetcher: AppFetcher): void;
+declare function getInternalFetcher(): AppFetcher | null;
+declare function clearInternalFetcher(): void;
+/**
+ * 创建进程内调度适配器。
+ *
+ * 将注册的 Hono `app.fetch` 包装为 `@soybeanjs/fetch` 的 `FetchAdapter`,
+ * 使其可通过 `createRequest` / `createTypedClient` / `toFlatTypedClient` 等 API
+ * 进行进程内调度(不发起新的网络请求)。
+ *
+ * 消费者可直接组合使用:
+ * ```typescript
+ * import { createInternalAdapter } from '@ubean/routes';
+ * import { createRequest, createTypedClient } from '@soybeanjs/fetch';
+ *
+ * const adapter = createInternalAdapter(c);
+ * const request = createRequest({ adapter, retry: { retries: 0 } }, { isBackendSuccess: () => true });
+ * const api = createTypedClient<paths>(request);
+ * ```
+ *
+ * @param c - Hono Context(可选,用于转发 cookie/authorization 等请求头)
+ * @param options - 选项(`headers` 自定义额外 header,`forwardHeaders` 自定义转发 header 列表)
+ */
+declare function createInternalAdapter(c?: Context<UbeanEnv$1>, options?: InternalFetchOptions): FetchAdapter;
+//#endregion
+//#region src/bot-detection.d.ts
+/**
+ * Bot / crawler User-Agent 检测(P9-24 / Task 6 流式 metadata)。
+ *
+ * 流式 SSR 把动态 `<head>` metadata 注入到响应尾部(浏览器把它们
+ * 移动到 `<head>`),但社交爬虫(Facebook OG、Twitter、Slack 等)
+ * 只解析初始 `<head>`,会错过这些标签。检测到爬虫 UA 时,router
+ * 自动降级为缓冲渲染(`renderPage`),保证 metadata 出现在初始
+ * `<head>` 中。
+ *
+ * 检测基于 UA 子串匹配(大小写不敏感),覆盖主流搜索引擎与社交
+ * 预览爬虫。空 UA 视为非爬虫(部分正常请求也带空 UA)。
+ */
+/**
+ * 判断 User-Agent 是否为爬虫/社交预览机器人。
+ *
+ * @param ua User-Agent 字符串(来自 `c.req.header('user-agent')`)
+ * @returns `true` 表示疑似爬虫,应降级为缓冲渲染以保证 metadata 完整
+ */
+declare function isBotUserAgent(ua: string | undefined | null): boolean;
+//#endregion
+//#region src/openapi.d.ts
+interface OpenAPIGenerationOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+  baseURL?: string;
+}
+declare function registerOpenAPIRoutes(app: Hono<UbeanEnv$1>, options?: OpenAPIGenerationOptions & {
+  scalarPath?: string;
+  openAPIPath?: string;
+}): void;
+//#endregion
+export { type CompiledLayout, type CompiledMiddleware, type CompiledPage, type CompiledRoute, type CompiledRouteRule, type ComposedHandler, type GenericSchema, type Input, type InternalFetchOptions, type IsrCacheEntry, type IsrCacheEntryInternal, type IsrCacheStore, type IsrRule, type IsrServeOptions, type OpenAPIGenerationOptions, type RegisterOptions, type RouteMeta, type RouteRegistrar, type RouteRule, type Span, type SpanAttributes, type SpanContext, type SpanEndOptions, type SpanEvent, type SpanOptions, type SpanStatus, type UbeanBindings, type UbeanContext, type UbeanEnv, type UbeanHandler, type UbeanMiddleware, UbeanRouter, type UbeanVariables, buildIsrCacheKey, clearInternalFetcher, compileRouteRules, createInternalAdapter, createRouteLoader, createRouteRulesMiddleware, createServerRouter, defineHandler, defineHandlerMeta, defineMiddleware, extractRouteMeta, getInternalFetcher, getIsrCache, getIsrRuleFromContext, getStaleIsrCache, invalidateIsrCache, invalidateIsrCachePattern, isBotUserAgent, isHandlerChain, isIsrEntryStale, matchRouteRules, normalizeIsrRule, registerApiRoutes, registerOpenAPIRoutes, registerPageRoutes, registerRoutes, serveIsr, setInternalFetcher, setIsrCache, sortPagesForRegistration, useRouter };