@taicode/common-server 3.7.7 → 3.7.8

package/output/redis-queue/types.d.ts

@@ -0,0 +1,146 @@
+import type { CatchResult } from '@taicode/common-base';
+import type { RedisClientType } from 'redis';
+/**
+ * 队列注册表（默认）
+ *
+ * 支持两种使用方式：
+ *
+ * **方式 1: 模块声明扩展（常规，全局生效）**
+ *
+ * @example
+ * ```ts
+ * // types/redis-queue.d.ts
+ * import '@taicode/common-server'
+ *
+ * declare module '@taicode/common-server/redis-queue' {
+ *   interface RedisQueueRegistry {
+ *     'email-queue': { to: string; subject: string; body: string }
+ *     'sms-queue': { phone: string; message: string }
+ *   }
+ * }
+ *
+ * // 使用时自动类型检查
+ * const provider = new RedisQueueProvider('email-queue', { redisUrl: '...' })
+ * const consumer = new RedisQueueConsumer('email-queue', {
+ *   handler: async (data) => {
+ *     // data 类型自动推断为 { to: string; subject: string; body: string }
+ *     console.log(data.to)
+ *   }
+ * })
+ * ```
+ *
+ * **方式 2: 泛型参数（灵活，局部使用）**
+ *
+ * @example
+ * ```ts
+ * // 定义自定义 Registry
+ * interface MyQueueRegistry {
+ *   'order-queue': { orderId: string; amount: number }
+ *   'notify-queue': { userId: string; message: string }
+ * }
+ *
+ * // 使用时传入泛型参数
+ * const provider = new RedisQueueProvider<MyQueueRegistry>(
+ *   'order-queue',
+ *   { redisUrl: '...' }
+ * )
+ *
+ * const consumer = new RedisQueueConsumer<MyQueueRegistry>(
+ *   'order-queue',
+ *   {
+ *     handler: async (data) => {
+ *       // data 类型自动推断为 { orderId: string; amount: number }
+ *       console.log(data.orderId)
+ *     }
+ *   }
+ * )
+ * ```
+ */
+export interface RedisQueueRegistry {
+}
+/**
+ * 任务状态
+ */
+export type Status = 'pending' | 'processing' | 'completed' | 'failed';
+/**
+ * 任务数据类型,支持可选的 id 字段用于幂等性
+ */
+export type TaskData = {
+    id?: string;
+    [key: string]: any;
+};
+/**
+ * 任务数据结构
+ */
+export interface Task<T = TaskData> {
+    id: string;
+    data: T;
+    status: Status;
+    retryCount: number;
+    maxRetries: number;
+    createdTime: string;
+    delayUntil?: number;
+    processingStartTime?: number;
+}
+/**
+ * 队列统计信息
+ */
+export interface QueueStats {
+    failed: number;
+    pending: number;
+    completed: number;
+    processing: number;
+}
+/**
+ * Redis 队列基础配置
+ */
+export interface RedisQueueCommonConfig {
+    redisUrl?: string;
+    redisClient?: RedisClientType;
+    cleanupDelay?: number;
+}
+/**
+ * 队列生产者配置
+ */
+export interface RedisQueueProviderConfig {
+    redisUrl?: string;
+    redisClient?: RedisClientType;
+    cleanupDelay?: number;
+    processingDelay?: number;
+}
+/**
+ * 队列消费者配置
+ */
+export interface RedisQueueConsumerConfig<T extends TaskData = TaskData> {
+    redisUrl?: string;
+    redisClient?: RedisClientType;
+    handler: TaskHandler<T>;
+    maxRetries?: number;
+    concurrency?: number;
+    consumerInterval?: number;
+    processingTimeout?: number;
+    cleanupDelay?: number;
+}
+/**
+ * 任务处理器函数
+ */
+export type TaskHandler<T extends TaskData = TaskData> = (data: T) => Promise<CatchResult<unknown, string>>;
+/**
+ * 批量消费者配置
+ */
+export interface BatchConsumerConfig<T extends TaskData = TaskData> {
+    redisUrl?: string;
+    redisClient?: RedisClientType;
+    handler: BatchTaskHandler<T>;
+    batchSize?: number;
+    maxRetries?: number;
+    concurrency?: number;
+    cleanupDelay?: number;
+    consumerInterval?: number;
+    processingTimeout?: number;
+}
+/**
+ * 批量任务处理器函数
+ */
+export type BatchTaskHandler<T extends TaskData = TaskData> = (dataList: T[]) => Promise<CatchResult<unknown, string>>;
+//# sourceMappingURL=types.d.ts.map

package/output/redis-queue/types.d.ts.map

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

package/output/redis-queue/types.js

@@ -0,0 +1 @@
+export {};

package/output/schema/index.d.ts

@@ -0,0 +1,177 @@
+import type { FastifySchema } from 'fastify';
+import { z, ZodEnum, ZodType } from 'zod';
+/**
+ * 标准查询请求体 Schema
+ * 用于定义包含过滤条件、分页参数和排序条件的查询请求
+ * @param f - 过滤条件的类型
+ * @param e - 排序字段的枚举类型（可选）
+ * @returns 查询请求体的 Schema
+ */
+export declare function queryParamsSchema<F extends ZodType, E extends ZodEnum>(f: F, e?: E): z.ZodObject<{
+    filter: F;
+    paging: z.ZodObject<{
+        size: z.ZodNumber;
+        index: z.ZodNumber;
+    }, z.core.$strip>;
+    sort: z.ZodArray<z.ZodObject<{
+        key: E;
+        order: z.ZodEnum<{
+            ASC: "ASC";
+            DESC: "DESC";
+        }>;
+    }, z.core.$strip>> | z.ZodUndefined;
+}, z.core.$strip>;
+/**
+ * 查询结果 Schema
+ * 用于定义分页查询的返回结果结构
+ * @param t - 数据项的类型
+ * @returns 包含总数和数据列表的 Schema
+ */
+export declare function queryResultSchema<T extends ZodType>(t: T): z.ZodObject<{
+    total: z.ZodNumber;
+    list: z.ZodArray<T>;
+}, z.core.$strip>;
+/**
+ * 列表查询参数 Schema
+ * 一次性列出全部数据
+ * @returns 列表查询参数的 Schema
+ */
+export declare function listParamsSchema(): z.ZodNullable<z.ZodUndefined>;
+/**
+ * 列表结果 Schema
+ * 用于定义列表查询的返回结果结构（与 queryResultSchema 功能相同）
+ * @param t - 数据项的类型
+ * @returns 包含总数和数据列表的 Schema
+ */
+export declare function listResultSchema<T extends ZodType>(t: T): z.ZodObject<{
+    total: z.ZodNumber;
+    list: z.ZodArray<T>;
+}, z.core.$strip>;
+/**
+ * 指定时间范围查询请求体 Schema
+ * 用于定义包含过滤条件、时间范围和排序条件的查询请求（不包含分页）
+ * @param f - 过滤条件的类型
+ * @param e - 排序字段的枚举类型（可选）
+ * @returns 范围查询请求体的 Schema
+ */
+export declare function rangeQueryParamsSchema<F extends ZodType, E extends ZodEnum>(f: F, e?: E): z.ZodObject<{
+    filter: F;
+    sort: z.ZodUndefined | z.ZodArray<z.ZodObject<{
+        key: E;
+        order: z.ZodEnum<{
+            ASC: "ASC";
+            DESC: "DESC";
+        }>;
+    }, z.core.$strip>>;
+    range: z.ZodTuple<[z.ZodISODateTime, z.ZodISODateTime], null>;
+}, z.core.$strip>;
+/**
+ * 范围查询结果 Schema
+ * 用于定义范围查询的返回结果结构
+ * @param t - 数据项的类型
+ * @returns 包含时间点和数据的数组 Schema
+ */
+export declare function rangeQueryResultSchema<T extends ZodType>(t: T): z.ZodArray<z.ZodObject<{
+    data: T;
+    time: z.ZodISODateTime;
+}, z.core.$strip>>;
+/**
+ * 统计查询参数 Schema
+ * 用于定义统计查询的请求参数
+ * @param f - 过滤条件的类型
+ * @param e - 排序字段的枚举类型（可选）
+ * @returns 统计查询参数的 Schema
+ */
+export declare function statisticQueryParamsSchema<F extends ZodType>(f: F): z.ZodObject<{
+    filter: F;
+    step: z.ZodEnum<{
+        minute: "minute";
+        hour: "hour";
+        day: "day";
+        week: "week";
+        month: "month";
+        year: "year";
+    }>;
+    range: z.ZodTuple<[z.ZodISODateTime, z.ZodISODateTime], null>;
+}, z.core.$strip>;
+/**
+ * 统计查询结果 Schema
+ * 用于定义统计查询的返回结果结构
+ * @param t - 数据项的类型
+ * @returns 包含时间点和数据的数组 Schema
+ */
+export declare function statisticQueryResultSchema<T extends ZodType>(t: T): z.ZodArray<z.ZodObject<{
+    data: T;
+    time: z.ZodISODateTime;
+}, z.core.$strip>>;
+/**
+ * 模糊查询请求体 Schema
+ * 用于定义包含模糊搜索关键词、时间范围和排序条件的查询请求
+ * @param f - 过滤条件的类型（此处为字符串类型，用作搜索关键词）
+ * @param e - 排序字段的枚举类型（可选）
+ * @returns 模糊查询请求体的 Schema
+ */
+export declare function fuzzQueryParamsSchema<F extends ZodType, E extends ZodEnum>(f: F, e?: E): z.ZodObject<{
+    filter: F;
+    paging: z.ZodObject<{
+        size: z.ZodNumber;
+        index: z.ZodNumber;
+    }, z.core.$strip>;
+    sort: z.ZodUndefined | z.ZodArray<z.ZodObject<{
+        key: E;
+        order: z.ZodEnum<{
+            ASC: "ASC";
+            DESC: "DESC";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * 模糊查询结果 Schema
+ * 用于定义模糊查询的返回结果结构
+ * @param t - 数据项的类型
+ * @returns 包含总数和数据列表的 Schema
+ */
+export declare function fuzzQueryResultSchema<T extends ZodType>(t: T): z.ZodObject<{
+    total: z.ZodNumber;
+    list: z.ZodArray<T>;
+}, z.core.$strip>;
+/**
+ * 标准响应数据内容 Schema
+ * 用于定义统一的 API 响应结构
+ * @param t - 响应数据的类型
+ * @param s - 状态码的枚举类型
+ * @returns 标准响应的 Schema
+ */
+export declare function responseDataSchema<T extends ZodType, S extends ZodEnum>(t: T, s: S): z.ZodObject<{
+    data: T;
+    status: S;
+    message: z.ZodString;
+}, z.core.$strip>;
+export declare function responseSchema<T extends ZodType, S extends ZodEnum, E extends ZodEnum>(t: T, u: S, e: E): {
+    '200': z.ZodObject<{
+        data: T;
+        status: z.ZodEnum<{
+            SUCCESS: "SUCCESS";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strip>;
+    '400': z.ZodObject<{
+        data: z.ZodNull;
+        status: S;
+        message: z.ZodString;
+    }, z.core.$strip>;
+    '500': z.ZodObject<{
+        data: z.ZodNull;
+        status: E;
+        message: z.ZodString;
+    }, z.core.$strip>;
+};
+interface RouterSchema extends FastifySchema {
+    tags: string[];
+    summary: string;
+    operationId: string;
+    description: string;
+}
+export declare function routerSchema<T extends RouterSchema>(schema: T & RouterSchema): T & RouterSchema;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/output/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/schema/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAC5C,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AA2BzC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;;;;;;;;;;;;;kBAMlF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;kBAKxD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,kCAE/B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;kBAKvD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;;;;;;;;;;kBAMvF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;mBAK7D;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;;;;;;;;;kBAMjE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;mBAKjE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;;;;;;;;;;;;;kBAMtF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;kBAK5D;AAGD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;;;;kBAMlF;AAED,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;;;;;;;;;;;;;;;;;;EAMvG;AAED,UAAU,YAAa,SAAQ,aAAa;IAC1C,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EAAE,MAAM,EAAE,CAAC,GAAG,YAAY,GAAG,CAAC,GAAG,YAAY,CAY/F"}

package/output/schema/index.js

@@ -0,0 +1,180 @@
+import { z, ZodEnum, ZodType } from 'zod';
+/**
+ * 分页查询参数 Schema
+ * 用于定义分页查询时的页面大小和页面索引
+ * @private
+ */
+function _pagingSchema() {
+    return z.object({
+        size: z.number().max(100).describe('每页数据量，最大100条'),
+        index: z.number().min(1).describe('页面索引，从1开始')
+    });
+}
+/**
+ * 排序查询参数 Schema
+ * 用于定义排序条件，支持多字段排序
+ * @private
+ * @param t - 排序字段的枚举类型
+ */
+function _sortSchema(t) {
+    return z.array(z.object({
+        key: t.describe('排序字段'),
+        order: z.enum(['ASC', 'DESC']).describe('排序方向：ASC-升序，DESC-降序')
+    }));
+}
+/**
+ * 标准查询请求体 Schema
+ * 用于定义包含过滤条件、分页参数和排序条件的查询请求
+ * @param f - 过滤条件的类型
+ * @param e - 排序字段的枚举类型（可选）
+ * @returns 查询请求体的 Schema
+ */
+export function queryParamsSchema(f, e) {
+    return z.object({
+        filter: f.describe('过滤条件'),
+        paging: _pagingSchema().describe('分页参数'),
+        sort: e ? _sortSchema(e).describe('排序条件') : z.undefined(),
+    });
+}
+/**
+ * 查询结果 Schema
+ * 用于定义分页查询的返回结果结构
+ * @param t - 数据项的类型
+ * @returns 包含总数和数据列表的 Schema
+ */
+export function queryResultSchema(t) {
+    return z.object({
+        total: z.number().describe('数据总数'),
+        list: z.array(t).describe('数据列表')
+    });
+}
+/**
+ * 列表查询参数 Schema
+ * 一次性列出全部数据
+ * @returns 列表查询参数的 Schema
+ */
+export function listParamsSchema() {
+    return z.undefined().nullable();
+}
+/**
+ * 列表结果 Schema
+ * 用于定义列表查询的返回结果结构（与 queryResultSchema 功能相同）
+ * @param t - 数据项的类型
+ * @returns 包含总数和数据列表的 Schema
+ */
+export function listResultSchema(t) {
+    return z.object({
+        total: z.number().describe('数据总数'),
+        list: z.array(t).describe('数据列表')
+    });
+}
+/**
+ * 指定时间范围查询请求体 Schema
+ * 用于定义包含过滤条件、时间范围和排序条件的查询请求（不包含分页）
+ * @param f - 过滤条件的类型
+ * @param e - 排序字段的枚举类型（可选）
+ * @returns 范围查询请求体的 Schema
+ */
+export function rangeQueryParamsSchema(f, e) {
+    return z.object({
+        filter: f.describe('过滤条件'),
+        sort: e ? _sortSchema(e).describe('排序条件') : z.undefined(),
+        range: z.tuple([z.iso.datetime(), z.iso.datetime()]).describe('时间范围，格式为 [开始时间, 结束时间]'),
+    });
+}
+/**
+ * 范围查询结果 Schema
+ * 用于定义范围查询的返回结果结构
+ * @param t - 数据项的类型
+ * @returns 包含时间点和数据的数组 Schema
+ */
+export function rangeQueryResultSchema(t) {
+    return z.array(z.object({
+        data: t,
+        time: z.iso.datetime().describe('时间点'),
+    }));
+}
+/**
+ * 统计查询参数 Schema
+ * 用于定义统计查询的请求参数
+ * @param f - 过滤条件的类型
+ * @param e - 排序字段的枚举类型（可选）
+ * @returns 统计查询参数的 Schema
+ */
+export function statisticQueryParamsSchema(f) {
+    return z.object({
+        filter: f.describe('过滤条件'),
+        step: z.enum(['minute', 'hour', 'day', 'week', 'month', 'year']).describe('统计粒度'),
+        range: z.tuple([z.iso.datetime(), z.iso.datetime()]).describe('时间范围，格式为 [开始时间, 结束时间]'),
+    });
+}
+/**
+ * 统计查询结果 Schema
+ * 用于定义统计查询的返回结果结构
+ * @param t - 数据项的类型
+ * @returns 包含时间点和数据的数组 Schema
+ */
+export function statisticQueryResultSchema(t) {
+    return z.array(z.object({
+        data: t,
+        time: z.iso.datetime().describe('时间点'),
+    }));
+}
+/**
+ * 模糊查询请求体 Schema
+ * 用于定义包含模糊搜索关键词、时间范围和排序条件的查询请求
+ * @param f - 过滤条件的类型（此处为字符串类型，用作搜索关键词）
+ * @param e - 排序字段的枚举类型（可选）
+ * @returns 模糊查询请求体的 Schema
+ */
+export function fuzzQueryParamsSchema(f, e) {
+    return z.object({
+        filter: f.describe('模糊搜索关键词，长度1-50字符'),
+        paging: _pagingSchema().describe('分页参数'),
+        sort: e ? _sortSchema(e).describe('排序条件') : z.undefined(),
+    });
+}
+/**
+ * 模糊查询结果 Schema
+ * 用于定义模糊查询的返回结果结构
+ * @param t - 数据项的类型
+ * @returns 包含总数和数据列表的 Schema
+ */
+export function fuzzQueryResultSchema(t) {
+    return z.object({
+        total: z.number().describe('数据总数'),
+        list: z.array(t).describe('数据列表')
+    });
+}
+/**
+ * 标准响应数据内容 Schema
+ * 用于定义统一的 API 响应结构
+ * @param t - 响应数据的类型
+ * @param s - 状态码的枚举类型
+ * @returns 标准响应的 Schema
+ */
+export function responseDataSchema(t, s) {
+    return z.object({
+        data: t.describe('响应数据'),
+        status: s.describe('响应状态码'),
+        message: z.string().describe('响应消息'),
+    });
+}
+export function responseSchema(t, u, e) {
+    return {
+        '200': responseDataSchema(t, z.enum(['SUCCESS'])),
+        '400': responseDataSchema(z.null(), u),
+        '500': responseDataSchema(z.null(), e),
+    };
+}
+export function routerSchema(schema) {
+    // 验证必需字段
+    if (!schema.operationId) {
+        throw new Error('routerSchema requires operationId');
+    }
+    // 如果没有提供 tags，设置默认值
+    if (!schema.tags) {
+        schema.tags = ['默认'];
+    }
+    return { ...schema };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-server",
-  "version": "3.7.7",
+  "version": "3.7.8",
   "author": "Alain",
   "license": "ISC",
   "description": "",
@@ -27,7 +27,7 @@
     "fastify": "^5.5.0",
     "redis": "^5.11.0",
     "zod": "^4.1.0",
-    "@taicode/common-base": "^3.7.7"
+    "@taicode/common-base": "^3.7.8"
   },
   "devDependencies": {
     "@types/node": "^22.19.13",