@ubean/routes 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+import { n as unwrapActionResult, r as unwrapServerFnResult, t as invokeServerFn } from "./invoke-CzODqUg-.js";
 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 { ACTION_BRAND, ActionContext, ActionContext as ActionContext$1, ActionError, ActionFailure, ActionHandler, ActionHandler as ActionHandler$1, ActionId, ActionId as ActionId$1, ActionResult, ActionResult as ActionResult$1, ActionSchema, ActionSchema as ActionSchema$1, ComposedHandler, GenericSchema, Input, IsrRule, IsrRule as IsrRule$1, RouteMeta, RouteMeta as RouteMeta$1, RouteRule, RouteRule as RouteRule$1, ServerAction, ServerAction as ServerAction$1, Span, SpanAttributes, SpanContext, SpanEndOptions, SpanEvent, SpanOptions, SpanStatus, UbeanBindings, UbeanContext, UbeanEnv, UbeanEnv as UbeanEnv$1, UbeanHandler, UbeanMiddleware, UbeanMiddleware as UbeanMiddleware$1, UbeanVariables, fail, isActionFailure, isServerAction } 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";
@@ -189,9 +190,12 @@ interface RegisterOptions {
   pageAssetTags?: unknown;
   pageLoaders?: Record<string, () => Promise<any>>;
   i18nConfig?: {
+    enabled?: boolean;
     strategy?: 'prefix' | 'prefix_except_default' | 'prefix_and_default' | 'no_prefix';
     defaultLocale?: string;
     locales?: string[];
+    cookieName?: string;
+    baseUrl?: string;
   };
   /**
    * 不进行 SSR 的路由模式列表(glob)。
@@ -249,6 +253,17 @@ declare function createRouteLoader(importMetaGlob: Record<string, () => Promise<
   [k: string]: () => Promise<any>;
 };
 //#endregion
+//#region src/path-transform.d.ts
+/**
+ * Apply a rewrite/proxy target to a request path (Nuxt-style wildcards).
+ *
+ * - `/old` + `/new` → `/new`
+ * - rule `/blog/**`, request `/blog/a/b`, target `/news/**` → `/news/a/b`
+ * - target containing `$1` receives the captured suffix without a leading slash
+ * - absolute `https://…` targets keep the origin and transform the pathname
+ */
+declare function applyPathTransform(requestPath: string, rulePath: string, target: string): string;
+//#endregion
 //#region src/route-rules.d.ts
 interface CompiledRouteRule {
   pattern: RegExp;
@@ -256,6 +271,13 @@ interface CompiledRouteRule {
   /** 原始路径模式(用于路径特异性计算) */
   path: string;
 }
+interface RouteRulesMiddlewareOptions {
+  /**
+   * Internal dispatch used to rematch Hono routes after a rewrite.
+   * Typically `req => app.fetch(req)` from `createUbeanApp`.
+   */
+  dispatch?: (request: Request) => Promise<Response>;
+}
 declare function compileRouteRules(rules: Record<string, RouteRule$1>): CompiledRouteRule[];
 /**
  * 规范化 `isr` 字段为 `IsrRule` 对象形式。
@@ -263,7 +285,364 @@ declare function compileRouteRules(rules: Record<string, RouteRule$1>): Compiled
  */
 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>;
+declare function createRouteRulesMiddleware(rules: Record<string, RouteRule$1>, options?: RouteRulesMiddlewareOptions): (c: Context, next: Next) => Promise<Response | undefined>;
+//#endregion
+//#region src/select-ssr.d.ts
+type SelectSsrValue = boolean | 'streaming' | 'data-only';
+type SelectSsrMode = 'ssr' | 'streaming' | 'data-only' | 'csr';
+interface ResolveSelectSsrInput {
+  pageSsr?: SelectSsrValue;
+  routeRuleSsr?: SelectSsrValue;
+  ppr?: boolean;
+  excludedByGlob: boolean;
+  streaming: boolean;
+}
+interface ResolvedSelectSsr {
+  mode: SelectSsrMode;
+  runLoader: boolean;
+  useRenderer: boolean;
+}
+/**
+ * TanStack-style select SSR: page meta wins over routeRules, which win over
+ * the global exclude list. Glob exclude stays backward-compatible (CSR shell
+ * still runs loader). Explicit `ssr: false` skips the loader.
+ */
+declare function resolveSelectSsr(input: ResolveSelectSsrInput): ResolvedSelectSsr;
+declare function ssrModeHeader(mode: SelectSsrMode): string;
+//#endregion
+//#region src/actions/define.d.ts
+interface DefineActionOptions {
+  /**
+   * Override the auto-generated action ID.
+   *
+   * The Vite plugin injects this for `'use server'` modules so the client
+   * and server agree on the ID. Inline `defineAction` calls use the
+   * auto-generated ID derived from `import.meta.url` + the call site.
+   */
+  id?: string;
+  /**
+   * Override the action's source file path (used for ID generation and
+   * debugging). Injected by the Vite plugin.
+   */
+  filePath?: string;
+  /**
+   * Override the action's export name (used for ID generation). Defaults
+   * to the function's `name` property or `'anonymous'`.
+   */
+  name?: string;
+}
+/**
+ * Define a server action with input schema validation.
+ *
+ * The handler receives the parsed/validated `data` (typed by the schema's
+ * output). On validation failure, the action returns an `ActionResult`
+ * with `errors` set to the schema's issue messages.
+ */
+declare function defineAction<TOutput>(schema: ActionSchema$1<TOutput>, handler: ActionHandler$1<TOutput, unknown>, options?: DefineActionOptions): ServerAction$1<TOutput, unknown>;
+/**
+ * Define a server action without a schema.
+ *
+ * The handler receives the raw input (FormData or parsed JSON object).
+ */
+declare function defineAction<TInput = unknown, TOutput = unknown>(handler: ActionHandler$1<TInput, TOutput>, options?: DefineActionOptions): ServerAction$1<TInput, TOutput>;
+/**
+ * Type-safe server function. Same ID, registry, and `POST /__actions` RPC as
+ * `defineAction` — use this alias when the function is a loader/query as well
+ * as a mutation. Do not invent a second RPC.
+ */
+declare const defineServerFn: typeof defineAction;
+/**
+ * Parse a Request body into a plain object suitable for action handlers.
+ *
+ * - `application/json` → parsed JSON object
+ * - `multipart/form-data` or `application/x-www-form-urlencoded` → Object
+ *   from FormData entries (string values, files skipped)
+ * - Otherwise → empty object (handler can read `ctx.request` directly)
+ */
+declare function parseActionInput(request: Request): Promise<Record<string, unknown>>;
+declare function validateActionInput<T>(schema: ActionSchema$1<T>, input: unknown): {
+  success: true;
+  data: T;
+} | {
+  success: false;
+  errors: Record<string, string>;
+};
+/**
+ * Normalize a handler return value into an `ActionResult`.
+ *
+ * - `ActionFailure` → `{ errors, status: failure.status }`
+ * - `ActionError` (thrown) → `{ error: { message, code }, status }`
+ * - Other thrown error → `{ error: { message }, status: 500 }`
+ * - Plain value → `{ data: value, status: 200 }`
+ */
+declare function normalizeActionResult(result: unknown, error: unknown, failureStatus?: number): {
+  data?: unknown;
+  error?: {
+    message: string;
+    code?: string;
+  };
+  errors?: Record<string, string> | null;
+  status: number;
+};
+/**
+ * Build an `ActionContext` from a Hono context.
+ *
+ * - `request`: the underlying `c.req.raw` Request
+ * - `context`: the Hono context (for `c.set`, `c.get`, etc.)
+ * - `params`: route params from `c.req.param()`
+ */
+declare function buildActionContext(c: Context<UbeanEnv$1>): ActionContext$1;
+//#endregion
+//#region src/actions/request-context.d.ts
+interface ActionContextStorage {
+  getStore(): ActionContext$1 | undefined;
+  run<T>(ctx: ActionContext$1, fn: () => T): T;
+}
+declare function bindActionContextStorage(storage: ActionContextStorage): void;
+declare function getActionContext(): ActionContext$1 | undefined;
+declare function runWithActionContext<T>(ctx: ActionContext$1, fn: () => T): T;
+declare function createDetachedActionContext(request?: Request): ActionContext$1;
+//#endregion
+//#region src/actions/openapi.d.ts
+/**
+ * Optional OpenAPI fragment for the shared `POST /__actions` RPC.
+ *
+ * Per-action operations stay on the same endpoint (id in the body) so this
+ * does not create a second RPC surface.
+ */
+declare function describeActionsOpenApi(): {
+  paths: Record<string, {
+    post: {
+      summary: string;
+      description: string;
+      operationId: string;
+    };
+  }>;
+};
+//#endregion
+//#region src/actions/id.d.ts
+/**
+ * Stable Action ID generation (P9-02).
+ *
+ * Action IDs are derived from the action's source location (file path +
+ * export name) so the client and server agree on the same ID without
+ * runtime coordination. The Vite plugin injects the ID at build time,
+ * but a runtime fallback is provided for actions defined outside the
+ * `'use server'` pipeline (e.g. inline `defineAction` in page modules).
+ *
+ * Format: `act_<base32(sha1(relPath:exportName)).slice(0, 12)>`
+ *   - `act_` prefix avoids collisions with other URL components
+ *   - 12 chars of base32 gives ~60 bits of entropy (collision-resistant
+ *     for any reasonable project size)
+ *   - base32 (RFC 4648, lowercase) is URL-safe and case-insensitive
+ */
+/**
+ * Compute a stable action ID from a file path and export name.
+ *
+ * @param filePath Project-relative file path (e.g. `src/actions/auth.ts`)
+ * @param exportName The export name (e.g. `login`, `default`)
+ * @returns A stable action ID string
+ */
+declare function createActionId(filePath: string, exportName: string): string;
+/**
+ * Validate that a string is a well-formed action ID.
+ *
+ * Used by the dispatcher to reject malformed requests early.
+ */
+declare function isValidActionId(id: string): boolean;
+//#endregion
+//#region src/actions/registry.d.ts
+/**
+ * Register a server action in the global registry.
+ *
+ * Called by `defineAction` (implicitly) and by the Vite plugin's virtual
+ * module (explicitly) for `'use server'` modules.
+ *
+ * If an action with the same ID is already registered, the call is a
+ * no-op (HMR-safe: re-registering the same action on hot reload doesn't
+ * throw).
+ */
+declare function registerAction(action: ServerAction$1): void;
+/**
+ * Look up a registered server action by ID.
+ */
+declare function getAction(id: ActionId$1): ServerAction$1 | undefined;
+/**
+ * Check whether an action with the given ID is registered.
+ */
+declare function hasAction(id: ActionId$1): boolean;
+/**
+ * List all registered actions (for debugging / DevTools).
+ */
+declare function listActions(): ServerAction$1[];
+/**
+ * Clear the registry (for tests).
+ *
+ * Not intended for application code — actions are registered once at
+ * module load and remain for the lifetime of the process.
+ */
+declare function clearActions(): void;
+/**
+ * Register a map of actions at once (bulk registration helper for the
+ * Vite plugin's virtual module).
+ */
+declare function registerActions(actions: ServerAction$1[]): void;
+//#endregion
+//#region src/actions/dispatch.d.ts
+/**
+ * Dispatch a registered server action by ID.
+ *
+ * Used by the `/__actions` POST endpoint (RPC-style invocation from the
+ * client). The action ID is looked up in the global registry; the request
+ * body is parsed as JSON or FormData depending on `Content-Type`.
+ *
+ * When `preParsedInput` is provided (RPC path — the middleware has already
+ * read the body to extract the `{ id, args }` envelope), body parsing is
+ * skipped and `preParsedInput` is used as the handler input directly.
+ *
+ * Returns an `ActionResult` (serializable). When the action ID is unknown
+ * or invalid, returns a 404 error result without throwing.
+ */
+declare function dispatchAction(actionId: string, c: Context<UbeanEnv$1>, preParsedInput?: unknown): Promise<ActionResult$1>;
+/**
+ * Run an arbitrary `ServerAction` against the given Hono context.
+ *
+ * Used internally by `dispatchAction` and by `handlePageRequest` for
+ * page-level form actions (which are not in the global registry but
+ * are exported from the page module's `actions` map).
+ *
+ * When `preParsedInput` is provided, body parsing is skipped (the caller
+ * has already read the request body — e.g. the RPC middleware extracting
+ * the `{ id, args }` envelope).
+ */
+declare function runAction<TInput, TOutput>(action: ServerAction$1<TInput, TOutput>, c: Context<UbeanEnv$1>, preParsedInput?: unknown): Promise<ActionResult$1<TOutput>>;
+/**
+ * Run a page-level form action by name (SvelteKit-style `?/name` convention).
+ *
+ * Page modules may export an `actions` map:
+ *
+ * ```ts
+ * export const actions = {
+ *   default: defineAction(async (input, ctx) => { ... }),
+ *   login: defineAction(async (input, ctx) => { ... }),
+ *   register: defineAction(async (input, ctx) => { ... })
+ * };
+ * ```
+ *
+ * - `POST /page` (no `?/`) → `actions.default`
+ * - `POST /page?/login` → `actions.login`
+ * - `POST /page?/register` → `actions.register`
+ *
+ * Returns `null` when:
+ *  - No `actions` export exists (caller should fall back to `mod.action`).
+ *  - The named action doesn't exist (caller should return 404).
+ *
+ * The caller (`handlePageRequest`) is responsible for converting the
+ * `ActionResult` into an HTTP response (HTML for browser navigation,
+ * JSON for SPA `submit()` calls).
+ */
+declare function runPageAction(actions: Record<string, ServerAction$1>, actionName: string, c: Context<UbeanEnv$1>): Promise<ActionResult$1 | null>;
+//#endregion
+//#region src/actions/constants.d.ts
+/**
+ * Shared constants for Server Actions RPC.
+ *
+ * Kept in a leaf module so the browser runtime can import them without
+ * pulling the Hono middleware barrel.
+ */
+declare const ACTIONS_ENDPOINT = "/__actions";
+declare const ACTION_RESPONSE_HEADER = "x-ubean-action";
+//#endregion
+//#region src/actions/middleware.d.ts
+/**
+ * Create the actions middleware — a Hono handler that mounts the
+ * `/__actions` POST endpoint.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { createUbeanApp } from 'ubean/runtime/app';
+ * import { createActionsMiddleware } from '@ubean/routes';
+ *
+ * const app = createUbeanApp();
+ * app.on('POST', '/__actions', createActionsMiddleware());
+ * ```
+ *
+ * The middleware is auto-registered by ubean's dev server / production
+ * server setup — users don't need to mount it manually.
+ */
+declare function createActionsMiddleware(): MiddlewareHandler<UbeanEnv$1>;
+/**
+ * Check whether a request targets the actions endpoint.
+ *
+ * Used by route registrars to skip registering regular API routes for
+ * the `/__actions` path.
+ */
+declare function isActionsRequest(c: {
+  req: {
+    path: string;
+    method: string;
+  };
+}): boolean;
+/**
+ * Check whether a response came from the actions middleware.
+ *
+ * Used by the client `callAction()` to validate the response shape.
+ */
+declare function isActionResponse(response: Response): boolean;
+//#endregion
+//#region src/actions/form-action.d.ts
+/**
+ * SvelteKit-style form action URL parsing (P9-02).
+ *
+ * Form actions are invoked via `POST /page?/<actionName>`:
+ *
+ *  - `POST /login` → `actions.default`
+ *  - `POST /login?/login` → `actions.login`
+ *  - `POST /login?/register` → `actions.register`
+ *
+ * The `?/<name>` syntax is URL-safe and works without JavaScript (the
+ * browser submits the form to the full URL). On the server, the page
+ * route handler parses the action name from the URL's search query.
+ *
+ * For progressive enhancement, the client can intercept the form submit
+ * and call the action via `useFormAction()` for SPA-style navigation.
+ */
+/**
+ * Extract the form action name from a URL's search query.
+ *
+ * SvelteKit's convention: the query string contains a single key `/<name>`
+ * with no value. URLSearchParams treats this as a key with empty value.
+ *
+ * - `?/login` → `login`
+ * - `?/register` → `register`
+ * - `?` (no action) → `default`
+ * - (no query) → `default`
+ *
+ * @returns The action name, or `'default'` when no specific action is
+ *          specified.
+ */
+declare function parseFormActionName(url: string | URL): string;
+/**
+ * Build a form action URL for the current page.
+ *
+ * Used by `useFormAction()` to generate the `action` attribute for
+ * `<form>` elements. The URL is relative so it works on any page.
+ *
+ * - `useFormAction()` → `?/default`
+ * - `useFormAction('login')` → `?/login`
+ * - `useFormAction('register')` → `?/register`
+ *
+ * The returned string is intended for `<form :action="formAction">` —
+ * the browser submits to the current page URL with the action name
+ * appended as a query parameter.
+ */
+declare function buildFormActionUrl(actionName?: string): string;
+/**
+ * Check whether a URL's query string contains a form action specifier
+ * (`?/<name>` pattern).
+ */
+declare function hasFormAction(url: string | URL): boolean;
 //#endregion
 //#region src/internal-fetch.d.ts
 interface InternalFetchOptions {
@@ -331,4 +710,4 @@ declare function registerOpenAPIRoutes(app: Hono<UbeanEnv$1>, options?: OpenAPIG
   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 };
+export { ACTIONS_ENDPOINT, ACTION_BRAND, ACTION_RESPONSE_HEADER, type ActionContext, type ActionContextStorage, ActionError, type ActionFailure, type ActionHandler, type ActionId, type ActionResult, type ActionSchema, type CompiledLayout, type CompiledMiddleware, type CompiledPage, type CompiledRoute, type CompiledRouteRule, type ComposedHandler, type DefineActionOptions, type GenericSchema, type Input, type InternalFetchOptions, type IsrCacheEntry, type IsrCacheEntryInternal, type IsrCacheStore, type IsrRule, type IsrServeOptions, type OpenAPIGenerationOptions, type RegisterOptions, type ResolveSelectSsrInput, type ResolvedSelectSsr, type RouteMeta, type RouteRegistrar, type RouteRule, type RouteRulesMiddlewareOptions, type SelectSsrMode, type SelectSsrValue, type ServerAction, 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, applyPathTransform, bindActionContextStorage, buildActionContext, buildFormActionUrl, buildIsrCacheKey, clearActions, clearInternalFetcher, compileRouteRules, createActionId, createActionsMiddleware, createDetachedActionContext, createInternalAdapter, createRouteLoader, createRouteRulesMiddleware, createServerRouter, defineAction, defineHandler, defineHandlerMeta, defineMiddleware, defineServerFn, describeActionsOpenApi, dispatchAction, extractRouteMeta, fail, getAction, getActionContext, getInternalFetcher, getIsrCache, getIsrRuleFromContext, getStaleIsrCache, hasAction, hasFormAction, invalidateIsrCache, invalidateIsrCachePattern, invokeServerFn, isActionFailure, isActionResponse, isActionsRequest, isBotUserAgent, isHandlerChain, isIsrEntryStale, isServerAction, isValidActionId, listActions, matchRouteRules, normalizeActionResult, normalizeIsrRule, parseActionInput, parseFormActionName, registerAction, registerActions, registerApiRoutes, registerOpenAPIRoutes, registerPageRoutes, registerRoutes, resolveSelectSsr, runAction, runPageAction, runWithActionContext, serveIsr, setInternalFetcher, setIsrCache, sortPagesForRegistration, ssrModeHeader, unwrapActionResult, unwrapServerFnResult, useRouter, validateActionInput };