stratal 0.0.13 → 0.0.15

package/dist/index-Cfkie8JM.d.mts

@@ -0,0 +1,263 @@
+//#region src/logger/logger.tokens.d.ts
+/**
+ * Dependency Injection Tokens for Logger Module
+ *
+ * Symbol-based tokens ensure type-safe dependency injection
+ * and prevent naming collisions.
+ */
+declare const LOGGER_TOKENS: {
+  /**
+   * Main logger service facade
+   */
+  readonly LoggerService: symbol;
+  /**
+   * Log formatter (JSON or Pretty)
+   */
+  readonly Formatter: symbol;
+  /**
+   * Array of active transports
+   */
+  readonly Transports: symbol;
+  /**
+   * Individual transport tokens (for factory registration)
+   */
+  readonly ConsoleTransport: symbol;
+  /**
+   * Configured log level for filtering
+   */
+  readonly LogLevelOptions: symbol;
+};
+//#endregion
+//#region src/logger/contracts/log-level.d.ts
+/**
+ * Log severity levels
+ * Ordered from least to most severe
+ */
+declare enum LogLevel {
+  DEBUG = "debug",
+  INFO = "info",
+  WARN = "warn",
+  ERROR = "error"
+}
+/**
+ * Map log levels to numeric priorities (for filtering)
+ * Higher numbers = more severe = higher priority
+ */
+declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
+//#endregion
+//#region src/logger/contracts/log-context.d.ts
+/**
+ * Structured metadata attached to log entries
+ * Supports arbitrary key-value pairs for context enrichment
+ */
+type LogContext = Record<string, unknown>;
+/**
+ * Internal context automatically added by LoggerService
+ * Contains request metadata, etc.
+ */
+interface InternalLogContext extends LogContext {
+  userId?: string;
+  timestamp: number;
+}
+//#endregion
+//#region src/logger/contracts/log-entry.d.ts
+/**
+ * Complete log entry structure passed to transports
+ * Combines message, level, and enriched context
+ */
+interface LogEntry {
+  level: LogLevel;
+  message: string;
+  context: InternalLogContext;
+  error?: {
+    message: string;
+    stack?: string;
+    name?: string;
+  };
+}
+//#endregion
+//#region src/logger/formatters/formatter.interface.d.ts
+/**
+ * Formatter contract
+ * Transforms LogEntry into string representation for transport output
+ */
+interface ILogFormatter {
+  /**
+   * Format log entry into string
+   * @param entry - Complete log entry with context
+   * @returns Formatted string ready for transport
+   */
+  format(entry: LogEntry): string;
+}
+//#endregion
+//#region src/logger/transports/transport.interface.d.ts
+/**
+ * Transport contract
+ * Handles delivery of formatted log entries to destinations
+ */
+interface ILogTransport {
+  /**
+   * Transport name for identification
+   */
+  readonly name: string;
+  /**
+   * Write log entry to destination
+   * Must be async to support waitUntil pattern
+   *
+   * @param entry - Complete log entry
+   * @param formatted - Pre-formatted string from formatter
+   * @returns Promise that resolves when log is written
+   */
+  write(entry: LogEntry, formatted: string): Promise<void>;
+}
+//#endregion
+//#region src/logger/services/logger.service.d.ts
+/**
+ * Logger Service
+ *
+ * Main logging facade.
+ *
+ * **Features:**
+ * - Async logging via ctx.waitUntil() for non-blocking performance
+ * - Multi-transport support (console, future Sentry/Cloudflare Analytics)
+ * - Configurable formatters (JSON production, Pretty development)
+ * - Log level filtering based on environment
+ *
+ * **Architecture:**
+ * - Transports and formatters injected via DI
+ *
+ * @example Basic usage
+ * ```typescript
+ * @Transient()
+ * export class UserService {
+ *   constructor(
+ *     @inject(LOGGER_TOKENS.LoggerService)
+ *     private readonly logger: LoggerService
+ *   ) {}
+ *
+ *   async createUser(input: CreateUserInput) {
+ *     this.logger.info('Creating user', { email: input.email })
+ *   }
+ * }
+ * ```
+ */
+declare class LoggerService {
+  private readonly logLevel;
+  private readonly executionContext;
+  private readonly formatter;
+  private readonly transports;
+  constructor(logLevel: LogLevel, executionContext: globalThis.ExecutionContext, formatter: ILogFormatter, transports: ILogTransport[]);
+  /**
+   * Log debug message (development only)
+   */
+  debug(message: string, context?: LogContext): void;
+  /**
+   * Log info message
+   */
+  info(message: string, context?: LogContext): void;
+  /**
+   * Log warning message
+   */
+  warn(message: string, context?: LogContext): void;
+  /**
+   * Log error message
+   * Accepts Error object or custom context
+   */
+  error(message: string, contextOrError?: LogContext | Error): void;
+  /**
+   * Core logging implementation
+   * Enriches context, formats message, dispatches to transports
+   * Uses ctx.waitUntil() for async non-blocking processing
+   */
+  private log;
+  /**
+   * Enrich log context with request info and timestamp
+   * Context enrichment can be extended by application modules
+   */
+  private enrichContext;
+  /**
+   * Serialize Error object for transport
+   */
+  private serializeError;
+}
+//#endregion
+//#region src/logger/formatters/json-formatter.d.ts
+/**
+ * JSON Formatter
+ *
+ * Produces structured JSON logs for production environments.
+ * Optimized for log aggregation systems (Cloudflare Analytics, Datadog, etc.)
+ *
+ * Output format:
+ * {
+ *   "level": "info",
+ *   "message": "User logged in",
+ *   "timestamp": 1234567890,
+ *   "userId": "user_456",
+ *   "error": { "message": "...", "stack": "..." }
+ * }
+ */
+declare class JsonFormatter implements ILogFormatter {
+  format(entry: LogEntry): string;
+}
+//#endregion
+//#region src/logger/formatters/pretty-formatter.d.ts
+/**
+ * Pretty Formatter
+ *
+ * Human-readable colored output for development environments.
+ * Uses ANSI color codes for terminal output.
+ *
+ * Output format:
+ * [2024-01-15 10:30:45] INFO: User logged in
+ *   userId: user_456
+ */
+declare class PrettyFormatter implements ILogFormatter {
+  private readonly colors;
+  private readonly reset;
+  format(entry: LogEntry): string;
+}
+//#endregion
+//#region src/logger/transports/base-transport.d.ts
+/**
+ * Base Transport
+ *
+ * Abstract base class providing shared transport logic.
+ * Reduces code duplication across transport implementations.
+ */
+declare abstract class BaseTransport implements ILogTransport {
+  abstract readonly name: string;
+  /**
+   * Write log entry - must be implemented by concrete transports
+   */
+  abstract write(entry: LogEntry, formatted: string): Promise<void>;
+  /**
+   * Handle transport errors gracefully
+   * Logs to console.error as fallback to prevent log loss
+   *
+   * @param error - Error that occurred during write
+   * @param entry - Log entry that failed
+   */
+  protected handleError(error: unknown, entry: LogEntry): void;
+}
+//#endregion
+//#region src/logger/transports/console-transport.d.ts
+/**
+ * Console Transport
+ *
+ * Writes logs to console using appropriate console methods.
+ * Maps log levels to console.debug, console.info, console.warn, console.error.
+ *
+ * Thread-safe for Cloudflare Workers environment.
+ */
+declare class ConsoleTransport extends BaseTransport {
+  readonly name = "console";
+  write(entry: LogEntry, formatted: string): Promise<void>;
+  /**
+   * Map log level to console method
+   */
+  private getConsoleMethod;
+}
+//#endregion
+export { LogEntry as a, LOG_LEVEL_PRIORITY as c, LoggerService as i, LogLevel as l, PrettyFormatter as n, InternalLogContext as o, JsonFormatter as r, LogContext as s, ConsoleTransport as t, LOGGER_TOKENS as u };
+//# sourceMappingURL=index-Cfkie8JM.d.mts.map

package/dist/index-Cfkie8JM.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-Cfkie8JM.d.mts","names":[],"sources":["../src/logger/logger.tokens.ts","../src/logger/contracts/log-level.ts","../src/logger/contracts/log-context.ts","../src/logger/contracts/log-entry.ts","../src/logger/formatters/formatter.interface.ts","../src/logger/transports/transport.interface.ts","../src/logger/services/logger.service.ts","../src/logger/formatters/json-formatter.ts","../src/logger/formatters/pretty-formatter.ts","../src/logger/transports/base-transport.ts","../src/logger/transports/console-transport.ts"],"mappings":";;AAMA;;;;;cAAa,aAAA;;;;;;;;;ECFD;;;EAAA;EACV;;;EAAA;EAGK;;AAOP;EAPO;;;;;ADFP;;;aCFY,QAAA;EACV,KAAA;EACA,IAAA;EACA,IAAA;EACA,KAAA;AAAA;;;;;cAOW,kBAAA,EAAoB,MAAA,CAAO,QAAA;;;;ADTxC;;;KEFY,UAAA,GAAa,MAAA;;;;;UAMR,kBAAA,SAA2B,UAAA;EAC1C,MAAA;EACA,SAAA;AAAA;;;;;;;UCLe,QAAA;EACf,KAAA,EAAO,QAAA;EACP,OAAA;EACA,OAAA,EAAS,kBAAA;EACT,KAAA;IACE,OAAA;IACA,KAAA;IACA,IAAA;EAAA;AAAA;;;AHRJ;;;;AAAA,UIAiB,aAAA;;;;;;EAMf,MAAA,CAAO,KAAA,EAAO,QAAA;AAAA;;;AJNhB;;;;AAAA,UKAiB,aAAA;;;;WAIN,IAAA;;;;;;AJNX;;;EIgBE,KAAA,CAAM,KAAA,EAAO,QAAA,EAAU,SAAA,WAAoB,OAAA;AAAA;;;;;;;;;;;;;;AJhB7C;;;;;;;;;;AAWA;;;;;;;;cKwBa,aAAA;EAAA,iBAGQ,QAAA;EAAA,iBAGA,gBAAA;EAAA,iBAGA,SAAA;EAAA,iBAGA,UAAA;cATA,QAAA,EAAU,QAAA,EAGV,gBAAA,EAAkB,UAAA,CAAW,gBAAA,EAG7B,SAAA,EAAW,aAAA,EAGX,UAAA,EAAY,aAAA;EJzCG;;;EI+ClC,KAAA,CAAM,OAAA,UAAiB,OAAA,GAAU,UAAA;EJ9CjC;;;EIqDA,IAAA,CAAK,OAAA,UAAiB,OAAA,GAAU,UAAA;;;;EAOhC,IAAA,CAAK,OAAA,UAAiB,OAAA,GAAU,UAAA;EHhET;;;;EGwEvB,KAAA,CAAM,OAAA,UAAiB,cAAA,GAAiB,UAAA,GAAa,KAAA;EHtErD;;;;;EAAA,QGwFQ,GAAA;EHnFN;;;;EAAA,QGgIM,aAAA;;AFxIV;;UEkJU,cAAA;AAAA;;;;;;;;;;;;;;;;ALpJV;;cMca,aAAA,YAAyB,aAAA;EACpC,MAAA,CAAO,KAAA,EAAO,QAAA;AAAA;;;;;;;;;;;;;cCLH,eAAA,YAA2B,aAAA;EAAA,iBACrB,MAAA;EAAA,iBAOA,KAAA;EAEjB,MAAA,CAAO,KAAA,EAAO,QAAA;AAAA;;;;;;;;;uBCfM,aAAA,YAAyB,aAAA;EAAA,kBAC3B,IAAA;;;;WAKT,KAAA,CAAM,KAAA,EAAO,QAAA,EAAU,SAAA,WAAoB,OAAA;;ARXtD;;;;;;YQoBY,WAAA,CAAY,KAAA,WAAgB,KAAA,EAAO,QAAA;AAAA;;;;;;;;;;;cCTlC,gBAAA,SAAyB,aAAA;EAAA,SAC3B,IAAA;EAET,KAAA,CAAM,KAAA,EAAO,QAAA,EAAU,SAAA,WAAoB,OAAA;;;ATd7C;US4BU,gBAAA;AAAA"}

package/dist/index-CpAN9ENH.d.mts

@@ -0,0 +1,185 @@
+import { t as index_d_exports$1 } from "./index-CSuHOJc3.mjs";
+import { OpenAPIHono, z } from "@hono/zod-openapi";
+import * as zod from "zod";
+import { ZodError } from "zod";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { OpenAPIObject, PathItemObject } from "openapi3-ts/oas30";
+import * as zod_v4_core0 from "zod/v4/core";
+import { $ZodIssueCustom } from "zod/v4/core";
+
+//#region src/i18n/i18n.types.d.ts
+/**
+ * Recursively extract nested keys from an object type
+ * Converts nested object to dot-notation string union
+ *
+ * @example
+ * ```typescript
+ * type Example = { auth: { login: { title: string } } }
+ * type Keys = DeepKeys<Example>
+ * // Results in: 'auth.login.title'
+ * ```
+ */
+type DeepKeys<T, Prefix extends string = ''> = T extends object ? { [K in keyof T & string]: T[K] extends object ? DeepKeys<T[K], `${Prefix}${K}.`> : `${Prefix}${K}` }[keyof T & string] : never;
+/**
+ * System message keys - auto-derived from system en messages
+ * These are messages used by packages/modules infrastructure
+ */
+type SystemMessageKeys = DeepKeys<typeof index_d_exports$1>;
+/**
+ * Augmentable interface for app-specific messages
+ *
+ * Applications should augment this interface with their message types:
+ *
+ * @example
+ * ```typescript
+ * // In apps/backend/src/i18n/types.ts
+ * import type * as appEn from 'stratal/i18n/messages/en'
+ *
+ * declare module 'stratal' {
+ *   interface AppMessages extends typeof appEn {}
+ * }
+ * ```
+ */
+interface AppMessages {}
+/**
+ * Auto-derive app keys from AppMessages
+ * When AppMessages is augmented, this type automatically includes all app message keys
+ */
+type AppMessageKeys = DeepKeys<AppMessages>;
+/**
+ * Union type used by I18nService.t()
+ * Combines system message keys with app-specific message keys
+ */
+type MessageKeys = SystemMessageKeys | AppMessageKeys;
+/**
+ * Type for translation parameters
+ * Used for string interpolation in messages
+ */
+type MessageParams = Record<string, string | number>;
+/**
+ * I18n Service interface
+ */
+interface II18nService {
+  /**
+   * Translate a message key
+   *
+   * @param key - Message key (e.g., 'common.actions.save', 'errors.notFound')
+   * @param params - Optional parameters for interpolation
+   * @returns Translated string
+   */
+  t(key: MessageKeys, params?: MessageParams): string;
+  /**
+   * Get current locale
+   *
+   * @returns Current locale code from RouterContext or default
+   */
+  getLocale(): string;
+}
+//#endregion
+//#region src/i18n/validation/with-i18n.d.ts
+/**
+ * Type-safe helper for creating custom Zod error messages with i18n support (Backend)
+ *
+ * Usage with .refine():
+ * ```typescript
+ * const schema = z.string().refine(
+ *   (val) => val.length > 5,
+ *   withI18n('validation.minLength', { min: 5 })
+ * )
+ * ```
+ *
+ * Usage with built-in validators:
+ * ```typescript
+ * const schema = z.string().min(5, withI18n('validation.minLength', { min: 5 }))
+ * const schema = z.string().email(withI18n('validation.email'))
+ * ```
+ *
+ * Note: This is the backend version using AsyncLocalStorage.
+ * For frontend, use withI18nFrontend from the frontend validation module
+ *
+ * @param key - Message key from shared i18n messages (type-safe via MessageKeys)
+ * @param params - Optional interpolation parameters for the message
+ * @returns Zod error configuration object with translated message
+ */
+declare function withI18n(key: MessageKeys, params?: Record<string, unknown>): {
+  error: () => string;
+};
+//#endregion
+//#region src/i18n/validation/validation.types.d.ts
+/**
+ * Context provided to error map for locale-aware translation
+ */
+interface ErrorMapContext {
+  /**
+   * Translate a message key with optional parameters
+   */
+  t: (key: MessageKeys, params?: Record<string, unknown>) => string;
+  /**
+   * Current locale code (e.g., 'en', 'fr')
+   */
+  locale: string;
+}
+/**
+ * Function that provides the current translation context
+ * Used by error maps to access request-scoped or application-wide i18n
+ */
+type LocaleProvider = () => ErrorMapContext | undefined;
+/**
+ * Custom error metadata for withI18n helper
+ */
+interface I18nErrorMetadata {
+  /**
+   * Message key for translation
+   */
+  key: MessageKeys;
+  /**
+   * Parameters for message interpolation
+   */
+  params?: Record<string, unknown>;
+}
+/**
+ * Zod custom issue with i18n metadata
+ * Uses Zod v4 native $ZodIssueCustom type
+ */
+type ZodCustomIssue = $ZodIssueCustom & {
+  params?: {
+    i18n?: I18nErrorMetadata;
+    [key: string]: unknown;
+  };
+};
+//#endregion
+//#region src/i18n/validation/validation.context.d.ts
+/**
+ * Backend error map that accesses I18nService from AsyncLocalStorage
+ * Must be initialized in router middleware after locale detection
+ */
+declare const backendErrorMap: zod.ZodErrorMap<zod_v4_core0.$ZodIssue>;
+/**
+ * Runs a function within an error map context
+ * Used by router middleware to provide I18nService to validation
+ *
+ * @example
+ * ```typescript
+ * router.use('*', async (c, next) => {
+ *   const i18nService = c.get('i18nService')
+ *   const locale = c.get('locale')
+ *
+ *   return runWithErrorMapContext(
+ *     {
+ *       t: (key, params) => i18nService.t(key, params),
+ *       locale,
+ *     },
+ *     () => next()
+ *   )
+ * })
+ * ```
+ */
+declare function runWithErrorMapContext<T>(context: ErrorMapContext, fn: () => T): T;
+declare namespace index_d_exports {
+  export { ErrorMapContext, I18nErrorMetadata, LocaleProvider, OpenAPIHono, OpenAPIObject, PathItemObject, ZodCustomIssue, ZodError, backendErrorMap, runWithErrorMapContext, withI18n, z };
+}
+import * as import_zod from "zod";
+import * as import__hono_zod_openapi from "@hono/zod-openapi";
+//#endregion
+export { II18nService as _, index_d_exports as a, SystemMessageKeys as b, runWithErrorMapContext as c, LocaleProvider as d, ZodCustomIssue as f, DeepKeys as g, AppMessages as h, ZodError as i, ErrorMapContext as l, AppMessageKeys as m, OpenAPIObject as n, z as o, withI18n as p, PathItemObject as r, backendErrorMap as s, OpenAPIHono as t, I18nErrorMetadata as u, MessageKeys as v, MessageParams as y };
+//# sourceMappingURL=index-CpAN9ENH.d.mts.map

package/dist/index-CpAN9ENH.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CpAN9ENH.d.mts","names":[],"sources":["../src/i18n/i18n.types.ts","../src/i18n/validation/with-i18n.ts","../src/i18n/validation/validation.types.ts","../src/i18n/validation/validation.context.ts","../src/i18n/validation/index.ts"],"mappings":";;;;;;;;;;;;;;AAoBA;;;;;;;KAAY,QAAA,kCAA0C,CAAA,gCAEpC,CAAA,YAAa,CAAA,CAAE,CAAA,mBACvB,QAAA,CAAS,CAAA,CAAE,CAAA,MAAO,MAAA,GAAS,CAAA,UACxB,MAAA,GAAS,CAAA,WACV,CAAA;;;;;KAOA,iBAAA,GAAoB,QAAA,QAAgB,iBAAA;;;;;;;;;;;;;;;;UAiB/B,WAAA;;;AAjBjB;;KAuBY,cAAA,GAAiB,QAAA,CAAS,WAAA;;;AANtC;;KAaY,WAAA,GAAc,iBAAA,GAAoB,cAAA;;;AAP9C;;KAaY,aAAA,GAAgB,MAAA;;;AAN5B;UAWiB,YAAA;;;;AALjB;;;;EAaE,CAAA,CAAE,GAAA,EAAK,WAAA,EAAa,MAAA,GAAS,aAAA;EARd;;;;;EAef,SAAA;AAAA;;;;;;;;;;;;;AApEF;;;;;;;;;;;;;;iBCOgB,QAAA,CACd,GAAA,EAAK,WAAA,EACL,MAAA,GAAS,MAAA;EACN,KAAA;AAAA;;;;;;UCxBY,eAAA;;;;EAIf,CAAA,GAAI,GAAA,EAAK,WAAA,EAAa,MAAA,GAAS,MAAA;;AFUjC;;EELE,MAAA;AAAA;;;;;KAOU,cAAA,SAAuB,eAAA;;;;UAKlB,iBAAA;EFHK;;;EEOpB,GAAA,EAAK,WAAA;EFXc;;;EEgBnB,MAAA,GAAS,MAAA;AAAA;;;;;KAOC,cAAA,GAAiB,eAAA;EAC3B,MAAA;IACE,IAAA,GAAO,iBAAA;IAAA,CACN,GAAA;EAAA;AAAA;;;;;;;cCzBQ,eAAA,EAAe,GAAA,CAAA,WAAA,CAAyC,YAAA,CAAzC,SAAA;;;;;;;;;;;;;;;;;;;;;iBAsBZ,sBAAA,GAAA,CACd,OAAA,EAAS,eAAA,EACT,EAAA,QAAU,CAAA,GACT,CAAA;AAAA"}