stratal 0.0.13 → 0.0.14

package/dist/errors-BRJgVd5-.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-BRJgVd5-.mjs","names":[],"sources":["../src/errors/application-error.ts","../src/errors/error-response.ts","../src/errors/error-codes.ts","../src/errors/get-http-status.ts","../src/router/router.tokens.ts","../src/di/errors/conditional-binding-fallback.error.ts","../src/di/errors/request-scope-operation-not-allowed.error.ts","../src/di/conditional-binding-builder.ts","../src/di/container.ts","../src/di/types.ts","../src/i18n/i18n.tokens.ts","../src/errors/internal-error.ts","../src/errors/is-application-error.ts","../src/errors/global-error-handler.ts","../src/errors/request-container-not-initialized.error.ts","../src/errors/stratal-not-initialized.error.ts"],"sourcesContent":["import type { Environment, ErrorResponse } from './error-response'\nimport type { MessageKeys } from '../i18n'\nimport type { ErrorCode } from './error-codes'\n\n/**\n * ApplicationError\n *\n * Abstract base class for all application errors.\n * This class should never be used directly - always extend it to create specific error types.\n *\n * Features:\n * - Type-safe error codes from ERROR_CODES registry\n * - Type-safe message keys from i18n module\n * - Localized message keys (translated by GlobalErrorHandler)\n * - Structured metadata for logging and interpolation\n * - Proper Error prototype chain\n * - Automatic timestamp generation\n * - Serialization for RPC transmission\n *\n * Message Localization:\n * - Each error class passes an i18n key (e.g., 'errors.userNotFound') to super()\n * - `Error.message` contains the i18n key for useful stack traces and fallback display\n * - Metadata provides interpolation parameters (e.g., { userId: '123' })\n * - GlobalErrorHandler translates the message key using I18nService before sending response\n * - This ensures errors are localized based on the user's locale (from X-Locale header)\n */\nexport abstract class ApplicationError extends Error {\n  /**\n   * Controls whether stack traces are captured.\n   * Set to false in production to skip the expensive Error.captureStackTrace() call,\n   * since stack traces are stripped from responses in production anyway.\n   */\n  static captureStackTraces = true\n\n  /**\n   * Type-safe error code from ERROR_CODES registry\n   * See error-codes.ts for the complete registry\n   */\n  public readonly code: ErrorCode\n\n  /**\n   * ISO timestamp when the error was created\n   */\n  public readonly timestamp: string\n\n  /**\n   * Additional structured data about the error\n   * Used for:\n   * 1. Logging and debugging\n   * 2. Message interpolation (e.g., { userId: '123', email: 'user@example.com' })\n   */\n  public readonly metadata?: Record<string, unknown>\n\n  /**\n   * @param i18nKey - Type-safe i18n message key (e.g., 'errors.userNotFound')\n   * @param code - Type-safe error code from ERROR_CODES registry\n   * @param metadata - Optional data for logging and interpolation\n   */\n  constructor(\n    i18nKey: MessageKeys,\n    code: ErrorCode,\n    metadata?: Record<string, unknown>\n  ) {\n    // Pass i18nKey to Error.message for useful stack traces (e.g., \"InternalError: errors.internalError\")\n    super(i18nKey)\n\n    // Maintains proper prototype chain for instanceof checks\n    Object.setPrototypeOf(this, new.target.prototype)\n\n    this.name = this.constructor.name\n    this.code = code\n    this.timestamp = new Date().toISOString()\n    this.metadata = metadata\n\n    // Capture stack trace, excluding constructor call from it\n    // Skip in production where stack traces are stripped from responses anyway\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- captureStackTrace is V8-specific, not always present\n    if (ApplicationError.captureStackTraces && Error.captureStackTrace) {\n      Error.captureStackTrace(this, this.constructor)\n    }\n  }\n\n  /**\n   * Filter metadata to include only user-facing properties\n   *\n   * User-facing properties (validation/constraint errors):\n   * - issues: Validation errors from SchemaValidationError\n   * - fields: Constraint violation fields\n   * - field: Single field constraint/foreign key\n   *\n   * Internal properties (excluded from response):\n   * - path, method: Route debugging\n   * - controllerName, reason: Controller errors\n   * - details, etc.: Internal debugging info\n   *\n   * @param metadata - Raw metadata object\n   * @returns Filtered metadata with only whitelisted properties\n   */\n  private static filterMetadata(\n    metadata?: Record<string, unknown>\n  ): Record<string, unknown> | undefined {\n    if (!metadata) return undefined\n\n    // Whitelist of user-facing metadata properties\n    const whitelist = ['issues', 'fields', 'field']\n\n    const filtered: Record<string, unknown> = {}\n    let hasUserFacingData = false\n\n    for (const key of whitelist) {\n      if (key in metadata && metadata[key] !== undefined) {\n        filtered[key] = metadata[key]\n        hasUserFacingData = true\n      }\n    }\n\n    // Only return metadata if there's actual user-facing data\n    return hasUserFacingData ? filtered : undefined\n  }\n\n  /**\n   * Serialize error to ErrorResponse format for RPC transmission\n   *\n   * @param env - Environment (development | production)\n   * @param translatedMessage - Optional translated message (from GlobalErrorHandler)\n   * @returns ErrorResponse object suitable for JSON serialization\n   */\n  toErrorResponse(env: Environment, translatedMessage?: string): ErrorResponse {\n    const message = translatedMessage ?? this.message\n\n    return {\n      code: this.code,\n      message,\n      timestamp: this.timestamp,\n      // Include filtered user-facing metadata in all environments\n      metadata: ApplicationError.filterMetadata(this.metadata),\n      // Stack trace only in development for debugging\n      // Rewrite first line with translated message for readable debugging\n      stack: env === 'development'\n        ? this.stack?.replace(this.message, message)\n        : undefined,\n    }\n  }\n\n  /**\n   * JSON serialization (used by JSON.stringify)\n   * Defaults to development mode for backward compatibility\n   * Note: This will use the untranslated message key - use GlobalErrorHandler for proper localization\n   */\n  toJSON(): ErrorResponse {\n    return this.toErrorResponse('development')\n  }\n}\n","export type Environment = 'development' | 'staging' | 'production'\n\nexport interface ErrorResponse {\n  /**\n   * Numeric error code for identification and escalation\n   * See error-codes.ts for the complete registry\n   */\n  code: number\n\n  /**\n   * Human-readable error message\n   * Fixed per error type, not customizable\n   */\n  message: string\n\n  /**\n   * ISO timestamp when the error occurred\n   */\n  timestamp: string\n\n  /**\n   * Additional structured data about the error\n   * Only included in development environment\n   */\n  metadata?: Record<string, unknown>\n\n  /**\n   * Stack trace for debugging\n   * Only included in development environment\n   */\n  stack?: string\n}\n\n/**\n * Type guard to check if an object is an ErrorResponse\n */\nexport function isErrorResponse(obj: unknown): obj is ErrorResponse {\n  return (\n    typeof obj === 'object' &&\n    obj !== null &&\n    'code' in obj &&\n    typeof (obj as ErrorResponse).code === 'number' &&\n    'message' in obj &&\n    typeof (obj as ErrorResponse).message === 'string' &&\n    'timestamp' in obj &&\n    typeof (obj as ErrorResponse).timestamp === 'string'\n  )\n}\n","/**\n * Centralized Error Code Registry\n *\n * Error codes are organized by category with specific ranges:\n * - 1000-1999: Validation errors\n * - 2000-2999: Database errors (generic)\n * - 3000-3999: Authentication & Authorization\n * - 4000-4999: Resource errors\n * - 5000-5999: Domain-specific business logic (per module)\n * - 9000-9999: System/Internal errors\n *   - 9000-9099: Router errors\n *   - 9100-9199: Configuration errors\n *   - 9200-9299: Infrastructure errors\n *   - 9300-9399: I18n errors\n */\n\nexport const ERROR_CODES = {\n  /**\n   * Database Errors (2000-2999)\n   * Generic database errors thrown by Prisma client extensions\n   */\n  DATABASE: {\n    /** Generic database error */\n    GENERIC: 2000,\n    /** Record not found in database */\n    RECORD_NOT_FOUND: 2001,\n    /** Unique constraint violation */\n    UNIQUE_CONSTRAINT: 2002,\n    /** Foreign key constraint violation */\n    FOREIGN_KEY_CONSTRAINT: 2003,\n    /** Database connection failed */\n    CONNECTION_FAILED: 2004,\n    /** Database timeout */\n    TIMEOUT: 2005,\n    /** Null constraint violation */\n    NULL_CONSTRAINT: 2006,\n    /** Too many database connections */\n    TOO_MANY_CONNECTIONS: 2007,\n    /** Transaction conflict or deadlock */\n    TRANSACTION_CONFLICT: 2008,\n  },\n\n  /**\n   * Authentication Errors (3000-3099)\n   * Authentication-related failures\n   */\n  AUTH: {\n    /** Invalid credentials provided */\n    INVALID_CREDENTIALS: 3000,\n    /** Session expired or invalid */\n    SESSION_EXPIRED: 3001,\n    /** Account locked or disabled */\n    ACCOUNT_LOCKED: 3002,\n    /** Invalid or expired token */\n    INVALID_TOKEN: 3003,\n    /** Context not initialized */\n    CONTEXT_NOT_INITIALIZED: 3004,\n    /** User not authenticated */\n    USER_NOT_AUTHENTICATED: 3005,\n    /** Email verification required before login */\n    EMAIL_NOT_VERIFIED: 3007,\n    /** Password doesn't meet minimum length */\n    PASSWORD_TOO_SHORT: 3008,\n    /** Password exceeds maximum length */\n    PASSWORD_TOO_LONG: 3009,\n    /** Account with email already exists */\n    ACCOUNT_ALREADY_EXISTS: 3010,\n    /** User creation failed */\n    FAILED_TO_CREATE_USER: 3011,\n    /** Session creation failed */\n    FAILED_TO_CREATE_SESSION: 3012,\n    /** User update failed */\n    FAILED_TO_UPDATE_USER: 3013,\n    /** Social account already linked */\n    SOCIAL_ACCOUNT_LINKED: 3014,\n    /** Last account cannot be unlinked */\n    CANNOT_UNLINK_LAST_ACCOUNT: 3015,\n  },\n\n  /**\n   * Authorization Errors (3100-3199)\n   * Permission and access control failures\n   */\n  AUTHZ: {\n    /** Insufficient permissions */\n    FORBIDDEN: 3100,\n    /** Resource access denied */\n    ACCESS_DENIED: 3101,\n    /** User lacks required role */\n    INSUFFICIENT_PERMISSIONS: 3102,\n  },\n\n  /**\n   * Resource Errors (4000-4999)\n   * Generic resource-related errors\n   */\n  RESOURCE: {\n    /** Generic resource not found */\n    NOT_FOUND: 4000,\n    /** Route/endpoint not found */\n    ROUTE_NOT_FOUND: 4004,\n    /** Resource conflict or duplicate */\n    CONFLICT: 4100,\n    /** Resource already exists */\n    ALREADY_EXISTS: 4101,\n  },\n\n  /**\n   * Validation Errors (1000-1999)\n   * Input validation failures\n   */\n  VALIDATION: {\n    /** Generic validation error */\n    GENERIC: 1000,\n    /** Required field missing */\n    REQUIRED_FIELD: 1001,\n    /** Invalid format */\n    INVALID_FORMAT: 1002,\n    /** Schema validation failed */\n    SCHEMA_VALIDATION: 1003,\n    /** Request validation failed (OpenAPI, etc.) */\n    REQUEST_VALIDATION: 1004,\n  },\n\n  /**\n   * Router Errors (9000-9099)\n   * Router and controller-related INTERNAL errors\n   */\n  ROUTER: {\n    /** Controller registration error */\n    CONTROLLER_REGISTRATION_ERROR: 9005,\n    /** Controller method not found */\n    CONTROLLER_METHOD_NOT_FOUND: 9006,\n    /** OpenAPI route registration failed */\n    OPENAPI_ROUTE_REGISTRATION: 9008,\n  },\n\n  /**\n   * I18n Errors (9300-9399)\n   * Internationalization and localization errors\n   */\n  I18N: {\n    /** Translation key missing from all locales */\n    TRANSLATION_MISSING: 9300,\n    /** Requested locale not supported */\n    LOCALE_NOT_SUPPORTED: 9301,\n  },\n\n  /**\n   * System Errors (9000-9999)\n   * Internal system errors and unexpected failures\n   */\n  SYSTEM: {\n    /** Internal server error */\n    INTERNAL_ERROR: 9000,\n\n    // Configuration Errors (9100-9199)\n    /** Generic configuration error */\n    CONFIGURATION_ERROR: 9100,\n    /** ConfigService not initialized */\n    CONFIG_NOT_INITIALIZED: 9101,\n    /** Module already registered */\n    MODULE_ALREADY_REGISTERED: 9102,\n    /** Circular module dependency detected */\n    MODULE_CIRCULAR_DEPENDENCY: 9103,\n    /** Module dependency not found */\n    MODULE_DEPENDENCY_NOT_FOUND: 9104,\n    /** Invalid error code range */\n    INVALID_ERROR_CODE_RANGE: 9105,\n    /** Invalid module provider configuration */\n    INVALID_MODULE_PROVIDER: 9106,\n    /** ConfigModule.forRoot() was not called */\n    CONFIG_MODULE_NOT_INITIALIZED: 9107,\n\n    // Infrastructure Errors (9200-9299)\n    /** Generic infrastructure error */\n    INFRASTRUCTURE_ERROR: 9200,\n    /** Execution context not initialized */\n    EXECUTION_CONTEXT_NOT_INITIALIZED: 9201,\n    /** Request container not initialized */\n    REQUEST_CONTAINER_NOT_INITIALIZED: 9202,\n    /** Queue binding not found */\n    QUEUE_BINDING_NOT_FOUND: 9203,\n    /** Cron job execution failed */\n    CRON_EXECUTION_FAILED: 9204,\n    /** Queue provider not supported */\n    QUEUE_PROVIDER_NOT_SUPPORTED: 9205,\n    /** body() called on WebSocket gateway context */\n    WEBSOCKET_BODY_NOT_AVAILABLE: 9206,\n    /** Duplicate WebSocket event decorator on a gateway */\n    WEBSOCKET_DUPLICATE_EVENT_HANDLER: 9207,\n  },\n} as const\n\n/**\n * Recursively extract all leaf values from a nested object type\n * Similar to DeepKeys but extracts values instead of keys\n *\n * Example:\n *   { DATABASE: { GENERIC: 2000, NOT_FOUND: 2001 }, AUTH: { INVALID: 3000 } }\n *   becomes\n *   2000 | 2001 | 3000\n */\ntype DeepValues<T> = T extends object\n  ? { [K in keyof T]: DeepValues<T[K]> }[keyof T]\n  : T\n\n/**\n * Type helper to extract all error code values\n * Union type of all numeric error codes defined in ERROR_CODES\n *\n * Type: 2000 | 2001 | 2002 | ... | 9203\n */\nexport type ErrorCode = DeepValues<typeof ERROR_CODES>\n","import type { ContentfulStatusCode } from 'hono/utils/http-status'\nimport { ERROR_CODES } from './error-codes'\n\n/**\n * Maps error codes to HTTP status codes\n *\n * This utility is used by the frontend to set appropriate HTTP status codes\n * when returning errors from API routes.\n *\n * @param code - Numeric error code from ERROR_CODES registry\n * @returns HTTP status code (200-599)\n */\nexport function getHttpStatus(code: number): ContentfulStatusCode {\n  // Validation errors (1000-1999) → 400 Bad Request\n  if (code >= 1000 && code < 2000) {\n    return 400\n  }\n\n  // Database errors (2000-2999)\n  if (code >= 2000 && code < 3000) {\n    // Record not found → 404\n    if (code === ERROR_CODES.DATABASE.RECORD_NOT_FOUND) return 404\n    // Unique constraint / conflict → 409\n    if (code === ERROR_CODES.DATABASE.UNIQUE_CONSTRAINT) return 409\n    // Other database errors → 500\n    return 500\n  }\n\n  // Authentication errors (3000-3099) → 401 Unauthorized\n  if (code >= 3000 && code < 3100) {\n    return 401\n  }\n\n  // Authorization errors (3100-3199) → 403 Forbidden\n  if (code >= 3100 && code < 3200) {\n    return 403\n  }\n\n  // Resource not found (4000-4099) → 404 Not Found\n  if (code >= 4000 && code < 4100) {\n    return 404\n  }\n\n  // Resource conflict (4100-4199) → 409 Conflict\n  if (code >= 4100 && code < 4200) {\n    return 409\n  }\n\n  // Business logic errors (5000-5999)\n  if (code >= 5000 && code < 6000) {\n    // Domain-specific NOT_FOUND errors → 404\n    // 5000: NOTES.NOT_FOUND\n    // 5100: USERS.NOT_FOUND\n    // 5200: APPLICATIONS.NOT_FOUND\n    if (code === 5000 || code === 5100 || code === 5200) {\n      return 404\n    }\n    // Other business logic errors → 422 Unprocessable Entity\n    return 422\n  }\n\n  // System errors (9000-9999) → 500 Internal Server Error\n  if (code >= 9000) {\n    return 500\n  }\n\n  // Default to 500 for unknown codes\n  return 500\n}\n","/**\n * Dependency injection tokens for the router system\n */\nexport const ROUTER_TOKENS = {\n  /**\n   * Token for RouterContext (request-scoped)\n   * Contains Hono context wrapper with helper methods\n   */\n  RouterContext: Symbol.for('stratal:router:context'),\n} as const\n","import { ERROR_CODES } from '../../errors'\nimport { ApplicationError } from '../../errors'\n\n/**\n * ConditionalBindingFallbackError\n *\n * Thrown when a conditional binding predicate returns false but no fallback\n * implementation was provided and no existing registration exists for the token.\n *\n * This typically indicates a misconfiguration in the DI setup where:\n * - A `when().use().give()` chain was used without `otherwise()`\n * - AND the token wasn't previously registered\n * - AND the predicate evaluated to false at resolution time\n */\nexport class ConditionalBindingFallbackError extends ApplicationError {\n  constructor(token: string) {\n    super(\n      'errors.conditionalBindingFallback',\n      ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR,\n      { token }\n    )\n  }\n}\n","import { ERROR_CODES } from '../../errors'\nimport { ApplicationError } from '../../errors'\n\n/**\n * RequestScopeOperationNotAllowedError\n *\n * Thrown when attempting to call a method that is not allowed on the current container scope.\n * - `createRequestScope()` and `runInRequestScope()` can only be called on global containers\n */\nexport class RequestScopeOperationNotAllowedError extends ApplicationError {\n  constructor(methodName: string) {\n    super(\n      'errors.requestScopeOperationNotAllowed',\n      ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR,\n      { methodName }\n    )\n  }\n}\n","/**\n * Conditional Binding Builder\n *\n * Provides a fluent API for predicate-based service registration.\n * The predicate is evaluated lazily at resolution time using tsyringe's\n * predicateAwareClassFactory.\n *\n * @example With explicit fallback\n * ```typescript\n * container\n *   .when((c) => c.resolve(CONFIG_TOKEN).get('env') === 'development')\n *   .use(FORMATTER_TOKEN)\n *   .give(PrettyFormatter)\n *   .otherwise(JsonFormatter)\n * ```\n *\n * @example Without fallback (uses existing registration)\n * ```typescript\n * container\n *   .when((c) => c.resolve(FEATURE_FLAG_TOKEN).isEnabled('newFeature'))\n *   .use(SERVICE_TOKEN)\n *   .give(NewServiceImpl)  // Falls back to existing if predicate is false\n * ```\n */\n\nimport type { DependencyContainer } from 'tsyringe'\nimport { predicateAwareClassFactory } from 'tsyringe'\nimport type InjectionToken from 'tsyringe/dist/typings/providers/injection-token'\nimport type { Constructor } from '../types'\nimport { ConditionalBindingFallbackError } from './errors'\nimport type { WhenOptions } from './types'\n\n/**\n * Container interface for predicate functions\n * Using a minimal interface to avoid circular imports\n */\nexport interface PredicateContainer {\n  resolve<T>(token: InjectionToken<T>): T\n  isRegistered<T>(token: InjectionToken<T>): boolean\n}\n\n/**\n * Initial builder returned by container.when()\n */\nexport interface ConditionalBindingBuilder {\n  /**\n   * Specify the token to conditionally bind\n   *\n   * @param token - DI token for the service\n   * @returns Builder for specifying implementations\n   */\n  use<T extends object>(token: InjectionToken<T>): ConditionalBindingUse<T>\n}\n\n/**\n * Builder after specifying token with use()\n */\nexport interface ConditionalBindingUse<T extends object> {\n  /**\n   * Specify the implementation when predicate returns true.\n   * Registration is completed immediately.\n   *\n   * If predicate is false at resolution time:\n   * - Uses `otherwise()` implementation if provided\n   * - Falls back to existing registration if available\n   * - Throws error if no fallback exists\n   *\n   * @param implementation - Service class to use when predicate is true\n   * @returns Builder for optional fallback specification\n   */\n  give(implementation: Constructor<T>): ConditionalBindingGive<T>\n}\n\n/**\n * Builder after specifying true implementation with give()\n * Registration is already complete at this point.\n */\nexport interface ConditionalBindingGive<T extends object> {\n  /**\n   * Optionally specify a fallback implementation when predicate returns false.\n   * This re-registers with the explicit fallback instead of existing registration.\n   *\n   * @param implementation - Service class to use when predicate is false\n   */\n  otherwise(implementation: Constructor<T>): void\n}\n\n/**\n * Implementation of ConditionalBindingBuilder\n *\n * @internal\n */\nexport class ConditionalBindingBuilderImpl implements ConditionalBindingBuilder {\n  constructor(\n    private readonly tsyringeContainer: DependencyContainer,\n    private readonly predicateContainer: PredicateContainer,\n    private readonly predicate: (container: PredicateContainer) => boolean,\n    private readonly options: WhenOptions\n  ) { }\n\n  use<T extends object>(token: InjectionToken<T>): ConditionalBindingUse<T> {\n    return new ConditionalBindingUseImpl<T>(\n      this.tsyringeContainer,\n      this.predicateContainer,\n      this.predicate,\n      this.options,\n      token\n    )\n  }\n}\n\n/**\n * Implementation of ConditionalBindingUse\n *\n * @internal\n */\nclass ConditionalBindingUseImpl<T extends object> implements ConditionalBindingUse<T> {\n  constructor(\n    private readonly tsyringeContainer: DependencyContainer,\n    private readonly predicateContainer: PredicateContainer,\n    private readonly predicate: (container: PredicateContainer) => boolean,\n    private readonly options: WhenOptions,\n    private readonly token: InjectionToken<T>\n  ) { }\n\n  give(trueImplementation: Constructor<T>): ConditionalBindingGive<T> {\n    // Get fallback: existing registration or a class that throws\n    const falseImplementation = this.getFallbackImplementation()\n\n    // Register using predicateAwareClassFactory\n    this.registerWithPredicate(trueImplementation, falseImplementation)\n\n    // Return builder for optional otherwise()\n    return {\n      otherwise: (implementation: Constructor<T>) => {\n        this.registerWithPredicate(trueImplementation, implementation,)\n      },\n    }\n  }\n\n  /**\n   * Get fallback implementation: existing registration or throw-on-resolve class\n   */\n  private getFallbackImplementation(): Constructor<T> {\n    // Check if token is already registered\n    if (this.tsyringeContainer.isRegistered(this.token)) {\n      // Create a class that resolves the existing registration\n      // We need to capture the current registration before we overwrite it\n      const existingInstance = this.tsyringeContainer.resolve<T>(this.token)\n\n      // Return a \"class\" that just returns the existing instance\n      // Using a factory wrapper since predicateAwareClassFactory expects a constructor\n      return class ExistingInstanceWrapper {\n        static instance = existingInstance\n        constructor() {\n          return ExistingInstanceWrapper.instance as unknown as ExistingInstanceWrapper\n        }\n      } as unknown as Constructor<T>\n    }\n\n    // No existing registration - create a class that throws\n    const tokenStr = typeof this.token === 'symbol'\n      ? (this.token.description ?? 'unknown')\n      : typeof this.token === 'function'\n        ? this.token.name\n        // eslint-disable-next-line @typescript-eslint/no-base-to-string -- token can be string or object; String() is intentional fallback\n        : String(this.token)\n    return class NoFallbackError {\n      constructor() {\n        throw new ConditionalBindingFallbackError(tokenStr)\n      }\n    } as unknown as Constructor<T>\n  }\n\n  private registerWithPredicate(\n    trueImplementation: Constructor<T>,\n    falseImplementation: Constructor<T>\n  ): void {\n    const { predicate, predicateContainer, options } = this\n\n    this.tsyringeContainer.register(this.token, {\n      useFactory: predicateAwareClassFactory<T>(\n        () => predicate(predicateContainer),\n        trueImplementation,\n        falseImplementation,\n        options.cache ?? false\n      )\n    })\n  }\n}\n","/**\n * Unified DI Container\n *\n * Provides a developer-friendly wrapper around tsyringe with:\n * - Auto-token extraction from decorator metadata\n * - Auto-scope detection from decorator metadata\n * - Seamless global/request scope interoperability\n * - Request scope lifecycle management\n *\n * **Two-Tier Container Architecture:**\n * ```\n * Global Container (managed by Container)\n *        ↓\n *   All services registered here\n *   (singletons + container-scoped)\n *        ↓\n * Request Container (child, per request)\n *        ↓\n *   Fresh instances for ContainerScoped services\n *   RouterContext registered per request\n * ```\n */\nimport { type DependencyContainer, type Lifecycle } from 'tsyringe'\nimport type InjectionToken from 'tsyringe/dist/typings/providers/injection-token'\nimport type { RouterContext } from '../router/router-context'\nimport { ROUTER_TOKENS } from '../router/router.tokens'\nimport type { Constructor } from '../types'\nimport { ConditionalBindingBuilderImpl, type ConditionalBindingBuilder, type PredicateContainer } from './conditional-binding-builder'\nimport { RequestScopeOperationNotAllowedError } from './errors/request-scope-operation-not-allowed.error'\nimport { CONTAINER_TOKEN } from './tokens'\nimport type { ExtensionDecorator, Scope, WhenOptions } from './types'\n\n/**\n * Options for creating a Container instance\n */\nexport interface ContainerOptions {\n  /** Pre-created DependencyContainer */\n  container: DependencyContainer\n  /** Whether this is a request-scoped container */\n  isRequestScoped?: boolean\n}\n\n/**\n * Unified Container for DI management\n *\n * Manages the two-tier container hierarchy:\n * - Global scope: Singletons, base instances of request-scoped services\n * - Request scope: Context-enriched instances per HTTP request\n *\n * @example Basic registration\n * ```typescript\n * import { container as tsyringeRootContainer } from 'tsyringe'\n *\n * const container = new Container({\n *   container: tsyringeRootContainer.createChildContainer()\n * })\n *\n * container.register(I18nService)\n * container.register(MY_TOKEN, MyService)\n * container.registerSingleton(ConfigService)\n * container.registerValue(MY_TOKEN, myInstance)\n * ```\n *\n * @example Request scope (automatic lifecycle)\n * ```typescript\n * await container.runInRequestScope(routerContext, async (requestContainer) => {\n *   const i18n = requestContainer.resolve(I18N_TOKEN)\n * })\n * ```\n */\nexport class Container {\n  private readonly container: DependencyContainer\n  private readonly isRequestScoped: boolean\n\n  constructor(options: ContainerOptions) {\n    this.isRequestScoped = options.isRequestScoped ?? false\n    this.container = options.container\n\n    // Only register CONTAINER_TOKEN for global container (not request-scoped)\n    if (!this.isRequestScoped) {\n      this.container.register(CONTAINER_TOKEN, { useValue: this })\n    }\n  }\n\n  // ============================================================\n  // Registration Methods\n  // ============================================================\n\n  /**\n   * Register a service with optional explicit token and scope\n   */\n  register<T extends object>(serviceClass: Constructor<T>, scope?: Scope): void\n  register<T extends object>(token: InjectionToken<T>, serviceClass: Constructor<T>, scope?: Scope): void\n  register<T extends object>(\n    tokenOrClass: InjectionToken<T> | Constructor<T>,\n    serviceClassOrScope?: Constructor<T> | Scope,\n    scope?: Scope\n  ): void {\n    let token: InjectionToken<T>\n    let serviceClass: Constructor<T>\n    let lifecycle: Lifecycle | undefined\n\n    if (typeof serviceClassOrScope === 'function') {\n      // Called as register(token, class, scope?)\n      token = tokenOrClass as InjectionToken<T>\n      serviceClass = serviceClassOrScope\n      lifecycle = scope as Lifecycle | undefined\n    } else {\n      // Called as register(class, scope?)\n      token = tokenOrClass as Constructor<T>\n      serviceClass = tokenOrClass as Constructor<T>\n      lifecycle = serviceClassOrScope as Lifecycle | undefined\n    }\n\n    if (lifecycle !== undefined) {\n      this.container.register(token, { useClass: serviceClass }, { lifecycle })\n    } else {\n      this.container.register(token, { useClass: serviceClass })\n    }\n  }\n\n  /**\n   * Register a service as singleton\n   */\n  registerSingleton<T extends object>(serviceClass: Constructor<T>): void\n  registerSingleton<T extends object>(token: InjectionToken<T>, serviceClass: Constructor<T>): void\n  registerSingleton<T extends object>(\n    tokenOrClass: InjectionToken<T> | Constructor<T>,\n    serviceClass?: Constructor<T>\n  ): void {\n    if (serviceClass !== undefined) {\n      this.container.registerSingleton(tokenOrClass as InjectionToken<T>, serviceClass)\n    } else {\n      const targetClass = tokenOrClass as Constructor<T>\n      this.container.registerSingleton(targetClass, targetClass)\n    }\n  }\n\n  /**\n   * Register a value (instance) directly\n   */\n  registerValue<T>(token: InjectionToken<T>, value: T): void {\n    this.container.register(token, { useValue: value })\n  }\n\n  /**\n   * Register with factory function\n   */\n  registerFactory<T>(\n    token: InjectionToken<T>,\n    factory: (container: Container) => T\n  ): void {\n    this.container.register(token, { useFactory: () => factory(this) })\n  }\n\n  /**\n   * Register an alias to an existing token\n   */\n  registerExisting<T>(alias: InjectionToken<T>, target: InjectionToken<T>): void {\n    this.container.register(alias, { useToken: target })\n  }\n\n  // ============================================================\n  // Resolution Methods\n  // ============================================================\n\n  /**\n   * Resolve a service from the container\n   */\n  resolve<T>(token: InjectionToken<T>): T {\n    return this.container.resolve<T>(token)\n  }\n\n  /**\n   * Check if a token is registered\n   */\n  isRegistered<T>(token: InjectionToken<T>): boolean {\n    return this.container.isRegistered(token)\n  }\n\n  // ============================================================\n  // Conditional Registration Methods\n  // ============================================================\n\n  /**\n   * Start a conditional binding with predicate evaluation\n   */\n  when(\n    predicate: (container: PredicateContainer) => boolean,\n    options: WhenOptions = {}\n  ): ConditionalBindingBuilder {\n    return new ConditionalBindingBuilderImpl(\n      this.container,\n      this,\n      predicate,\n      options\n    )\n  }\n\n  /**\n   * Replace a service registration with a decorated version\n   */\n  extend<T>(token: InjectionToken<T>, decorator: ExtensionDecorator<T>): void {\n    const currentInstance = this.container.resolve<T>(token)\n    const decoratedInstance = decorator(currentInstance, this)\n    this.container.register(token, { useValue: decoratedInstance })\n  }\n\n  // ============================================================\n  // Request Scope Management\n  // ============================================================\n\n  /**\n   * Run callback within request scope\n   *\n   * Creates a child container with fresh instances for services registered with `scope: Scope.Request`.\n   * Callback receives the request-scoped container as argument.\n   *\n   * Can only be called on global container (not request-scoped).\n   */\n  async runInRequestScope<T>(\n    routerContext: RouterContext,\n    callback: (requestContainer: Container) => T | Promise<T>\n  ): Promise<T> {\n    if (this.isRequestScoped) {\n      throw new RequestScopeOperationNotAllowedError('runInRequestScope')\n    }\n\n    const requestContainer = this.createRequestScope(routerContext)\n    try {\n      return await callback(requestContainer)\n    } finally {\n      await requestContainer.dispose()\n    }\n  }\n\n  /**\n   * Create request scope container\n   *\n   * Can only be called on global container (not request-scoped).\n   */\n  createRequestScope(routerContext: RouterContext): Container {\n    if (this.isRequestScoped) {\n      throw new RequestScopeOperationNotAllowedError('createRequestScope')\n    }\n\n    const childContainer = this.container.createChildContainer()\n    childContainer.register(ROUTER_TOKENS.RouterContext, { useValue: routerContext })\n\n    return new Container({ container: childContainer, isRequestScoped: true })\n  }\n\n  // ============================================================\n  // Escape Hatches\n  // ============================================================\n\n  /**\n   * Get underlying tsyringe container\n   */\n  getTsyringeContainer(): DependencyContainer {\n    return this.container\n  }\n\n  dispose() {\n    return this.container.dispose()\n  }\n}\n\n// Re-export tsyringe utilities for convenience\nexport { container, delay, inject, injectable, instancePerContainerCachingFactory, singleton } from 'tsyringe'\nexport type { DependencyContainer } from 'tsyringe'\n\n","/**\n * DI Type Definitions\n *\n * Core type definitions for the dependency injection system.\n * Simplified after removing LazyProxy - no more type wrappers needed.\n */\n\nimport { Lifecycle } from 'tsyringe'\nimport type InjectionToken from 'tsyringe/dist/typings/providers/injection-token'\n\n/**\n * Service scope for DI registration\n *\n * Maps directly to tsyringe's Lifecycle enum.\n * Scope is specified at registration time via provider configuration,\n * not at class decoration time.\n *\n * @example\n * ```typescript\n * // In module providers:\n * { provide: MY_TOKEN, useClass: MyService, scope: Scope.Singleton }\n *\n * // In Application.ts:\n * container.register(MY_TOKEN, MyService, Scope.Request)\n * ```\n */\n/* eslint-disable @typescript-eslint/prefer-literal-enum-member -- values must stay in sync with tsyringe Lifecycle */\nexport enum Scope {\n  /** New instance per resolution (default) */\n  Transient = Lifecycle.Transient,\n  /** Single instance shared globally */\n  Singleton = Lifecycle.Singleton,\n  /** New instance per child container (per request) */\n  Request = Lifecycle.ContainerScoped,\n}\n/* eslint-enable @typescript-eslint/prefer-literal-enum-member */\n\n/**\n * Options for conditional binding with `when()` method\n */\nexport interface WhenOptions {\n  /**\n   * Cache predicate result after first evaluation.\n   * When true, the predicate is evaluated once and the result is reused.\n   * When false (default), predicate is evaluated on each resolution.\n   */\n  cache?: boolean\n}\n\n/**\n * Decorator function type for extend() method\n *\n * @template T The service type being decorated\n */\nexport type ExtensionDecorator<T> = (service: T, container: ContainerLike) => T\n\n/**\n * Minimal container interface for decorator functions\n * Avoids circular dependency with Container class\n */\nexport interface ContainerLike {\n  resolve<T>(token: InjectionToken<T>): T\n}\n\n","/**\n * I18n Module DI Tokens\n * Symbol-based tokens to avoid string collisions\n */\n\nexport const I18N_TOKENS = {\n  /** MessageLoaderService - loads and caches locale messages */\n  MessageLoader: Symbol.for('stratal:i18n:message:loader'),\n  /** I18nService - request-scoped translation service */\n  I18nService: Symbol.for('stratal:i18n:service'),\n  /** I18nModuleOptions - configuration options from forRoot() */\n  Options: Symbol.for('stratal:i18n:options')\n} as const\n","import { ERROR_CODES } from './error-codes'\nimport { ApplicationError } from './application-error'\n\n/**\n * InternalError\n *\n * Represents an unexpected internal server error.\n * Used to wrap unknown errors that don't fit into specific error categories.\n *\n * This error is thrown when:\n * - An unexpected exception occurs\n * - An error type is not recognized\n * - A system-level failure happens\n */\nexport class InternalError extends ApplicationError {\n  constructor(metadata?: Record<string, unknown>) {\n    super(\n      'errors.internalError',\n      ERROR_CODES.SYSTEM.INTERNAL_ERROR,\n      metadata\n    )\n  }\n}\n","import { ApplicationError } from './application-error'\n\n/**\n * Type guard to check if an error is an ApplicationError\n *\n * @param error - The error to check\n * @returns True if the error is an ApplicationError instance\n */\nexport function isApplicationError(error: unknown): error is ApplicationError {\n  return error instanceof ApplicationError\n}\n","import { inject } from 'tsyringe'\nimport { DI_TOKENS } from '../di'\nimport { Transient } from '../di/decorators'\nimport { type StratalEnv } from '../env'\nimport { I18N_TOKENS } from '../i18n/i18n.tokens'\nimport type { II18nService, MessageKeys } from '../i18n/i18n.types'\nimport { LOGGER_TOKENS, type LoggerService } from '../logger'\nimport { ApplicationError } from './application-error'\nimport type { Environment, ErrorResponse } from './error-response'\nimport { InternalError } from './internal-error'\nimport { isApplicationError } from './is-application-error'\n\n/**\n * Log severity levels\n */\ntype LogSeverity = 'error' | 'warn' | 'info'\n\n/**\n * GlobalErrorHandler\n *\n * Centralized error handler registered in the DI container.\n * Responsible for:\n * - Intercepting all errors in the application\n * - Logging errors with appropriate severity via Logger service\n * - Translating error message keys using I18nService (when available)\n * - Serializing errors for RPC transmission\n * - Wrapping unexpected errors in InternalError\n *\n * **Translation Availability by Context:**\n *\n * ✅ **HTTP Requests**: Errors are fully translated\n *    - GlobalErrorHandler resolved from request container\n *    - I18nService available via AsyncLocalStorage with user's locale\n *    - Full translation with parameter interpolation\n *\n * ✅ **Queue Processing**: Errors are fully translated\n *    - Error handling executes inside AsyncLocalStorage scope\n *    - Locale extracted from queue message metadata\n *    - Request container created with mock RouterContext\n *    - I18nService available with correct locale\n *\n * ⚠️ **RPC/Startup**: Message keys returned as-is (i18n unavailable)\n *    - No request context available during service binding or startup\n *    - No locale information available\n *    - Frontend can translate message keys using its own i18n if needed\n *    - This is expected behavior, not a bug\n *\n * **Implementation Note:**\n * The `isAvailable()` check exists to gracefully handle RPC/startup contexts\n * where no request container exists. For HTTP and Queue contexts, i18n is\n * always available thanks to AsyncLocalStorage scope propagation. This follows\n * the \"Laravel philosophy\" - transparent dependency injection for request contexts,\n * with explicit handling only for legitimate non-request edge cases.\n */\n@Transient()\nexport class GlobalErrorHandler {\n  private readonly environment: Environment\n  constructor(\n    @inject(LOGGER_TOKENS.LoggerService) private readonly logger: LoggerService,\n    @inject(I18N_TOKENS.I18nService) private readonly i18n: II18nService,\n    @inject(DI_TOKENS.CloudflareEnv)\n    private readonly env: StratalEnv,\n  ) {\n    this.environment = this.env.ENVIRONMENT as Environment\n  }\n\n  /**\n   * Handle an error, log it, and serialize for response\n   *\n   * @param error - The error to handle\n   * @returns Serialized ErrorResponse for RPC transmission\n   */\n  handle(error: unknown): ErrorResponse {\n    // Check if it's an ApplicationError\n    if (isApplicationError(error)) {\n      // Translate once, use for both logging and response\n      const translatedMessage = this.translateError(error)\n\n      this.log(error, translatedMessage)\n\n      return error.toErrorResponse(this.environment, translatedMessage)\n    }\n\n    // Unexpected error - wrap in InternalError\n    this.logUnexpectedError(error)\n\n    const internalError = new InternalError({\n      originalError: error instanceof Error ? error.message : String(error),\n      stack: error instanceof Error ? error.stack : undefined,\n    })\n\n    const translatedMessage = this.translateError(internalError)\n\n    return internalError.toErrorResponse(this.environment, translatedMessage)\n  }\n\n  /**\n   * Translate error message key using I18nService\n   * Uses error metadata as interpolation parameters\n   *\n   * No try/catch - if translation fails, it's a bug that should fail loudly\n   *\n   * **Note**: This method is only called when isAvailable() returns true,\n   * so the service is guaranteed to be resolved.\n   *\n   * @param error - ApplicationError with messageKey and metadata\n   * @returns Translated message string\n   */\n  private translateError(error: ApplicationError): string {\n    // Cast metadata to MessageParams (assuming values are string | number)\n    const params = error.metadata as Record<string, string | number> | undefined\n    return this.i18n.t(error.message as MessageKeys, params)\n  }\n\n  /**\n   * Log an ApplicationError with appropriate severity\n   */\n  private log(error: ApplicationError, translatedMessage: string): void {\n    const severity = this.getSeverity(error.code)\n\n    const logData = {\n      code: error.code,\n      message: translatedMessage,\n      timestamp: error.timestamp,\n      metadata: error.metadata,\n      name: error.name,\n    }\n\n    switch (severity) {\n      case 'error':\n        this.logger.error('[ApplicationError]', logData)\n        break\n      case 'warn':\n        this.logger.warn('[ApplicationError]', logData)\n        break\n      case 'info':\n        this.logger.info('[ApplicationError]', logData)\n        break\n    }\n  }\n\n  /**\n   * Log an unexpected error\n   */\n  private logUnexpectedError(error: unknown): void {\n    this.logger.error('[UnexpectedError]', {\n      error: error instanceof Error ? {\n        message: error.message,\n        stack: error.stack,\n        name: error.name,\n      } : String(error),\n      timestamp: new Date().toISOString(),\n    })\n  }\n\n  /**\n   * Determine log severity based on error code\n   */\n  private getSeverity(code: number): LogSeverity {\n    // System errors (9000+) are critical\n    if (code >= 9000) return 'error'\n\n    // Database errors (2000-2999) are errors\n    if (code >= 2000 && code < 3000) return 'error'\n\n    // Business logic errors (5000-5999) are warnings\n    if (code >= 5000 && code < 6000) return 'warn'\n\n    // Validation errors (1000-1999) are info\n    if (code >= 1000 && code < 2000) return 'info'\n\n    // Auth/Resource errors (3000-4999) are warnings\n    if (code >= 3000 && code < 5000) return 'warn'\n\n    // Default to error\n    return 'error'\n  }\n}\n","import { ApplicationError } from './application-error'\nimport { ERROR_CODES } from './error-codes'\n\n/**\n * RequestContainerNotInitializedError\n *\n * Thrown when attempting to access the request-scoped container before it has been initialized.\n * This typically indicates that the RouterService middleware hasn't run yet,\n * or the router context is being accessed outside of a request lifecycle.\n */\nexport class RequestContainerNotInitializedError extends ApplicationError {\n  constructor() {\n    super(\n      'errors.requestContainerNotInitialized',\n      ERROR_CODES.SYSTEM.REQUEST_CONTAINER_NOT_INITIALIZED\n    )\n  }\n}\n","import { ApplicationError } from './application-error'\nimport { ERROR_CODES } from './error-codes'\n\n/**\n * StratalNotInitializedError\n *\n * Thrown when attempting to resolve the Application instance before Stratal has been instantiated.\n * This typically indicates that the Stratal instance is not exported as the default export.\n */\nexport class StratalNotInitializedError extends ApplicationError {\n  constructor() {\n    super(\n      'errors.stratalNotInitialized',\n      ERROR_CODES.SYSTEM.INFRASTRUCTURE_ERROR\n    )\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA0BA,IAAsB,mBAAtB,MAAsB,yBAAyB,MAAM;;;;;;CAMnD,OAAO,qBAAqB;;;;;CAM5B;;;;CAKA;;;;;;;CAQA;;;;;;CAOA,YACE,SACA,MACA,UACA;AAEA,QAAM,QAAQ;AAGd,SAAO,eAAe,MAAM,IAAI,OAAO,UAAU;AAEjD,OAAK,OAAO,KAAK,YAAY;AAC7B,OAAK,OAAO;AACZ,OAAK,6BAAY,IAAI,MAAM,EAAC,aAAa;AACzC,OAAK,WAAW;AAKhB,MAAI,iBAAiB,sBAAsB,MAAM,kBAC/C,OAAM,kBAAkB,MAAM,KAAK,YAAY;;;;;;;;;;;;;;;;;;CAoBnD,OAAe,eACb,UACqC;AACrC,MAAI,CAAC,SAAU,QAAO,KAAA;EAGtB,MAAM,YAAY;GAAC;GAAU;GAAU;GAAQ;EAE/C,MAAM,WAAoC,EAAE;EAC5C,IAAI,oBAAoB;AAExB,OAAK,MAAM,OAAO,UAChB,KAAI,OAAO,YAAY,SAAS,SAAS,KAAA,GAAW;AAClD,YAAS,OAAO,SAAS;AACzB,uBAAoB;;AAKxB,SAAO,oBAAoB,WAAW,KAAA;;;;;;;;;CAUxC,gBAAgB,KAAkB,mBAA2C;EAC3E,MAAM,UAAU,qBAAqB,KAAK;AAE1C,SAAO;GACL,MAAM,KAAK;GACX;GACA,WAAW,KAAK;GAEhB,UAAU,iBAAiB,eAAe,KAAK,SAAS;GAGxD,OAAO,QAAQ,gBACX,KAAK,OAAO,QAAQ,KAAK,SAAS,QAAQ,GAC1C,KAAA;GACL;;;;;;;CAQH,SAAwB;AACtB,SAAO,KAAK,gBAAgB,cAAc;;;;;;;;AClH9C,SAAgB,gBAAgB,KAAoC;AAClE,QACE,OAAO,QAAQ,YACf,QAAQ,QACR,UAAU,OACV,OAAQ,IAAsB,SAAS,YACvC,aAAa,OACb,OAAQ,IAAsB,YAAY,YAC1C,eAAe,OACf,OAAQ,IAAsB,cAAc;;;;;;;;;;;;;;;;;;;AC7BhD,MAAa,cAAc;CAKzB,UAAU;EAER,SAAS;EAET,kBAAkB;EAElB,mBAAmB;EAEnB,wBAAwB;EAExB,mBAAmB;EAEnB,SAAS;EAET,iBAAiB;EAEjB,sBAAsB;EAEtB,sBAAsB;EACvB;CAMD,MAAM;EAEJ,qBAAqB;EAErB,iBAAiB;EAEjB,gBAAgB;EAEhB,eAAe;EAEf,yBAAyB;EAEzB,wBAAwB;EAExB,oBAAoB;EAEpB,oBAAoB;EAEpB,mBAAmB;EAEnB,wBAAwB;EAExB,uBAAuB;EAEvB,0BAA0B;EAE1B,uBAAuB;EAEvB,uBAAuB;EAEvB,4BAA4B;EAC7B;CAMD,OAAO;EAEL,WAAW;EAEX,eAAe;EAEf,0BAA0B;EAC3B;CAMD,UAAU;EAER,WAAW;EAEX,iBAAiB;EAEjB,UAAU;EAEV,gBAAgB;EACjB;CAMD,YAAY;EAEV,SAAS;EAET,gBAAgB;EAEhB,gBAAgB;EAEhB,mBAAmB;EAEnB,oBAAoB;EACrB;CAMD,QAAQ;EAEN,+BAA+B;EAE/B,6BAA6B;EAE7B,4BAA4B;EAC7B;CAMD,MAAM;EAEJ,qBAAqB;EAErB,sBAAsB;EACvB;CAMD,QAAQ;EAEN,gBAAgB;EAIhB,qBAAqB;EAErB,wBAAwB;EAExB,2BAA2B;EAE3B,4BAA4B;EAE5B,6BAA6B;EAE7B,0BAA0B;EAE1B,yBAAyB;EAEzB,+BAA+B;EAI/B,sBAAsB;EAEtB,mCAAmC;EAEnC,mCAAmC;EAEnC,yBAAyB;EAEzB,uBAAuB;EAEvB,8BAA8B;EAE9B,8BAA8B;EAE9B,mCAAmC;EACpC;CACF;;;;;;;;;;;;ACpLD,SAAgB,cAAc,MAAoC;AAEhE,KAAI,QAAQ,OAAQ,OAAO,IACzB,QAAO;AAIT,KAAI,QAAQ,OAAQ,OAAO,KAAM;AAE/B,MAAI,SAAS,YAAY,SAAS,iBAAkB,QAAO;AAE3D,MAAI,SAAS,YAAY,SAAS,kBAAmB,QAAO;AAE5D,SAAO;;AAIT,KAAI,QAAQ,OAAQ,OAAO,KACzB,QAAO;AAIT,KAAI,QAAQ,QAAQ,OAAO,KACzB,QAAO;AAIT,KAAI,QAAQ,OAAQ,OAAO,KACzB,QAAO;AAIT,KAAI,QAAQ,QAAQ,OAAO,KACzB,QAAO;AAIT,KAAI,QAAQ,OAAQ,OAAO,KAAM;AAK/B,MAAI,SAAS,OAAQ,SAAS,QAAQ,SAAS,KAC7C,QAAO;AAGT,SAAO;;AAIT,KAAI,QAAQ,IACV,QAAO;AAIT,QAAO;;;;;;;AChET,MAAa,gBAAgB,EAK3B,eAAe,OAAO,IAAI,yBAAyB,EACpD;;;;;;;;;;;;;;ACKD,IAAa,kCAAb,cAAqD,iBAAiB;CACpE,YAAY,OAAe;AACzB,QACE,qCACA,YAAY,OAAO,sBACnB,EAAE,OAAO,CACV;;;;;;;;;;;ACXL,IAAa,uCAAb,cAA0D,iBAAiB;CACzE,YAAY,YAAoB;AAC9B,QACE,0CACA,YAAY,OAAO,sBACnB,EAAE,YAAY,CACf;;;;;;;;;;AC6EL,IAAa,gCAAb,MAAgF;CAC9E,YACE,mBACA,oBACA,WACA,SACA;AAJiB,OAAA,oBAAA;AACA,OAAA,qBAAA;AACA,OAAA,YAAA;AACA,OAAA,UAAA;;CAGnB,IAAsB,OAAoD;AACxE,SAAO,IAAI,0BACT,KAAK,mBACL,KAAK,oBACL,KAAK,WACL,KAAK,SACL,MACD;;;;;;;;AASL,IAAM,4BAAN,MAAsF;CACpF,YACE,mBACA,oBACA,WACA,SACA,OACA;AALiB,OAAA,oBAAA;AACA,OAAA,qBAAA;AACA,OAAA,YAAA;AACA,OAAA,UAAA;AACA,OAAA,QAAA;;CAGnB,KAAK,oBAA+D;EAElE,MAAM,sBAAsB,KAAK,2BAA2B;AAG5D,OAAK,sBAAsB,oBAAoB,oBAAoB;AAGnE,SAAO,EACL,YAAY,mBAAmC;AAC7C,QAAK,sBAAsB,oBAAoB,eAAgB;KAElE;;;;;CAMH,4BAAoD;AAElD,MAAI,KAAK,kBAAkB,aAAa,KAAK,MAAM,EAAE;GAGnD,MAAM,mBAAmB,KAAK,kBAAkB,QAAW,KAAK,MAAM;AAItE,UAAO,MAAM,wBAAwB;IACnC,OAAO,WAAW;IAClB,cAAc;AACZ,YAAO,wBAAwB;;;;EAMrC,MAAM,WAAW,OAAO,KAAK,UAAU,WAClC,KAAK,MAAM,eAAe,YAC3B,OAAO,KAAK,UAAU,aACpB,KAAK,MAAM,OAEX,OAAO,KAAK,MAAM;AACxB,SAAO,MAAM,gBAAgB;GAC3B,cAAc;AACZ,UAAM,IAAI,gCAAgC,SAAS;;;;CAKzD,sBACE,oBACA,qBACM;EACN,MAAM,EAAE,WAAW,oBAAoB,YAAY;AAEnD,OAAK,kBAAkB,SAAS,KAAK,OAAO,EAC1C,YAAY,iCACJ,UAAU,mBAAmB,EACnC,oBACA,qBACA,QAAQ,SAAS,MAClB,EACF,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACrHN,IAAa,YAAb,MAAa,UAAU;CACrB;CACA;CAEA,YAAY,SAA2B;AACrC,OAAK,kBAAkB,QAAQ,mBAAmB;AAClD,OAAK,YAAY,QAAQ;AAGzB,MAAI,CAAC,KAAK,gBACR,MAAK,UAAU,SAAS,iBAAiB,EAAE,UAAU,MAAM,CAAC;;CAahE,SACE,cACA,qBACA,OACM;EACN,IAAI;EACJ,IAAI;EACJ,IAAI;AAEJ,MAAI,OAAO,wBAAwB,YAAY;AAE7C,WAAQ;AACR,kBAAe;AACf,eAAY;SACP;AAEL,WAAQ;AACR,kBAAe;AACf,eAAY;;AAGd,MAAI,cAAc,KAAA,EAChB,MAAK,UAAU,SAAS,OAAO,EAAE,UAAU,cAAc,EAAE,EAAE,WAAW,CAAC;MAEzE,MAAK,UAAU,SAAS,OAAO,EAAE,UAAU,cAAc,CAAC;;CAS9D,kBACE,cACA,cACM;AACN,MAAI,iBAAiB,KAAA,EACnB,MAAK,UAAU,kBAAkB,cAAmC,aAAa;OAC5E;GACL,MAAM,cAAc;AACpB,QAAK,UAAU,kBAAkB,aAAa,YAAY;;;;;;CAO9D,cAAiB,OAA0B,OAAgB;AACzD,OAAK,UAAU,SAAS,OAAO,EAAE,UAAU,OAAO,CAAC;;;;;CAMrD,gBACE,OACA,SACM;AACN,OAAK,UAAU,SAAS,OAAO,EAAE,kBAAkB,QAAQ,KAAK,EAAE,CAAC;;;;;CAMrE,iBAAoB,OAA0B,QAAiC;AAC7E,OAAK,UAAU,SAAS,OAAO,EAAE,UAAU,QAAQ,CAAC;;;;;CAUtD,QAAW,OAA6B;AACtC,SAAO,KAAK,UAAU,QAAW,MAAM;;;;;CAMzC,aAAgB,OAAmC;AACjD,SAAO,KAAK,UAAU,aAAa,MAAM;;;;;CAU3C,KACE,WACA,UAAuB,EAAE,EACE;AAC3B,SAAO,IAAI,8BACT,KAAK,WACL,MACA,WACA,QACD;;;;;CAMH,OAAU,OAA0B,WAAwC;EAE1E,MAAM,oBAAoB,UADF,KAAK,UAAU,QAAW,MAAM,EACH,KAAK;AAC1D,OAAK,UAAU,SAAS,OAAO,EAAE,UAAU,mBAAmB,CAAC;;;;;;;;;;CAejE,MAAM,kBACJ,eACA,UACY;AACZ,MAAI,KAAK,gBACP,OAAM,IAAI,qCAAqC,oBAAoB;EAGrE,MAAM,mBAAmB,KAAK,mBAAmB,cAAc;AAC/D,MAAI;AACF,UAAO,MAAM,SAAS,iBAAiB;YAC/B;AACR,SAAM,iBAAiB,SAAS;;;;;;;;CASpC,mBAAmB,eAAyC;AAC1D,MAAI,KAAK,gBACP,OAAM,IAAI,qCAAqC,qBAAqB;EAGtE,MAAM,iBAAiB,KAAK,UAAU,sBAAsB;AAC5D,iBAAe,SAAS,cAAc,eAAe,EAAE,UAAU,eAAe,CAAC;AAEjF,SAAO,IAAI,UAAU;GAAE,WAAW;GAAgB,iBAAiB;GAAM,CAAC;;;;;CAU5E,uBAA4C;AAC1C,SAAO,KAAK;;CAGd,UAAU;AACR,SAAO,KAAK,UAAU,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;AC7OnC,IAAY,QAAL,yBAAA,OAAA;;AAEL,OAAA,MAAA,eAAY,UAAU,aAAA;;AAEtB,OAAA,MAAA,eAAY,UAAU,aAAA;;AAEtB,OAAA,MAAA,aAAU,UAAU,mBAAA;;KACrB;;;;;;;AC7BD,MAAa,cAAc;CAEzB,eAAe,OAAO,IAAI,8BAA8B;CAExD,aAAa,OAAO,IAAI,uBAAuB;CAE/C,SAAS,OAAO,IAAI,uBAAuB;CAC5C;;;;;;;;;;;;;;ACED,IAAa,gBAAb,cAAmC,iBAAiB;CAClD,YAAY,UAAoC;AAC9C,QACE,wBACA,YAAY,OAAO,gBACnB,SACD;;;;;;;;;;;ACZL,SAAgB,mBAAmB,OAA2C;AAC5E,QAAO,iBAAiB;;;;AC8CnB,IAAA,qBAAA,MAAM,mBAAmB;CAC9B;CACA,YACE,QACA,MACA,KAEA;AAJsD,OAAA,SAAA;AACJ,OAAA,OAAA;AAEjC,OAAA,MAAA;AAEjB,OAAK,cAAc,KAAK,IAAI;;;;;;;;CAS9B,OAAO,OAA+B;AAEpC,MAAI,mBAAmB,MAAM,EAAE;GAE7B,MAAM,oBAAoB,KAAK,eAAe,MAAM;AAEpD,QAAK,IAAI,OAAO,kBAAkB;AAElC,UAAO,MAAM,gBAAgB,KAAK,aAAa,kBAAkB;;AAInE,OAAK,mBAAmB,MAAM;EAE9B,MAAM,gBAAgB,IAAI,cAAc;GACtC,eAAe,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;GACrE,OAAO,iBAAiB,QAAQ,MAAM,QAAQ,KAAA;GAC/C,CAAC;EAEF,MAAM,oBAAoB,KAAK,eAAe,cAAc;AAE5D,SAAO,cAAc,gBAAgB,KAAK,aAAa,kBAAkB;;;;;;;;;;;;;;CAe3E,eAAuB,OAAiC;EAEtD,MAAM,SAAS,MAAM;AACrB,SAAO,KAAK,KAAK,EAAE,MAAM,SAAwB,OAAO;;;;;CAM1D,IAAY,OAAyB,mBAAiC;EACpE,MAAM,WAAW,KAAK,YAAY,MAAM,KAAK;EAE7C,MAAM,UAAU;GACd,MAAM,MAAM;GACZ,SAAS;GACT,WAAW,MAAM;GACjB,UAAU,MAAM;GAChB,MAAM,MAAM;GACb;AAED,UAAQ,UAAR;GACE,KAAK;AACH,SAAK,OAAO,MAAM,sBAAsB,QAAQ;AAChD;GACF,KAAK;AACH,SAAK,OAAO,KAAK,sBAAsB,QAAQ;AAC/C;GACF,KAAK;AACH,SAAK,OAAO,KAAK,sBAAsB,QAAQ;AAC/C;;;;;;CAON,mBAA2B,OAAsB;AAC/C,OAAK,OAAO,MAAM,qBAAqB;GACrC,OAAO,iBAAiB,QAAQ;IAC9B,SAAS,MAAM;IACf,OAAO,MAAM;IACb,MAAM,MAAM;IACb,GAAG,OAAO,MAAM;GACjB,4BAAW,IAAI,MAAM,EAAC,aAAa;GACpC,CAAC;;;;;CAMJ,YAAoB,MAA2B;AAE7C,MAAI,QAAQ,IAAM,QAAO;AAGzB,MAAI,QAAQ,OAAQ,OAAO,IAAM,QAAO;AAGxC,MAAI,QAAQ,OAAQ,OAAO,IAAM,QAAO;AAGxC,MAAI,QAAQ,OAAQ,OAAO,IAAM,QAAO;AAGxC,MAAI,QAAQ,OAAQ,OAAO,IAAM,QAAO;AAGxC,SAAO;;;;CAzHV,WAAW;oBAIP,OAAO,cAAc,cAAc,CAAA;oBACnC,OAAO,YAAY,YAAY,CAAA;oBAC/B,OAAO,UAAU,cAAc,CAAA;;;;;;;;;;;;;;;;AClDpC,IAAa,sCAAb,cAAyD,iBAAiB;CACxE,cAAc;AACZ,QACE,yCACA,YAAY,OAAO,kCACpB;;;;;;;;;;;ACNL,IAAa,6BAAb,cAAgD,iBAAiB;CAC/D,cAAc;AACZ,QACE,gCACA,YAAY,OAAO,qBACpB"}

package/dist/events/index.d.mts

@@ -0,0 +1,210 @@
+import { t as Constructor } from "../types-JUIHSW_a.mjs";
+import { i as LoggerService } from "../index-3TtGtYlJ.mjs";
+
+//#region src/events/constants.d.ts
+/**
+ * Metadata keys for event listener decorators.
+ *
+ * Uses `Symbol.for()` (global symbol registry) so that both core and
+ * framework packages can reference the same symbols without cross-imports.
+ */
+declare const LISTENER_METADATA_KEYS: {
+  readonly IS_LISTENER: symbol;
+  readonly EVENT_HANDLERS: symbol;
+};
+//#endregion
+//#region src/events/decorators/listener.decorator.d.ts
+/**
+ * Mark a class as an event listener.
+ *
+ * Applies `@Transient()` for DI and sets metadata so the module system
+ * can auto-discover and wire listener handlers at bootstrap time.
+ *
+ * @example
+ * ```typescript
+ * @Listener()
+ * export class UserCreatedListener {
+ *   @On('after.User.create')
+ *   async sendWelcomeEmail(context: EventContext<'after.User.create'>) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+declare function Listener(): <T extends Constructor>(target: T) => T;
+/**
+ * Check if a class is decorated with `@Listener()`
+ */
+declare function isListener(target: Constructor): boolean;
+//#endregion
+//#region src/events/types.d.ts
+/**
+ * Core Event System Types
+ *
+ * Provides a generic, augmentable event system for Stratal.
+ * Core owns the base types; framework's database module augments
+ * `CustomEventRegistry` with richly typed database event contexts.
+ *
+ * ## Custom Events
+ *
+ * Custom application events can be added via module augmentation:
+ *
+ * @example
+ * ```typescript
+ * declare module 'stratal/events' {
+ *   interface CustomEventRegistry {
+ *     'user.verified': CustomEventContext<{ userId: string; email: string }>
+ *     'email.sent': CustomEventContext<{ to: string; subject: string }>
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Augmentable event registry.
+ * Maps event name -> full context type.
+ *
+ * Framework's database module augments this with `DatabaseEvents`.
+ * Users augment for custom events using `CustomEventContext<TData>`.
+ *
+ * @example
+ * ```typescript
+ * declare module 'stratal/events' {
+ *   interface CustomEventRegistry {
+ *     'user.verified': CustomEventContext<{ userId: string; email: string }>
+ *   }
+ * }
+ * ```
+ */
+interface CustomEventRegistry {}
+/**
+ * All valid event names.
+ * Falls back to `string` when no events are registered in CustomEventRegistry.
+ */
+type EventName = keyof CustomEventRegistry extends never ? string : Extract<keyof CustomEventRegistry, string>;
+/**
+ * Helper for user-defined custom events.
+ *
+ * @example
+ * ```typescript
+ * declare module 'stratal/events' {
+ *   interface CustomEventRegistry {
+ *     'user.verified': CustomEventContext<{ userId: string; email: string }>
+ *   }
+ * }
+ * ```
+ */
+interface CustomEventContext<TData = unknown> {
+  data: TData;
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Event context — looks up the full context type from CustomEventRegistry.
+ * For database events, this includes typed data and result from ZenStack schema.
+ * Falls back to a generic context shape for unregistered events.
+ */
+type EventContext<E extends EventName = EventName> = E extends keyof CustomEventRegistry ? CustomEventRegistry[E] : {
+  data?: unknown;
+  result?: unknown;
+};
+/**
+ * Options for registering event handlers
+ */
+interface EventOptions {
+  /** Handler execution priority. Higher values execute first. @default 0 */
+  priority?: number;
+  /**
+   * Whether to force blocking (await) vs non-blocking (waitUntil) behavior.
+   *
+   * Default behavior:
+   * - `before.*` events: Always blocking (true)
+   * - `after.*` events: Non-blocking via waitUntil (false)
+   * - Custom events: Blocking (true)
+   */
+  blocking?: boolean;
+}
+/**
+ * Event handler function signature with typed context
+ */
+type EventHandler<E extends EventName = EventName> = (context: EventContext<E>) => Promise<void> | void;
+/**
+ * Internal structure for storing registered handlers
+ * @internal
+ */
+interface RegisteredHandler {
+  handler: EventHandler;
+  priority: number;
+  blocking?: boolean;
+}
+/**
+ * EventRegistry interface — main API for event system
+ */
+interface IEventRegistry {
+  on<E extends EventName>(event: E, handler: EventHandler<E>, options?: EventOptions): void;
+  emit<E extends EventName>(event: E, context?: Partial<EventContext<E>>): Promise<void>;
+  off<E extends EventName>(event: E, handler: EventHandler<E>): void;
+  once<E extends EventName>(event: E, handler: EventHandler<E>, options?: EventOptions): void;
+}
+/**
+ * Metadata stored by `@On()` decorator for each handler method
+ */
+interface ListenerHandlerMetadata {
+  methodName: string;
+  event: string;
+  options?: EventOptions;
+}
+//#endregion
+//#region src/events/decorators/on.decorator.d.ts
+/**
+ * Register a method as an event handler within a `@Listener()` class.
+ *
+ * Accumulates handler metadata on the class so the framework can
+ * auto-wire handlers with the EventRegistry at bootstrap time.
+ *
+ * @param event - Event name to listen for (fully typed with autocomplete)
+ * @param options - Optional handler options (priority, blocking)
+ *
+ * @example
+ * ```typescript
+ * @Listener()
+ * export class AuditListener {
+ *   @On('after.User.create')
+ *   async logCreate(context: EventContext<'after.User.create'>) { ... }
+ *
+ *   @On('after.User.delete', { priority: 10 })
+ *   async logDelete(context: EventContext<'after.User.delete'>) { ... }
+ * }
+ * ```
+ */
+declare function On<E extends EventName>(event: E, options?: EventOptions): (target: object, propertyKey: string, _descriptor: PropertyDescriptor) => void;
+/**
+ * Get all `@On()` handler metadata from a listener class
+ */
+declare function getListenerHandlers(target: object): ListenerHandlerMetadata[];
+//#endregion
+//#region src/events/event-registry.d.ts
+declare class EventRegistry implements IEventRegistry {
+  private readonly ctx;
+  private readonly logger;
+  private handlers;
+  constructor(ctx: ExecutionContext, logger: LoggerService);
+  on<E extends EventName>(event: E, handler: EventHandler<E>, options?: EventOptions): void;
+  emit<E extends EventName>(event: E, context?: Partial<EventContext<E>>): Promise<void>;
+  off<E extends EventName>(event: E, handler: EventHandler<E>): void;
+  once<E extends EventName>(event: E, handler: EventHandler<E>, options?: EventOptions): void;
+  /**
+   * Find all handlers matching the event using pattern matching.
+   * Order: exact match -> model wildcard -> operation wildcard -> global wildcard
+   */
+  private findMatchingHandlers;
+  /**
+   * Determine if we should use ctx.waitUntil (non-blocking) or await (blocking)
+   */
+  private shouldUseWaitUntil;
+  /**
+   * Execute a single handler with error isolation
+   */
+  private executeHandler;
+}
+//#endregion
+export { type CustomEventContext, type CustomEventRegistry, type EventContext, type EventHandler, type EventName, type EventOptions, EventRegistry, type IEventRegistry, LISTENER_METADATA_KEYS, Listener, type ListenerHandlerMetadata, On, type RegisteredHandler, getListenerHandlers, isListener };
+//# sourceMappingURL=index.d.mts.map

package/dist/events/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/events/constants.ts","../../src/events/decorators/listener.decorator.ts","../../src/events/types.ts","../../src/events/decorators/on.decorator.ts","../../src/events/event-registry.ts"],"mappings":";;;;;;;;AAMA;;cAAa,sBAAA;EAAA,SAGH,WAAA;EAAA,SAAA,cAAA;AAAA;;;;;;AAHV;;;;;;;;ACeA;;;;;;iBAAgB,QAAA,CAAA,cACa,WAAA,EAAa,MAAA,EAAQ,CAAA,KAAC,CAAA;;;;iBAUnC,UAAA,CAAW,MAAA,EAAQ,WAAA;;;;;;;AD1BnC;;;;;;;;ACeA;;;;;;;;;;;;;;;AAWA;;;;;;;;ACUA;;UAAiB,mBAAA;;AAMjB;;;KAAY,SAAA,SAAkB,mBAAA,0BAE1B,OAAA,OAAc,mBAAA;;;;;;;;;;AAkBlB;;;UAAiB,kBAAA;EACf,IAAA,EAAM,KAAA;EACN,QAAA,GAAW,MAAA;AAAA;;;;;AAQb;KAAY,YAAA,WAAuB,SAAA,GAAY,SAAA,IAC7C,CAAA,eAAgB,mBAAA,GACd,mBAAA,CAAoB,CAAA;EAClB,IAAA;EAAgB,MAAA;AAAA;;;;UASL,YAAA;EAVQ;EAYvB,QAAA;EAduB;;;;;;;;EAuBvB,QAAA;AAAA;;AAXF;;KAiBY,YAAA,WAAuB,SAAA,GAAY,SAAA,KAC7C,OAAA,EAAS,YAAA,CAAa,CAAA,MACnB,OAAA;;;AAFL;;UAQiB,iBAAA;EACf,OAAA,EAAS,YAAA;EACT,QAAA;EACA,QAAA;AAAA;;;;UAMe,cAAA;EACf,EAAA,WAAa,SAAA,EACX,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,YAAA,CAAa,CAAA,GACtB,OAAA,GAAU,YAAA;EAGZ,IAAA,WAAe,SAAA,EACb,KAAA,EAAO,CAAA,EACP,OAAA,GAAU,OAAA,CAAQ,YAAA,CAAa,CAAA,KAC9B,OAAA;EAEH,GAAA,WAAc,SAAA,EAAW,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,YAAA,CAAa,CAAA;EAEzD,IAAA,WAAe,SAAA,EACb,KAAA,EAAO,CAAA,EACP,OAAA,EAAS,YAAA,CAAa,CAAA,GACtB,OAAA,GAAU,YAAA;AAAA;;;;UAWG,uBAAA;EACf,UAAA;EACA,KAAA;EACA,OAAA,GAAU,YAAA;AAAA;;;;;;AFrJZ;;;;;;;;ACeA;;;;;;;;;;iBEGgB,EAAA,WAAa,SAAA,CAAA,CAAW,KAAA,EAAO,CAAA,EAAG,OAAA,GAAU,YAAA,IAExD,MAAA,UACA,WAAA,UACA,WAAA,EAAa,kBAAA;;;;iBAsBD,mBAAA,CAAoB,MAAA,WAAiB,uBAAA;;;cCpCxC,aAAA,YAAyB,cAAA;EAAA,iBAImB,GAAA;EAAA,iBACC,MAAA;EAAA,QAJhD,QAAA;cAG+C,GAAA,EAAK,gBAAA,EACJ,MAAA,EAAQ,aAAA;EAGhE,EAAA,WAAa,SAAA,CAAA,CAAW,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,YAAA,CAAa,CAAA,GAAI,OAAA,GAAU,YAAA;EAkBhE,IAAA,WAAe,SAAA,CAAA,CACnB,KAAA,EAAO,CAAA,EACP,OAAA,GAAU,OAAA,CAAQ,YAAA,CAAa,CAAA,KAC9B,OAAA;EAmCH,GAAA,WAAc,SAAA,CAAA,CAAW,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,YAAA,CAAa,CAAA;EAczD,IAAA,WAAe,SAAA,CAAA,CAAW,KAAA,EAAO,CAAA,EAAG,OAAA,EAAS,YAAA,CAAa,CAAA,GAAI,OAAA,GAAU,YAAA;;AHvE1E;;;UGoFU,oBAAA;EHnFwC;;;EAAA,QGwHxC,kBAAA;EHxHS;;;EAAA,QG2IH,cAAA;AAAA"}

package/dist/events/index.mjs

@@ -0,0 +1,3 @@
+import "../logger-Bg-CuidS.mjs";
+import { a as isListener, i as Listener, n as On, o as LISTENER_METADATA_KEYS, r as getListenerHandlers, t as EventRegistry } from "../events-CQyvSyrQ.mjs";
+export { EventRegistry, LISTENER_METADATA_KEYS, Listener, On, getListenerHandlers, isListener };

package/dist/events-CQyvSyrQ.mjs

@@ -0,0 +1,190 @@
+import { a as __decorate, d as Transient, g as DI_TOKENS, o as __decorateParam, s as __decorateMetadata, u as LOGGER_TOKENS } from "./logger-Bg-CuidS.mjs";
+import { inject } from "tsyringe";
+//#region src/events/constants.ts
+/**
+* Metadata keys for event listener decorators.
+*
+* Uses `Symbol.for()` (global symbol registry) so that both core and
+* framework packages can reference the same symbols without cross-imports.
+*/
+const LISTENER_METADATA_KEYS = {
+	IS_LISTENER: Symbol.for("stratal:listener"),
+	EVENT_HANDLERS: Symbol.for("stratal:listener:handlers")
+};
+//#endregion
+//#region src/events/decorators/listener.decorator.ts
+/**
+* Mark a class as an event listener.
+*
+* Applies `@Transient()` for DI and sets metadata so the module system
+* can auto-discover and wire listener handlers at bootstrap time.
+*
+* @example
+* ```typescript
+* @Listener()
+* export class UserCreatedListener {
+*   @On('after.User.create')
+*   async sendWelcomeEmail(context: EventContext<'after.User.create'>) {
+*     // ...
+*   }
+* }
+* ```
+*/
+function Listener() {
+	return function(target) {
+		Transient()(target);
+		Reflect.defineMetadata(LISTENER_METADATA_KEYS.IS_LISTENER, true, target);
+		return target;
+	};
+}
+/**
+* Check if a class is decorated with `@Listener()`
+*/
+function isListener(target) {
+	return Reflect.getMetadata(LISTENER_METADATA_KEYS.IS_LISTENER, target) === true;
+}
+//#endregion
+//#region src/events/decorators/on.decorator.ts
+/**
+* Register a method as an event handler within a `@Listener()` class.
+*
+* Accumulates handler metadata on the class so the framework can
+* auto-wire handlers with the EventRegistry at bootstrap time.
+*
+* @param event - Event name to listen for (fully typed with autocomplete)
+* @param options - Optional handler options (priority, blocking)
+*
+* @example
+* ```typescript
+* @Listener()
+* export class AuditListener {
+*   @On('after.User.create')
+*   async logCreate(context: EventContext<'after.User.create'>) { ... }
+*
+*   @On('after.User.delete', { priority: 10 })
+*   async logDelete(context: EventContext<'after.User.delete'>) { ... }
+* }
+* ```
+*/
+function On(event, options) {
+	return function(target, propertyKey, _descriptor) {
+		const existingHandlers = Reflect.getMetadata(LISTENER_METADATA_KEYS.EVENT_HANDLERS, target.constructor) ?? [];
+		existingHandlers.push({
+			methodName: propertyKey,
+			event,
+			options
+		});
+		Reflect.defineMetadata(LISTENER_METADATA_KEYS.EVENT_HANDLERS, existingHandlers, target.constructor);
+	};
+}
+/**
+* Get all `@On()` handler metadata from a listener class
+*/
+function getListenerHandlers(target) {
+	const metadataTarget = typeof target === "function" ? target : target.constructor;
+	return Reflect.getMetadata(LISTENER_METADATA_KEYS.EVENT_HANDLERS, metadataTarget) ?? [];
+}
+//#endregion
+//#region src/events/event-registry.ts
+var _ref;
+let EventRegistry = class EventRegistry {
+	handlers = /* @__PURE__ */ new Map();
+	constructor(ctx, logger) {
+		this.ctx = ctx;
+		this.logger = logger;
+	}
+	on(event, handler, options) {
+		const registered = {
+			handler,
+			priority: options?.priority ?? 0,
+			blocking: options?.blocking
+		};
+		const existingHandlers = this.handlers.get(event) ?? [];
+		existingHandlers.push(registered);
+		this.handlers.set(event, existingHandlers);
+		this.logger.debug("Event handler registered", {
+			event,
+			priority: registered.priority,
+			blocking: registered.blocking
+		});
+	}
+	async emit(event, context) {
+		const fullContext = { ...context };
+		const matchingHandlers = this.findMatchingHandlers(event);
+		if (matchingHandlers.length === 0) return;
+		const sortedHandlers = [...matchingHandlers].sort((a, b) => b.priority - a.priority);
+		const shouldUseWaitUntil = this.shouldUseWaitUntil(event, sortedHandlers);
+		const promises = sortedHandlers.map((registered) => this.executeHandler(registered.handler, fullContext, event));
+		if (shouldUseWaitUntil) this.ctx.waitUntil(Promise.all(promises));
+		else await Promise.all(promises);
+	}
+	off(event, handler) {
+		const existingHandlers = this.handlers.get(event);
+		if (!existingHandlers) return;
+		const filtered = existingHandlers.filter((h) => h.handler !== handler);
+		if (filtered.length > 0) this.handlers.set(event, filtered);
+		else this.handlers.delete(event);
+		this.logger.debug("Event handler unregistered", { event });
+	}
+	once(event, handler, options) {
+		const wrappedHandler = (async (context) => {
+			await handler(context);
+			this.off(event, wrappedHandler);
+		});
+		this.on(event, wrappedHandler, options);
+	}
+	/**
+	* Find all handlers matching the event using pattern matching.
+	* Order: exact match -> model wildcard -> operation wildcard -> global wildcard
+	*/
+	findMatchingHandlers(event) {
+		const handlers = [];
+		const parts = event.split(".");
+		if (parts.length === 3) {
+			const [phase, model, operation] = parts;
+			handlers.push(...this.handlers.get(event) ?? []);
+			handlers.push(...this.handlers.get(`${phase}.${model}`) ?? []);
+			handlers.push(...this.handlers.get(`${phase}.${operation}`) ?? []);
+			handlers.push(...this.handlers.get(phase) ?? []);
+		} else if (parts.length === 2) {
+			handlers.push(...this.handlers.get(event) ?? []);
+			if (parts[0] === "before" || parts[0] === "after") handlers.push(...this.handlers.get(parts[0]) ?? []);
+		} else handlers.push(...this.handlers.get(event) ?? []);
+		return handlers;
+	}
+	/**
+	* Determine if we should use ctx.waitUntil (non-blocking) or await (blocking)
+	*/
+	shouldUseWaitUntil(event, handlers) {
+		if (handlers.some((h) => h.blocking === true)) return false;
+		if (handlers.some((h) => h.blocking === false)) return true;
+		const phase = event.split(".")[0];
+		if (phase === "before") return false;
+		if (phase === "after") return true;
+		return false;
+	}
+	/**
+	* Execute a single handler with error isolation
+	*/
+	async executeHandler(handler, context, event) {
+		try {
+			await handler(context);
+		} catch (error) {
+			this.logger.error("Event handler error", {
+				event,
+				error: error instanceof Error ? error.message : String(error),
+				stack: error instanceof Error ? error.stack : void 0
+			});
+		}
+	}
+};
+EventRegistry = __decorate([
+	Transient(),
+	__decorateParam(0, inject(DI_TOKENS.ExecutionContext)),
+	__decorateParam(1, inject(LOGGER_TOKENS.LoggerService)),
+	__decorateMetadata("design:paramtypes", [typeof (_ref = typeof ExecutionContext !== "undefined" && ExecutionContext) === "function" ? _ref : Object, Object])
+], EventRegistry);
+//#endregion
+export { isListener as a, Listener as i, On as n, LISTENER_METADATA_KEYS as o, getListenerHandlers as r, EventRegistry as t };
+
+//# sourceMappingURL=events-CQyvSyrQ.mjs.map

package/dist/events-CQyvSyrQ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-CQyvSyrQ.mjs","names":[],"sources":["../src/events/constants.ts","../src/events/decorators/listener.decorator.ts","../src/events/decorators/on.decorator.ts","../src/events/event-registry.ts"],"sourcesContent":["/**\n * Metadata keys for event listener decorators.\n *\n * Uses `Symbol.for()` (global symbol registry) so that both core and\n * framework packages can reference the same symbols without cross-imports.\n */\nexport const LISTENER_METADATA_KEYS = {\n  IS_LISTENER: Symbol.for('stratal:listener'),\n  EVENT_HANDLERS: Symbol.for('stratal:listener:handlers'),\n} as const\n","import { Transient } from '../../di/decorators'\nimport type { Constructor } from '../../types'\nimport { LISTENER_METADATA_KEYS } from '../constants'\n\n/**\n * Mark a class as an event listener.\n *\n * Applies `@Transient()` for DI and sets metadata so the module system\n * can auto-discover and wire listener handlers at bootstrap time.\n *\n * @example\n * ```typescript\n * @Listener()\n * export class UserCreatedListener {\n *   @On('after.User.create')\n *   async sendWelcomeEmail(context: EventContext<'after.User.create'>) {\n *     // ...\n *   }\n * }\n * ```\n */\nexport function Listener() {\n  return function <T extends Constructor>(target: T) {\n    Transient()(target)\n    Reflect.defineMetadata(LISTENER_METADATA_KEYS.IS_LISTENER, true, target)\n    return target\n  }\n}\n\n/**\n * Check if a class is decorated with `@Listener()`\n */\nexport function isListener(target: Constructor): boolean {\n  return Reflect.getMetadata(LISTENER_METADATA_KEYS.IS_LISTENER, target) === true\n}\n","import { LISTENER_METADATA_KEYS } from '../constants'\nimport type { EventName, EventOptions, ListenerHandlerMetadata } from '../types'\n\n/**\n * Register a method as an event handler within a `@Listener()` class.\n *\n * Accumulates handler metadata on the class so the framework can\n * auto-wire handlers with the EventRegistry at bootstrap time.\n *\n * @param event - Event name to listen for (fully typed with autocomplete)\n * @param options - Optional handler options (priority, blocking)\n *\n * @example\n * ```typescript\n * @Listener()\n * export class AuditListener {\n *   @On('after.User.create')\n *   async logCreate(context: EventContext<'after.User.create'>) { ... }\n *\n *   @On('after.User.delete', { priority: 10 })\n *   async logDelete(context: EventContext<'after.User.delete'>) { ... }\n * }\n * ```\n */\nexport function On<E extends EventName>(event: E, options?: EventOptions) {\n  return function (\n    target: object,\n    propertyKey: string,\n    _descriptor: PropertyDescriptor\n  ) {\n    const existingHandlers: ListenerHandlerMetadata[] =\n      (Reflect.getMetadata(LISTENER_METADATA_KEYS.EVENT_HANDLERS, target.constructor) as ListenerHandlerMetadata[] | undefined) ?? []\n\n    existingHandlers.push({\n      methodName: propertyKey,\n      event: event as string,\n      options,\n    })\n\n    Reflect.defineMetadata(\n      LISTENER_METADATA_KEYS.EVENT_HANDLERS,\n      existingHandlers,\n      target.constructor\n    )\n  }\n}\n\n/**\n * Get all `@On()` handler metadata from a listener class\n */\nexport function getListenerHandlers(target: object): ListenerHandlerMetadata[] {\n  const metadataTarget = typeof target === 'function' ? target : target.constructor\n  return (Reflect.getMetadata(LISTENER_METADATA_KEYS.EVENT_HANDLERS, metadataTarget) as ListenerHandlerMetadata[] | undefined) ?? []\n}\n","import { inject } from 'tsyringe'\nimport { Transient } from '../di/decorators'\nimport { DI_TOKENS } from '../di/tokens'\nimport { LOGGER_TOKENS, type LoggerService } from '../logger'\nimport type {\n  EventContext,\n  EventHandler,\n  EventName,\n  EventOptions,\n  IEventRegistry,\n  RegisteredHandler\n} from './types'\n\n@Transient()\nexport class EventRegistry implements IEventRegistry {\n  private handlers = new Map<string, RegisteredHandler[]>()\n\n  constructor(\n    @inject(DI_TOKENS.ExecutionContext) private readonly ctx: ExecutionContext,\n    @inject(LOGGER_TOKENS.LoggerService) private readonly logger: LoggerService\n  ) { }\n\n  on<E extends EventName>(event: E, handler: EventHandler<E>, options?: EventOptions): void {\n    const registered: RegisteredHandler = {\n      handler: handler as EventHandler,\n      priority: options?.priority ?? 0,\n      blocking: options?.blocking\n    }\n\n    const existingHandlers = this.handlers.get(event) ?? []\n    existingHandlers.push(registered)\n    this.handlers.set(event, existingHandlers)\n\n    this.logger.debug('Event handler registered', {\n      event,\n      priority: registered.priority,\n      blocking: registered.blocking\n    })\n  }\n\n  async emit<E extends EventName>(\n    event: E,\n    context?: Partial<EventContext<E>>\n  ): Promise<void> {\n    // Build full context with caller-provided fields\n    const fullContext = {\n      ...context\n    } as EventContext<E>\n\n    // Find matching handlers using pattern matching\n    const matchingHandlers = this.findMatchingHandlers(event)\n\n    if (matchingHandlers.length === 0) {\n      return\n    }\n\n    // Sort by priority (higher first)\n    const sortedHandlers = [...matchingHandlers].sort(\n      (a, b) => b.priority - a.priority\n    )\n\n    // Determine if we should use waitUntil\n    const shouldUseWaitUntil = this.shouldUseWaitUntil(event, sortedHandlers)\n\n    // Execute handlers\n    const promises = sortedHandlers.map((registered) =>\n      this.executeHandler(registered.handler, fullContext, event)\n    )\n\n    if (shouldUseWaitUntil) {\n      // Non-blocking: use ctx.waitUntil\n      this.ctx.waitUntil(Promise.all(promises))\n    } else {\n      // Blocking: await all handlers\n      await Promise.all(promises)\n    }\n  }\n\n  off<E extends EventName>(event: E, handler: EventHandler<E>): void {\n    const existingHandlers = this.handlers.get(event)\n    if (!existingHandlers) return\n\n    const filtered = existingHandlers.filter((h) => h.handler !== handler)\n    if (filtered.length > 0) {\n      this.handlers.set(event, filtered)\n    } else {\n      this.handlers.delete(event)\n    }\n\n    this.logger.debug('Event handler unregistered', { event })\n  }\n\n  once<E extends EventName>(event: E, handler: EventHandler<E>, options?: EventOptions): void {\n    const wrappedHandler = (async (context: EventContext<E>) => {\n      await handler(context)\n      this.off(event, wrappedHandler)\n    }) as EventHandler<E>\n\n    this.on(event, wrappedHandler, options)\n  }\n\n  /**\n   * Find all handlers matching the event using pattern matching.\n   * Order: exact match -> model wildcard -> operation wildcard -> global wildcard\n   */\n  private findMatchingHandlers(event: string): RegisteredHandler[] {\n    const handlers: RegisteredHandler[] = []\n\n    const parts = event.split('.')\n\n    if (parts.length === 3) {\n      // Database event: \"phase.model.operation\"\n      const [phase, model, operation] = parts\n\n      // 1. Exact match: \"after.user.create\"\n      handlers.push(...(this.handlers.get(event) ?? []))\n\n      // 2. Model wildcard: \"after.user\"\n      handlers.push(...(this.handlers.get(`${phase}.${model}`) ?? []))\n\n      // 3. Operation wildcard: \"after.create\"\n      handlers.push(...(this.handlers.get(`${phase}.${operation}`) ?? []))\n\n      // 4. Global wildcard: \"after\"\n      handlers.push(...(this.handlers.get(phase) ?? []))\n    } else if (parts.length === 2) {\n      // Could be wildcard like \"after.user\" or custom event like \"auth.verified\"\n      handlers.push(...(this.handlers.get(event) ?? []))\n\n      if (parts[0] === 'before' || parts[0] === 'after') {\n        handlers.push(...(this.handlers.get(parts[0]) ?? []))\n      }\n    } else {\n      handlers.push(...(this.handlers.get(event) ?? []))\n    }\n\n    return handlers\n  }\n\n  /**\n   * Determine if we should use ctx.waitUntil (non-blocking) or await (blocking)\n   */\n  private shouldUseWaitUntil(\n    event: string,\n    handlers: RegisteredHandler[]\n  ): boolean {\n    const hasBlockingHandler = handlers.some((h) => h.blocking === true)\n    if (hasBlockingHandler) return false\n\n    const hasNonBlockingHandler = handlers.some((h) => h.blocking === false)\n    if (hasNonBlockingHandler) return true\n\n    const phase = event.split('.')[0]\n    if (phase === 'before') return false\n    if (phase === 'after') return true\n    return false // Custom events block by default\n  }\n\n  /**\n   * Execute a single handler with error isolation\n   */\n  private async executeHandler<E extends EventName>(\n    handler: EventHandler,\n    context: EventContext<E>,\n    event: string\n  ): Promise<void> {\n    try {\n      await handler(context as EventContext)\n    } catch (error) {\n      this.logger.error('Event handler error', {\n        event,\n        error: error instanceof Error ? error.message : String(error),\n        stack: error instanceof Error ? error.stack : undefined,\n      })\n    }\n  }\n}\n"],"mappings":"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"}