@finesoft/front 0.1.39 → 0.1.41

package/dist/index.d.cts

@@ -1,582 +0,0 @@
-import { FrameworkConfig, Framework, BasePage, PrefetchedIntent } from './browser.cjs';
-export { ACTION_KINDS, Action, ActionDispatcher, ActionHandler, ActionHandlerDependencies, AfterLoadGuard, AsyncMapper, BaseController, BaseItem, BaseLogger, BaseShelf, BeforeLoadGuard, BrowserAppConfig, BrowserContextOptions, CompositeLogger, CompositeLoggerFactory, CompoundAction, ConsoleLogger, ConsoleLoggerFactory, Container, DEP_KEYS, DenyResult, ExternalUrlAction, ExternalUrlDependencies, FeatureFlags, FlowAction, FlowActionCallbacks, FlowActionDependencies, History, HttpClient, HttpClientConfig, HttpError, Intent, IntentController, IntentDispatcher, Locale, Logger, LoggerFactory, Logger as LoggerInterface, LruMap, Mapper, MetricsRecorder, MiddlewareResult, NavigationContext, Net, NextResult, None, Optional, PostLoadContext, PrefetchedIntents, RedirectResult, RenderMode, RewriteResult, RouteAddOptions, RouteDefinition, RouteMatch, Router, ServerContextOptions, Storage, buildUrl, createBrowserContext, createPrefetchedIntentsFromDom, createServerContext, defineRoutes, deny, deserializeServerData, generateUuid, getBaseUrl, isCompoundAction, isExternalUrlAction, isFlowAction, isNone, isSome, makeDependencies, makeExternalUrlAction, makeFlowAction, mapEach, next, pipe, pipeAsync, redirect, registerActionHandlers, registerExternalUrlHandler, registerFlowActionHandler, removeHost, removeQueryParams, removeScheme, resetFilterCache, rewrite, runAfterLoadGuards, runBeforeLoadGuards, shouldLog, stableStringify, startBrowserApp, tryScroll } from './browser.cjs';
-import * as node_fs from 'node:fs';
-import { Hono } from 'hono';
-import { ViteDevServer } from 'vite';
-
-/**
- * ssrRender — 通用 SSR 渲染管线
- *
- * 1. 创建 Framework + 注册 Controllers
- * 2. routeUrl → Intent
- * 3. dispatch → Page 数据
- * 4. 调用应用层提供的渲染函数
- */
-
-interface SSRRenderOptions {
-    /** 请求 URL */
-    url: string;
-    /** Framework 配置（含路由注册等） */
-    frameworkConfig: FrameworkConfig;
-    /** 注册 controllers 和路由的引导函数 */
-    bootstrap: (framework: Framework) => void;
-    /** 获取错误页面 */
-    getErrorPage: (status: number, message: string) => BasePage;
-    /** 应用层渲染函数（如 Svelte SSR render） */
-    renderApp: (page: BasePage, framework: Framework) => SSRAppResult;
-    /** 可选的 SSR 请求上下文（如自定义 fetch） */
-    ssrContext?: SSRContext;
-}
-/** SSR 请求级上下文 */
-interface SSRContext {
-    /** 自定义 fetch（如 Hono 内部路由回环） */
-    fetch?: typeof globalThis.fetch;
-    /** 原始 Request 对象（用于中间件读取 cookie/header） */
-    request?: Request;
-}
-interface SSRAppResult {
-    html: string;
-    head: string;
-    css: string;
-}
-interface SSRRenderResult {
-    html: string;
-    head: string;
-    css: string;
-    serverData: PrefetchedIntent[];
-    /** 该路由的渲染模式（由 Router 返回） */
-    renderMode?: string;
-    /** 中间件要求的重定向（服务端应返回 HTTP 301/302） */
-    redirect?: {
-        url: string;
-        status: number;
-    };
-}
-declare function ssrRender(options: SSRRenderOptions): Promise<SSRRenderResult>;
-
-/**
- * createSSRRender — 工厂函数，返回可直接被 SSR 服务器调用的 render 函数
- *
- * 将一次性配置（bootstrap / getErrorPage / renderApp）绑定后，
- * 返回 `(url, locale) => Promise<SSRRenderResult>` 签名，
- * 与 @finesoft/server 的 SSRModule 接口对齐。
- */
-
-interface SSRRenderConfig {
-    /** 注册 controllers 和路由的引导函数 */
-    bootstrap: (framework: Framework) => void;
-    /** 获取错误页面 */
-    getErrorPage: (status: number, message: string) => BasePage;
-    /**
-     * 应用层渲染函数
-     *
-     * @param page - 当前页面数据
-     * @param locale - 当前语言
-     * @returns SSR 渲染结果 { html, head, css }
-     */
-    renderApp: (page: BasePage, locale: string) => SSRAppResult;
-    /** Framework 构造配置（可选） */
-    frameworkConfig?: FrameworkConfig;
-}
-/**
- * 创建 render 函数
- *
- * @returns `render(url, locale, ssrContext?)` — 供 @finesoft/server SSRModule 使用
- */
-declare function createSSRRender(config: SSRRenderConfig): (url: string, locale: string, ssrContext?: SSRContext) => Promise<SSRRenderResult>;
-
-/**
- * injectSSRContent — 将 SSR 渲染结果注入 HTML 模板
- */
-/** SSR HTML 模板占位符常量 */
-declare const SSR_PLACEHOLDERS: {
-    readonly LANG: "<!--ssr-lang-->";
-    readonly HEAD: "<!--ssr-head-->";
-    readonly BODY: "<!--ssr-body-->";
-    readonly DATA: "<!--ssr-data-->";
-};
-interface InjectSSROptions {
-    template: string;
-    locale: string;
-    head: string;
-    css: string;
-    html: string;
-    serializedData: string;
-}
-declare function injectSSRContent(options: InjectSSROptions): string;
-/**
- * CSR 空壳注入 — 只替换 lang，清空 body/head/data 占位符
- * 用于 renderMode === "csr" 的路由
- */
-declare function injectCSRShell(template: string, locale: string): string;
-
-/**
- * serializeServerData — 将 PrefetchedIntents 数据序列化为安全的 JSON
- *
- * 返回值可安全嵌入 <script> 标签。
- */
-
-declare function serializeServerData(data: PrefetchedIntent[]): string;
-
-/**
- * 框架级声明式代理路由
- *
- * 将代理路由从业务层手写 Hono 路由，改为框架级配置。
- * 框架统一执行路径校验（SSRF 防护）、Host 限制、错误处理、响应头控制。
- */
-
-/** 代理路由认证配置 */
-interface ProxyAuthConfig {
-    /** 认证类型 */
-    type: "bearer" | "basic";
-    /** 环境变量名称（运行时从 process.env 读取） */
-    envKey: string;
-}
-/** 声明式代理路由配置 */
-interface ProxyRouteConfig {
-    /** URL 前缀，如 "/api/apple"（必须以 "/" 开头） */
-    prefix: string;
-    /** 代理目标地址（必须以 "https://" 开头） */
-    target: string;
-    /** HTTP 方法（默认 ["all"]） */
-    methods?: ("all" | "get" | "post" | "put" | "delete" | "patch")[];
-    /** 附加到代理请求的头部 */
-    headers?: Record<string, string>;
-    /** 认证配置 */
-    auth?: ProxyAuthConfig;
-    /** Cache-Control 响应头 */
-    cache?: string;
-    /** 是否跟随重定向（默认 false） */
-    followRedirects?: boolean;
-}
-/**
- * 注册声明式代理路由到 Hono app（运行时使用：dev / preview / createServer）
- */
-declare function registerProxyRoutes(app: Hono, configs: ProxyRouteConfig[]): void;
-/**
- * 生成代理路由的内联代码（用于 serverless/edge 入口，避免运行时依赖）
- */
-declare function generateProxyCode(configs: ProxyRouteConfig[]): string;
-
-/** 适配器上下文 — 由 vite-plugin 的 closeBundle 构造后传入 adapter.build() */
-interface AdapterContext {
-    /** 项目根路径 */
-    root: string;
-    /** SSR 入口文件相对路径（如 "src/ssr.ts"） */
-    ssrEntry: string;
-    /** setup 文件相对路径（如 "src/proxies.ts"），仅当 options.setup 为 string 时有值 */
-    setupPath?: string;
-    /** 路由定义入口文件（用于预渲染时加载路由），如 "src/lib/bootstrap.ts" */
-    bootstrapEntry?: string;
-    /** 支持的语言列表 */
-    locales: string[];
-    /** 默认语言 */
-    defaultLocale: string;
-    /** dist/client/index.html 的内容 */
-    templateHtml: string;
-    /** Vite 的 resolve 配置 */
-    resolvedResolve: unknown;
-    /** Vite 的 css 配置 */
-    resolvedCss: unknown;
-    /**
-     * 按路由覆盖的渲染模式。
-     * key: 精确路径或 glob 模式，value: "ssr" | "csr" | "prerender"
-     */
-    renderModes?: Record<string, string>;
-    /** 声明式代理路由配置 */
-    proxies?: ProxyRouteConfig[];
-    vite: any;
-    fs: typeof node_fs;
-    path: {
-        resolve: (...args: string[]) => string;
-        join: (...args: string[]) => string;
-    };
-    /** 生成 serverless/edge function 入口源码 */
-    generateSSREntry(opts: GenerateSSREntryOptions): string;
-    /** 用 Vite SSR 模式构建 bundle */
-    buildBundle(opts: BuildBundleOptions): Promise<void>;
-    /** 复制 dist/client 静态资源到目标目录 */
-    copyStaticAssets(destDir: string, opts?: CopyStaticAssetsOptions): void;
-}
-interface GenerateSSREntryOptions {
-    /** 平台特定的导入语句（如 `import { handle } from "hono/vercel";`） */
-    platformImport: string;
-    /** 平台特定的导出语句（如 `export default handle(app);`） */
-    platformExport: string;
-    /**
-     * 平台特定的 ISR 缓存实现代码（可选）。
-     * 需提供 `async function platformCacheGet(url)` 返回 string|null，
-     * 和 `async function platformCacheSet(url, html)` 的函数定义。
-     * 不提供时使用内置的内存 Map 缓存。
-     */
-    platformCache?: string;
-    /**
-     * 平台特定的响应后处理代码（可选）。
-     * 在 prerender 路由返回前执行，可用于设置 CDN 缓存头等。
-     * 代码中可使用变量 `c`（Hono Context）。
-     */
-    platformPrerenderResponseHook?: string;
-    /**
-     * 平台特定的中间件代码（可选）。
-     * 插入在 catch-all GET 路由之前，可用于添加静态文件服务等。
-     * 代码中可使用变量 `app`（Hono 实例）。
-     */
-    platformMiddleware?: string;
-}
-interface BuildBundleOptions {
-    /** 临时入口文件路径 */
-    entry: string;
-    /** 输出目录 */
-    outDir: string;
-    /** 构建 target（默认 "node18"） */
-    target?: string;
-    /** 输出文件名（默认 "index.mjs"） */
-    fileName?: string;
-    /** 排除的模块（默认 ["vite", "esbuild", "rollup", "fsevents", "lightningcss"]） */
-    external?: string[];
-    /** 是否打包所有依赖（默认 true） */
-    noExternal?: boolean;
-}
-interface CopyStaticAssetsOptions {
-    /** 是否排除 index.html（默认 true） */
-    excludeHtml?: boolean;
-}
-/** 适配器接口 */
-interface Adapter {
-    /** 适配器名称（用于日志） */
-    name: string;
-    /** 生成目标平台部署产物 */
-    build(ctx: AdapterContext): Promise<void>;
-}
-
-/**
- * Auto 适配器 — 根据环境变量自动选择目标平台
- *
- * 检测顺序：
- *   VERCEL       → vercel
- *   CF_PAGES     → cloudflare
- *   NETLIFY      → netlify
- *   (default)    → node
- */
-
-declare function autoAdapter(): Adapter;
-
-/**
- * Cloudflare Pages 适配器
- *
- * 生成 dist/cloudflare/ 目录：
- * - _worker.js — Workers 入口（Hono 原生支持 CF fetch 接口）
- * - assets/    — 静态资源
- *
- * 注意：Cloudflare Workers 不支持原生 Node.js API。
- * 若 setup 代理使用了 process.env，需在 wrangler.toml 启用 nodejs_compat。
- */
-
-declare function cloudflareAdapter(): Adapter;
-
-/**
- * Netlify 适配器 — Netlify Functions v2
- *
- * 生成：
- * - .netlify/functions-internal/ssr/index.mjs — Serverless Function
- * - dist/client/_redirects — 路由重写规则
- */
-
-declare function netlifyAdapter(): Adapter;
-
-/**
- * Node 适配器 — 独立 HTTP 服务器
- *
- * 生成 dist/server/index.mjs，使用 @hono/node-server 监听端口。
- * 运行：node dist/server/index.mjs
- */
-
-declare function nodeAdapter(): Adapter;
-
-/**
- * resolveAdapter — 字符串 → Adapter 映射
- */
-
-declare function resolveAdapter(value: string | Adapter): Adapter;
-
-/**
- * Static 适配器 — 构建时预渲染
- *
- * 加载 SSR 模块和路由定义，将无参数路由自动预渲染为静态 HTML。
- * 动态参数路由通过 dynamicRoutes 选项补充具体 URL。
- *
- * 输出：dist/static/ — 纯静态站点，可部署到任何静态托管。
- */
-
-interface StaticAdapterOptions {
-    /**
-     * 导出 routes 数组的文件路径（相对于项目根目录）。
-     * 默认 "src/lib/bootstrap.ts"。
-     * 文件需 export 一个 RouteDefinition[] 类型的 routes 变量。
-     */
-    routesExport?: string;
-    /**
-     * 额外的动态路由 URL（带具体参数值），如：
-     * ["/product/123", "/list/games"]
-     */
-    dynamicRoutes?: string[];
-}
-declare function staticAdapter(opts?: StaticAdapterOptions): Adapter;
-
-/**
- * Vercel 适配器 — Build Output API v3
- *
- * 生成 .vercel/output/ 目录：
- * - config.json — 路由规则
- * - static/     — 静态资源
- * - functions/ssr.func/ — Serverless Function
- */
-
-declare function vercelAdapter(): Adapter;
-
-/**
- * createSSRApp — 创建 Hono SSR 应用
- *
- * 提供 SSR 通配路由，读取模板、加载 SSR 模块、渲染。
- * 应用层可在此之上追加自定义路由（API 代理等）。
- */
-
-interface SSRModule {
-    render: (url: string, locale: string, ssrContext?: {
-        fetch?: typeof globalThis.fetch;
-        request?: Request;
-    }) => Promise<{
-        html: string;
-        head: string;
-        css: string;
-        serverData: unknown;
-        renderMode?: string;
-        redirect?: {
-            url: string;
-            status: number;
-        };
-    }>;
-    serializeServerData: (data: unknown) => string;
-}
-interface SSRAppOptions {
-    /** 项目根路径 */
-    root: string;
-    /** Vite dev server（仅开发模式） */
-    vite?: ViteDevServer;
-    /** 是否生产环境 */
-    isProduction: boolean;
-    /** SSR 入口文件路径（开发用，如 "/src/ssr.ts"） */
-    ssrEntryPath?: string;
-    /** 生产环境 SSR 模块路径（如 "../dist/server/ssr.js"） */
-    ssrProductionModule?: string;
-    /** 支持的语言列表 */
-    supportedLocales?: string[];
-    /** 默认语言 */
-    defaultLocale?: string;
-    /**
-     * 父级 Hono app 的 fetch 函数，用于 SSR 内部路由回环。
-     * SSR 渲染时，控制器的 fetch 请求（如 /api/apple/*）会通过此函数
-     * 直接在进程内路由到代理 handler，避免网络自请求死锁。
-     */
-    parentFetch?: (request: Request) => Response | Promise<Response>;
-    /**
-     * 按路由覆盖渲染模式（精确路径或 glob 模式）。
-     * 优先级高于路由级 renderMode。
-     */
-    renderModes?: Record<string, string>;
-}
-declare function createSSRApp(options: SSRAppOptions): Hono;
-
-/**
- * runtime — 运行时检测 + 项目根路径推导
- */
-interface RuntimeInfo {
-    isDeno: boolean;
-    isBun: boolean;
-    isVercel: boolean;
-    isProduction: boolean;
-}
-/** 检测当前运行时环境 */
-declare function detectRuntime(): RuntimeInfo;
-/**
- * 从 `import.meta.url` 推导项目根路径
- *
- * @param importMetaUrl - 调用方的 `import.meta.url`
- * @param levelsUp - 向上移动多少级（默认 0，即调用方所在目录就是项目根）
- */
-declare function resolveRoot(importMetaUrl: string, levelsUp?: number): Promise<string>;
-
-/**
- * createServer — 一站式服务器工厂
- *
- * 封装 env 加载、运行时检测、Vite 创建、Hono app、SSR、启动。
- * 保留 setup() 钩子用于注册业务路由。
- */
-
-interface ServerConfig {
-    /** 项目根路径（默认 process.cwd()） */
-    root?: string;
-    /** 支持的语言列表 */
-    locales?: string[];
-    /** 默认语言 */
-    defaultLocale?: string;
-    /** 端口号（默认 3000） */
-    port?: number;
-    /** 注册自定义路由（在 SSR catch-all 之前调用，但在声明式代理之后） */
-    setup?: (app: Hono) => void | Promise<void>;
-    /** 声明式代理路由配置 */
-    proxies?: ProxyRouteConfig[];
-    /** SSR 相关选项（透传给 createSSRApp） */
-    ssr?: Pick<SSRAppOptions, "ssrEntryPath" | "ssrProductionModule">;
-}
-interface ServerInstance {
-    app: Hono;
-    vite?: ViteDevServer;
-    runtime: RuntimeInfo;
-}
-/**
- * 创建并启动 SSR 服务器
- *
- * @example
- * ```ts
- * const { app } = await createServer({
- *   locales: ["zh", "en"],
- *   setup: (app) => registerProxies(app),
- * });
- * export { app };
- * ```
- */
-declare function createServer(config?: ServerConfig): Promise<ServerInstance>;
-
-/**
- * Accept-Language 解析
- */
-declare function parseAcceptLanguage(header: string | undefined, supported?: string[], fallback?: string): string;
-
-/**
- * startServer — 多运行时自动启动
- *
- * 支持 Node.js (dev HMR + prod)、Deno、Bun、Vercel。
- */
-
-interface StartServerOptions {
-    /** 最终的 Hono app（已包含 SSR + 自定义路由） */
-    app: Hono;
-    /** 项目根路径 */
-    root: string;
-    /** 端口号 */
-    port?: number;
-    /** 是否生产环境 */
-    isProduction: boolean;
-    /** Vite dev server（仅开发模式传入） */
-    vite?: ViteDevServer;
-    /** 运行时信息（可选，不传时自动检测） */
-    runtime?: RuntimeInfo;
-    /** 已注册的路由列表（用于启动日志） */
-    routes?: string[];
-    /** 支持的语言列表（用于启动日志） */
-    locales?: string[];
-    /** SSR 入口路径（用于启动日志） */
-    ssrEntryPath?: string;
-}
-declare function startServer(options: StartServerOptions): Promise<{
-    vite?: ViteDevServer;
-}>;
-
-/**
- * finesoftFrontViteConfig — Vite 插件
- *
- * 将 Hono SSR 服务器集成到 Vite 的 dev / build / preview 生命周期中，
- * 使 template-project 只需 `vite` / `vite build` / `vite preview` 即可运行。
- *
- * 支持多平台 adapter: "vercel" | "cloudflare" | "netlify" | "node" | "static" | "auto"
- * 或自定义 Adapter 对象。
- */
-
-interface FinesoftFrontViteOptions {
-    /** 支持的语言列表 */
-    locales?: string[];
-    /** 默认语言 */
-    defaultLocale?: string;
-    /** SSR 配置 */
-    ssr?: {
-        /** SSR 入口文件路径（默认 "src/ssr.ts"） */
-        entry?: string;
-    };
-    /**
-     * 声明式代理路由配置。
-     * 框架统一执行路径校验（SSRF 防护）、Host 限制、错误处理、响应头控制。
-     * 代理路由在 setup 之前注册，优先级高于自定义路由。
-     */
-    proxies?: ProxyRouteConfig[];
-    /**
-     * 注册自定义路由（非代理类）。
-     * - 传入 Function：仅 dev/preview 时可用。
-     * - 传入 string（文件路径）：dev/preview/adapter 均可用，
-     *   文件需 export default 一个 (app: Hono) => void 函数。
-     * 注意：代理路由请使用 proxies 选项，不要在 setup 中手写代理。
-     */
-    setup?: ((app: Hono) => void | Promise<void>) | string;
-    /**
-     * 部署适配器。
-     * - 字符串快捷方式："vercel" | "cloudflare" | "netlify" | "node" | "static" | "auto"
-     * - 自定义 Adapter 对象：{ name, build(ctx) }
-     * - 不设置则不生成部署产物
-     */
-    adapter?: string | Adapter;
-    /**
-     * 按路由覆盖渲染模式（优先级高于 RouteDefinition.renderMode）。
-     * key: 精确路径或 glob 模式，如 "/search" 或 "/blog/*"
-     * value: "ssr" | "csr" | "prerender"
-     *
-     * @example
-     * ```ts
-     * renderModes: {
-     *   "/search": "csr",
-     *   "/blog/*": "prerender",
-     * }
-     * ```
-     */
-    renderModes?: Record<string, "ssr" | "csr" | "prerender">;
-    /**
-     * 路由定义入口文件（用于预渲染时加载路由），默认 "src/lib/bootstrap.ts"。
-     * 如果项目不使用声明式路由定义，可以不设置。
-     */
-    bootstrapEntry?: string;
-}
-declare function finesoftFrontViteConfig(options?: FinesoftFrontViteOptions): {
-    name: string;
-    config(userConfig: Record<string, any>, env: {
-        command: string;
-    }): Record<string, any>;
-    configResolved(config: Record<string, any>): void;
-    /**
-     * Dev 模式 CSS 内联 — 消除 SSR 首屏布局抖动
-     *
-     * Vite dev 模式下，global.scss 等非组件 CSS 通过 JS 模块系统异步加载，
-     * 导致 SSR HTML 初次渲染缺少布局关键样式（box-sizing、flex 布局、padding-top 等）。
-     *
-     * 此 hook 在 HTML 模板变换阶段（SSR 渲染之前）：
-     * 1. 找到浏览器入口脚本（排除 /@vite/client 等内部脚本）
-     * 2. 编译入口脚本，填充 Vite 模块图
-     * 3. 遍历模块图收集所有 CSS 依赖（排除 .svelte 组件 CSS，由 SSR 渲染自行处理）
-     * 4. 通过 ssrLoadModule 获取编译后 CSS（SCSS→CSS）
-     * 5. 注入 <style data-vite-dev-id> 标签到 <head>
-     *
-     * data-vite-dev-id 确保 Vite HMR 客户端复用已有标签，避免重复注入。
-     */
-    transformIndexHtml: {
-        order: "pre";
-        handler(html: string, ctx: any): Promise<{
-            tag: string;
-            attrs: Record<string, string>;
-            children: string;
-            injectTo: "head";
-        }[] | undefined>;
-    };
-    configureServer(server: any): () => Promise<void>;
-    configurePreviewServer(server: any): () => Promise<void>;
-    closeBundle(): Promise<void>;
-};
-
-export { type Adapter, type AdapterContext, BasePage, type FinesoftFrontViteOptions, Framework, FrameworkConfig, type InjectSSROptions, PrefetchedIntent, type ProxyAuthConfig, type ProxyRouteConfig, type RuntimeInfo, type SSRAppOptions, type SSRContext, type SSRModule, type SSRRenderConfig, type SSRRenderOptions, type SSRRenderResult, SSR_PLACEHOLDERS, type ServerConfig, type ServerInstance, type StartServerOptions, autoAdapter, cloudflareAdapter, createSSRApp, createSSRRender, createServer, detectRuntime, finesoftFrontViteConfig, generateProxyCode, injectCSRShell, injectSSRContent, netlifyAdapter, nodeAdapter, parseAcceptLanguage, registerProxyRoutes, resolveAdapter, resolveRoot, serializeServerData, ssrRender, startServer, staticAdapter, vercelAdapter };