@lee-zg/melange 1.0.0

package/dist/core/index.d.ts

@@ -0,0 +1,718 @@
+import { v as EventHandler, x as Subscription, C as Constructor } from '../types-BtOUCLB-.js';
+
+/**
+ * @fileoverview 用于发布/订阅模式的事件发射器类
+ * @module melange/core/events
+ * @description 提供一个类型安全的事件发射器实现
+ * 遵循观察者模式。
+ */
+
+/**
+ * 类型安全的事件映射接口。
+ * 扩展此接口以定义您的事件类型。
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   userLogin: { userId: string; timestamp: Date };
+ *   userLogout: { userId: string };
+ *   error: Error;
+ * }
+ *
+ * const emitter = new EventEmitter<MyEvents>();
+ * emitter.on('userLogin', event => console.log(event.userId));
+ * ```
+ */
+interface EventMap {
+    [event: string]: unknown;
+}
+/**
+ * 类型安全的事件发射器类。
+ * 实现观察者模式以进行解耦的事件驱动编程。
+ *
+ * @description
+ * EventEmitter 提供了一种订阅和发射事件的方式，具有完整的
+ * TypeScript 类型安全性。它支持一次性监听器、监听器移除
+ * 和适当的清理。
+ *
+ * @template Events - 定义事件名称和载荷类型的事件映射类型
+ *
+ * @example
+ * ```typescript
+ * interface AppEvents {
+ *   'user:created': { id: string; name: string };
+ *   'user:deleted': { id: string };
+ *   'error': Error;
+ * }
+ *
+ * const events = new EventEmitter<AppEvents>();
+ *
+ * // 订阅事件
+ * events.on('user:created', user => {
+ *   console.log(`创建用户: ${user.name}`);
+ * });
+ *
+ * // 发射事件
+ * events.emit('user:created', { id: '1', name: 'John' });
+ *
+ * // 一次性监听器
+ * events.once('error', err => console.error(err));
+ *
+ * // 取消订阅
+ * const subscription = events.on('user:deleted', handleDelete);
+ * subscription.unsubscribe();
+ * ```
+ */
+declare class EventEmitter<Events extends EventMap = EventMap> {
+    /**
+     * 事件名称到其监听器的映射
+     */
+    private listeners;
+    /**
+     * 订阅事件。
+     *
+     * @param event - 要订阅的事件名称
+     * @param handler - 事件发射时要调用的处理函数
+     * @returns 带有取消订阅方法的订阅对象
+     */
+    on<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): Subscription;
+    /**
+     * 仅订阅事件的一次发射。
+     * 监听器在被调用一次后自动移除。
+     *
+     * @param event - 要订阅的事件名称
+     * @param handler - 事件发射时要调用的处理函数
+     * @returns 带有取消订阅方法的订阅对象
+     */
+    once<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): Subscription;
+    /**
+     * 从事件中移除特定监听器。
+     *
+     * @param event - 事件名称
+     * @param handler - 要移除的处理函数
+     */
+    off<K extends keyof Events>(event: K, handler: EventHandler<Events[K]>): void;
+    /**
+     * 发射带有给定载荷的事件。
+     * 所有订阅的监听器将同步调用。
+     *
+     * @param event - 要发射的事件名称
+     * @param payload - 事件载荷
+     */
+    emit<K extends keyof Events>(event: K, payload: Events[K]): void;
+    /**
+     * 移除特定事件的所有监听器，或如果不指定事件则移除所有监听器。
+     *
+     * @param event - 可选的事件名称，用于清除监听器
+     */
+    removeAllListeners<K extends keyof Events>(event?: K): void;
+    /**
+     * 返回特定事件的监听器数量。
+     *
+     * @param event - 事件名称
+     * @returns 监听器数量
+     */
+    listenerCount<K extends keyof Events>(event: K): number;
+    /**
+     * 返回所有具有监听器的事件名称。
+     *
+     * @returns 事件名称数组
+     */
+    eventNames(): Array<keyof Events>;
+    /**
+     * 添加监听器的内部方法。
+     */
+    private addListener;
+}
+
+/**
+ * @fileoverview 依赖注入容器
+ * @module melange/core/container
+ * @description 提供一个简单而强大的依赖注入容器
+ * 支持单例、工厂函数和自动解析。
+ */
+
+/**
+ * 用于标识依赖项的令牌类型。
+ * 可以是字符串、符号或类构造函数。
+ */
+type Token<T = unknown> = string | symbol | Constructor<T>;
+/**
+ * 创建实例的工厂函数类型。
+ */
+type Factory<T> = (container: Container) => T;
+/**
+ * 依赖注册的生命周期选项。
+ */
+declare enum Lifecycle {
+    /** 每次都创建新实例 */
+    Transient = "transient",
+    /** 创建单个实例并重复使用 */
+    Singleton = "singleton"
+}
+/**
+ * 依赖注入容器。
+ * 管理依赖项的生命周期和解析。
+ *
+ * @description
+ * Container 类提供控制反转 (IoC) 功能，
+ * 允许您通过在运行时注册和解析依赖项来解耦代码。
+ *
+ * @example
+ * ```typescript
+ * // 创建容器
+ * const container = new Container();
+ *
+ * // 注册类
+ * container.register('logger', () => new ConsoleLogger());
+ *
+ * // 注册单例
+ * container.registerSingleton('config', () => loadConfig());
+ *
+ * // 解析依赖项
+ * const logger = container.resolve<Logger>('logger');
+ *
+ * // 使用装饰器
+ * @Injectable()
+ * class UserService {
+ *   constructor(@Inject('logger') private logger: Logger) {}
+ * }
+ * container.registerClass(UserService);
+ * ```
+ */
+declare class Container {
+    /**
+     * 已注册依赖项的映射
+     */
+    private registrations;
+    /**
+     * 用于分层解析的父容器
+     */
+    private parent;
+    /**
+     * 创建新的容器实例。
+     *
+     * @param parent - 用于分层解析的可选父容器
+     */
+    constructor(parent?: Container);
+    /**
+     * 使用工厂函数注册依赖项。
+     *
+     * @template T - 依赖项类型
+     * @param token - 用于标识依赖项的令牌
+     * @param factory - 创建依赖项的工厂函数
+     * @param lifecycle - 依赖项的生命周期（默认：Transient）
+     * @returns 容器实例，用于链式调用
+     */
+    register<T>(token: Token<T>, factory: Factory<T>, lifecycle?: Lifecycle): this;
+    /**
+     * 注册单例依赖项。
+     * 工厂函数只会被调用一次，之后返回相同的实例。
+     *
+     * @template T - 依赖项类型
+     * @param token - 用于标识依赖项的令牌
+     * @param factory - 创建依赖项的工厂函数
+     * @returns 容器实例，用于链式调用
+     */
+    registerSingleton<T>(token: Token<T>, factory: Factory<T>): this;
+    /**
+     * 直接将值注册为单例。
+     *
+     * @template T - 值类型
+     * @param token - 用于标识依赖项的令牌
+     * @param value - 要注册的值
+     * @returns 容器实例，用于链式调用
+     */
+    registerValue<T>(token: Token<T>, value: T): this;
+    /**
+     * 将类注册为依赖项。
+     * 类的实例化会自动解析其依赖项。
+     *
+     * @template T - 类类型
+     * @param ClassConstructor - 要注册的类构造函数
+     * @param lifecycle - 依赖项的生命周期（默认：Transient）
+     * @returns 容器实例，用于链式调用
+     */
+    registerClass<T extends object>(ClassConstructor: Constructor<T>, lifecycle?: Lifecycle): this;
+    /**
+     * 通过令牌解析依赖项。
+     *
+     * @template T - 依赖项类型
+     * @param token - 标识依赖项的令牌
+     * @returns 已解析的依赖项
+     * @throws Error 如果依赖项未注册
+     */
+    resolve<T>(token: Token<T>): T;
+    /**
+     * 检查依赖项是否已注册。
+     *
+     * @param token - 要检查的令牌
+     * @returns 如果依赖项已注册则返回 true
+     */
+    has(token: Token): boolean;
+    /**
+     * 移除依赖项注册。
+     *
+     * @param token - 要移除的令牌
+     * @returns 如果注册已被移除则返回 true
+     */
+    unregister(token: Token): boolean;
+    /**
+     * 清除所有注册。
+     */
+    clear(): void;
+    /**
+     * 创建子容器。
+     * 子容器从父容器继承注册。
+     *
+     * @returns 新的子容器
+     */
+    createChild(): Container;
+    /**
+     * 获取类的注入元数据。
+     */
+    private getInjectMetadata;
+}
+/**
+ * 为了方便而提供的全局容器实例。
+ */
+declare const globalContainer: Container;
+/**
+ * 将类标记为可注入。
+ * 自动依赖解析所必需。
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class UserService {
+ *   constructor(private userRepo: UserRepository) {}
+ * }
+ * ```
+ *
+ * @returns 类装饰器
+ */
+declare function Injectable(): ClassDecorator;
+/**
+ * 标记构造函数参数以进行注入。
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class UserService {
+ *   constructor(@Inject('logger') private logger: Logger) {}
+ * }
+ * ```
+ *
+ * @param token - 要注入的令牌
+ * @returns 参数装饰器
+ */
+declare function Inject(token: Token): ParameterDecorator;
+/**
+ * 将类标记为单例。
+ * 结合 @Injectable 和单例生命周期。
+ *
+ * @example
+ * ```typescript
+ * @Singleton()
+ * class ConfigService {
+ *   // 只会存在一个实例
+ * }
+ * ```
+ *
+ * @returns 类装饰器
+ */
+declare function Singleton(): ClassDecorator;
+
+/**
+ * @fileoverview 方法和类装饰器
+ * @module melange/core/decorators
+ * @description 提供一系列有用的装饰器，用于增强
+ * 类和方法的横切关注点。
+ */
+/**
+ * 用于缓存方法结果的记忆化装饰器。
+ * 根据方法的参数缓存结果。
+ *
+ * @description
+ * 此装饰器根据方法的参数缓存其返回值。
+ * 后续使用相同参数的调用将返回缓存的值。
+ *
+ * @example
+ * ```typescript
+ * class Calculator {
+ *   @Memoize()
+ *   fibonacci(n: number): number {
+ *     if (n <= 1) return n;
+ *     return this.fibonacci(n - 1) + this.fibonacci(n - 2);
+ *   }
+ * }
+ * ```
+ *
+ * @param keyFn - 生成缓存键的可选函数
+ * @returns 方法装饰器
+ */
+declare function Memoize(keyFn?: (...args: unknown[]) => string): MethodDecorator;
+/**
+ * 用于限制方法调用频率的防抖装饰器。
+ * 延迟方法执行直到指定的等待时间过后。
+ *
+ * @example
+ * ```typescript
+ * class SearchInput {
+ *   @Debounce(300)
+ *   onSearch(query: string): void {
+ *     // 这将在上次调用后300毫秒才被调用
+ *     console.log('搜索中:', query);
+ *   }
+ * }
+ * ```
+ *
+ * @param waitMs - 等待的毫秒数
+ * @returns 方法装饰器
+ */
+declare function Debounce(waitMs: number): MethodDecorator;
+/**
+ * 用于限制方法调用频率的节流装饰器。
+ * 确保方法在指定的时间段内最多被调用一次。
+ *
+ * @example
+ * ```typescript
+ * class ScrollHandler {
+ *   @Throttle(100)
+ *   onScroll(event: Event): void {
+ *     // 这将最多每100毫秒被调用一次
+ *     console.log('滚动中');
+ *   }
+ * }
+ * ```
+ *
+ * @param limitMs - 调用之间的最小时间间隔（毫秒）
+ * @returns 方法装饰器
+ */
+declare function Throttle(limitMs: number): MethodDecorator;
+/**
+ * 用于记录方法调用的日志装饰器。
+ * 记录方法进入、退出，以及可选的参数和返回值。
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @Log({ logArgs: true, logResult: true })
+ *   getUser(id: string): User {
+ *     return this.userRepository.findById(id);
+ *   }
+ * }
+ * // 日志: "Entering getUser with args: ["123"]"
+ * // 日志: "Exiting getUser with result: { id: "123", name: "John" }"
+ * ```
+ *
+ * @param options - 日志选项
+ * @returns 方法装饰器
+ */
+declare function Log(options?: {
+    logArgs?: boolean;
+    logResult?: boolean;
+    prefix?: string;
+}): MethodDecorator;
+/**
+ * 用于验证方法参数的验证装饰器。
+ * 在方法执行前运行验证函数。
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @Validate((id: string) => {
+ *     if (!id) throw new Error('ID 是必需的');
+ *   })
+ *   getUser(id: string): User {
+ *     return this.userRepository.findById(id);
+ *   }
+ * }
+ * ```
+ *
+ * @param validator - 在输入无效时抛出异常的验证函数
+ * @returns 方法装饰器
+ */
+declare function Validate(validator: (...args: unknown[]) => void): MethodDecorator;
+/**
+ * 用于标记方法已弃用的装饰器。
+ * 在调用方法时记录警告。
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @Deprecated('请改用 getUserById')
+ *   getUser(id: string): User {
+ *     return this.getUserById(id);
+ *   }
+ * }
+ * ```
+ *
+ * @param message - 弃用消息
+ * @returns 方法装饰器
+ */
+declare function Deprecated(message?: string): MethodDecorator;
+/**
+ * 用于密封类的装饰器。
+ * 防止向实例添加新属性。
+ *
+ * @example
+ * ```typescript
+ * @Sealed()
+ * class Config {
+ *   readonly apiUrl: string = 'https://api.example.com';
+ * }
+ *
+ * const config = new Config();
+ * config.newProp = 'value'; // 错误: 无法添加属性
+ * ```
+ *
+ * @returns 类装饰器
+ */
+declare function Sealed(): ClassDecorator;
+/**
+ * 用于冻结类的装饰器。
+ * 防止对实例进行任何修改。
+ *
+ * @example
+ * ```typescript
+ * @Frozen()
+ * class Constants {
+ *   static readonly PI = 3.14159;
+ * }
+ *
+ * Constants.PI = 3; // 错误: 无法修改
+ * ```
+ *
+ * @returns 类装饰器
+ */
+declare function Frozen(): ClassDecorator;
+/**
+ * 用于自动将方法绑定到类实例的装饰器。
+ * 对于作为回调函数传递的方法很有用。
+ *
+ * @example
+ * ```typescript
+ * class Button {
+ *   @Bind()
+ *   onClick() {
+ *     console.log(this); // 总是指向 Button 实例
+ *   }
+ * }
+ *
+ * const button = new Button();
+ * const handler = button.onClick;
+ * handler(); // `this` 仍然是 button 实例
+ * ```
+ *
+ * @returns 方法装饰器
+ */
+declare function Bind(): MethodDecorator;
+/**
+ * 用于自动重试失败方法调用的装饰器。
+ *
+ * @example
+ * ```typescript
+ * class ApiClient {
+ *   @Retry(3, 1000)
+ *   async fetchData(): Promise<Data> {
+ *     const response = await fetch('/api/data');
+ *     if (!response.ok) throw new Error('请求失败');
+ *     return response.json();
+ *   }
+ * }
+ * ```
+ *
+ * @param maxRetries - 最大重试次数
+ * @param delayMs - 重试之间的延迟（毫秒）
+ * @returns 方法装饰器
+ */
+declare function Retry(maxRetries: number, delayMs?: number): MethodDecorator;
+/**
+ * 用于为异步方法添加超时的装饰器。
+ *
+ * @example
+ * ```typescript
+ * class ApiClient {
+ *   @Timeout(5000)
+ *   async fetchData(): Promise<Data> {
+ *     // 如果这花费超过5秒，将抛出异常
+ *     return await fetch('/api/data').then(r => r.json());
+ *   }
+ * }
+ * ```
+ *
+ * @param timeoutMs - 超时时间（毫秒）
+ * @param errorMessage - 可选的错误消息
+ * @returns 方法装饰器
+ */
+declare function Timeout(timeoutMs: number, errorMessage?: string): MethodDecorator;
+
+/**
+ * @fileoverview 用于资源管理的可释放基类
+ * @module melange/core/disposable
+ * @description 提供一个基类用于管理可释放资源
+ * 包含适当的清理和生命周期管理。
+ */
+/**
+ * 可释放对象的接口。
+ * 实现此接口的对象可以被正确清理。
+ */
+interface IDisposable {
+    /**
+     * 释放此对象持有的资源。
+     */
+    dispose(): void;
+    /**
+     * 此对象是否已被释放。
+     */
+    readonly isDisposed: boolean;
+}
+/**
+ * 管理可释放资源的对象的抽象基类。
+ *
+ * @description
+ * Disposable 类提供了一种管理模式，用于管理需要显式清理的资源。
+ * 它跟踪释放状态并防止重复释放。
+ *
+ * @example
+ * ```typescript
+ * class DatabaseConnection extends Disposable {
+ *   private connection: Connection;
+ *
+ *   constructor() {
+ *     super();
+ *     this.connection = createConnection();
+ *     // 注册清理
+ *     this.addDisposable({
+ *       dispose: () => this.connection.close()
+ *     });
+ *   }
+ *
+ *   query(sql: string) {
+ *     this.ensureNotDisposed();
+ *     return this.connection.query(sql);
+ *   }
+ * }
+ *
+ * // 使用
+ * const db = new DatabaseConnection();
+ * try {
+ *   await db.query('SELECT * FROM users');
+ * } finally {
+ *   db.dispose();
+ * }
+ * ```
+ */
+declare abstract class Disposable implements IDisposable {
+    /**
+     * 此对象是否已被释放
+     */
+    private _isDisposed;
+    /**
+     * 待清理的可释放对象列表
+     */
+    private readonly disposables;
+    /**
+     * 获取此对象是否已被释放。
+     */
+    get isDisposed(): boolean;
+    /**
+     * 释放此对象和所有已注册的可释放对象。
+     * 多次调用 dispose 是安全的（后续调用无效）。
+     */
+    dispose(): void;
+    /**
+     * 注册一个可释放对象，在此对象被释放时进行清理。
+     *
+     * @template T - 可释放对象类型
+     * @param disposable - 要注册的可释放对象
+     * @returns 相同的可释放对象，用于链式调用
+     */
+    protected addDisposable<T extends IDisposable>(disposable: T): T;
+    /**
+     * 注册一个清理函数，在此对象被释放时调用。
+     *
+     * @param fn - 清理函数
+     */
+    protected addDisposeFn(fn: () => void): void;
+    /**
+     * 如果此对象已被释放则抛出错误。
+     * 在不应在释放后调用的方法开头使用此函数。
+     *
+     * @throws Error 如果对象已被释放
+     */
+    protected ensureNotDisposed(): void;
+    /**
+     * 在对象被释放时调用。
+     * 在子类中重写以执行自定义清理。
+     */
+    protected onDispose(): void;
+}
+/**
+ * 用于管理多个可释放对象的工具类。
+ * 适用于收集应一起释放的可释放对象。
+ *
+ * @example
+ * ```typescript
+ * const disposables = new DisposableStore();
+ *
+ * // 添加各种可释放对象
+ * disposables.add(eventListener1);
+ * disposables.add(eventListener2);
+ * disposables.add({ dispose: () => cleanupSomething() });
+ *
+ * // 一次性释放所有对象
+ * disposables.dispose();
+ * ```
+ */
+declare class DisposableStore implements IDisposable {
+    private readonly items;
+    private _isDisposed;
+    /**
+     * 获取此存储是否已被释放。
+     */
+    get isDisposed(): boolean;
+    /**
+     * 向存储中添加可释放对象。
+     *
+     * @template T - 可释放对象类型
+     * @param disposable - 要添加的可释放对象
+     * @returns 相同的可释放对象，用于链式调用
+     */
+    add<T extends IDisposable>(disposable: T): T;
+    /**
+     * 从存储中移除可释放对象而不释放它。
+     *
+     * @param disposable - 要移除的可释放对象
+     */
+    delete(disposable: IDisposable): void;
+    /**
+     * 释放存储中的所有项目并清空存储。
+     */
+    dispose(): void;
+    /**
+     * 释放所有项目但保持存储活跃以接收新项目。
+     */
+    clear(): void;
+    /**
+     * 获取存储中的项目数量。
+     */
+    get size(): number;
+}
+/**
+ * 从清理函数创建可释放对象。
+ *
+ * @param dispose - 清理函数
+ * @returns 可释放对象
+ */
+declare function toDisposable(dispose: () => void): IDisposable;
+/**
+ * 将多个可释放对象组合成单个可释放对象。
+ *
+ * @param disposables - 要组合的可释放对象
+ * @returns 一次性释放所有对象的单个可释放对象
+ */
+declare function combineDisposables(...disposables: IDisposable[]): IDisposable;
+
+export { Bind, Container, Debounce, Deprecated, Disposable, DisposableStore, EventEmitter, type EventMap, type Factory, Frozen, type IDisposable, Inject, Injectable, Lifecycle, Log, Memoize, Retry, Sealed, Singleton, Throttle, Timeout, type Token, Validate, combineDisposables, globalContainer, toDisposable };

package/dist/core/index.js

@@ -0,0 +1,4 @@
+export { Bind, Container, Debounce, Deprecated, Disposable, DisposableStore, EventEmitter, Frozen, Inject, Injectable, Lifecycle, Log, Memoize, Retry, Sealed, Singleton, Throttle, Timeout, Validate, combineDisposables, globalContainer, toDisposable } from '../chunk-2PXWQDZC.js';
+import '../chunk-7QVYU63E.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}