@guren/server 0.2.0-alpha.7 → 1.0.0-rc.9

package/dist/BroadcastManager-AkIWUGJo.d.ts

@@ -0,0 +1,466 @@
+import { M as Middleware } from './index-9_Jzj5jo.js';
+
+/**
+ * Broadcast event payload.
+ */
+interface BroadcastEvent {
+    channel: string;
+    event: string;
+    data: unknown;
+    timestamp: Date;
+}
+/**
+ * Broadcast driver interface.
+ */
+interface BroadcastDriver {
+    /**
+     * Publish an event to a channel.
+     */
+    publish(channel: string, event: string, data: unknown): Promise<void>;
+    /**
+     * Subscribe to a channel.
+     * Returns an unsubscribe function.
+     */
+    subscribe(channel: string, callback: (event: BroadcastEvent) => void): () => void;
+    /**
+     * Unsubscribe from a channel.
+     */
+    unsubscribe(channel: string, callback: (event: BroadcastEvent) => void): void;
+}
+/**
+ * Broadcast driver with presence support.
+ */
+interface PresenceBroadcastDriver extends BroadcastDriver {
+    /**
+     * Get members of a presence channel.
+     */
+    getMembers(channel: string): PresenceMember[];
+    /**
+     * Add a member to a presence channel.
+     */
+    addMember(channel: string, member: PresenceMember): void;
+    /**
+     * Remove a member from a presence channel.
+     */
+    removeMember(channel: string, memberId: string | number): void;
+}
+/**
+ * Channel authorizer function.
+ */
+interface ChannelAuthorizer {
+    (channelName: string, user: unknown): boolean | Promise<boolean>;
+}
+/**
+ * Presence channel authorizer function.
+ * Returns member info if authorized, null otherwise.
+ */
+interface PresenceChannelAuthorizer {
+    (channelName: string, user: unknown): PresenceMember | null | Promise<PresenceMember | null>;
+}
+/**
+ * Presence channel member.
+ */
+interface PresenceMember {
+    id: string | number;
+    info?: Record<string, unknown>;
+}
+/**
+ * SSE client connection.
+ */
+interface SSEClient {
+    id: string;
+    userId?: string | number;
+    channels: Set<string>;
+    send(event: string, data: unknown): void;
+    close(): void;
+}
+/**
+ * WebSocket client connection.
+ */
+interface WebSocketClient {
+    id: string;
+    userId?: string | number;
+    channels: Set<string>;
+    send(event: string, data: unknown): void | Promise<void>;
+    close(): void;
+}
+/**
+ * Broadcast manager options.
+ */
+interface BroadcastManagerOptions {
+    /**
+     * Default driver name.
+     */
+    default?: string;
+    /**
+     * Driver factories.
+     */
+    drivers?: Record<string, BroadcastDriverFactory>;
+}
+/**
+ * Broadcast driver factory.
+ */
+interface BroadcastDriverFactory {
+    (): BroadcastDriver;
+}
+/**
+ * Channel registration.
+ */
+interface ChannelRegistration {
+    pattern: string;
+    type: 'public' | 'private' | 'presence';
+    authorizer: ChannelAuthorizer | PresenceChannelAuthorizer;
+}
+/**
+ * SSE middleware options.
+ */
+interface SSEMiddlewareOptions {
+    /**
+     * Ping interval in milliseconds.
+     */
+    pingInterval?: number;
+    /**
+     * Retry delay for SSE reconnection.
+     */
+    retry?: number;
+}
+/**
+ * Auth middleware options.
+ */
+interface AuthMiddlewareOptions {
+    /**
+     * Function to get user from context.
+     */
+    getUser?: (ctx: unknown) => unknown | Promise<unknown>;
+}
+/**
+ * Broadcasted event interface (for Event class integration).
+ */
+interface BroadcastableEvent {
+    /**
+     * Get channels to broadcast to.
+     */
+    broadcastOn(): string[];
+    /**
+     * Get the event name for broadcasting.
+     */
+    broadcastAs?(): string;
+    /**
+     * Get the data to broadcast.
+     */
+    broadcastWith?(): Record<string, unknown>;
+}
+
+/**
+ * Base broadcast channel.
+ *
+ * @example
+ * ```typescript
+ * const channel = new Channel('notifications', driver)
+ * await channel.broadcast('NewMessage', { content: 'Hello!' })
+ * ```
+ */
+declare class Channel {
+    readonly name: string;
+    protected driver: BroadcastDriver;
+    constructor(name: string, driver: BroadcastDriver);
+    /**
+     * Broadcast an event to this channel.
+     */
+    broadcast(event: string, data: unknown): Promise<void>;
+    /**
+     * Subscribe to events on this channel.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback: (event: string, data: unknown) => void): () => void;
+    /**
+     * Get the full channel name for broadcasting.
+     */
+    getChannelName(): string;
+}
+
+/**
+ * Private broadcast channel.
+ *
+ * Requires authentication to subscribe.
+ *
+ * @example
+ * ```typescript
+ * const channel = new PrivateChannel('orders.123', driver)
+ * await channel.broadcast('OrderUpdated', { status: 'shipped' })
+ * ```
+ */
+declare class PrivateChannel extends Channel {
+    /**
+     * Channel name prefix.
+     */
+    static readonly PREFIX = "private-";
+    constructor(name: string, driver: BroadcastDriver);
+    /**
+     * Get the channel name without the private prefix.
+     */
+    getBaseName(): string;
+    /**
+     * Check if a channel name is a private channel.
+     */
+    static isPrivateChannel(name: string): boolean;
+    /**
+     * Normalize a channel name to include the private prefix.
+     */
+    static normalize(name: string): string;
+}
+
+/**
+ * Presence broadcast channel.
+ *
+ * Tracks members who have joined the channel.
+ *
+ * @example
+ * ```typescript
+ * const channel = new PresenceChannel('chat.1', driver)
+ *
+ * // Join channel
+ * await channel.join({ id: 1, info: { name: 'John' } })
+ *
+ * // Get members
+ * const members = channel.members()
+ *
+ * // Leave channel
+ * await channel.leave(1)
+ *
+ * // Broadcast
+ * await channel.broadcast('UserTyping', { userId: 1 })
+ * ```
+ */
+declare class PresenceChannel extends Channel {
+    /**
+     * Channel name prefix.
+     */
+    static readonly PREFIX = "presence-";
+    protected presenceDriver: PresenceBroadcastDriver;
+    constructor(name: string, driver: BroadcastDriver);
+    /**
+     * Check if a driver supports presence.
+     */
+    protected isPresenceDriver(driver: BroadcastDriver): driver is PresenceBroadcastDriver;
+    /**
+     * Get members in this channel.
+     */
+    members(): PresenceMember[];
+    /**
+     * Join the channel.
+     */
+    join(member: PresenceMember): Promise<void>;
+    /**
+     * Leave the channel.
+     */
+    leave(memberId: string | number): Promise<void>;
+    /**
+     * Check if a member is in the channel.
+     */
+    hasMember(memberId: string | number): boolean;
+    /**
+     * Get member by ID.
+     */
+    getMember(memberId: string | number): PresenceMember | undefined;
+    /**
+     * Get member count.
+     */
+    count(): number;
+    /**
+     * Get the channel name without the presence prefix.
+     */
+    getBaseName(): string;
+    /**
+     * Check if a channel name is a presence channel.
+     */
+    static isPresenceChannel(name: string): boolean;
+    /**
+     * Normalize a channel name to include the presence prefix.
+     */
+    static normalize(name: string): string;
+}
+
+/**
+ * Broadcast manager for real-time event broadcasting.
+ *
+ * @example
+ * ```typescript
+ * const broadcast = new BroadcastManager({
+ *   default: 'memory',
+ *   drivers: {
+ *     memory: () => new MemoryDriver(),
+ *     redis: () => new RedisDriver(redis),
+ *   },
+ * })
+ *
+ * // Register channel authorizers
+ * broadcast
+ *   .channel('public.*', () => true)
+ *   .privateChannel('orders.{orderId}', async (channel, user) => {
+ *     const orderId = channel.split('.')[1]
+ *     return order.userId === user.id
+ *   })
+ *   .presenceChannel('chat.{roomId}', async (channel, user) => {
+ *     return { id: user.id, info: { name: user.name } }
+ *   })
+ *
+ * // Broadcast events
+ * await broadcast.broadcast('notifications', 'NewMessage', { content: 'Hello!' })
+ *
+ * // Or use channel helpers
+ * await broadcast.toChannel('notifications').broadcast('NewMessage', data)
+ * await broadcast.toPrivate('orders.123').broadcast('OrderUpdated', data)
+ * await broadcast.toPresence('chat.1').broadcast('UserTyping', data)
+ * ```
+ */
+declare class BroadcastManager {
+    /**
+     * Default driver name.
+     */
+    protected defaultDriver: string;
+    /**
+     * Driver factories.
+     */
+    protected driverFactories: Map<string, BroadcastDriverFactory>;
+    /**
+     * Resolved drivers.
+     */
+    protected resolvedDrivers: Map<string, BroadcastDriver>;
+    /**
+     * Channel registrations.
+     */
+    protected channelRegistrations: ChannelRegistration[];
+    /**
+     * SSE clients.
+     */
+    protected sseClients: Map<string, SSEClient>;
+    /**
+     * WebSocket clients.
+     */
+    protected wsClients: Map<string, WebSocketClient>;
+    constructor(options?: BroadcastManagerOptions);
+    /**
+     * Register a driver factory.
+     */
+    registerDriver(name: string, factory: BroadcastDriverFactory): this;
+    /**
+     * Get a driver by name.
+     */
+    driver(name?: string): BroadcastDriver;
+    /**
+     * Register a public channel authorizer.
+     */
+    channel(pattern: string, authorizer: ChannelAuthorizer): this;
+    /**
+     * Register a private channel authorizer.
+     */
+    privateChannel(pattern: string, authorizer: ChannelAuthorizer): this;
+    /**
+     * Register a presence channel authorizer.
+     */
+    presenceChannel(pattern: string, authorizer: PresenceChannelAuthorizer): this;
+    /**
+     * Broadcast an event to a channel.
+     */
+    broadcast(channelName: string, event: string, data: unknown): Promise<void>;
+    /**
+     * Get a public channel.
+     */
+    toChannel(name: string): Channel;
+    /**
+     * Get a private channel.
+     */
+    toPrivate(name: string): PrivateChannel;
+    /**
+     * Get a presence channel.
+     */
+    toPresence(name: string): PresenceChannel;
+    /**
+     * Authorize a channel for a user.
+     */
+    authorize(channelName: string, user: unknown): Promise<boolean | {
+        id: string | number;
+        info?: Record<string, unknown>;
+    } | null>;
+    /**
+     * Find channel registration for a channel name.
+     */
+    protected findChannelRegistration(channelName: string): ChannelRegistration | undefined;
+    /**
+     * Match a channel name against a pattern.
+     */
+    protected matchPattern(pattern: string, channelName: string): boolean;
+    /**
+     * Create SSE middleware.
+     */
+    sseMiddleware(options?: SSEMiddlewareOptions): Middleware;
+    /**
+     * Create auth middleware for channel authorization.
+     */
+    authMiddleware(options?: AuthMiddlewareOptions): Middleware;
+    /**
+     * Subscribe a client to a channel.
+     */
+    subscribeClient(clientId: string, channel: string): boolean;
+    /**
+     * Register a WebSocket client and return its generated client ID.
+     */
+    registerWebSocketClient(client: Omit<WebSocketClient, 'id' | 'channels'> & {
+        userId?: string | number;
+    }): string;
+    /**
+     * Remove a WebSocket client and close the underlying connection.
+     */
+    removeWebSocketClient(clientId: string): boolean;
+    /**
+     * Subscribe a WebSocket client to a channel.
+     */
+    subscribeWebSocketClient(clientId: string, channel: string): boolean;
+    /**
+     * Unsubscribe a WebSocket client from a channel.
+     */
+    unsubscribeWebSocketClient(clientId: string, channel: string): boolean;
+    /**
+     * Get a WebSocket client by ID.
+     */
+    getWebSocketClient(clientId: string): WebSocketClient | undefined;
+    /**
+     * Get all WebSocket clients.
+     */
+    getWebSocketClients(): WebSocketClient[];
+    /**
+     * Unsubscribe a client from a channel.
+     */
+    unsubscribeClient(clientId: string, channel: string): boolean;
+    /**
+     * Get SSE client by ID.
+     */
+    getClient(clientId: string): SSEClient | undefined;
+    /**
+     * Get all SSE clients.
+     */
+    getClients(): SSEClient[];
+    /**
+     * Get clients subscribed to a channel.
+     */
+    getChannelClients(channel: string): SSEClient[];
+    /**
+     * Generate a unique client ID.
+     */
+    protected generateClientId(prefix?: 'sse' | 'ws'): string;
+}
+/**
+ * Set the global broadcast manager.
+ */
+declare function setBroadcastManager(manager: BroadcastManager): void;
+/**
+ * Get the global broadcast manager.
+ */
+declare function getBroadcastManager(): BroadcastManager;
+/**
+ * Create a broadcast manager.
+ */
+declare function createBroadcastManager(options?: BroadcastManagerOptions): BroadcastManager;
+
+export { type AuthMiddlewareOptions as A, BroadcastManager as B, Channel as C, type PresenceBroadcastDriver as P, type SSEClient as S, type WebSocketClient as W, type BroadcastDriver as a, type BroadcastDriverFactory as b, type BroadcastEvent as c, type BroadcastManagerOptions as d, type BroadcastableEvent as e, type ChannelAuthorizer as f, type ChannelRegistration as g, PresenceChannel as h, type PresenceChannelAuthorizer as i, type PresenceMember as j, PrivateChannel as k, type SSEMiddlewareOptions as l, createBroadcastManager as m, getBroadcastManager as n, setBroadcastManager as s };

package/dist/CacheManager-BkvHEOZX.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Cache store interface.
+ */
+interface CacheStore {
+    /**
+     * Get a value from the cache.
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Set a value in the cache.
+     * @param key Cache key
+     * @param value Value to cache
+     * @param ttl Time-to-live in seconds (optional)
+     */
+    set<T>(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Check if a key exists in the cache.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a key from the cache.
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Clear all items from the cache.
+     */
+    clear(): Promise<void>;
+    /**
+     * Increment a numeric value.
+     * @param key Cache key
+     * @param value Amount to increment (default: 1)
+     * @returns The new value
+     */
+    increment(key: string, value?: number): Promise<number>;
+    /**
+     * Decrement a numeric value.
+     * @param key Cache key
+     * @param value Amount to decrement (default: 1)
+     * @returns The new value
+     */
+    decrement(key: string, value?: number): Promise<number>;
+    /**
+     * Get a value from the cache, or store and return the result of the callback.
+     * @param key Cache key
+     * @param ttl Time-to-live in seconds
+     * @param callback Function to compute the value if not cached
+     */
+    remember<T>(key: string, ttl: number, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Get a value from the cache, or store and return the result of the callback forever.
+     * @param key Cache key
+     * @param callback Function to compute the value if not cached
+     */
+    rememberForever<T>(key: string, callback: () => Promise<T>): Promise<T>;
+    /**
+     * Get multiple values from the cache.
+     */
+    getMany<T>(keys: string[]): Promise<Map<string, T | null>>;
+    /**
+     * Set multiple values in the cache.
+     */
+    setMany<T>(items: Map<string, T>, ttl?: number): Promise<void>;
+    /**
+     * Delete multiple keys from the cache.
+     */
+    deleteMany(keys: string[]): Promise<number>;
+    /**
+     * Get the remaining TTL for a key in seconds.
+     * Returns -1 if the key has no expiration, -2 if the key does not exist.
+     */
+    ttl(key: string): Promise<number>;
+}
+/**
+ * Cache store that supports tagging.
+ */
+interface TaggableCacheStore extends CacheStore {
+    /**
+     * Get a tagged cache instance.
+     */
+    tags(tags: string[]): TaggedCacheStore;
+}
+/**
+ * Tagged cache store interface.
+ */
+interface TaggedCacheStore extends CacheStore {
+    /**
+     * Flush all items with the current tags.
+     */
+    flush(): Promise<void>;
+    /**
+     * Get the current tags.
+     */
+    getTags(): string[];
+}
+/**
+ * Cache store factory function.
+ */
+type CacheStoreFactory = () => CacheStore;
+/**
+ * Memory store options.
+ */
+interface MemoryStoreOptions {
+    /**
+     * Maximum number of items to store.
+     * @default Infinity
+     */
+    maxSize?: number;
+    /**
+     * Check interval for expired items in milliseconds.
+     * @default 60000 (1 minute)
+     */
+    checkPeriod?: number;
+}
+/**
+ * Redis store options.
+ */
+interface RedisStoreOptions {
+    /**
+     * Redis client instance (ioredis).
+     */
+    client: unknown;
+    /**
+     * Key prefix.
+     * @default 'cache:'
+     */
+    prefix?: string;
+}
+/**
+ * File store options.
+ */
+interface FileStoreOptions {
+    /**
+     * Directory path for cache files.
+     */
+    path: string;
+    /**
+     * File extension.
+     * @default '.cache'
+     */
+    extension?: string;
+}
+/**
+ * Store configuration union type.
+ */
+type StoreConfig = {
+    driver: 'memory';
+} & MemoryStoreOptions | {
+    driver: 'redis';
+} & RedisStoreOptions | {
+    driver: 'file';
+} & FileStoreOptions;
+/**
+ * Cache manager configuration.
+ */
+interface CacheConfig {
+    /**
+     * Default store name.
+     * @default 'memory'
+     */
+    default?: string;
+    /**
+     * Store configurations.
+     */
+    stores?: Record<string, StoreConfig>;
+}
+/**
+ * Cached item with metadata.
+ */
+interface CachedItem<T = unknown> {
+    value: T;
+    expiresAt: number | null;
+}
+
+/**
+ * Cache manager for handling multiple cache stores.
+ *
+ * @example
+ * ```ts
+ * const cache = new CacheManager({
+ *   default: 'redis',
+ *   stores: {
+ *     memory: { driver: 'memory' },
+ *     redis: { driver: 'redis', client: redisClient },
+ *     file: { driver: 'file', path: './storage/cache' },
+ *   }
+ * })
+ *
+ * // Use the default store
+ * await cache.store().set('key', 'value', 3600)
+ *
+ * // Use a specific store
+ * await cache.store('memory').set('key', 'value')
+ *
+ * // Use tagged cache
+ * await cache.store().tags(['posts', 'user:1']).set('user:1:posts', posts)
+ * await cache.store().tags(['user:1']).flush()
+ * ```
+ */
+declare class CacheManager {
+    private readonly defaultStoreName;
+    private readonly storeFactories;
+    private readonly resolvedStores;
+    constructor(config?: CacheConfig);
+    private driverFactories;
+    /**
+     * Register built-in store drivers.
+     */
+    private registerBuiltinDrivers;
+    /**
+     * Register a store from configuration.
+     */
+    private registerStoreFromConfig;
+    /**
+     * Get a cache store by name.
+     * Returns the default store if no name is specified.
+     */
+    store(name?: string): TaggableCacheStore;
+    /**
+     * Register a custom store factory.
+     */
+    registerStore(name: string, factory: CacheStoreFactory): void;
+    /**
+     * Register a custom driver.
+     */
+    registerDriver(name: string, factory: (options: unknown) => CacheStore): void;
+    /**
+     * Check if a store is registered.
+     */
+    hasStore(name: string): boolean;
+    /**
+     * Get the default store name.
+     */
+    getDefaultStoreName(): string;
+    /**
+     * Get all registered store names.
+     */
+    getStoreNames(): string[];
+}
+/**
+ * Create a cache manager with configuration.
+ */
+declare function createCacheManager(config?: CacheConfig): CacheManager;
+
+export { CacheManager as C, type FileStoreOptions as F, type MemoryStoreOptions as M, type RedisStoreOptions as R, type StoreConfig as S, type TaggedCacheStore as T, type CacheConfig as a, type CacheStore as b, type CacheStoreFactory as c, createCacheManager as d, type CachedItem as e, type TaggableCacheStore as f };