weifuwu 0.55.0 → 0.55.1

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'
 ```
 
 ### 方法面
@@ -967,6 +1019,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 +2127,7 @@ props 变化 ──────────────────────
 
 # 布局系统 (`weifuwu/layout`)
 
-纯 CSS 布局原语 + 72 个主题 Token。不绑定任何 JS 框架。
+纯 CSS 布局原语 + 82 个主题 Token。不绑定任何 JS 框架。
 
 > **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
 > 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
@@ -2121,7 +2187,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/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.1",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {