@weifuwujs/weifuwu 0.9.0

package/dist/resources.js

@@ -0,0 +1,54 @@
+/** `App.use()` 识别该 symbol 上的 dispose 并注册到 `app.close()`（内部协议） */
+export const RESOURCE_DISPOSE = Symbol('weifuwu.resource.dispose');
+/**
+ * 懒初始化的共享资源中间件。
+ *
+ * ```ts
+ * const db = resource('db', () => openDatabase(), { close: (db) => db.end() })
+ * const app = createApp().use(db)
+ * app.get('/', (req, ctx) => json(ctx.db.query()))
+ * ```
+ */
+export function resource(key, create, options = {}) {
+    let value;
+    let created = false;
+    let pending;
+    const load = () => {
+        if (created)
+            return Promise.resolve(value);
+        pending ??= Promise.resolve()
+            .then(() => create())
+            .then((resolved) => {
+            value = resolved;
+            created = true;
+            pending = undefined;
+            return resolved;
+        }, (error) => {
+            pending = undefined;
+            throw error;
+        });
+        return pending;
+    };
+    const close = async () => {
+        if (!created) {
+            pending = undefined;
+            return;
+        }
+        const resolved = value;
+        value = undefined;
+        created = false;
+        pending = undefined;
+        await options.close?.(resolved);
+    };
+    const middleware = (async (req, ctx, next) => {
+        const resolved = await load();
+        return next(req, { ...ctx, [key]: resolved });
+    });
+    Object.defineProperty(middleware, 'key', { value: key });
+    middleware.peek = () => (created ? value : undefined);
+    middleware.load = load;
+    middleware.close = close;
+    Object.defineProperty(middleware, RESOURCE_DISPOSE, { value: close });
+    return middleware;
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAkB,MAAM,CAAC,0BAA0B,CAAC,CAAA;AA6BjF;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAKtB,GAAM,EACN,MAA4B,EAC5B,UAA8B,EAAE;IAEhC,IAAI,KAAoB,CAAA;IACxB,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,IAAI,OAA+B,CAAA;IAEnC,MAAM,IAAI,GAAG,GAAe,EAAE;QAC5B,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAU,CAAC,CAAA;QAC/C,OAAO,KAAK,OAAO,CAAC,OAAO,EAAE;aAC1B,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC;aACpB,IAAI,CACH,CAAC,QAAQ,EAAE,EAAE;YACX,KAAK,GAAG,QAAQ,CAAA;YAChB,OAAO,GAAG,IAAI,CAAA;YACd,OAAO,GAAG,SAAS,CAAA;YACnB,OAAO,QAAQ,CAAA;QACjB,CAAC,EACD,CAAC,KAAc,EAAE,EAAE;YACjB,OAAO,GAAG,SAAS,CAAA;YACnB,MAAM,KAAK,CAAA;QACb,CAAC,CACF,CAAA;QACH,OAAO,OAAO,CAAA;IAChB,CAAC,CAAA;IAED,MAAM,KAAK,GAAG,KAAK,IAAmB,EAAE;QACtC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,SAAS,CAAA;YACnB,OAAM;QACR,CAAC;QACD,MAAM,QAAQ,GAAG,KAAU,CAAA;QAC3B,KAAK,GAAG,SAAS,CAAA;QACjB,OAAO,GAAG,KAAK,CAAA;QACf,OAAO,GAAG,SAAS,CAAA;QACnB,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,CAAA;IACjC,CAAC,CAAA;IAED,MAAM,UAAU,GAAG,CAAC,KAAK,EACvB,GAAY,EACZ,GAAM,EACN,IAA+B,EAC/B,EAAE;QACF,MAAM,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAA;QAC7B,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAsB,CAAC,CAAA;IACnE,CAAC,CAAsB,CAAA;IAEvB,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;IACxD,UAAU,CAAC,IAAI,GAAG,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,KAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC5D,UAAU,CAAC,IAAI,GAAG,IAAI,CAAA;IACtB,UAAU,CAAC,KAAK,GAAG,KAAK,CAAA;IACxB,MAAM,CAAC,cAAc,CAAC,UAAU,EAAE,gBAAgB,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAA;IAErE,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/dist/router.d.ts

@@ -0,0 +1,30 @@
+import type { Context, Handler, Middleware } from './types.ts';
+export interface RouteLike {
+    method: string;
+    path: string;
+}
+export interface RouteEntry<C extends Context = Context, H = Handler<any>> extends RouteLike {
+    middlewares: Array<Middleware<any, any>>;
+    handler: H;
+}
+export type RouteMatch<C extends Context, E extends RouteLike = RouteEntry<C>> = {
+    type: 'match';
+    entry: E;
+    params: Record<string, string>;
+} | {
+    type: 'method';
+    allowed: string[];
+} | {
+    type: 'none';
+};
+/**
+ * 路径树路由器。
+ *
+ * 匹配优先级：静态段 > `:param` > `*` 通配符。
+ */
+export declare class Router<C extends Context = Context, E extends RouteLike = RouteEntry<C>> {
+    #private;
+    add(entry: E): void;
+    match(method: string, path: string): RouteMatch<C, E>;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE9D,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,UAAU,CACzB,CAAC,SAAS,OAAO,GAAG,OAAO,EAC3B,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAChB,SAAQ,SAAS;IACjB,WAAW,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;IACxC,OAAO,EAAE,CAAC,CAAA;CACX;AAED,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,OAAO,EACjB,CAAC,SAAS,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,IAEjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AA4BpB;;;;GAIG;AACH,qBAAa,MAAM,CACjB,CAAC,SAAS,OAAO,GAAG,OAAO,EAC3B,CAAC,SAAS,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC;;IAInC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IA2CnB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC;CA0DtD"}

package/dist/router.js

@@ -0,0 +1,122 @@
+import { splitPath } from "./path.js";
+function createNode() {
+    return {
+        literals: new Map(),
+        params: [],
+        wildcard: null,
+        wildcardName: '*',
+        routes: new Map(),
+    };
+}
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/**
+ * 路径树路由器。
+ *
+ * 匹配优先级：静态段 > `:param` > `*` 通配符。
+ */
+export class Router {
+    #root = createNode();
+    add(entry) {
+        if (!entry.path.startsWith('/')) {
+            throw new Error(`Route path must start with "/": ${entry.path}`);
+        }
+        const segments = splitPath(entry.path);
+        let node = this.#root;
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            if (segment.startsWith(':')) {
+                const name = segment.slice(1);
+                if (!name)
+                    throw new Error(`Invalid route parameter: ${entry.path}`);
+                let child = node.params.find((param) => param.name === name);
+                if (!child) {
+                    child = { name, node: createNode() };
+                    node.params.push(child);
+                }
+                node = child.node;
+            }
+            else if (segment.startsWith('*')) {
+                if (i !== segments.length - 1) {
+                    throw new Error(`Wildcard "*" must be the last segment: ${entry.path}`);
+                }
+                node.wildcard ??= createNode();
+                node.wildcard.wildcardName = segment.slice(1) || '*';
+                node = node.wildcard;
+            }
+            else {
+                let child = node.literals.get(segment);
+                if (!child) {
+                    child = createNode();
+                    node.literals.set(segment, child);
+                }
+                node = child;
+            }
+        }
+        if (node.routes.has(entry.method)) {
+            throw new Error(`Duplicate route: ${entry.method} ${entry.path}`);
+        }
+        node.routes.set(entry.method, entry);
+    }
+    match(method, path) {
+        const params = {};
+        const node = this.#find(this.#root, splitPath(path), 0, params);
+        if (!node)
+            return { type: 'none' };
+        let entry = node.routes.get(method);
+        if (!entry && method === 'HEAD')
+            entry = node.routes.get('GET');
+        const allowed = new Set(node.routes.keys());
+        if (allowed.has('GET'))
+            allowed.add('HEAD');
+        if (allowed.size > 0 && !allowed.has('OPTIONS'))
+            allowed.add('OPTIONS');
+        if (entry)
+            return { type: 'match', entry, params };
+        return { type: 'method', allowed: [...allowed].sort() };
+    }
+    #find(node, segments, index, params) {
+        if (index === segments.length) {
+            if (node.routes.size > 0)
+                return node;
+            if (node.wildcard && node.wildcard.routes.size > 0) {
+                params[node.wildcard.wildcardName] = '';
+                return node.wildcard;
+            }
+            return null;
+        }
+        const segment = segments[index];
+        const literal = node.literals.get(segment);
+        if (literal) {
+            const found = this.#find(literal, segments, index + 1, params);
+            if (found)
+                return found;
+        }
+        for (const param of node.params) {
+            const previous = params[param.name];
+            params[param.name] = decodeSegment(segment);
+            const found = this.#find(param.node, segments, index + 1, params);
+            if (found)
+                return found;
+            if (previous === undefined)
+                delete params[param.name];
+            else
+                params[param.name] = previous;
+        }
+        if (node.wildcard && node.wildcard.routes.size > 0) {
+            params[node.wildcard.wildcardName] = segments
+                .slice(index)
+                .map(decodeSegment)
+                .join('/');
+            return node.wildcard;
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 请求上下文。
+ *
+ * - `params` 由路由匹配填充（例如 `/users/:id` 会得到 `params.id`）
+ * - `query` 由 URL 查询串解析填充
+ * - 索引签名允许任意中间件向上下文注入数据
+ *
+ * 也可以通过声明合并来全局扩展字段：
+ *
+ * ```ts
+ * declare module '@weifuwujs/weifuwu' {
+ *   interface Context {
+ *     user: User
+ *   }
+ * }
+ * ```
+ */
+export interface Context {
+    params: Record<string, string>;
+    query: Record<string, string>;
+    [key: string]: unknown;
+}
+/** 链上的一环：`next(req, ctx)` 的类型（HTTP 的 next 返回 Response，WS 还可能是 void） */
+export type Next<In extends Context = Context, R = Response> = (req: Request, ctx: In) => R | Promise<R>;
+/** 终端处理器：请求进，响应出 */
+export type Handler<T extends Context = Context> = Next<T, Response>;
+/**
+ * 中间件。HTTP 与 WebSocket 共用同一类型：
+ *
+ * - `R` 是**注册位实例化**的链结果类型：HTTP 默认 `Response`，WebSocket 为 `Response | void`
+ * - 返回 `Response` 表示短路（HTTP 直接响应 / WS 拒绝升级）
+ * - 调用 `next(req, ctx?)` 继续，并可通过新的 `ctx` 累积类型
+ *
+ * 只在一端使用时保持默认（`R = Response`）即可；同一个实例要在 HTTP 与 WS
+ * 两处复用（如鉴权）时写 `Middleware<In, Out, Response | void>`。
+ *
+ * ```ts
+ * const auth: Middleware<Context, Context & { user: User }, Response | void> =
+ *   async (req, ctx, next) => {
+ *     const user = await verify(req)
+ *     return user
+ *       ? next(req, { ...ctx, user })
+ *       : new Response('Unauthorized', { status: 401 })
+ *   }
+ * ```
+ */
+export type Middleware<In extends Context = Context, Out extends Context = In, R = Response> = (req: Request, ctx: In, next: Next<Out, R>) => Response | R | Promise<Response | R>;
+/**
+ * 全局错误处理器。返回 `Response` 表示接管错误；
+ * 返回 `undefined`（或不返回）则使用默认行为。
+ */
+export type ErrorHandler<C extends Context = Context> = (error: unknown, req: Request, ctx: C) => Response | void | Promise<Response | void>;
+export type NotFoundHandler<C extends Context = Context> = Handler<C>;
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/** `app.mount()` 需要的路由形状（结构化：不依赖具体 API 实现） */
+export interface MountableRoute {
+    method: string;
+    path: string;
+    handler: Handler<any>;
+}
+/** `app.mount()` 需要的最小接口：`routes()`，可选 GraphQL handler */
+export interface MountableApi<Ctx extends Context = Context> {
+    routes(): MountableRoute[];
+    graphqlHandler?: () => Handler<any>;
+}
+/** `app.mount()` 选项 */
+export interface MountOptions {
+    /** 是否挂载 REST 路由，默认 true */
+    rest?: boolean;
+    /** GraphQL 端点路径；不传则不挂载 */
+    graphql?: string | false;
+}
+/**
+ * 从路径字符串中提取参数类型。
+ *
+ * ```ts
+ * PathParams<'/users/:id/posts/:postId'>
+ * // => Record<string, string> & { id: string } & { postId: string }
+ * PathParams<'/files/*'>
+ * // => Record<string, string> & { '*': string }
+ * ```
+ */
+export type PathParams<Path extends string> = Record<string, string> & ExtractParams<Path>;
+type ExtractParams<Path extends string> = string extends Path ? unknown : Path extends `${string}:${infer Rest}` ? Rest extends `${infer Name}/${infer Tail}` ? {
+    [K in Name]: string;
+} & ExtractParams<`/${Tail}`> : {
+    [K in Rest]: string;
+} : Path extends `${string}*${infer Name}` ? {
+    [K in Name extends '' ? '*' : Name]: string;
+} : unknown;
+/** 在上下文基础上叠加路由参数类型 */
+export type ContextWithParams<C extends Context, Path extends string> = C & {
+    params: PathParams<Path>;
+};
+/**
+ * 一条路由的处理链：任意个中间件 + 最后一个处理器。
+ *
+ * ```ts
+ * app.get('/users/:id', auth, (req, ctx) => json(ctx.user))
+ * ```
+ */
+export type RouteHandlers<C extends Context, Path extends string> = [
+    ...middlewares: Middleware<ContextWithParams<C, Path>, any, any>[],
+    handler: Handler<ContextWithParams<C, Path>>
+];
+/** 路由级中间件：与 {@link Middleware} 同一个类型，保留别名以兼容既有导入 */
+export type RouteMiddleware<In extends Context, Out extends Context = In> = Middleware<In, Out>;
+/** 路由注册方法（`app.get` / `app.post` / ...）的调用签名 */
+export interface RouteRegistrar<C extends Context, Prefix extends string, R> {
+    <P extends string>(path: P, handler: Handler<ContextWithParams<C, `${Prefix}${P}`>>): R;
+    <P extends string, O1 extends Context>(path: P, middleware: Middleware<ContextWithParams<C, `${Prefix}${P}`>, O1, any>, handler: Handler<O1 & ContextWithParams<C, `${Prefix}${P}`>>): R;
+    <P extends string, O1 extends Context, O2 extends Context>(path: P, middleware1: Middleware<ContextWithParams<C, `${Prefix}${P}`>, O1, any>, middleware2: Middleware<O1 & ContextWithParams<C, `${Prefix}${P}`>, O2, any>, handler: Handler<O2 & ContextWithParams<C, `${Prefix}${P}`>>): R;
+    /** 3 个及以上中间件：类型不再逐步累积，最后一个参数必须是处理器 */
+    <P extends string>(path: P, ...handlers: RouteHandlers<C, `${Prefix}${P}`>): R;
+}
+/** `app.on(method, path, ...handlers)` 的调用签名 */
+export interface OnRegistrar<C extends Context, Prefix extends string, R> {
+    <M extends string, P extends string>(method: M, path: P, handler: Handler<ContextWithParams<C, `${Prefix}${P}`>>): R;
+    <M extends string, P extends string, O1 extends Context>(method: M, path: P, middleware: Middleware<ContextWithParams<C, `${Prefix}${P}`>, O1, any>, handler: Handler<O1 & ContextWithParams<C, `${Prefix}${P}`>>): R;
+    <M extends string, P extends string, O1 extends Context, O2 extends Context>(method: M, path: P, middleware1: Middleware<ContextWithParams<C, `${Prefix}${P}`>, O1, any>, middleware2: Middleware<O1 & ContextWithParams<C, `${Prefix}${P}`>, O2, any>, handler: Handler<O2 & ContextWithParams<C, `${Prefix}${P}`>>): R;
+    <M extends string, P extends string>(method: M, path: P, ...handlers: RouteHandlers<C, `${Prefix}${P}`>): R;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/vite.d.ts

@@ -0,0 +1,21 @@
+import { reactRouter } from '@react-router/dev/vite';
+import type { UserConfig } from 'vite';
+export { reactRouter };
+export interface WeifuwuConfig extends UserConfig {
+    /** 自定义 server 入口（相对项目根目录），默认 `./app/server.ts` */
+    serverEntry?: string;
+    /** 追加需要强制打进 SSR bundle 的包 */
+    ssrNoExternal?: Array<string | RegExp>;
+}
+/**
+ * weifuwu + React Router 的 Vite 预设。
+ *
+ * 自动完成：
+ * - 注册 `reactRouter()` 插件（未手动注册时）
+ * - 把 `app/server.ts` 设为 SSR 构建入口，使 `react-router build`
+ *   产出的 `build/server/index.js` 就是 weifuwu 应用
+ * - 把 `@weifuwujs/weifuwu` 打进 SSR bundle，让
+ *   `virtual:react-router/server-build` 在构建期被解析
+ */
+export declare function defineConfig(config?: WeifuwuConfig): UserConfig;
+//# sourceMappingURL=vite.d.ts.map

package/dist/vite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAEpD,OAAO,KAAK,EAAwB,UAAU,EAAE,MAAM,MAAM,CAAA;AAE5D,OAAO,EAAE,WAAW,EAAE,CAAA;AAEtB,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6BAA6B;IAC7B,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAA;CACvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAE,aAAkB,GAAG,UAAU,CAgDnE"}

package/dist/vite.js

@@ -0,0 +1,101 @@
+import { reactRouter } from '@react-router/dev/vite';
+import { join } from 'node:path';
+export { reactRouter };
+/**
+ * weifuwu + React Router 的 Vite 预设。
+ *
+ * 自动完成：
+ * - 注册 `reactRouter()` 插件（未手动注册时）
+ * - 把 `app/server.ts` 设为 SSR 构建入口，使 `react-router build`
+ *   产出的 `build/server/index.js` 就是 weifuwu 应用
+ * - 把 `@weifuwujs/weifuwu` 打进 SSR bundle，让
+ *   `virtual:react-router/server-build` 在构建期被解析
+ */
+export function defineConfig(config = {}) {
+    const { serverEntry = './app/server.ts', ssrNoExternal = [], ...userConfig } = config;
+    const plugins = userConfig.plugins ?? [];
+    const hasReactRouter = plugins.some((plugin) => containsPlugin(plugin, 'react-router'));
+    const extraPlugins = [];
+    if (!hasTildeAlias(userConfig))
+        extraPlugins.push(tildeAppAlias());
+    if (!hasReactRouter)
+        extraPlugins.push(...reactRouter());
+    const noExternal = userConfig.ssr?.noExternal === true
+        ? true
+        : [
+            ...new Set([
+                ...normalizeNoExternal(userConfig.ssr?.noExternal),
+                '@weifuwujs/weifuwu',
+                ...ssrNoExternal,
+            ]),
+        ];
+    const environments = userConfig.environments ?? {};
+    const ssrEnvironment = environments.ssr ?? {};
+    const rollupOptions = ssrEnvironment.build?.rollupOptions ?? {};
+    return {
+        ...userConfig,
+        plugins: [...plugins, ...extraPlugins],
+        ssr: { ...userConfig.ssr, noExternal },
+        environments: {
+            ...environments,
+            ssr: {
+                ...ssrEnvironment,
+                build: {
+                    ...ssrEnvironment.build,
+                    rollupOptions: {
+                        ...rollupOptions,
+                        input: rollupOptions.input ?? serverEntry,
+                    },
+                },
+            },
+        },
+    };
+}
+function normalizeNoExternal(value) {
+    if (!value || value === true)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function containsPlugin(option, name) {
+    if (!option)
+        return false;
+    if (Array.isArray(option)) {
+        return option.some((item) => containsPlugin(item, name));
+    }
+    if (typeof option === 'object' && 'name' in option) {
+        return option.name === name;
+    }
+    return false;
+}
+/**
+ * `~/` → `<root>/app`（React Router 官方模板约定）。
+ *
+ * tsconfig `paths` 只覆盖类型检查与 build；dev 的 SSR module runner
+ * 不解析 TS paths，所以这里用 resolver 插件补齐，保证 dev/prod 一致。
+ */
+function tildeAppAlias() {
+    let root = process.cwd();
+    return {
+        name: 'weifuwu:tilde-app-alias',
+        configResolved(config) {
+            root = config.root;
+        },
+        async resolveId(source, importer) {
+            if (!source.startsWith('~/'))
+                return null;
+            return this.resolve(join(root, 'app', source.slice(2)), importer, {
+                skipSelf: true,
+            });
+        },
+    };
+}
+function hasTildeAlias(config) {
+    const alias = config.resolve?.alias;
+    if (!alias)
+        return false;
+    if (Array.isArray(alias)) {
+        return alias.some((entry) => 'find' in entry && entry.find === '~');
+    }
+    return '~' in alias;
+}
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"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"}

package/dist/websocket/accept.d.ts

@@ -0,0 +1,22 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketConnection } from './connection.ts';
+import type { WebSocketOptions } from './types.ts';
+export interface AcceptOptions extends WebSocketOptions {
+    /** 升级请求头之后已经读到的字节（交给 `ws` 处理） */
+    head?: Uint8Array;
+    /** Node 原始升级请求；`ws.handleUpgrade` 需要它完成握手 */
+    rawRequest?: IncomingMessage;
+}
+/**
+ * 校验升级请求；返回 `null` 表示可以升级，
+ * 否则返回应当写回的 HTTP 响应。
+ */
+export declare function validateUpgradeRequest(request: Request): Response | null;
+/**
+ * 完成握手并创建连接。调用前应先用 `validateUpgradeRequest` 校验。
+ *
+ * 握手 / 子协议协商 / 帧编解码由 `ws` 负责，`WebSocketConnection` 只做适配。
+ */
+export declare function acceptWebSocket(socket: Duplex, _request: Request, options?: AcceptOptions): WebSocketConnection;
+//# sourceMappingURL=accept.d.ts.map

package/dist/websocket/accept.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accept.d.ts","sourceRoot":"","sources":["../../src/websocket/accept.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,iCAAiC;IACjC,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,eAAe,CAAA;CAC7B;AAkBD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CA4BxE;AAUD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,EACjB,OAAO,GAAE,aAAkB,GAC1B,mBAAmB,CAyCrB"}

package/dist/websocket/accept.js

@@ -0,0 +1,104 @@
+import { createRequire } from 'node:module';
+import { WebSocketConnection } from "./connection.js";
+/** 默认 4 MiB，与 `WebSocketOptions.maxMessageSize` 一致 */
+const DEFAULT_MAX_MESSAGE_SIZE = 4 * 1024 * 1024;
+let wsModule;
+/**
+ * 懒加载 `ws`：根入口导出 WebSocket API，但不应该让 HTTP-only 用户
+ * 承担依赖加载；首次真正升级（`acceptWebSocket`）时才 require。
+ */
+function loadWs() {
+    wsModule ??= createRequire(import.meta.url)('ws');
+    return wsModule;
+}
+/**
+ * 校验升级请求；返回 `null` 表示可以升级，
+ * 否则返回应当写回的 HTTP 响应。
+ */
+export function validateUpgradeRequest(request) {
+    const upgrade = request.headers.get('upgrade')?.toLowerCase().trim();
+    const connection = request.headers.get('connection')?.toLowerCase() ?? '';
+    const connectionTokens = connection.split(',').map((token) => token.trim());
+    if (request.method.toUpperCase() !== 'GET') {
+        return new Response('Method Not Allowed', {
+            status: 405,
+            headers: { allow: 'GET' },
+        });
+    }
+    if (upgrade !== 'websocket' || !connectionTokens.includes('upgrade')) {
+        return new Response('Upgrade Required', {
+            status: 426,
+            headers: { upgrade: 'websocket' },
+        });
+    }
+    if (request.headers.get('sec-websocket-version') !== '13') {
+        return new Response('Unsupported WebSocket Version', {
+            status: 426,
+            headers: { 'sec-websocket-version': '13' },
+        });
+    }
+    const key = request.headers.get('sec-websocket-key');
+    if (!key || !isValidKey(key)) {
+        return new Response('Bad Request', { status: 400 });
+    }
+    return null;
+}
+function isValidKey(key) {
+    try {
+        return Buffer.from(key, 'base64').length === 16;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 完成握手并创建连接。调用前应先用 `validateUpgradeRequest` 校验。
+ *
+ * 握手 / 子协议协商 / 帧编解码由 `ws` 负责，`WebSocketConnection` 只做适配。
+ */
+export function acceptWebSocket(socket, _request, options = {}) {
+    const { rawRequest } = options;
+    if (!rawRequest) {
+        throw new Error('acceptWebSocket requires options.rawRequest (the Node IncomingMessage)');
+    }
+    const { WebSocketServer } = loadWs();
+    const server = new WebSocketServer({
+        noServer: true,
+        maxPayload: options.maxMessageSize ?? DEFAULT_MAX_MESSAGE_SIZE,
+        autoPong: options.autoPong !== false,
+        perMessageDeflate: false,
+        handleProtocols: (requested) => negotiateProtocol(requested, options.protocols),
+        // ws 运行时支持 closeTimeout，但 @types/ws 未把它写进 ServerOptions
+        closeTimeout: options.closeTimeout ?? 5000,
+    });
+    let connection;
+    server.handleUpgrade(rawRequest, socket, Buffer.from(options.head ?? new Uint8Array(0)), (ws) => {
+        connection = new WebSocketConnection(ws, {
+            protocol: ws.protocol,
+            maxMessageSize: options.maxMessageSize,
+            autoPong: options.autoPong,
+            closeTimeout: options.closeTimeout,
+            pingInterval: options.pingInterval,
+            idleTimeout: options.idleTimeout,
+        });
+    });
+    server.close();
+    if (!connection) {
+        throw new Error('WebSocket upgrade failed');
+    }
+    return connection;
+}
+/**
+ * 从客户端子协议中挑选一个服务端支持的，没有则返回 `false`（不发该响应头）。
+ * 与旧语义一致：按客户端优先级取第一个交集。
+ */
+function negotiateProtocol(requested, supported) {
+    if (!supported || supported.length === 0)
+        return false;
+    for (const protocol of requested) {
+        if (supported.includes(protocol))
+            return protocol;
+    }
+    return false;
+}
+//# sourceMappingURL=accept.js.map

package/dist/websocket/accept.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accept.js","sourceRoot":"","sources":["../../src/websocket/accept.ts"],"names":[],"mappings":"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"}