weifuwu 0.54.1 → 0.55.1

package/README.md

@@ -17,7 +17,7 @@ npm install weifuwu
 
 ## 设计理念
 
-**零运行时依赖** — 前端无 npm 运行时依赖，不引入 Virtual DOM 库、rxjs、immer 等重型依赖。esbuild 编译 TSX 的结果即可直接运行。
+**零运行时依赖** — 前端无 npm 运行时依赖（自研 VDOM，不引入 Virtual DOM 库、rxjs、immer 等）。后端仅依赖 `graphql` + `ws`（语言/协议本身）——**数据库客户端（PostgreSQL/Redis 协议）、GraphQL schema 工具全部自研**。esbuild 编译 TSX 的结果即可直接运行。
 
 **两阶段组件模型** — 组件 = `(initProps, ctx) => (props) => VNode`。外层函数只执行一次（mount），内层函数每次状态/props 变化时执行（render）。无 class、无 `this`、无 Hook。
 
@@ -25,6 +25,8 @@ npm install weifuwu
 
 **中间件注入一切** — 后端和前端共用同一理念：中间件向 `ctx` 注入能力（`ctx.sql` / `ctx.redis` / `ctx.api` / `ctx.auth` / `ctx.i18n` 等），Handler/组件从 `ctx` 读取。
 
+**自研数据层** — `ctx.sql`（PG v3 协议）与 `ctx.redis`（RESP2 协议）为**自研客户端**：确定性输出、行为可预测、统一错误模型。jsonb 自动解码、TTL 安全 API、schema 写前校验——高频痛点（双重编码/parseRow 样板/`'EX'` 参数顺序）从根上消除。
+
 **SSR + 动态编译** — 后端 `ctx.ui.js()` 用 esbuild 实时编译 TSX，开发时改代码即刷即用，零构建步骤。
 
 ---
@@ -148,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 |
 
 
@@ -162,8 +164,8 @@ createApp()
 | `weifuwu` | **serve** | HTTP 服务器 | Router |
 | `weifuwu` | **cors** | CORS 跨域中间件 | Router |
 | `weifuwu` | **serveStatic** | 静态文件服务（ETag/304/目录索引） | Router |
-| `weifuwu` | **postgres** | PostgreSQL 连接池 → `ctx.sql` | Router, DATABASE_URL |
-| `weifuwu` | **redis** | Redis 客户端 → `ctx.redis` | Router, REDIS_URL |
+| `weifuwu` | **postgres** | PostgreSQL 客户端（自研 PG v3 协议）→ `ctx.sql` | Router, DATABASE_URL |
+| `weifuwu` | **redis** | Redis 客户端（自研 RESP2 协议）→ `ctx.redis` | Router, REDIS_URL |
 | `weifuwu` | **ui** | SSR 渲染 + esbuild JS/CSS 动态编译 → `ctx.ui` | Router |
 | `weifuwu` | **graphql** | GraphQL 端点（支持 GraphiQL） | Router |
 | `weifuwu` | **createMiddleware** | 类型安全中间件工厂 | — |
@@ -177,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`） | — |
 
 ---
 
@@ -461,82 +463,204 @@ app.get('/assets/*', serveStatic('./assets', {
 
 ---
 
-## postgres — PostgreSQL 客户端
+## postgres — PostgreSQL 客户端（自研）
+
+> **自研 PG v3 协议**（零第三方依赖）——支持 SCRAM-SHA-256 认证、扩展查询（参数化）、类型映射（int8 超范围自动 string 防丢精度）、事务、连接池（acquire 超时防饿死）、schema 写前校验、statement_timeout 慢查询保护。
 
 ```ts
-import { postgres, MIGRATIONS_TABLE } from 'weifuwu'
+import { postgres } from 'weifuwu'
 
-// 注入 ctx.sql — postgres.js 客户端
+// 注入 ctx.sql（懒连接池）
 app.use(postgres())
 
-// 使用 ctx.sql
+// ① tagged template —— 插值自动参数化（防注入）
 app.get('/users', async (req, ctx) => {
-  const users = await ctx.sql`SELECT * FROM users WHERE active = ${true}`
+  const users = await ctx.sql`SELECT * FROM users WHERE id = ${ctx.params.id}`
   return Response.json(users)
 })
 
-// 事务
+// ② jsonb 对象直传——自动序列化，不再有双重编码/parseRow 样板
+app.post('/decks', async (req, ctx) => {
+  const deck = await req.json()
+  await ctx.sql`INSERT INTO decks (title, deck_json) VALUES (${deck.title}, ${deck})`
+  // 读回来自动是对象：rows[0].deck_json === { slides: [...] }（不是字符串）
+})
+
+// ③ 事务（postgres.js 兼容 begin）
 app.post('/transfer', async (req, ctx) => {
-  const result = await ctx.sql.begin(async sql => {
+  await ctx.sql.begin(async sql => {
     await sql`UPDATE accounts SET balance = balance - 100 WHERE id = 1`
     await sql`UPDATE accounts SET balance = balance + 100 WHERE id = 2`
   })
-  return Response.json({ ok: true })
 })
 ```
 
+### 类型映射（自动）
+
+| 数据库类型 | 返回 JS 类型 |
+|-----------|-------------|
+| json / jsonb | `object`（自动 JSON.parse） |
+| int2 / int4 / int8（安全范围内） | `number` |
+| **int8（超出安全范围）** | **`string`**（防静默丢精度，金额/ID 关键） |
+| float / numeric | `number` |
+| boolean | `boolean` |
+| text / varchar / uuid / date | `string` |
+| NULL | `null` |
+
+### 类型层（查询泛型 + schema 写前校验）
+
+```ts
+// ① 查询结果泛型（编译期类型，无需手写 interface + 断言）
+interface Deck { id: number; title: string; deck_json: { slides: unknown[] } }
+const decks = await ctx.sql.query<Deck>('SELECT id, title, deck_json FROM decks')
+
+// ② schema 注册 → insert 写前校验（脏数据源头拦截）
+ctx.sql.register('decks', {
+  title: { type: 'text', required: true },
+  status: { type: 'enum', values: ['outline', 'ready'] },
+  deck_json: { type: 'jsonb' },
+})
+await ctx.sql.insert('decks', { title: 'x', status: 'INVALID' }) // → ValidationError
+```
+
+### 方法面
+
+| 方法 | 说明 |
+|------|------|
+| `ctx.sql\`...\`` | tagged template → 参数化查询（插值=参数，表名需硬编码） |
+| `ctx.sql.query<T>(sql, params?)` | 参数化查询 + 泛型 |
+| `ctx.sql.unsafe(sql, params?)` | 原生 SQL（DDL / 动态表名） |
+| `ctx.sql.begin(fn)` | 事务（回调收到 tagged template sql） |
+| `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 无论条件多少都安全参数化
+```
+
+### 选项
+
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `url` | `string` | `DATABASE_URL` 环境变量 | 连接字符串 |
-| `max` | `number` | `10` | 连接池大小 |
-| `idleTimeout` | `number` | `30` | 空闲连接超时（秒）|
-| `maxLifetime` | `number` | `3600` | 连接最大生存时间（秒）|
+| `connection` | `string` | `DATABASE_URL` | 连接字符串 |
+| `max`（或 `poolSize`） | `number` | `10` | 连接池大小 |
+| `acquireTimeoutMs` | `number` | `30000` | 池全忙时 acquire 超时（防饿死，0=无限） |
+| `statementTimeoutMs`（或 `statementTimeout`） | `number` | `0` | 语句超时（慢查询保护，0=禁用） |
+| `onQuery` | `(sql, durationMs, rowCount) => void` | — | 查询观测钩子（慢查询日志/审计） |
 
-| ctx 注入 | 类型 | 说明 |
-|----------|------|------|
-| `ctx.sql` | `postgres.Sql` | postgres.js 客户端（模板标签）|
-| `ctx.sql.close()` | `() => Promise<void>` | 关闭连接池 |
+### 幂等迁移（内置）
+
+`postgres()` 返回的中间件自带迁移跟踪（`_weifuwu_migrations` 表），模块启动时检查-执行-记录三步幂等：
 
 ```ts
-// 关闭
-const pg = postgres()
-app.use(pg)
-// 关闭时框架自动调用 pg.close()
+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`，两个实例同时迁移也不会重复执行。
+
+### 错误映射（自动）
+
+`ctx.sql` 查询错误自动映射为 `HttpError`，业务无需手写 catch：
+
+| 错误码 | 含义 | HTTP |
+|--------|------|------|
+| `23505` | 唯一约束冲突 | **409** |
+| `23503` / `23502` / `23514` | 外键 / 非空 / 检查约束 | **400** |
+| `22P02` / `22003` | 类型 / 数值错误 | **400** |
+
+> 未映射的错误码原样抛出（带 `code` 属性，如 `42P01` 表不存在）。
+
+> **裁剪声明**：逻辑复制 / 大对象 / 显式游标 / 二进制 COPY 不支持（明确抛 `ProtocolError('unsupported')`，而非静默出错）。
+
 ---
 
-## redis — Redis 客户端
+## redis — Redis 客户端（自研）
+
+> **自研 RESP2 协议**（零第三方依赖）——连接/重连（断线 pending 拒绝、指数退避）/离线队列/管道/Pub-Sub（订阅断线自动重放）+ 消除 ioredis 高频痛点（TTL 参数顺序、JSON 手动序列化、缓存样板）。
 
 ```ts
 import { redis } from 'weifuwu'
 
 app.use(redis())
 
+// ① TTL 安全 —— 直接传秒，不会写错
+app.post('/cache/:key', async (req, ctx) => {
+  const { value } = await req.json()
+  await ctx.redis.set(ctx.params.key, value, 3600)  // ioredis 要 set(k, v, 'EX', 3600)
+})
+
+// ② JSON 零样板 —— 自动序列化（AI 缓存场景）
 app.get('/cache/:key', async (req, ctx) => {
-  const val = await ctx.redis.get(ctx.params.key)
-  if (!val) return Response.json({ miss: true })
-  return Response.json({ value: val })
+  const val = await ctx.redis.jsonGet(ctx.params.key)  // 自动 JSON.parse
+  return Response.json(val ?? { miss: true })
 })
 
-app.post('/cache/:key', async (req, ctx) => {
-  const { value } = await req.json()
-  await ctx.redis.set(ctx.params.key, JSON.stringify(value), 'EX', 3600)
-  return Response.json({ ok: true })
+// ③ 缓存便捷 —— 读-算-写一体，null 不缓存（防穿透）
+app.get('/llm/:id', async (req, ctx) => {
+  const result = await ctx.redis.cache(`llm:${ctx.params.id}`, async () => {
+    return await generateLLM(ctx.params.id)  // miss 才执行
+  }, 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'
 ```
 
+### 方法面
+
+| 方法 | 说明 |
+|------|------|
+| `get / set(key, val, ttl?) / del / incr / expire / ttl` | 基础命令（set 直接传秒） |
+| `jsonGet / jsonSet(key, val, ttl?)` | JSON 自动序列化 |
+| `cache(key, fn, ttl)` | 缓存读-算-写（null 不缓存防穿透） |
+| `publish(channel, msg)` | Pub-Sub 发布 |
+| `createSubscriber()` | 独立订阅连接（`subscribe`/`psubscribe` 回调式） |
+| `command(name, ...args)` | 底层命令透传 |
+| `close()` | 关闭连接池 |
+
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `url` | `string` | `REDIS_URL` 环境变量 | 连接字符串 |
-| `options` | `RedisOptions` | — | ioredis 配置选项 |
-
-| ctx 注入 | 类型 | 说明 |
-|----------|------|------|
-| `ctx.redis` | `ioredis.Redis` | ioredis 实例 |
-| `ctx.redis.close()` | `() => Promise<void>` | 关闭连接 |
+| `poolSize` | `number` | `5` | 连接池大小 |
+| `keyPrefix` | `string` | `''` | 所有 key 自动加前缀（多应用隔离） |
 
-支持全部 ioredis API：`get`, `set`, `del`, `hget`, `hset`, `lpush`, `publish` 等。
+> **裁剪声明**：集群（MOVED 路由）/ 哨兵 / 自动管道不支持（standalone 优先）。
 
 ---
 
@@ -594,6 +718,8 @@ app.get('/style.css', (req, ctx) => ctx.ui.css('weifuwu/components/style.css'))
 
 ## graphql — GraphQL 端点
 
+> **SDL + resolvers 绑定为自研实现**（`makeExecutableSchema`，56 行替代 @graphql-tools/schema）——支持根类型与嵌套类型字段 resolver、默认属性查找。
+
 ```ts
 import type { GraphQLHandler } from 'weifuwu'
 
@@ -893,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'])
+```
 
 ---
 
@@ -1987,7 +2127,7 @@ props 变化 ──────────────────────
 
 # 布局系统 (`weifuwu/layout`)
 
-纯 CSS 布局原语 + 72 个主题 Token。不绑定任何 JS 框架。
+纯 CSS 布局原语 + 82 个主题 Token。不绑定任何 JS 框架。
 
 > **全栈 weifuwu 项目**：`weifuwu/components/style.css` 已包含布局系统，一条 import 就够了，无需单独引用本页。
 > 本页仅适用于**非 weifuwu 项目**或**只需 CSS 布局**的场景。
@@ -2047,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/db/errors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * weifuwu/db — 统一错误模型
+ *
+ * 自研 postgres/redis 客户端共享的错误类型体系。
+ * 目标：错误语义统一 → 业务层 catch 可编程（按 kind/code 决策）。
+ *
+ *   kind:          connection | protocol | timeout | validation | retryable
+ *   code:          PG 错误码（如 23505 唯一冲突）或协议码
+ */
+export type DbErrorKind = 'connection' | 'protocol' | 'timeout' | 'validation' | 'retryable';
+export declare class DbError extends Error {
+    readonly kind: DbErrorKind;
+    readonly code?: string;
+    readonly cause?: unknown;
+    constructor(kind: DbErrorKind, message: string, options?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+/** 明确不支持的协议能力（诚实裁剪）：COPY 二进制、逻辑复制、集群、哨兵等 */
+export declare class ProtocolError extends DbError {
+    constructor(feature: string, message?: string);
+}
+/** 连接失败（含重连尝试次数） */
+export declare class ConnectionError extends DbError {
+    readonly attempts: number;
+    constructor(message: string, attempts?: number, cause?: unknown);
+}
+/** 可重试错误：序列化失败/死锁（PG 40P01/40001）等 */
+export declare class RetryableError extends DbError {
+    constructor(message: string, code?: string, cause?: unknown);
+}
+/** 超时：statement_timeout / connect_timeout / idle 等 */
+export declare class TimeoutError extends DbError {
+    readonly operation: string;
+    readonly ms: number;
+    constructor(operation: string, ms: number);
+}
+/** 写前校验失败（schema 注册 → 脏数据拦截） */
+export declare class ValidationError extends DbError {
+    constructor(message: string);
+}
+/** 判断错误是否可安全重试（事务层用） */
+export declare function isRetryable(err: unknown): boolean;

package/dist/db/postgres/connection.d.ts

@@ -0,0 +1,64 @@
+/**
+ * weifuwu/db/postgres — PostgreSQL 连接（v3 协议）
+ *
+ * 连接流程: startup → 认证（SCRAM-SHA-256 / md5 / cleartext）→ 参数/就绪
+ * 查询流程: Query(Q) → RowDescription/DataRow/CommandComplete → ReadyForQuery
+ *
+ * 认证支持:
+ *   R=0    OK
+ *   R=3    cleartext
+ *   R=5    md5
+ *   R=10/11/12  SCRAM-SHA-256（PG15+ 默认）
+ */
+export interface PgConnectionOptions {
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+    /** 连接超时 ms。默认 10_000。 */
+    connectTimeoutMs?: number;
+    /** 语句超时 ms（慢查询保护，会话级 SET statement_timeout）。默认 0 = 禁用。 */
+    statementTimeoutMs?: number;
+}
+export interface Row {
+    [col: string]: unknown;
+}
+export declare class PgConnection {
+    private opts;
+    private timeoutSet;
+    private awaitingReady;
+    private pendingErrorZ;
+    private socket;
+    private stream;
+    private status;
+    private waiters;
+    constructor(options?: PgConnectionOptions);
+    get connected(): boolean;
+    connect(): Promise<void>;
+    private onReady;
+    private onAuthFail;
+    private expectingAuth;
+    private authStage;
+    private authCtx;
+    private prepared;
+    private stmtSeq;
+    private currentQuery;
+    private onData;
+    private handle;
+    /** SCRAM client-final 消息 */
+    private scramFinal;
+    private scramServerSignature;
+    /** 事务：BEGIN → fn(tx) → COMMIT；fn 抛错 → ROLLBACK（回滚失败吞掉，保留原始错误） */
+    transaction<T>(fn: (tx: {
+        query: (sql: string, params?: (string | number | boolean | object | null)[]) => Promise<Row[]>;
+    }) => Promise<T>): Promise<T>;
+    /** 查询：无参数走简单协议（Q），有参数走扩展查询（Parse/Bind/Execute/Sync） */
+    query(sql: string, params?: (string | number | boolean | object | null)[]): Promise<Row[]>;
+    private send;
+    private notifyIdle;
+    /** 等待连接空闲（事务/多语句流程用） */
+    waitIdle(): Promise<void>;
+    /** 终止连接 */
+    close(): Promise<void>;
+}

package/dist/db/postgres/pool.d.ts

@@ -0,0 +1,76 @@
+/**
+ * weifuwu/db/postgres — PostgreSQL 连接池（借贷模型）
+ *
+ * 连接空闲队列 + 等待者队列：
+ *   query  → acquire（空闲连接 or 等待）→ 执行 → release
+ *   事务   → acquire 单个连接执行整个 BEGIN→fn→COMMIT/ROLLBACK
+ *
+ * 解决 PgConnection 单连接串行（一个 currentQuery）的限制：
+ * 并发查询路由到不同连接，全忙时排队等待而非 reject。
+ */
+import { type PgConnectionOptions, type Row } from './connection.ts';
+import { type Schema } from './schema.ts';
+export interface PgPoolOptions extends PgConnectionOptions {
+    /** 池大小（连接数）。默认 5。 */
+    poolSize?: number;
+    /** acquire 超时 ms（池全忙时等待上限，防饿死）。默认 30_000。0 = 无限。 */
+    acquireTimeoutMs?: number;
+    /** 查询观测钩子（慢查询日志/审计） */
+    onQuery?: (sql: string, durationMs: number, rowCount: number) => void;
+}
+type QueryParams = (string | number | boolean | object | null)[];
+export declare class PgPool {
+    private all;
+    private available;
+    private waiters;
+    private closed;
+    private opts;
+    private initPromise;
+    private schemas;
+    /** 懒连接：构造不连接，ensure() 首次初始化（中间件注入场景） */
+    constructor(options?: PgPoolOptions);
+    static create(options?: PgPoolOptions): Promise<PgPool>;
+    private readyPromise;
+    private ensure;
+    private init;
+    /** 获取一个空闲连接（全忙则排队等待） */
+    private acquire;
+    private release;
+    /** 连接可用事件统一入口：优先唤醒等待者，否则回空闲池（release 与 replenish 共用） */
+    private dispatchAvailable;
+    /** 坏连接剔除后异步重建（池容量保持）——就绪后走统一分发（唤醒 waiter） */
+    private replenish;
+    query<T = Row>(sql: string, params?: QueryParams): Promise<T[]>;
+    /** 注册表结构（元数据闭环：校验/类型推断的起点） */
+    register(table: string, schema: Schema): void;
+    /** 写前校验 + 参数化插入（schema 驱动，脏数据源头拦截） */
+    insert<T = Row>(table: string, row: Record<string, unknown>): Promise<T[]>;
+    /**
+     * tagged template: sql\`SELECT * FROM t WHERE id = \${id}\`
+     * 插值 = 参数（postgres.js 语义，防注入）；表名必须硬编码（插值会被当参数）。
+     * 对象插值自动 JSON.stringify → jsonb。
+     */
+    tag(strings: TemplateStringsArray, ...values: unknown[]): Promise<Row[]>;
+    /** postgres.js 兼容事务 API: begin(fn)——fn 收到 tagged template 事务 sql */
+    begin<T>(fn: (txSql: TaggedSql) => Promise<T>): Promise<T>;
+    /** 片段：可嵌套的 SQL 片段（postgres.js fragment 语义，条件过滤模式） */
+    frag(strings: TemplateStringsArray, ...values: unknown[]): SqlFragment;
+    /** 原生 SQL（DDL / 动态表名场景）；$1 占位符 + 参数数组 */
+    unsafe(sql: string, params?: QueryParams): Promise<Row[]>;
+    /** 事务：固定在单个连接上执行整个 BEGIN→fn→COMMIT/ROLLBACK */
+    transaction<T>(fn: (tx: {
+        query: (sql: string, params?: QueryParams) => Promise<Row[]>;
+    }) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    get size(): number;
+}
+/** 片段对象：嵌套 SQL 片段（内部含已解析的 sql + params） */
+export interface SqlFragment {
+    __fragment: {
+        sql: string;
+        params: QueryParams;
+    };
+}
+/** tagged template 事务 sql（begin 回调参数） */
+export type TaggedSql = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<Row[]>;
+export {};

package/dist/db/postgres/protocol.d.ts

@@ -0,0 +1,71 @@
+/**
+ * weifuwu/db/postgres — PostgreSQL v3 协议消息编解码
+ *
+ * 消息帧: type(1) + length(4, 含自身) + payload
+ * StartupMessage 特殊: length(4) + version(4) + 参数(键\0值\0...\0)
+ *
+ * 响应解析辅助: authCode / parseRowDescription / parseDataRow / readyStatus / parseErrorFields
+ */
+/** 客户端消息类型 */
+export type ClientMessageType = 'Q' | 'P' | 'B' | 'E' | 'S' | 'X' | 'p' | 'd' | 'H' | 'C' | 'D' | 'c' | 'f';
+/** 解析后的消息 */
+export interface Message {
+    type: string;
+    payload: Uint8Array;
+}
+/** 编码消息帧: type + length(4) + payload */
+export declare function encodeMessage(type: string, payload: Uint8Array): Uint8Array;
+/** StartupMessage: length(4) + version(4=196608) + 参数键值对 + \0 */
+export declare function startupMessage(params: Record<string, string>): Uint8Array;
+/** 简单查询消息: Q + SQL + \0 终止符 */
+export declare function queryMessage(sql: string): Uint8Array;
+/** Parse: P + statementName\0 + query\0 + paramTypeCount(2) + OIDs */
+export declare function parseMessage(name: string, sql: string, paramTypes?: number[]): Uint8Array;
+/** Bind: B + portal\0 + statement\0 + fmtCount + formats + paramCount + params + resultFmtCount */
+export declare function bindMessage(statement: string, params: (string | Uint8Array | null)[], paramFormats?: number[]): Uint8Array;
+/** Execute: E + portal\0 + maxRows(4) */
+export declare function executeMessage(portal?: string, maxRows?: number): Uint8Array;
+/** Sync / Terminate / PasswordMessage */
+export declare function syncMessage(): Uint8Array;
+/** Flush: 强制服务器处理已缓冲的扩展查询消息（Parse/Bind/Execute 需 Flush 或 Sync 才执行） */
+export declare function flushMessage(): Uint8Array;
+/** Describe: D + 目标类型(S/P) + name\0——服务器返回 ParameterDescription(t) / RowDescription(T) */
+export declare function describeMessage(kind: 'S' | 'P', name?: string): Uint8Array;
+export declare function terminateMessage(): Uint8Array;
+export declare function passwordMessage(password: string): Uint8Array;
+/** 增量消息流解析：零拷贝（buffer + offset 指针），喂入任意分片 */
+export declare class MessageStream {
+    private buf;
+    private off;
+    push(chunk: Uint8Array): Message[];
+    /** 追加分片：已消费部分先行压缩（一次拷贝），避免 O(n²) 累积 */
+    private append;
+    private compact;
+    /** 尝试读一条完整消息；不完整返回 null（不消费） */
+    private tryRead;
+}
+/** 便捷：解析 buffer 中所有完整消息 */
+export declare function parseMessageStream(data: Uint8Array): Message[];
+/** Authentication (R) 的认证码 */
+export declare function authCode(msg: Message): number;
+export interface ColumnInfo {
+    name: string;
+    typeOid: number;
+    typeLen: number;
+}
+/** RowDescription (T): 列信息 */
+export declare function parseRowDescription(payload: Uint8Array): ColumnInfo[];
+/** DataRow (D): 值列表（null 为 null，其余为文本字节） */
+export declare function parseDataRow(payload: Uint8Array): (string | null)[];
+/** ReadyForQuery (Z) 状态 */
+export declare function readyStatus(payload: Uint8Array): 'idle' | 'tx' | 'error';
+export interface ErrorFields {
+    severity?: string;
+    code?: string;
+    message?: string;
+    detail?: string;
+    hint?: string;
+    position?: string;
+}
+/** ErrorResponse (E) 字段 */
+export declare function parseErrorFields(payload: Uint8Array): ErrorFields;

package/dist/db/postgres/schema.d.ts

@@ -0,0 +1,19 @@
+/**
+ * weifuwu/db/postgres — Schema 注册与写前校验
+ *
+ * 注册表结构后，insert 在写入前校验字段类型/必填/枚举——脏数据在源头拦截。
+ * 这是元数据闭环的第一环（迁移/类型推断/缓存失效共享 schema 的起点）。
+ */
+export type ColumnType = 'text' | 'int' | 'jsonb' | 'enum';
+export interface ColumnDef {
+    type: ColumnType;
+    /** 必填（INSERT 时缺失报错） */
+    required?: boolean;
+    /** enum 类型允许的值 */
+    values?: string[];
+}
+export type Schema = Record<string, ColumnDef>;
+/** 校验单值；失败抛 ValidationError */
+export declare function validateValue(def: ColumnDef, value: unknown, column: string): void;
+/** 校验整个 row（必填 + 各列类型） */
+export declare function validateRow(schema: Schema, row: Record<string, unknown>): void;

package/dist/db/redis/client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * weifuwu/db/redis — Redis 客户端高层 API
+ *
+ * 在 RedisConnection 之上提供：
+ * - TTL 安全:  set(key, val, ttl) 直接生效（无需记 'EX' 前缀顺序）
+ * - JSON 存取: jsonGet/jsonSet 自动序列化（AI 缓存场景零样板）
+ * - 缓存便捷:  cache(key, fn, ttl) 读缓存 → miss 执行 fn → 回填
+ */
+import { type RedisConnectionOptions } from './connection.ts';
+import type { RespValue } from './resp.ts';
+export interface RedisClientOptions extends RedisConnectionOptions {
+}
+export declare class RedisClient {
+    private conn;
+    private constructor();
+    /** 建立连接并返回就绪的客户端 */
+    static connect(options?: RedisClientOptions): Promise<RedisClient>;
+    /** 底层命令透传（RESP 值） */
+    command(name: string, ...args: (string | number)[]): Promise<RespValue>;
+    get(key: string): Promise<string | null>;
+    /**
+     * SET。ttl 秒可省略；传入即安全生效（内部转 SET key val EX ttl）。
+     */
+    set(key: string, value: string | number, ttl?: number): Promise<'OK'>;
+    /** DEL 多 key，返回删除数量 */
+    del(...keys: string[]): Promise<number>;
+    /** INCR，返回自增后的值 */
+    incr(key: string): Promise<number>;
+    /** EXPIRE，返回 1=设置成功 0=key 不存在 */
+    expire(key: string, seconds: number): Promise<number>;
+    /** TTL 剩余秒数；-1=无 TTL -2=key 不存在 */
+    ttl(key: string): Promise<number>;
+    /** 读取并 JSON.parse；key 不存在返回 null */
+    jsonGet(key: string): Promise<unknown | null>;
+    /** JSON.stringify 后写入，可选 TTL */
+    jsonSet(key: string, value: unknown, ttl?: number): Promise<'OK'>;
+    /**
+     * 缓存读-算-写。命中返回缓存值；miss 执行 fn 并回填。
+     * fn 返回 null 时不缓存（防穿透）。
+     */
+    cache<T>(key: string, fn: () => Promise<T | null>, ttl: number): Promise<T | null>;
+    /** 主动关闭连接 */
+    close(): Promise<void>;
+}