@dangao/bun-server 1.0.0 → 1.0.3

package/src/cache/types.ts

@@ -0,0 +1,420 @@
+/**
+ * 缓存存储接口
+ */
+export interface CacheStore {
+  /**
+   * 获取缓存值
+   * @param key - 缓存键
+   * @returns 缓存值，如果不存在则返回 undefined
+   */
+  get<T = unknown>(key: string): Promise<T | undefined>;
+
+  /**
+   * 设置缓存值
+   * @param key - 缓存键
+   * @param value - 缓存值
+   * @param ttl - 过期时间（毫秒），0 表示永不过期
+   * @returns 是否设置成功
+   */
+  set<T = unknown>(key: string, value: T, ttl?: number): Promise<boolean>;
+
+  /**
+   * 删除缓存
+   * @param key - 缓存键
+   * @returns 是否删除成功
+   */
+  delete(key: string): Promise<boolean>;
+
+  /**
+   * 检查缓存是否存在
+   * @param key - 缓存键
+   * @returns 是否存在
+   */
+  has(key: string): Promise<boolean>;
+
+  /**
+   * 清空所有缓存
+   * @returns 是否清空成功
+   */
+  clear(): Promise<boolean>;
+
+  /**
+   * 获取多个缓存值
+   * @param keys - 缓存键数组
+   * @returns 缓存值映射
+   */
+  getMany<T = unknown>(keys: string[]): Promise<Map<string, T>>;
+
+  /**
+   * 设置多个缓存值
+   * @param entries - 缓存条目数组
+   * @param ttl - 过期时间（毫秒），0 表示永不过期
+   * @returns 是否设置成功
+   */
+  setMany<T = unknown>(
+    entries: Array<{ key: string; value: T }>,
+    ttl?: number,
+  ): Promise<boolean>;
+
+  /**
+   * 删除多个缓存
+   * @param keys - 缓存键数组
+   * @returns 删除成功的键数组
+   */
+  deleteMany(keys: string[]): Promise<string[]>;
+}
+
+/**
+ * 内存缓存存储实现
+ */
+export class MemoryCacheStore implements CacheStore {
+  private store: Map<
+    string,
+    { value: unknown; expiresAt?: number }
+  > = new Map();
+
+  private cleanupInterval?: ReturnType<typeof setInterval>;
+
+  public constructor(options?: { cleanupInterval?: number }) {
+    // 定期清理过期条目
+    if (options?.cleanupInterval !== undefined) {
+      this.cleanupInterval = setInterval(() => {
+        this.cleanup();
+      }, options.cleanupInterval);
+    }
+  }
+
+  public async get<T = unknown>(key: string): Promise<T | undefined> {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return undefined;
+    }
+
+    // 检查是否过期
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+
+    return entry.value as T;
+  }
+
+  public async set<T = unknown>(
+    key: string,
+    value: T,
+    ttl?: number,
+  ): Promise<boolean> {
+    const expiresAt = ttl && ttl > 0 ? Date.now() + ttl : undefined;
+    this.store.set(key, { value, expiresAt });
+    return true;
+  }
+
+  public async delete(key: string): Promise<boolean> {
+    return this.store.delete(key);
+  }
+
+  public async has(key: string): Promise<boolean> {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return false;
+    }
+
+    // 检查是否过期
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  public async clear(): Promise<boolean> {
+    this.store.clear();
+    return true;
+  }
+
+  public async getMany<T = unknown>(
+    keys: string[],
+  ): Promise<Map<string, T>> {
+    const result = new Map<string, T>();
+    const now = Date.now();
+
+    for (const key of keys) {
+      const entry = this.store.get(key);
+      if (entry) {
+        // 检查是否过期
+        if (entry.expiresAt && now > entry.expiresAt) {
+          this.store.delete(key);
+          continue;
+        }
+        result.set(key, entry.value as T);
+      }
+    }
+
+    return result;
+  }
+
+  public async setMany<T = unknown>(
+    entries: Array<{ key: string; value: T }>,
+    ttl?: number,
+  ): Promise<boolean> {
+    const expiresAt = ttl && ttl > 0 ? Date.now() + ttl : undefined;
+
+    for (const { key, value } of entries) {
+      this.store.set(key, { value, expiresAt });
+    }
+
+    return true;
+  }
+
+  public async deleteMany(keys: string[]): Promise<string[]> {
+    const deleted: string[] = [];
+
+    for (const key of keys) {
+      if (this.store.delete(key)) {
+        deleted.push(key);
+      }
+    }
+
+    return deleted;
+  }
+
+  /**
+   * 清理过期条目
+   */
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store.entries()) {
+      if (entry.expiresAt && now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  /**
+   * 销毁存储，清理定时器
+   */
+  public destroy(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = undefined;
+    }
+    this.store.clear();
+  }
+}
+
+/**
+ * Redis 缓存存储实现（需要 redis 包）
+ */
+export interface RedisCacheStoreOptions {
+  /**
+   * Redis 客户端（需要用户提供）
+   */
+  client: {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: { PX?: number }): Promise<void>;
+    del(key: string): Promise<void>;
+    exists(key: string): Promise<number>;
+    mget(keys: string[]): Promise<(string | null)[]>;
+    mset(entries: Array<{ key: string; value: string }>): Promise<void>;
+    flushdb(): Promise<void>;
+  };
+  /**
+   * 键前缀
+   * @default 'cache:'
+   */
+  keyPrefix?: string;
+}
+
+export class RedisCacheStore implements CacheStore {
+  private client: RedisCacheStoreOptions['client'];
+  private keyPrefix: string;
+
+  public constructor(options: RedisCacheStoreOptions) {
+    this.client = options.client;
+    this.keyPrefix = options.keyPrefix ?? 'cache:';
+  }
+
+  private getKey(key: string): string {
+    return `${this.keyPrefix}${key}`;
+  }
+
+  public async get<T = unknown>(key: string): Promise<T | undefined> {
+    const value = await this.client.get(this.getKey(key));
+    if (value === null) {
+      return undefined;
+    }
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return undefined;
+    }
+  }
+
+  public async set<T = unknown>(
+    key: string,
+    value: T,
+    ttl?: number,
+  ): Promise<boolean> {
+    try {
+      const serialized = JSON.stringify(value);
+      if (ttl && ttl > 0) {
+        await this.client.set(this.getKey(key), serialized, { PX: ttl });
+      } else {
+        await this.client.set(this.getKey(key), serialized);
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  public async delete(key: string): Promise<boolean> {
+    try {
+      await this.client.del(this.getKey(key));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  public async has(key: string): Promise<boolean> {
+    try {
+      const result = await this.client.exists(this.getKey(key));
+      return result === 1;
+    } catch {
+      return false;
+    }
+  }
+
+  public async clear(): Promise<boolean> {
+    try {
+      await this.client.flushdb();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  public async getMany<T = unknown>(
+    keys: string[],
+  ): Promise<Map<string, T>> {
+    const result = new Map<string, T>();
+    if (keys.length === 0) {
+      return result;
+    }
+
+    try {
+      const prefixedKeys = keys.map((k) => this.getKey(k));
+      const values = await this.client.mget(prefixedKeys);
+
+      for (let i = 0; i < keys.length; i++) {
+        const value = values[i];
+        if (value !== null) {
+          try {
+            result.set(keys[i], JSON.parse(value) as T);
+          } catch {
+            // 忽略解析错误
+          }
+        }
+      }
+    } catch {
+      // 忽略错误，返回空 Map
+    }
+
+    return result;
+  }
+
+  public async setMany<T = unknown>(
+    entries: Array<{ key: string; value: T }>,
+    ttl?: number,
+  ): Promise<boolean> {
+    if (entries.length === 0) {
+      return true;
+    }
+
+    try {
+      const redisEntries = entries.map(({ key, value }) => ({
+        key: this.getKey(key),
+        value: JSON.stringify(value),
+      }));
+
+      await this.client.mset(redisEntries);
+
+      // 如果设置了 TTL，需要单独为每个键设置过期时间
+      // 注意：这里假设 Redis 客户端支持 PX 选项，如果不支持，需要单独调用 EXPIRE
+      if (ttl && ttl > 0) {
+        // 由于 mset 可能不支持批量设置 TTL，这里需要单独处理
+        // 实际实现可能需要根据具体的 Redis 客户端调整
+        for (const entry of redisEntries) {
+          await this.client.set(entry.key, entry.value, { PX: ttl });
+        }
+      }
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  public async deleteMany(keys: string[]): Promise<string[]> {
+    if (keys.length === 0) {
+      return [];
+    }
+
+    try {
+      const prefixedKeys = keys.map((k) => this.getKey(k));
+      const deleted: string[] = [];
+
+      // 注意：这里假设 Redis 客户端支持批量删除
+      // 如果不支持，需要循环调用 del
+      for (const key of prefixedKeys) {
+        try {
+          await this.client.del(key);
+          deleted.push(key.replace(this.keyPrefix, ''));
+        } catch {
+          // 忽略单个删除错误
+        }
+      }
+
+      return deleted;
+    } catch {
+      return [];
+    }
+  }
+}
+
+/**
+ * CacheModule 配置选项
+ */
+export interface CacheModuleOptions {
+  /**
+   * 缓存存储实现
+   * @default MemoryCacheStore
+   */
+  store?: CacheStore;
+
+  /**
+   * 默认 TTL（毫秒）
+   * @default 3600000 (1 小时)
+   */
+  defaultTtl?: number;
+
+  /**
+   * 键前缀
+   * @default ''
+   */
+  keyPrefix?: string;
+}
+
+/**
+ * CacheService Token
+ */
+export const CACHE_SERVICE_TOKEN = Symbol(
+  '@dangao/bun-server:cache:service',
+);
+
+/**
+ * CacheModule Options Token
+ */
+export const CACHE_OPTIONS_TOKEN = Symbol('@dangao/bun-server:cache:options');

package/src/config/config-module.ts

@@ -0,0 +1,76 @@
+import { Module, MODULE_METADATA_KEY, type ModuleProvider } from '../di/module';
+
+import { ConfigService } from './service';
+import { CONFIG_SERVICE_TOKEN, type ConfigModuleOptions } from './types';
+
+@Module({
+  providers: [],
+})
+export class ConfigModule {
+  /**
+   * 创建配置模块
+   * @param options - 模块配置
+   */
+  public static forRoot(
+    options: ConfigModuleOptions = {},
+  ): typeof ConfigModule {
+    const providers: ModuleProvider[] = [];
+
+    const env = ConfigModule.snapshotEnv();
+    const defaultConfig = (options.defaultConfig ?? {}) as Record<
+      string,
+      unknown
+    >;
+    const loadedConfig =
+      (options.load ? options.load(env) : {}) as Record<string, unknown>;
+
+    // 默认配置 < 环境变量加载配置
+    const mergedConfig = {
+      ...defaultConfig,
+      ...loadedConfig,
+    } as Record<string, unknown>;
+
+    const service = new ConfigService(mergedConfig, options.namespace);
+
+    if (options.validate) {
+      options.validate(mergedConfig);
+    }
+
+    providers.push(
+      {
+        provide: CONFIG_SERVICE_TOKEN,
+        useValue: service,
+      },
+      ConfigService,
+    );
+
+    const existingMetadata =
+      Reflect.getMetadata(MODULE_METADATA_KEY, ConfigModule) || {};
+    const metadata = {
+      ...existingMetadata,
+      providers: [...(existingMetadata.providers || []), ...providers],
+      exports: [
+        ...(existingMetadata.exports || []),
+        CONFIG_SERVICE_TOKEN,
+        ConfigService,
+      ],
+    };
+    Reflect.defineMetadata(MODULE_METADATA_KEY, metadata, ConfigModule);
+
+    return ConfigModule;
+  }
+
+  /**
+   * 获取环境变量快照
+   * 方便测试和未来扩展（如 .env 文件解析）
+   */
+  private static snapshotEnv(): Record<string, string | undefined> {
+    const env: Record<string, string | undefined> = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      env[key] = value;
+    }
+    return env;
+  }
+}
+
+

package/src/config/index.ts

@@ -0,0 +1,8 @@
+export { ConfigModule } from './config-module';
+export { ConfigService } from './service';
+export {
+  CONFIG_SERVICE_TOKEN,
+  type ConfigModuleOptions,
+} from './types';
+
+

package/src/config/service.ts

@@ -0,0 +1,93 @@
+/**
+ * 配置服务
+ * 提供类型安全的配置访问能力
+ */
+export class ConfigService<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+  private readonly config: TConfig;
+  private readonly namespace?: string;
+
+  public constructor(config: TConfig, namespace?: string) {
+    this.config = config;
+    this.namespace = namespace;
+  }
+
+  /**
+   * 获取完整配置对象
+   */
+  public getAll(): TConfig {
+    return this.config;
+  }
+
+  /**
+   * 获取配置值（支持点号路径）
+   * @param key - 配置键（如 "db.host"）
+   * @param defaultValue - 默认值（可选）
+   */
+  public get<T = unknown>(key: string, defaultValue?: T): T | undefined {
+    const namespacedKey = this.applyNamespace(key);
+    const value = this.getValueByPath(this.config, namespacedKey);
+    if (value === undefined) {
+      return defaultValue;
+    }
+    return value as T;
+  }
+
+  /**
+   * 获取必需的配置值，如果不存在则抛出错误
+   * @param key - 配置键
+   */
+  public getRequired<T = unknown>(key: string): T {
+    const value = this.get<T>(key);
+    if (value === undefined) {
+      throw new Error(`Config value required for key: ${key}`);
+    }
+    return value;
+  }
+
+  /**
+   * 创建带命名空间的 ConfigService 视图
+   * @param namespace - 命名空间前缀
+   */
+  public withNamespace(namespace: string): ConfigService<TConfig> {
+    return new ConfigService<TConfig>(this.config, namespace);
+  }
+
+  private applyNamespace(key: string): string {
+    if (!this.namespace) {
+      return key;
+    }
+    if (!key) {
+      return this.namespace;
+    }
+    if (key.startsWith(this.namespace + '.')) {
+      return key;
+    }
+    return `${this.namespace}.${key}`;
+  }
+
+  private getValueByPath(
+    obj: Record<string, unknown>,
+    path: string,
+  ): unknown {
+    if (!path) {
+      return obj;
+    }
+    const segments = path.split('.');
+    let current: unknown = obj;
+
+    for (const segment of segments) {
+      if (
+        current === undefined ||
+        current === null ||
+        typeof current !== 'object'
+      ) {
+        return undefined;
+      }
+      current = (current as Record<string, unknown>)[segment];
+    }
+
+    return current;
+  }
+}
+
+

package/src/config/types.ts

@@ -0,0 +1,27 @@
+export interface ConfigModuleOptions<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * 默认配置对象（最低优先级）
+   */
+  defaultConfig?: Partial<TConfig>;
+
+  /**
+   * 从环境变量加载配置
+   * @param env - process.env 快照
+   */
+  load?: (env: Record<string, string | undefined>) => Partial<TConfig>;
+
+  /**
+   * 配置验证函数（可抛出错误）
+   * 可用于集成 class-validator 风格的校验逻辑
+   */
+  validate?: (config: TConfig) => void;
+
+  /**
+   * 命名空间前缀，用于逻辑分组（可选）
+   */
+  namespace?: string;
+}
+
+export const CONFIG_SERVICE_TOKEN = Symbol('@dangao/bun-server:config:service');
+
+