weifuwu 0.61.2 → 0.63.0

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

@@ -24,6 +24,10 @@ export interface PgConnectionOptions {
 export interface Row {
     [col: string]: unknown;
 }
+/** 查询结果：行数组 + 影响行数（INSERT/UPDATE/DELETE/MERGE 的 CommandComplete tag） */
+export interface QueryResult<T = Row> extends Array<T> {
+    affectedRows?: number;
+}
 export declare class PgConnection {
     private opts;
     private timeoutSet;
@@ -35,6 +39,8 @@ export declare class PgConnection {
     private waiters;
     constructor(options?: PgConnectionOptions);
     get connected(): boolean;
+    /** 池空闲回收用：最近一次查询完成时间戳（pool release 时更新） */
+    lastUsed: number;
     connect(): Promise<void>;
     private onReady;
     private onAuthFail;
@@ -43,7 +49,13 @@ export declare class PgConnection {
     private prepared;
     private static readonly PREPARED_MAX;
     private stmtSeq;
+    /** LRU 淘汰的 statement 名——连接空闲时批量 DEALLOCATE（服务端同步释放，防 plan 缓存膨胀） */
+    private deallocQueue;
+    /** DEALLOCATE 批量的响应 Z——仅消费（不 resolve 查询） */
+    private awaitingDeallocZ;
     private currentQuery;
+    /** DDL 失效重试：缓存语句被 DROP 后服务器拒绝执行，Sync 复位后以新语句名重 Parse */
+    private pendingRetry;
     private onData;
     private handle;
     /** SCRAM client-final 消息 */
@@ -51,14 +63,23 @@ export declare class PgConnection {
     private scramServerSignature;
     /** LRU 读取：命中移到尾部（最近使用），超限删最旧 */
     private getPrepared;
-    /** LRU 写入：刷新位置；超上限淘汰最旧（长运行服务防无限累积） */
+    /** LRU 写入：刷新位置；超上限淘汰最旧（长运行服务防无限累积）——淘汰的 statement 推入 deallocQueue，连接空闲时服务端同步释放 */
     private setPrepared;
+    /** 连接空闲时批量 DEALLOCATE：LRU 淘汰的 statement 不残留服务端（plan 缓存膨胀防线）。
+     * 同步 write 先于后续查询（调用点在 Z handler 的同步段内，resolve 的微任务后至）。
+     * 其响应 C+Z 在无 currentQuery 时到达——awaitingDeallocZ 消费首个 Z，后续查询 Z 正常。 */
+    private flushDealloc;
     /** 事务：BEGIN → fn(tx) → COMMIT；fn 抛错 → ROLLBACK（回滚失败吞掉，保留原始错误） */
     transaction<T>(fn: (tx: {
-        query: (sql: string, params?: (string | number | boolean | object | null)[]) => Promise<Row[]>;
+        query: (sql: string, params?: (string | number | boolean | object | null)[]) => Promise<QueryResult<Row>>;
     }) => Promise<T>): Promise<T>;
     /** 查询：无参数走简单协议（Q），有参数走扩展查询（Parse/Bind/Execute/Sync） */
-    query(sql: string, params?: (string | number | boolean | object | null)[]): Promise<Row[]>;
+    query(sql: string, params?: (string | number | boolean | object | null)[]): Promise<QueryResult<Row>>;
+    /**
+     * 扩展查询首次准备：Parse + Describe + Flush（无 Sync——错误时由调用方发 Sync 复位）。
+     * retry 路径复用：新语句名强制服务器按当前 schema 重新解析（DDL 失效恢复）。
+     */
+    private issueExtendedQuery;
     private send;
     private notifyIdle;
     /** 等待连接空闲（事务/多语句流程用） */

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

@@ -8,13 +8,15 @@
  * 解决 PgConnection 单连接串行（一个 currentQuery）的限制：
  * 并发查询路由到不同连接，全忙时排队等待而非 reject。
  */
-import { type PgConnectionOptions, type Row } from './connection.ts';
+import { type PgConnectionOptions, type Row, type QueryResult } from './connection.ts';
 import { type Schema } from './schema.ts';
 export interface PgPoolOptions extends PgConnectionOptions {
     /** 池大小（连接数）。默认 5。 */
     poolSize?: number;
     /** acquire 超时 ms（池全忙时等待上限，防饿死）。默认 30_000。0 = 无限。 */
     acquireTimeoutMs?: number;
+    /** 空闲连接回收 ms（超时未使用的连接关闭，容量收缩；下次需要时自动重建）。默认 0 = 禁用。 */
+    idleTimeoutMs?: number;
     /** 查询观测钩子（慢查询日志/审计） */
     onQuery?: (sql: string, durationMs: number, rowCount: number) => void;
 }
@@ -27,39 +29,59 @@ export declare class PgPool {
     private opts;
     private initPromise;
     private schemas;
+    private idleTimer;
     /** 懒连接：构造不连接，ensure() 首次初始化（中间件注入场景） */
     constructor(options?: PgPoolOptions);
     static create(options?: PgPoolOptions): Promise<PgPool>;
     private readyPromise;
     private ensure;
     private init;
-    /** 获取一个空闲连接（全忙则排队等待） */
+    /** 空闲回收定时器（idleTimeoutMs > 0 时启动；unref 不阻塞进程退出） */
+    private startIdleReaper;
+    /** 扫描空闲连接：超时未使用 → close + 从池移除（容量收缩；acquire 时自动重建） */
+    private reapIdle;
+    /** 当前打开的连接数（含借出；测试/观测用） */
+    get open(): number;
+    /** 获取一个空闲连接（全忙则排队等待；池被空闲回收收缩时自动新建恢复容量） */
     private acquire;
     private release;
     /** 连接可用事件统一入口：优先唤醒等待者，否则回空闲池（release 与 replenish 共用） */
     private dispatchAvailable;
     /** 坏连接剔除后异步重建（池容量保持）——就绪后走统一分发（唤醒 waiter） */
     private replenish;
-    query<T = Row>(sql: string, params?: QueryParams): Promise<T[]>;
+    query<T = Row>(sql: string, params?: QueryParams): Promise<QueryResult<T>>;
     /** 注册表结构（元数据闭环：校验/类型推断的起点） */
     register(table: string, schema: Schema): void;
+    /**
+     * 批量插入：多行 VALUES 单次往返（种子/批量写场景 N 往返 → 1）。
+     * 诚实裁剪：所有行必须键集合一致（否则抛 ValidationError）；batchSize 分批（默认 500）。
+     */
+    insertMany<T = Row>(table: string, rows: Record<string, unknown>[], opts?: {
+        batchSize?: number;
+    }): Promise<QueryResult<T>>;
+    /** 参数化 UPDATE：SET + WHERE 全部参数化（防注入）；返回 affectedRows；returning 可回读修改行 */
+    update<T = Row>(table: string, set: Record<string, unknown>, where: Record<string, unknown>, opts?: {
+        returning?: string[];
+    }): Promise<QueryResult<T>>;
+    /** 参数化 DELETE：WHERE 参数化；返回 affectedRows。WHERE 必填（防全表误删） */
+    delete<T = Row>(table: string, where: Record<string, unknown>): Promise<QueryResult<T>>;
     /** 写前校验 + 参数化插入（schema 驱动，脏数据源头拦截） */
-    insert<T = Row>(table: string, row: Record<string, unknown>): Promise<T[]>;
+    insert<T = Row>(table: string, row: Record<string, unknown>): Promise<QueryResult<T>>;
     /**
      * tagged template: sql\`SELECT * FROM t WHERE id = \${id}\`
      * 插值 = 参数（postgres.js 语义，防注入）；表名必须硬编码（插值会被当参数）。
      * 对象插值自动 JSON.stringify → jsonb。
      */
-    tag(strings: TemplateStringsArray, ...values: unknown[]): Promise<Row[]>;
+    tag(strings: TemplateStringsArray, ...values: unknown[]): Promise<QueryResult<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[]>;
+    unsafe(sql: string, params?: QueryParams): Promise<QueryResult<Row>>;
     /** 事务：固定在单个连接上执行整个 BEGIN→fn→COMMIT/ROLLBACK */
     transaction<T>(fn: (tx: {
-        query: (sql: string, params?: QueryParams) => Promise<Row[]>;
+        query: (sql: string, params?: QueryParams) => Promise<QueryResult<Row>>;
     }) => Promise<T>): Promise<T>;
     close(): Promise<void>;
     get size(): number;
@@ -72,5 +94,5 @@ export interface SqlFragment {
     };
 }
 /** tagged template 事务 sql（begin 回调参数） */
-export type TaggedSql = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<Row[]>;
+export type TaggedSql = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<QueryResult<Row>>;
 export {};

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

@@ -8,6 +8,7 @@
  */
 import { type RedisConnectionOptions } from './connection.ts';
 import type { RespValue } from './resp.ts';
+import { RedisPipeline } from './pipeline.ts';
 export interface RedisClientOptions extends RedisConnectionOptions {
 }
 export declare class RedisClient {
@@ -17,6 +18,8 @@ export declare class RedisClient {
     static connect(options?: RedisClientOptions): Promise<RedisClient>;
     /** 底层命令透传（RESP 值）；Buffer 参数字节原样发送 */
     command(name: string, ...args: (string | number | Buffer)[]): Promise<RespValue>;
+    /** 连接是否就绪（池坏连接剔除用） */
+    get connected(): boolean;
     get(key: string): Promise<string | null>;
     /**
      * 二进制安全读取：返回原始字节（Uint8Array），不经过字符串解码。
@@ -35,6 +38,46 @@ export declare class RedisClient {
     expire(key: string, seconds: number): Promise<number>;
     /** TTL 剩余秒数；-1=无 TTL -2=key 不存在 */
     ttl(key: string): Promise<number>;
+    /** 批量读：返回与 key 一一对应的值（缺失为 null） */
+    mget(...keys: string[]): Promise<(string | null)[]>;
+    /** 批量写：mset(k1, v1, k2, v2, ...)（偶数参数） */
+    mset(...kv: (string | number)[]): Promise<'OK'>;
+    /** 存在性：返回存在的 key 数 */
+    exists(...keys: string[]): Promise<number>;
+    /** 原子设置（仅 key 不存在时）：1=设置成功 0=已存在（分布式锁基础） */
+    setnx(key: string, value: string | number): Promise<number>;
+    /** 原子加增量，返回新值 */
+    incrby(key: string, delta: number): Promise<number>;
+    /** 设置字段，返回新增字段数 */
+    hset(key: string, field: string, value: string | number): Promise<number>;
+    /** 读字段（缺失 null） */
+    hget(key: string, field: string): Promise<string | null>;
+    /** 读整个 hash → Record（key 不存在 → {}） */
+    hgetall(key: string): Promise<Record<string, string>>;
+    /** 删除字段，返回删除数 */
+    hdel(key: string, ...fields: string[]): Promise<number>;
+    /** 头插，返回长度 */
+    lpush(key: string, ...values: (string | number)[]): Promise<number>;
+    /** 尾插，返回长度 */
+    rpush(key: string, ...values: (string | number)[]): Promise<number>;
+    /** 头弹（缺失 null） */
+    lpop(key: string): Promise<string | null>;
+    /** 尾弹（缺失 null） */
+    rpop(key: string): Promise<string | null>;
+    /** 范围读（start/stop 支持负数，如 0 -1 全量） */
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    /** 加成员，返回新增数（重复不加） */
+    sadd(key: string, ...members: (string | number)[]): Promise<number>;
+    /** 删成员，返回删除数 */
+    srem(key: string, ...members: (string | number)[]): Promise<number>;
+    /** 全部成员（无序） */
+    smembers(key: string): Promise<string[]>;
+    /** 加成员（score 排序），返回新增数 */
+    zadd(key: string, score: number, member: string | number): Promise<number>;
+    /** 范围读（按 score 升序；start/stop 为排名，支持负数） */
+    zrange(key: string, start: number, stop: number): Promise<string[]>;
+    /** 创建管道（批量命令一次往返；结果按序） */
+    pipeline(): RedisPipeline;
     /** 读取并 JSON.parse；key 不存在返回 null */
     jsonGet(key: string): Promise<unknown | null>;
     /** JSON.stringify 后写入，可选 TTL */

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

@@ -20,6 +20,12 @@ export interface RedisConnectionOptions {
     enableOfflineQueue?: boolean;
     /** 离线队列上限。默认 5000。超限命令立即 reject（防断线期间无限累积）。 */
     maxOfflineQueue?: number;
+    /** 命令超时 ms（服务器慢/挂起时 reject，防 promise 永久挂起）。默认 0 = 禁用。 */
+    commandTimeoutMs?: number;
+    /** socket 响应超时 ms（僵尸自愈：有 pending 命令且超时无数据 → 主动断开走重连）。默认 0 = 禁用。 */
+    socketTimeoutMs?: number;
+    /** 命令观测钩子（慢命令日志/审计；traceId 由中间件 ALS 注入第 4 参） */
+    onCommand?: (command: string, args: (string | number)[], durationMs: number, traceId?: string) => void;
 }
 export declare class RedisConnection {
     readonly ready = false;
@@ -35,6 +41,7 @@ export declare class RedisConnection {
     private status;
     private retries;
     private reconnectTimer;
+    private socketTimeoutTimer;
     private connectPromise;
     private closed;
     private connectedOnce;
@@ -54,6 +61,11 @@ export declare class RedisConnection {
         asBuffer?: boolean;
     })[]): Promise<RespValue>;
     private sendNow;
+    /** 命令超时（commandTimeoutMs > 0）：超时标记 timedOut + 处理（阻塞命令 resolve(null)，其余 reject） */
+    private armTimeout;
+    /** socket 响应超时（socketTimeoutMs > 0）：期望数据但超时未达 → 僵尸连接 → 主动断开走标准重连 */
+    private armSocketTimeout;
+    private clearSocketTimeout;
     private flushOffline;
     /** 批量执行：一次 write 发送所有命令字节，响应按序路由（管道） */
     batch(payload: Uint8Array, count: number): Promise<RespValue[]>;

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

@@ -0,0 +1,26 @@
+/**
+ * weifuwu/db/redis — Redis 管道
+ *
+ * 批量命令一次网络往返发送（单次 write + 响应 pushAll 批量解析）。
+ * 结果按命令顺序返回；错误命令对应位置返回 Error。
+ */
+import type { RedisConnection } from './connection.ts';
+import type { RespValue } from './resp.ts';
+export declare class RedisPipeline {
+    private cmds;
+    private conn;
+    constructor(conn: RedisConnection);
+    set(key: string, value: string | number, ttl?: number): this;
+    get(key: string): this;
+    del(...keys: string[]): this;
+    incr(key: string): this;
+    expire(key: string, seconds: number): this;
+    ttl(key: string): this;
+    /** 任意命令透传 */
+    raw(name: string, ...args: (string | number)[]): this;
+    /**
+     * 一次往返执行所有命令。结果按命令顺序；错误命令对应位置为 Error 实例，
+     * 其余命令不受影响（Redis 管道语义）。
+     */
+    exec(): Promise<RespValue[]>;
+}

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

@@ -6,6 +6,7 @@
  */
 import { type RedisClientOptions } from './client.ts';
 import { RedisSubscriber } from './subscriber.ts';
+import { RedisPipeline } from './pipeline.ts';
 import type { RespValue } from './resp.ts';
 export interface RedisPoolOptions extends RedisClientOptions {
     /** 池大小（连接数）。默认 5。 */
@@ -16,6 +17,7 @@ export interface RedisPoolOptions extends RedisClientOptions {
 export declare class RedisPool {
     private clients;
     private rr;
+    private replenishWaiters;
     private closed;
     private keyPrefix;
     private opts;
@@ -30,8 +32,11 @@ export declare class RedisPool {
     private init;
     /** 应用 key 前缀（command 透传不加） */
     private k;
-    /** round-robin 选择连接 */
-    private next;
+    /** round-robin 选择健康连接；跳过不可用连接（断线/重连中/closed）——剔除并异步重建，防分发到死连接。
+     * 全部不可用时等待 replenish 补位（Redis 真宕机 1s 后明确报错，不无限挂起）。 */
+    private acquireHealthy;
+    /** 剔除后补位：异步重建连接，就绪后回池并唤醒等待者 */
+    private replenish;
     command(name: string, ...args: (string | number)[]): Promise<RespValue>;
     get(key: string): Promise<string | null>;
     /** 二进制安全读取（原始字节，不解码） */
@@ -44,6 +49,26 @@ export declare class RedisPool {
     jsonGet(key: string): Promise<unknown | null>;
     jsonSet(key: string, value: unknown, ttl?: number): Promise<'OK'>;
     cache<T>(key: string, fn: () => Promise<T | null>, ttl: number): Promise<T | null>;
+    mget(...keys: string[]): Promise<(string | null)[]>;
+    mset(...kv: (string | number)[]): Promise<'OK'>;
+    exists(...keys: string[]): Promise<number>;
+    setnx(key: string, value: string | number): Promise<number>;
+    incrby(key: string, delta: number): Promise<number>;
+    hset(key: string, field: string, value: string | number): Promise<number>;
+    hget(key: string, field: string): Promise<string | null>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hdel(key: string, ...fields: string[]): Promise<number>;
+    lpush(key: string, ...values: (string | number)[]): Promise<number>;
+    rpush(key: string, ...values: (string | number)[]): Promise<number>;
+    lpop(key: string): Promise<string | null>;
+    rpop(key: string): Promise<string | null>;
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    sadd(key: string, ...members: (string | number)[]): Promise<number>;
+    srem(key: string, ...members: (string | number)[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    zadd(key: string, score: number, member: string | number): Promise<number>;
+    zrange(key: string, start: number, stop: number): Promise<string[]>;
+    pipeline(): Promise<RedisPipeline>;
     /** PUBLISH 消息到频道，返回收到消息的订阅者数 */
     publish(channel: string, message: string | number): Promise<number>;
     /** 创建独立订阅者连接（Pub/Sub 场景） */

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export { messager } from './messager/index.ts';
 export type { UserSystemOptions, UserInjected, AuthApi, RegisterInput } from './user/index.ts';
 export type { MessagerOptions, MessagerInjected, MessagerClient, MessagerSystem, Message, Conversation } from './messager/index.ts';
 export { queue } from './queue/index.ts';
+export { scheduler } from './scheduler/index.ts';
 export type { QueueOptions, QueueClient, QueueInjected, QueueWorker, WorkerOptions, AddOptions, Job } from './queue/index.ts';
 export { ai } from './ai/index.ts';
 export type { AiOptions, AiInjected, AiClient, AiClientModule, ChatResponse, AgentConfig, AgentTool, AgentRunner, ToolContext, AgentRunResult, AgentStep, WfEmitter, } from './ai/index.ts';