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

package/dist/events/index.d.ts

@@ -0,0 +1,155 @@
+import { a as Event, b as EventClass } from '../EventManager-CmIoLt7r.js';
+export { c as EventListener, E as EventManager, d as EventSubscription, L as ListenerOptions, R as RegisteredListener, e as createEventManager } from '../EventManager-CmIoLt7r.js';
+
+/**
+ * Base class for event listeners.
+ * Extend this class to create reusable, class-based event listeners.
+ *
+ * @example
+ * ```ts
+ * class SendWelcomeEmail extends Listener<UserRegistered> {
+ *   static event = UserRegistered
+ *   static shouldQueue = true
+ *   static queue = 'emails'
+ *
+ *   async handle(event: UserRegistered): Promise<void> {
+ *     await mail.to(event.email).subject('Welcome!').send()
+ *   }
+ *
+ *   shouldHandle(event: UserRegistered): boolean {
+ *     // Only send to non-admin users
+ *     return !event.isAdmin
+ *   }
+ * }
+ * ```
+ */
+declare abstract class Listener<T extends Event = Event> {
+    /**
+     * The event class this listener handles.
+     * Must be set by subclasses.
+     */
+    static event: EventClass;
+    /**
+     * Whether this listener should be queued instead of executed immediately.
+     * @default false
+     */
+    static shouldQueue: boolean;
+    /**
+     * The queue name to dispatch to when shouldQueue is true.
+     * @default 'default'
+     */
+    static queue: string;
+    /**
+     * Priority of this listener. Higher values are executed first.
+     * @default 0
+     */
+    static priority: number;
+    /**
+     * Handle the event.
+     * This method must be implemented by subclasses.
+     *
+     * @param event - The event instance
+     */
+    abstract handle(event: T): void | Promise<void>;
+    /**
+     * Determine if this listener should handle the event.
+     * Override this method to conditionally handle events.
+     *
+     * @param event - The event instance
+     * @returns true if the listener should handle the event
+     */
+    shouldHandle?(event: T): boolean;
+    /**
+     * Called when the listener fails to handle the event.
+     * Override this method to handle errors.
+     *
+     * @param event - The event instance
+     * @param error - The error that occurred
+     */
+    failed?(event: T, error: Error): void | Promise<void>;
+}
+/**
+ * Listener class constructor type.
+ */
+interface ListenerClass<T extends Event = Event> {
+    new (): Listener<T>;
+    event: EventClass<T>;
+    shouldQueue: boolean;
+    queue: string;
+    priority: number;
+}
+
+/**
+ * Emitted when an HTTP request is received.
+ */
+declare class RequestReceived extends Event {
+    readonly method: string;
+    readonly path: string;
+    readonly requestId?: string | undefined;
+    constructor(method: string, path: string, requestId?: string | undefined);
+}
+/**
+ * Emitted when an HTTP request has finished processing.
+ */
+declare class RequestFinished extends Event {
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    readonly durationMs: number;
+    readonly requestId?: string | undefined;
+    constructor(method: string, path: string, status: number, durationMs: number, requestId?: string | undefined);
+}
+/**
+ * Emitted when a user successfully authenticates.
+ */
+declare class UserAuthenticated extends Event {
+    readonly userId: string | number;
+    readonly guard: string;
+    constructor(userId: string | number, guard?: string);
+}
+/**
+ * Emitted when a user logs out.
+ */
+declare class UserLoggedOut extends Event {
+    readonly userId: string | number;
+    readonly guard: string;
+    constructor(userId: string | number, guard?: string);
+}
+/**
+ * Emitted when a queued job is successfully processed.
+ */
+declare class JobProcessed extends Event {
+    readonly jobId: string;
+    readonly jobName: string;
+    readonly queue: string;
+    readonly durationMs: number;
+    constructor(jobId: string, jobName: string, queue: string, durationMs: number);
+}
+/**
+ * Emitted when a queued job fails.
+ */
+declare class JobFailed extends Event {
+    readonly jobId: string;
+    readonly jobName: string;
+    readonly queue: string;
+    readonly error: Error;
+    readonly attempts: number;
+    constructor(jobId: string, jobName: string, queue: string, error: Error, attempts: number);
+}
+/**
+ * Emitted when the application starts.
+ */
+declare class ApplicationStarted extends Event {
+    readonly port: number;
+    readonly host: string;
+    constructor(port: number, host: string);
+}
+/**
+ * Emitted when the application is shutting down.
+ */
+declare class ApplicationShutdown extends Event {
+    readonly reason?: string | undefined;
+    constructor(reason?: string | undefined);
+}
+
+export { ApplicationShutdown, ApplicationStarted, Event, EventClass, JobFailed, JobProcessed, Listener, type ListenerClass, RequestFinished, RequestReceived, UserAuthenticated, UserLoggedOut };

package/dist/events/index.js

@@ -0,0 +1,330 @@
+// src/events/Event.ts
+var Event = class {
+  /**
+   * Timestamp when the event was created.
+   */
+  timestamp = /* @__PURE__ */ new Date();
+  /**
+   * Get the event name (class name by default).
+   * Override this to customize the event name.
+   */
+  static get eventName() {
+    return this.name;
+  }
+  /**
+   * Get the event name from an instance.
+   */
+  get eventName() {
+    return this.constructor.eventName;
+  }
+};
+
+// src/events/EventManager.ts
+var EventManager = class {
+  listeners = /* @__PURE__ */ new Map();
+  /**
+   * Queue dispatcher function (set when Queue system is integrated).
+   */
+  queueDispatcher;
+  /**
+   * Register a listener for an event.
+   *
+   * @param event - Event class to listen for
+   * @param listener - Listener function
+   * @param options - Listener options
+   * @returns Subscription handle for unsubscribing
+   *
+   * @example
+   * ```ts
+   * // Basic usage
+   * events.on(UserRegistered, (e) => console.log(e.email))
+   *
+   * // With options
+   * events.on(UserRegistered, (e) => sendEmail(e), { priority: 10 })
+   *
+   * // Unsubscribe later
+   * const sub = events.on(UserRegistered, handler)
+   * sub.unsubscribe()
+   * ```
+   */
+  on(event, listener, options = {}) {
+    const eventName = typeof event === "string" ? event : event.eventName;
+    const registeredListeners = this.listeners.get(eventName) ?? [];
+    const registered = {
+      listener,
+      options: { once: false, priority: 0, ...options }
+    };
+    registeredListeners.push(registered);
+    registeredListeners.sort((a, b) => (b.options.priority ?? 0) - (a.options.priority ?? 0));
+    this.listeners.set(eventName, registeredListeners);
+    return {
+      unsubscribe: () => this.off(event, listener)
+    };
+  }
+  /**
+   * Register a one-time listener for an event.
+   * The listener will be automatically removed after the first invocation.
+   *
+   * @param event - Event class to listen for
+   * @param listener - Listener function
+   * @param options - Additional listener options (once is always true)
+   * @returns Subscription handle for unsubscribing
+   */
+  once(event, listener, options = {}) {
+    return this.on(event, listener, { ...options, once: true });
+  }
+  /**
+   * Remove a listener for an event.
+   *
+   * @param event - Event class
+   * @param listener - Listener to remove (if omitted, all listeners for the event are removed)
+   */
+  off(event, listener) {
+    const eventName = typeof event === "string" ? event : event.eventName;
+    const registeredListeners = this.listeners.get(eventName);
+    if (!registeredListeners) return;
+    if (!listener) {
+      this.listeners.delete(eventName);
+      return;
+    }
+    const index = registeredListeners.findIndex((r) => r.listener === listener);
+    if (index !== -1) {
+      registeredListeners.splice(index, 1);
+      if (registeredListeners.length === 0) {
+        this.listeners.delete(eventName);
+      }
+    }
+  }
+  /**
+   * Emit an event to all registered listeners.
+   * Listeners are executed in order of priority (highest first).
+   * Async listeners are awaited sequentially.
+   *
+   * @param event - Event instance to emit
+   *
+   * @example
+   * ```ts
+   * await events.emit(new UserRegistered('123', 'user@example.com'))
+   * ```
+   */
+  async emit(event) {
+    const eventName = event.eventName;
+    const registeredListeners = this.listeners.get(eventName);
+    if (!registeredListeners || registeredListeners.length === 0) {
+      return;
+    }
+    const listenersToCall = [...registeredListeners];
+    const toRemove = [];
+    for (const registered of listenersToCall) {
+      if (registered.options.queue && this.queueDispatcher) {
+        await this.queueDispatcher(registered.options.queue, eventName, event);
+      } else {
+        await registered.listener(event);
+      }
+      if (registered.options.once) {
+        toRemove.push(registered);
+      }
+    }
+    for (const registered of toRemove) {
+      const index = registeredListeners.indexOf(registered);
+      if (index !== -1) {
+        registeredListeners.splice(index, 1);
+      }
+    }
+    if (registeredListeners.length === 0) {
+      this.listeners.delete(eventName);
+    }
+  }
+  /**
+   * Emit an event to all registered listeners in parallel.
+   * Use this when listener execution order doesn't matter and you want faster execution.
+   *
+   * @param event - Event instance to emit
+   */
+  async emitParallel(event) {
+    const eventName = event.eventName;
+    const registeredListeners = this.listeners.get(eventName);
+    if (!registeredListeners || registeredListeners.length === 0) {
+      return;
+    }
+    const listenersToCall = [...registeredListeners];
+    const toRemove = [];
+    await Promise.all(
+      listenersToCall.map(async (registered) => {
+        if (registered.options.queue && this.queueDispatcher) {
+          await this.queueDispatcher(registered.options.queue, eventName, event);
+        } else {
+          await registered.listener(event);
+        }
+        if (registered.options.once) {
+          toRemove.push(registered);
+        }
+      })
+    );
+    for (const registered of toRemove) {
+      const index = registeredListeners.indexOf(registered);
+      if (index !== -1) {
+        registeredListeners.splice(index, 1);
+      }
+    }
+    if (registeredListeners.length === 0) {
+      this.listeners.delete(eventName);
+    }
+  }
+  /**
+   * Check if an event has any listeners registered.
+   *
+   * @param event - Event class or event name
+   */
+  hasListeners(event) {
+    const eventName = typeof event === "string" ? event : event.eventName;
+    const listeners = this.listeners.get(eventName);
+    return listeners !== void 0 && listeners.length > 0;
+  }
+  /**
+   * Get all listeners for an event.
+   *
+   * @param event - Event class or event name
+   */
+  getListeners(event) {
+    const eventName = typeof event === "string" ? event : event.eventName;
+    const registeredListeners = this.listeners.get(eventName);
+    if (!registeredListeners) return [];
+    return registeredListeners.map((r) => r.listener);
+  }
+  /**
+   * Get the count of listeners for an event.
+   *
+   * @param event - Event class or event name
+   */
+  listenerCount(event) {
+    const eventName = typeof event === "string" ? event : event.eventName;
+    return this.listeners.get(eventName)?.length ?? 0;
+  }
+  /**
+   * Get all registered event names.
+   */
+  eventNames() {
+    return Array.from(this.listeners.keys());
+  }
+  /**
+   * Remove all listeners for all events.
+   */
+  removeAllListeners() {
+    this.listeners.clear();
+  }
+  /**
+   * Set the queue dispatcher function.
+   * This is called by the Queue system when it's integrated.
+   */
+  setQueueDispatcher(dispatcher) {
+    this.queueDispatcher = dispatcher;
+  }
+};
+function createEventManager() {
+  return new EventManager();
+}
+
+// src/events/Listener.ts
+var Listener = class {
+  /**
+   * The event class this listener handles.
+   * Must be set by subclasses.
+   */
+  static event;
+  /**
+   * Whether this listener should be queued instead of executed immediately.
+   * @default false
+   */
+  static shouldQueue = false;
+  /**
+   * The queue name to dispatch to when shouldQueue is true.
+   * @default 'default'
+   */
+  static queue = "default";
+  /**
+   * Priority of this listener. Higher values are executed first.
+   * @default 0
+   */
+  static priority = 0;
+};
+
+// src/events/builtin.ts
+var RequestReceived = class extends Event {
+  constructor(method, path, requestId) {
+    super();
+    this.method = method;
+    this.path = path;
+    this.requestId = requestId;
+  }
+};
+var RequestFinished = class extends Event {
+  constructor(method, path, status, durationMs, requestId) {
+    super();
+    this.method = method;
+    this.path = path;
+    this.status = status;
+    this.durationMs = durationMs;
+    this.requestId = requestId;
+  }
+};
+var UserAuthenticated = class extends Event {
+  constructor(userId, guard = "default") {
+    super();
+    this.userId = userId;
+    this.guard = guard;
+  }
+};
+var UserLoggedOut = class extends Event {
+  constructor(userId, guard = "default") {
+    super();
+    this.userId = userId;
+    this.guard = guard;
+  }
+};
+var JobProcessed = class extends Event {
+  constructor(jobId, jobName, queue, durationMs) {
+    super();
+    this.jobId = jobId;
+    this.jobName = jobName;
+    this.queue = queue;
+    this.durationMs = durationMs;
+  }
+};
+var JobFailed = class extends Event {
+  constructor(jobId, jobName, queue, error, attempts) {
+    super();
+    this.jobId = jobId;
+    this.jobName = jobName;
+    this.queue = queue;
+    this.error = error;
+    this.attempts = attempts;
+  }
+};
+var ApplicationStarted = class extends Event {
+  constructor(port, host) {
+    super();
+    this.port = port;
+    this.host = host;
+  }
+};
+var ApplicationShutdown = class extends Event {
+  constructor(reason) {
+    super();
+    this.reason = reason;
+  }
+};
+export {
+  ApplicationShutdown,
+  ApplicationStarted,
+  Event,
+  EventManager,
+  JobFailed,
+  JobProcessed,
+  Listener,
+  RequestFinished,
+  RequestReceived,
+  UserAuthenticated,
+  UserLoggedOut,
+  createEventManager
+};

package/dist/health/index.d.ts

@@ -0,0 +1,185 @@
+import { a as HealthCheck, C as CheckResult, e as HealthStatus } from '../HealthManager-DUyMIzsZ.js';
+export { b as HealthCheckOptions, H as HealthManager, c as HealthMiddlewareOptions, d as HealthReport, f as createHealthManager } from '../HealthManager-DUyMIzsZ.js';
+import '../index-9_Jzj5jo.js';
+import 'hono';
+
+/**
+ * Database connection interface (minimal).
+ */
+interface DatabaseConnection {
+    query(sql: string): Promise<unknown>;
+}
+/**
+ * Options for database health check.
+ */
+interface DatabaseCheckOptions {
+    /**
+     * Custom name for this check.
+     * @default 'database'
+     */
+    name?: string;
+    /**
+     * Custom query to execute.
+     * @default 'SELECT 1'
+     */
+    query?: string;
+}
+/**
+ * Health check for database connectivity.
+ */
+declare class DatabaseCheck extends HealthCheck {
+    readonly name: string;
+    private db;
+    private query;
+    constructor(db: DatabaseConnection, options?: DatabaseCheckOptions);
+    check(): Promise<CheckResult>;
+}
+
+/**
+ * Redis client interface (minimal).
+ */
+interface RedisClient {
+    ping(): Promise<string>;
+}
+/**
+ * Options for Redis health check.
+ */
+interface RedisCheckOptions {
+    /**
+     * Custom name for this check.
+     * @default 'redis'
+     */
+    name?: string;
+}
+/**
+ * Health check for Redis connectivity.
+ */
+declare class RedisCheck extends HealthCheck {
+    readonly name: string;
+    private redis;
+    constructor(redis: RedisClient, options?: RedisCheckOptions);
+    check(): Promise<CheckResult>;
+}
+
+/**
+ * Cache store interface (minimal).
+ */
+interface CacheStoreInterface {
+    get<T>(key: string): Promise<T | null>;
+    put<T>(key: string, value: T, ttl?: number): Promise<void>;
+    forget(key: string): Promise<boolean>;
+}
+/**
+ * Options for cache health check.
+ */
+interface CacheCheckOptions {
+    /**
+     * Custom name for this check.
+     * @default 'cache'
+     */
+    name?: string;
+    /**
+     * Key to use for health check test.
+     * @default '__health_check__'
+     */
+    testKey?: string;
+}
+/**
+ * Health check for cache functionality.
+ */
+declare class CacheCheck extends HealthCheck {
+    readonly name: string;
+    private cache;
+    private testKey;
+    constructor(cache: CacheStoreInterface, options?: CacheCheckOptions);
+    check(): Promise<CheckResult>;
+}
+
+/**
+ * Storage driver interface (minimal).
+ */
+interface StorageDriverInterface {
+    put(path: string, contents: string | Buffer): Promise<void>;
+    get(path: string): Promise<Buffer | null>;
+    delete(path: string): Promise<boolean>;
+}
+/**
+ * Options for storage health check.
+ */
+interface StorageCheckOptions {
+    /**
+     * Custom name for this check.
+     * @default 'storage'
+     */
+    name?: string;
+    /**
+     * Test file path.
+     * @default '__health_check__.txt'
+     */
+    testPath?: string;
+}
+/**
+ * Health check for storage functionality.
+ */
+declare class StorageCheck extends HealthCheck {
+    readonly name: string;
+    private storage;
+    private testPath;
+    constructor(storage: StorageDriverInterface, options?: StorageCheckOptions);
+    check(): Promise<CheckResult>;
+}
+
+/**
+ * Options for memory health check.
+ */
+interface MemoryCheckOptions {
+    /**
+     * Custom name for this check.
+     * @default 'memory'
+     */
+    name?: string;
+    /**
+     * Memory threshold in MB. Above this is degraded.
+     * @default 512
+     */
+    thresholdMb?: number;
+    /**
+     * Critical memory threshold in MB. Above this is unhealthy.
+     * @default 1024
+     */
+    criticalThresholdMb?: number;
+}
+/**
+ * Health check for memory usage.
+ */
+declare class MemoryCheck extends HealthCheck {
+    readonly name: string;
+    private thresholdMb;
+    private criticalThresholdMb;
+    constructor(options?: MemoryCheckOptions);
+    check(): Promise<CheckResult>;
+}
+
+/**
+ * Callback for custom health check.
+ */
+type CustomCheckCallback = () => Promise<{
+    status: HealthStatus;
+    message?: string;
+    meta?: Record<string, unknown>;
+}>;
+/**
+ * Custom health check with callback.
+ */
+declare class CustomCheck extends HealthCheck {
+    readonly name: string;
+    private callback;
+    constructor(name: string, callback: CustomCheckCallback);
+    check(): Promise<CheckResult>;
+}
+/**
+ * Create a custom health check.
+ */
+declare function customCheck(name: string, callback: CustomCheckCallback): CustomCheck;
+
+export { CacheCheck, type CacheCheckOptions, type CacheStoreInterface, CheckResult, CustomCheck, type CustomCheckCallback, DatabaseCheck, type DatabaseCheckOptions, type DatabaseConnection, HealthCheck, HealthStatus, MemoryCheck, type MemoryCheckOptions, RedisCheck, type RedisCheckOptions, type RedisClient, StorageCheck, type StorageCheckOptions, type StorageDriverInterface, customCheck };