weifuwu 0.55.0 → 0.55.2

package/README.md

@@ -150,7 +150,7 @@ createApp()
 |------|---------|------|
 | `weifuwu/client` | `https://unpkg.com/weifuwu@latest/dist/client/index.js` | 客户端核心（createApp, h, 路由, 状态管理等） |
 | `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 41 个 UI 组件（Button, Card, Table, Modal 等） |
-| 组件样式 | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 72 个主题 Token + 35 个布局原语 |
+| 组件样式 | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 82 个主题 Token + 35 个布局原语 |
 | 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
 
 
@@ -179,7 +179,7 @@ createApp()
 | `weifuwu/client` | **lockScroll/trapFocus** | 滚动锁定 / 焦点陷阱工具 | — |
 | `weifuwu/client` | **popup** | 弹层 fixed 定位工具（`computeFixedPos` / `computeFixedPosRect`） | — |
 | `weifuwu/components` | **42 个组件** | Button/Table/Modal/Confirm/Toast/... + `confirm()` / `toast()` 命令式中间件 | weifuwu/client |
-| `weifuwu/layout` | **CSS 布局** | 35 个布局原语 + 72 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
+| `weifuwu/layout` | **CSS 布局** | 35 个布局原语 + 82 个主题 Token（也支持 `weifuwu/layout/style.css`） | — |
 
 ---
 
@@ -465,7 +465,7 @@ app.get('/assets/*', serveStatic('./assets', {
 
 ## postgres — PostgreSQL 客户端（自研）
 
-> **自研 PG v3 协议**（零第三方依赖）——支持 SCRAM-SHA-256 认证、扩展查询（参数化）、类型映射、事务、连接池、schema 写前校验。
+> **自研 PG v3 协议**（零第三方依赖）——支持 SCRAM-SHA-256 认证、扩展查询（参数化）、类型映射（int8 超范围自动 string 防丢精度）、事务、连接池（acquire 超时防饿死）、schema 写前校验、statement_timeout 慢查询保护。
 
 ```ts
 import { postgres } from 'weifuwu'
@@ -534,15 +534,47 @@ await ctx.sql.insert('decks', { title: 'x', status: 'INVALID' }) // → Validati
 | `ctx.sql.transaction(fn)` | 事务（回调收到 `{ query }`） |
 | `ctx.sql.register(table, schema)` | 注册表结构（写前校验） |
 | `ctx.sql.insert(table, row)` | schema 校验 + 参数化插入 |
+| `ctx.sql\`...\` 内嵌片段` | 条件 SQL 片段（嵌套过滤，参数自动重编号） |
 | `ctx.sql.close()` | 关闭连接池 |
 
+### 条件片段（嵌套过滤）
+
+```ts
+const status = req.query.status // 可能为空
+const rows = await ctx.sql`
+  SELECT * FROM orders WHERE amount > ${100}
+    ${status ? ctx.sql`AND status = ${status}` : ctx.sql``}
+`
+// 空片段内联为空，参数自动重编号——同一 SQL 无论条件多少都安全参数化
+```
+
 ### 选项
 
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `poolSize` | `number` | `10` | 连接池大小 |
+| `connection` | `string` | `DATABASE_URL` | 连接字符串 |
+| `max`（或 `poolSize`） | `number` | `10` | 连接池大小 |
 | `acquireTimeoutMs` | `number` | `30000` | 池全忙时 acquire 超时（防饿死，0=无限） |
-| `statementTimeoutMs` | `number` | `0` | 语句超时（慢查询保护，0=禁用） |
+| `statementTimeoutMs`（或 `statementTimeout`） | `number` | `0` | 语句超时（慢查询保护，0=禁用） |
+| `onQuery` | `(sql, durationMs, rowCount) => void` | — | 查询观测钩子（慢查询日志/审计） |
+
+### 幂等迁移（内置）
+
+`postgres()` 返回的中间件自带迁移跟踪（`_weifuwu_migrations` 表），模块启动时检查-执行-记录三步幂等：
+
+```ts
+const db = postgres()
+await db.migrate()        // ① 建迁移跟踪表（幂等）
+
+if (!(await db.isMigrated('users'))) {       // ② 检查是否已迁移
+  await db.sql.unsafe(`CREATE TABLE users (...)`)
+  await db.markMigrated('users')             // ③ 记录（幂等，重复调用无害）
+}
+
+app.use(db)
+```
+
+> 多副本部署时天然安全：`markMigrated` 用 `ON CONFLICT DO NOTHING`，两个实例同时迁移也不会重复执行。
 
 ### 错误映射（自动）
 
@@ -562,7 +594,7 @@ await ctx.sql.insert('decks', { title: 'x', status: 'INVALID' }) // → Validati
 
 ## redis — Redis 客户端（自研）
 
-> **自研 RESP2 协议**（零第三方依赖）——连接/重连/离线队列/管道/Pub-Sub + 消除 ioredis 高频痛点（TTL 参数顺序、JSON 手动序列化、缓存样板）。
+> **自研 RESP2 协议**（零第三方依赖）——连接/重连（断线 pending 拒绝、指数退避）/离线队列/管道/Pub-Sub（订阅断线自动重放）+ 消除 ioredis 高频痛点（TTL 参数顺序、JSON 手动序列化、缓存样板）。
 
 ```ts
 import { redis } from 'weifuwu'
@@ -588,6 +620,26 @@ app.get('/llm/:id', async (req, ctx) => {
   }, 3600)
   return Response.json(result)
 })
+
+// ④ Pub/Sub —— 发布用 ctx.redis，订阅用独立连接（回调式，断线自动重连恢复订阅）
+app.post('/events', async (req, ctx) => {
+  await ctx.redis.publish('events', JSON.stringify({ type: 'deck.created' }))
+})
+
+const sub = ctx.redis.createSubscriber()
+await sub.connect()
+await sub.subscribe('events', (channel, message) => {
+  // 收到实时消息
+})
+await sub.psubscribe('jobs:*', (channel, message) => {
+  // 模式匹配订阅
+})
+
+// ⑤ 任意命令透传 + keyPrefix 隔离
+await ctx.redis.command('LRANGE', 'list', '0', '-1')
+
+app.use(redis({ keyPrefix: 'api:' }))  // 之后所有 key 自动加前缀
+await ctx.redis.set('user', 1)         // 实际写入 'api:user'
 ```
 
 ### 方法面
@@ -939,6 +991,35 @@ const Badge: Component = () =>
   (props) => h('span', { class: `badge-${props.variant}` }, props.children)
 ```
 
+### 类型流（props 泛型 + ctx 注入）
+
+```tsx
+import type { Component } from 'weifuwu/client'
+import type { ApiInjected, RouteInjected } from 'weifuwu/client'
+
+// ① props 泛型：JSX 使用时自动类型检查（传错类型编译期报错）
+interface DeckCardProps { title: string; pages: number }
+const DeckCard: Component<DeckCardProps> = (_init, ctx) =>
+  (props) => <div>{props.title} / {props.pages} 页</div>
+// <DeckCard title="x" pages={8} />     ✓
+// <DeckCard title="x" pages="8" />     ✗ 编译期报错
+
+// ② ctx 注入声明：use(api()).use(router()) 后组件声明依赖，ctx 直接访问
+const Home: Component<{}, ApiInjected & RouteInjected> = (_init, ctx) => {
+  ctx.api.get('/users')   // ✓ 有类型
+  ctx.app.navigate('/x')  // ✓ 有类型
+  return () => <h1>Home</h1>
+}
+// 未声明的注入字段编译期报错——注入从"文档约定"变成"类型保证"
+
+createApp()
+  .use(api())                    // 注入 ctx.api
+  .use(router({ routes }))       // 注入 ctx.route / ctx.app
+  .mount('#root', Home)          // mount 时类型累积完整
+```
+
+> 各中间件的注入接口：`api()` → `ApiInjected`、`auth()` → `AuthInjected`、`ws()` → `WsInjected`、`i18n()` → `I18nInjected`、`router()` → `RouteInjected`（均可从 `weifuwu/client` 导入）。
+
 | 规则 | 说明 |
 |------|------|
 | 组件签名 | `(initProps: P, ctx: WfuiContext) => (props: P) => VNode \| null` |
@@ -967,6 +1048,20 @@ h('div', { class: 'x' }, child1, child2)
 | `h(type, props, ...children)` | hyperscript |
 | `jsx` / `jsxs` / `jsxDEV` | JSX 编译目标 |
 | `Fragment` | 片段 |
+| `Portal` / `createPortal(children, portalKey?)` | 渲染到 `document.body#__wf_portal` 独立容器（弹层/对话框，脱离父级 overflow 裁剪） |
+
+```tsx
+import { createPortal } from 'weifuwu/client'
+
+// 内容渲染到 body 下的独立容器（不在父组件的 DOM 树内）
+const Tooltip = (_init, ctx) =>
+  (props) => createPortal(
+    <div class="tooltip">{props.text}</div>
+  )
+
+// 配合 ctx.ui.selfId('name') 可从任何地方精准刷新 portal 内容
+ctx.ui.render(['name'])
+```
 
 ---
 
@@ -2061,7 +2156,7 @@ props 变化 ──────────────────────
 
 # 布局系统 (`weifuwu/layout`)
 
-纯 CSS 布局原语 + 72 个主题 Token。不绑定任何 JS 框架。
+纯 CSS 布局原语 + 82 个主题 Token。不绑定任何 JS 框架。
 
 > **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
 > 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
@@ -2121,7 +2216,7 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 | | `wf-inline-block` | display: inline-block |
 | | `wf-contents` | display: contents |
 
-## 72 个主题 Token
+## 82 个主题 Token
 
 ```css
 /* 品牌色 */

package/dist/client/app.d.ts

@@ -14,11 +14,11 @@
  *   并设置 childCtx.ui._selfId = 组件 ID
  *   render() 无参时从 this._selfId 取当前组件 ID
  */
-import type { WfuiContext, AppMiddleware } from './types.ts';
+import type { AppMiddleware } from './types.ts';
 import type { Component } from './vnode.ts';
-export declare function createApp(): {
-    readonly ctx: WfuiContext;
-    use(mw: AppMiddleware): /*elided*/ any;
-    mount(rootSelector: string, RootComponent: Component): Promise<void>;
-    destroy(): void;
-};
+/** 应用句柄：use() 链式累积中间件注入的 ctx 类型，mount() 时组件拿到完整注入 */
+export interface App<C extends object = {}> {
+    use<I extends object, O extends object>(mw: AppMiddleware<I, O>): App<C & O>;
+    mount(rootSelector: string, root: Component<any, C>): Promise<void>;
+}
+export declare function createApp<C extends object = {}>(): App<C>;

package/dist/client/i18n.d.ts

@@ -24,4 +24,8 @@ export interface I18nState {
     setLocale: (lang: string) => void;
     components: Record<string, Record<string, string>>;
 }
-export declare function i18n(opts?: I18nOptions): AppMiddleware;
+/** i18n 中间件注入到 ctx 的字段 */
+export interface I18nInjected {
+    i18n: I18nState;
+}
+export declare function i18n(opts?: I18nOptions): AppMiddleware<{}, I18nInjected>;

package/dist/client/index.d.ts

@@ -18,19 +18,22 @@
 export { h, jsx, jsxs, jsxDEV, Fragment, Portal, createPortal } from './vnode.ts';
 export type { VNode, VNodeType, Component } from './vnode.ts';
 export { createApp } from './app.ts';
+export type { App } from './app.ts';
 export { router, RouteView } from './router.ts';
+export type { RouteInjected } from './router.ts';
 export { ws } from './middleware/ws.ts';
+export type { WsClient, WsInjected } from './middleware/ws.ts';
 export { api } from './middleware/api.ts';
 export { auth } from './middleware/auth.ts';
-export type { ApiClient, ApiOptions, ApiRequestOptions } from './middleware/api.ts';
+export type { ApiClient, ApiOptions, ApiRequestOptions, ApiInjected } from './middleware/api.ts';
 export { ApiError } from './middleware/api.ts';
-export type { AuthClient, AuthOptions } from './middleware/auth.ts';
+export type { AuthClient, AuthOptions, AuthInjected } from './middleware/auth.ts';
 export { extendCtx } from './types.ts';
 export type { WfuiContext, AppMiddleware, RouteDef } from './types.ts';
 export { ErrorBoundary } from './error-boundary.ts';
 export type { ErrorBoundaryProps } from './error-boundary.ts';
 export { i18n } from './i18n.ts';
-export type { I18nOptions, I18nState } from './i18n.ts';
+export type { I18nOptions, I18nState, I18nInjected } from './i18n.ts';
 export { lockScroll, unlockScroll } from './scroll-lock.ts';
 export { trapFocus } from './focus-trap.ts';
 export { computeFixedPos } from './popup.ts';

package/dist/client/middleware/api.d.ts

@@ -61,7 +61,11 @@ export interface ApiRequestOptions {
  * await ctx.api.delete('/users/1')
  * ```
  */
-export declare function api(options?: ApiOptions): AppMiddleware;
+/** api 中间件注入到 ctx 的字段 */
+export interface ApiInjected {
+    api: ApiClient;
+}
+export declare function api(options?: ApiOptions): AppMiddleware<{}, ApiInjected>;
 /**
  * API 错误 — 包含 HTTP 状态码和响应文本。
  *

package/dist/client/middleware/auth.d.ts

@@ -21,4 +21,8 @@ export interface AuthClient {
     setUser: (user: any) => void;
     refresh: () => Promise<boolean>;
 }
-export declare function auth(options?: AuthOptions): AppMiddleware;
+/** auth 中间件注入到 ctx 的字段 */
+export interface AuthInjected {
+    auth: AuthClient;
+}
+export declare function auth(options?: AuthOptions): AppMiddleware<{}, AuthInjected>;

package/dist/client/middleware/ws.d.ts

@@ -12,4 +12,14 @@ export interface WsOptions {
     pingInterval?: number;
     pingTimeout?: number;
 }
-export declare function ws(options?: WsOptions): AppMiddleware;
+/** ws 中间件注入到 ctx 的字段 */
+/** ws 中间件注入的客户端形状（与 WfuiContext.ws 一致） */
+export interface WsClient {
+    send: (msg: unknown) => void;
+    onMessage: (fn: (data: unknown) => void) => () => void;
+    isConnected: boolean;
+}
+export interface WsInjected {
+    ws: WsClient;
+}
+export declare function ws(options?: WsOptions): AppMiddleware<{}, WsInjected>;

package/dist/client/router.d.ts

@@ -9,5 +9,18 @@ export interface RouterOptions {
     routes: RouteDef[];
     notFound?: (props: any, ctx: WfuiContext) => any;
 }
-export declare function router(opts: RouterOptions): AppMiddleware;
+/** router 中间件注入到 ctx 的字段 */
+export interface RouteInjected {
+    route: {
+        path: string;
+        params: Record<string, string>;
+        query: Record<string, string>;
+        title?: string;
+    };
+    /** 编程式导航 */
+    app: {
+        navigate: (path: string) => void;
+    };
+}
+export declare function router(opts: RouterOptions): AppMiddleware<{}, RouteInjected>;
 export declare function RouteView(_props: {}, ctx: WfuiContext): () => any;

package/dist/client/type-flow.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 类型流测试（编译期验证）——组件 props 泛型 + ctx 注入链式累积。
+ *
+ * 运行方式：这些断言是类型层面的，由 tsc --noEmit 保证。
+ * 运行时测试仅验证 createApp().use() 链式调用不抛错。
+ */
+export {};

package/dist/client/types.d.ts

@@ -81,7 +81,12 @@ export interface WfuiContext {
     };
 }
 /** 中间件签名 */
-export type AppMiddleware = (ctx: WfuiContext) => WfuiContext;
+/**
+ * 前端中间件：输入 ctx 需要 I，输出 ctx 注入 O（链式累积，createApp().use() 类型自动合并）
+ *   api()   → AppMiddleware<{}, ApiInjected>   注入 ctx.api
+ *   router()→ AppMiddleware<{}, RouteInjected> 注入 ctx.route / ctx.app
+ */
+export type AppMiddleware<I extends object = {}, O extends object = I> = (ctx: WfuiContext & I) => (WfuiContext & O) | Promise<WfuiContext & O>;
 /** 路由定义 */
 export interface RouteDef {
     path: string;

package/dist/client/vnode.d.ts

@@ -30,7 +30,11 @@ export interface VNode {
     /** 组件 mount/render 时的 ctx 版本号（供三态 skip 判定） */
     _ctxVersion?: number;
 }
-export type Component<P = {}> = (initProps: P, ctx: WfuiContext) => ((props: P) => VNode | null) | null;
+/**
+ * 两阶段组件：外层 = mount（一次），内层 = render（每次 dirty/props 变化）。
+ * P = props 类型（JSX 自动推断），C = 组件依赖的 ctx 注入（如 ApiInjected & RouteInjected）
+ */
+export type Component<P = {}, C extends object = {}> = (initProps: P, ctx: WfuiContext & C) => ((props: P) => VNode | null) | null;
 export declare const Fragment: unique symbol;
 /** Portal — 将子 VNode 渲染到 document.body 下的独立容器 */
 export declare const Portal: unique symbol;

package/dist/index.js

@@ -2175,7 +2175,10 @@ function postgres(options) {
     user: decodeURIComponent(u.username),
     password: decodeURIComponent(u.password),
     database: u.pathname.replace(/^\//, ""),
-    poolSize: opts.max ?? 10
+    poolSize: opts.max ?? opts.poolSize ?? 10,
+    acquireTimeoutMs: opts.acquireTimeoutMs,
+    statementTimeoutMs: opts.statementTimeoutMs ?? opts.statementTimeout,
+    onQuery: opts.onQuery
   });
   const sql = makeSql(pool);
   const mw = ((req, ctx, next) => {

package/dist/postgres/types.d.ts

@@ -24,18 +24,26 @@ export interface PostgresInjected {
     sql: SqlClient;
 }
 export interface PostgresOptions {
+    /** 连接字符串（默认 DATABASE_URL） */
     connection?: string;
-    signal?: AbortSignal;
-    closeTimeout?: number;
     /** 池大小（连接数）。默认 10。 */
     max?: number;
+    /** 池全忙时 acquire 超时 ms（防饿死）。默认 30_000。0 = 无限。 */
+    acquireTimeoutMs?: number;
+    /** 语句超时 ms（慢查询保护，会话级 SET statement_timeout）。默认 0 = 禁用。 */
+    statementTimeoutMs?: number;
+    /** 查询观测钩子（慢查询日志/审计） */
+    onQuery?: (query: string, durationMs: number, rowCount: number) => void;
+    /** postgres.js 兼容名（= max） */
+    poolSize?: number;
+    /** postgres.js 兼容名（= statementTimeoutMs） */
+    statementTimeout?: number;
+    /** 连接超时 ms。默认 10_000。 */
+    connect_timeout?: number;
+    signal?: AbortSignal;
+    closeTimeout?: number;
     ssl?: boolean | Record<string, unknown>;
     idle_timeout?: number;
-    connect_timeout?: number;
-    /** 兼容保留（自研客户端暂以连接池替代 statement_timeout 注入） */
-    statementTimeout?: number;
-    /** Called after every query completes. */
-    onQuery?: (query: string, durationMs: number, rowCount: number) => void;
 }
 export interface PostgresClient extends Middleware<Context, Context & PostgresInjected>, Closeable {
     sql: SqlClient;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.55.0",
+  "version": "0.55.2",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {