@sentzunhat/zacatl 0.0.14 → 0.0.21

package/src/localization/locales/en.json

@@ -0,0 +1,9 @@
+{
+  "ERROR_MESSAGES": {
+    "DEFAULT": "An error occurred.",
+    "VALIDATION": "Validation error: required fields are missing or invalid. Please review your input and ensure all fields meet the expected format."
+  },
+  "SUCCESS_MESSAGES": {
+    "DEFAULT": "Your request was processed successfully."
+  }
+}

package/src/localization/locales/es.json

@@ -0,0 +1,9 @@
+{
+  "ERROR_MESSAGES": {
+    "DEFAULT": "Ocurrió un error.",
+    "VALIDATION": "Error de validación: faltan campos requeridos o son inválidos. Por favor, revise su entrada y asegúrese de que todos los campos cumplan con el formato esperado."
+  },
+  "SUCCESS_MESSAGES": {
+    "DEFAULT": "Su solicitud se procesó correctamente."
+  }
+}

package/src/localization/localization.ts

@@ -0,0 +1,222 @@
+import i18next from "i18next";
+import type { I18nAdapter, I18nConfig, I18nInstance } from "./types";
+import { FilesystemAdapter } from "./adapters";
+
+/**
+ * Create a new i18n instance with optional adapter and configuration.
+ * Follows the same factory pattern as createLogger().
+ *
+ * @param adapter - I18nAdapter implementation (defaults to FilesystemAdapter('./src/localization/locales'))
+ * @param config - I18n configuration options
+ * @returns Configured I18nInstance
+ *
+ * @example
+ * // With default filesystem adapter
+ * const i18n = createI18n();
+ *
+ * @example
+ * // With custom adapter
+ * import { MemoryAdapter } from './adapters';
+ * const i18n = createI18n(new MemoryAdapter({
+ *   en: { translation: { greeting: 'Hello' } }
+ * }));
+ *
+ * @example
+ * // With configuration
+ * const i18n = createI18n(undefined, {
+ *   defaultLanguage: 'en',
+ *   supportedLanguages: ['en', 'es'],
+ *   i18nextOptions: { ns: ['translation', 'errors'] }
+ * });
+ */
+export const createI18n = (
+  adapter?: I18nAdapter,
+  config?: I18nConfig,
+): I18nInstance => {
+  const finalAdapter =
+    adapter ??
+    new FilesystemAdapter(`${process.cwd()}/src/localization/locales`);
+  const finalConfig: I18nConfig = {
+    defaultLanguage: "en",
+    fallbackLanguage: "en",
+    supportedLanguages: ["en", "es"],
+    defaultNamespace: "translation",
+    ...config,
+  };
+
+  // Initialize adapter
+  if (finalAdapter.init) {
+    const result = finalAdapter.init();
+    if (result instanceof Promise) {
+      throw new Error(
+        "Async adapter.init() not supported in createI18n(); use createI18nAsync() instead",
+      );
+    }
+  }
+
+  // Configure i18next
+  const i18nInstance = i18next.createInstance();
+  i18nInstance.init(
+    {
+      lng: finalConfig.defaultLanguage,
+      fallbackLng: finalConfig.fallbackLanguage,
+      ns: [finalConfig.defaultNamespace],
+      defaultNS: finalConfig.defaultNamespace,
+      interpolation: {
+        escapeValue: false, // React/TypeScript handles escaping
+      },
+      resources: loadInitialResources(finalAdapter, finalConfig),
+      ...finalConfig.i18nextOptions,
+    } as Record<string, unknown>,
+    (err: unknown) => {
+      if (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        throw new Error(`i18n initialization failed: ${errorMessage}`);
+      }
+    },
+  );
+
+  return createI18nInstanceWrapper(i18nInstance, finalAdapter, finalConfig);
+};
+
+/**
+ * Create a new async i18n instance.
+ * Use this if your adapter.init() returns a Promise.
+ *
+ * @param adapter - I18nAdapter implementation
+ * @param config - I18n configuration options
+ * @returns Promise<I18nInstance>
+ */
+export const createI18nAsync = async (
+  adapter?: I18nAdapter,
+  config?: I18nConfig,
+): Promise<I18nInstance> => {
+  const finalAdapter =
+    adapter ??
+    new FilesystemAdapter(`${process.cwd()}/src/localization/locales`);
+  const finalConfig: I18nConfig = {
+    defaultLanguage: "en",
+    fallbackLanguage: "en",
+    supportedLanguages: ["en", "es"],
+    defaultNamespace: "translation",
+    ...config,
+  };
+
+  // Initialize adapter
+  if (finalAdapter.init) {
+    const result = finalAdapter.init();
+    if (result instanceof Promise) {
+      await result;
+    }
+  }
+
+  // Configure i18next
+  const i18nInstance = i18next.createInstance();
+  await new Promise<void>((resolve, reject) => {
+    i18nInstance.init(
+      {
+        lng: finalConfig.defaultLanguage,
+        fallbackLng: finalConfig.fallbackLanguage,
+        ns: [finalConfig.defaultNamespace],
+        defaultNS: finalConfig.defaultNamespace,
+        interpolation: {
+          escapeValue: false,
+        },
+        resources: loadInitialResources(finalAdapter, finalConfig),
+        ...finalConfig.i18nextOptions,
+      } as Record<string, unknown>,
+      (err: unknown) => {
+        if (err) {
+          const errorMessage = err instanceof Error ? err.message : String(err);
+          reject(new Error(`i18n initialization failed: ${errorMessage}`));
+        } else {
+          resolve();
+        }
+      },
+    );
+  });
+
+  return createI18nInstanceWrapper(i18nInstance, finalAdapter, finalConfig);
+};
+
+/**
+ * Get or throw error if not initialized.
+ * Used internally; not part of public API.
+ */
+let globalI18nInstance: I18nInstance | null = null;
+
+export const setGlobalI18n = (instance: I18nInstance): void => {
+  globalI18nInstance = instance;
+};
+
+export const getI18nOrThrow = (): I18nInstance => {
+  if (!globalI18nInstance) {
+    throw new Error(
+      "i18n not initialized. Call setGlobalI18n() first or use createI18n() to create an instance.",
+    );
+  }
+  return globalI18nInstance;
+};
+
+/**
+ * Internal: Load initial resources from adapter.
+ */
+const loadInitialResources = (
+  adapter: I18nAdapter,
+  config: I18nConfig,
+): Record<string, Record<string, unknown>> => {
+  const resources: Record<string, Record<string, unknown>> = {};
+
+  for (const lang of config.supportedLanguages ?? []) {
+    const res = adapter.loadResources(
+      lang,
+      config.defaultNamespace ?? "translation",
+    );
+    if (res) {
+      resources[lang] = {
+        [config.defaultNamespace ?? "translation"]: res,
+      };
+    }
+  }
+
+  return resources;
+};
+
+/**
+ * Internal: Create the I18nInstance wrapper.
+ */
+const createI18nInstanceWrapper = (
+  i18nInstance: unknown,
+  _adapter: I18nAdapter,
+  config: I18nConfig,
+): I18nInstance => {
+  const inst = i18nInstance as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  return {
+    t: (key: string, options?: Record<string, unknown>) =>
+      inst.t(key, options) as string,
+
+    getLanguage: () => inst.language,
+
+    setLanguage: async (language: string) => {
+      await inst.changeLanguage(language);
+    },
+
+    getSupportedLanguages: () => config.supportedLanguages ?? ["en"],
+
+    getI18next: () => i18nInstance,
+
+    addResources: (
+      language: string,
+      namespace: string,
+      resources: Record<string, unknown>,
+    ) => {
+      inst.addResourceBundle(language, namespace, resources, true, true);
+    },
+
+    getResources: (language?: string, namespace?: string) => {
+      const lang = language ?? inst.language;
+      const ns = namespace ?? config.defaultNamespace ?? "translation";
+      return inst.getResourceBundle(lang, ns) ?? null;
+    },
+  };
+};

package/src/localization/types.ts

@@ -0,0 +1,110 @@
+/**
+ * I18n adapter interface for pluggable i18n backends.
+ * Implementations define where translations are loaded from (filesystem, API, memory, etc.).
+ */
+export interface I18nAdapter {
+  /**
+   * Initialize the adapter with optional configuration.
+   */
+  init?(config?: Record<string, unknown>): Promise<void> | void;
+
+  /**
+   * Load translations for a specific language and namespace.
+   * Returns the loaded resources object.
+   */
+  loadResources(
+    language: string,
+    namespace: string,
+  ): Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
+
+  /**
+   * Optional: Save translations (useful for some backends).
+   */
+  saveResources?(
+    language: string,
+    namespace: string,
+    resources: Record<string, unknown>,
+  ): Promise<void> | void;
+}
+
+/**
+ * I18n configuration options.
+ */
+export interface I18nConfig {
+  /**
+   * Default language for translations.
+   * @default 'en'
+   */
+  defaultLanguage?: string;
+
+  /**
+   * Fallback language if translation not found.
+   * @default 'en'
+   */
+  fallbackLanguage?: string;
+
+  /**
+   * List of supported languages.
+   * @default ['en']
+   */
+  supportedLanguages?: string[];
+
+  /**
+   * Default namespace for translations.
+   * @default 'translation'
+   */
+  defaultNamespace?: string;
+
+  /**
+   * Additional i18next options to merge with defaults.
+   */
+  i18nextOptions?: Record<string, unknown>;
+}
+
+/**
+ * I18n instance returned by createI18n().
+ * Provides translation, language switching, and management methods.
+ */
+export interface I18nInstance {
+  /**
+   * Translate a key with optional interpolation.
+   */
+  t(key: string, options?: Record<string, unknown>): string;
+
+  /**
+   * Get the current language.
+   */
+  getLanguage(): string;
+
+  /**
+   * Change the current language.
+   */
+  setLanguage(language: string): Promise<void>;
+
+  /**
+   * Get all supported languages.
+   */
+  getSupportedLanguages(): string[];
+
+  /**
+   * Get the raw i18next instance for advanced usage.
+   */
+  getI18next(): unknown;
+
+  /**
+   * Add resources programmatically.
+   */
+  addResources(
+    language: string,
+    namespace: string,
+    resources: Record<string, unknown>,
+  ): void;
+
+  /**
+   * Get resource bundles for a language/namespace.
+   */
+  getResources(
+    language?: string,
+    namespace?: string,
+  ): Record<string, unknown> | null;
+}

package/src/localization/validation.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for validating i18n configuration.
+ * Ensures all required language files and namespaces are present.
+ */
+export const I18nConfigSchema = z.object({
+  defaultLanguage: z.string().default("en").describe("Default language code"),
+  fallbackLanguage: z.string().default("en").describe("Fallback language code"),
+  supportedLanguages: z
+    .array(z.string())
+    .default(["en"])
+    .describe("List of supported language codes"),
+  defaultNamespace: z
+    .string()
+    .default("translation")
+    .describe("Default translation namespace"),
+});
+
+/**
+ * Validate a configuration object against the I18n schema.
+ * Throws ZodError if validation fails.
+ */
+export const validateI18nConfig = (
+  config: unknown,
+): ReturnType<typeof I18nConfigSchema.parse> => {
+  return I18nConfigSchema.parse(config);
+};
+
+/**
+ * Safe version of validateI18nConfig.
+ * Returns { success: true, data } or { success: false, errors }.
+ */
+export const safeValidateI18nConfig = (
+  config: unknown,
+):
+  | { success: true; data: z.infer<typeof I18nConfigSchema> }
+  | { success: false; errors: z.ZodError } => {
+  const result = I18nConfigSchema.safeParse(config);
+  return result.success
+    ? { success: true, data: result.data }
+    : { success: false, errors: result.error };
+};

package/src/logs/adapters/console-adapter.ts

@@ -0,0 +1,90 @@
+import type { LoggerAdapter, LoggerInput } from "../types";
+
+/**
+ * Lightweight console-based logger adapter for CLI, desktop apps,
+ * and environments where structured logging is not needed.
+ */
+export class ConsoleLoggerAdapter implements LoggerAdapter {
+  private readonly enableColors: boolean;
+  private readonly enableTimestamps: boolean;
+
+  constructor(options?: { colors?: boolean; timestamps?: boolean }) {
+    this.enableColors = options?.colors ?? true;
+    this.enableTimestamps = options?.timestamps ?? true;
+  }
+
+  private formatMessage(
+    level: string,
+    message: string,
+    input?: LoggerInput,
+  ): string {
+    const timestamp = this.enableTimestamps
+      ? `[${new Date().toISOString()}]`
+      : "";
+    const levelTag = `[${level.toUpperCase()}]`;
+
+    let output = `${timestamp} ${levelTag} ${message}`;
+
+    if (input) {
+      const structured: Record<string, unknown> = {};
+
+      if (input.data !== undefined) {
+        structured["data"] = input.data;
+      }
+
+      if (input.details !== undefined) {
+        structured["details"] = input.details;
+      }
+
+      if (Object.keys(structured).length > 0) {
+        output += ` ${JSON.stringify(structured)}`;
+      }
+    }
+
+    return output;
+  }
+
+  private colorize(text: string, color: string): string {
+    if (!this.enableColors) return text;
+
+    const colors: Record<string, string> = {
+      reset: "\x1b[0m",
+      red: "\x1b[31m",
+      yellow: "\x1b[33m",
+      blue: "\x1b[34m",
+      gray: "\x1b[90m",
+      magenta: "\x1b[35m",
+    };
+
+    return `${colors[color] || ""}${text}${colors["reset"]}`;
+  }
+
+  log(message: string, input?: LoggerInput): void {
+    this.info(message, input);
+  }
+
+  info(message: string, input?: LoggerInput): void {
+    const formatted = this.formatMessage("info", message, input);
+    console.log(this.colorize(formatted, "blue"));
+  }
+
+  trace(message: string, input?: LoggerInput): void {
+    const formatted = this.formatMessage("trace", message, input);
+    console.log(this.colorize(formatted, "gray"));
+  }
+
+  warn(message: string, input?: LoggerInput): void {
+    const formatted = this.formatMessage("warn", message, input);
+    console.warn(this.colorize(formatted, "yellow"));
+  }
+
+  error(message: string, input?: LoggerInput): void {
+    const formatted = this.formatMessage("error", message, input);
+    console.error(this.colorize(formatted, "red"));
+  }
+
+  fatal(message: string, input?: LoggerInput): void {
+    const formatted = this.formatMessage("fatal", message, input);
+    console.error(this.colorize(formatted, "magenta"));
+  }
+}

package/src/logs/adapters/pino-adapter.ts

@@ -0,0 +1,65 @@
+import pino from "pino";
+
+import { createPinoConfig } from "../config";
+import type { LoggerAdapter, LoggerInput } from "../types";
+
+/**
+ * Pino-based logger adapter for production microservices
+ * providing structured, high-performance logging.
+ */
+export class PinoLoggerAdapter implements LoggerAdapter {
+  private readonly pinoLogger: pino.BaseLogger;
+
+  constructor(
+    config?: pino.LoggerOptions,
+    destination?: pino.DestinationStream,
+  ) {
+    this.pinoLogger = pino(config ?? createPinoConfig(), destination);
+  }
+
+  /**
+   * Get the underlying Pino logger instance for advanced usage
+   */
+  getPinoInstance(): pino.BaseLogger {
+    return this.pinoLogger;
+  }
+
+  log(message: string, input?: LoggerInput): void {
+    this.info(message, input);
+  }
+
+  info(message: string, input?: LoggerInput): void {
+    this.pinoLogger.info(
+      { data: input?.data, details: input?.details },
+      message,
+    );
+  }
+
+  trace(message: string, input?: LoggerInput): void {
+    this.pinoLogger.trace(
+      { data: input?.data, details: input?.details },
+      message,
+    );
+  }
+
+  warn(message: string, input?: LoggerInput): void {
+    this.pinoLogger.warn(
+      { data: input?.data, details: input?.details },
+      message,
+    );
+  }
+
+  error(message: string, input?: LoggerInput): void {
+    this.pinoLogger.error(
+      { data: input?.data, details: input?.details },
+      message,
+    );
+  }
+
+  fatal(message: string, input?: LoggerInput): void {
+    this.pinoLogger.fatal(
+      { data: input?.data, details: input?.details },
+      message,
+    );
+  }
+}

package/src/logs/config.ts

@@ -0,0 +1,53 @@
+import type pino from "pino";
+
+export interface PinoConfigOptions {
+  env?: string;
+  serviceName?: string;
+  appVersion?: string;
+  appEnv?: string;
+}
+
+/**
+ * Default Pino logger configuration with sensible fallbacks.
+ * - Uses pino-pretty in non-production environments for readability
+ * - Emits structured JSON in production
+ */
+export const createPinoConfig = (
+  options?: PinoConfigOptions,
+): pino.LoggerOptions => {
+  const env = options?.env ?? process.env["NODE_ENV"] ?? "development";
+  const isPretty = env !== "production";
+
+  const transport = isPretty
+    ? {
+        target: "pino-pretty",
+        options: {
+          colorize: true,
+        },
+      }
+    : undefined;
+
+  return {
+    level: process.env["LOG_LEVEL"] ?? "info",
+    ...(transport ? { transport } : {}),
+    formatters: {
+      bindings: (bindings) => {
+        return {
+          pid: bindings["pid"],
+          service:
+            options?.serviceName ?? process.env["SERVICE_NAME"] ?? "zacatl",
+          environment: env,
+          app: {
+            version:
+              options?.appVersion ?? process.env["APP_VERSION"] ?? "0.0.0",
+            environment: options?.appEnv ?? process.env["APP_ENV"] ?? env,
+          },
+          host: bindings["hostname"],
+        };
+      },
+      level: (label) => {
+        return { level: label.toLowerCase() };
+      },
+    },
+  };
+};

package/src/logs/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Logs module - Pluggable structured logging
+ * @module logs
+ */
+
+export { logger, createLogger } from "./logger";
+export type {
+  Logger,
+  LoggerAdapter,
+  LoggerInput,
+  LoggerAdapterType,
+  PinoLoggerConfig,
+} from "./types";
+export { createPinoConfig, type PinoConfigOptions } from "./config";
+export { ConsoleLoggerAdapter } from "./adapters/console-adapter";
+export { PinoLoggerAdapter } from "./adapters/pino-adapter";

package/src/logs/logger.ts

@@ -0,0 +1,66 @@
+import { PinoLoggerAdapter } from "./adapters/pino-adapter";
+import type { Logger, LoggerAdapter, LoggerInput } from "./types";
+
+/**
+ * Creates a logger instance with a specific adapter.
+ * This is the recommended way to create loggers with custom adapters.
+ *
+ * @param adapter - LoggerAdapter implementation (defaults to PinoLoggerAdapter)
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * import { createLogger, ConsoleLoggerAdapter } from '@sentzunhat/zacatl';
+ *
+ * // Default Pino logger
+ * const logger = createLogger();
+ *
+ * // Console logger for CLI apps
+ * const cliLogger = createLogger(new ConsoleLoggerAdapter());
+ *
+ * // Custom adapter
+ * class WinstonAdapter implements LoggerAdapter { ... }
+ * const customLogger = createLogger(new WinstonAdapter());
+ * ```
+ */
+export const createLogger = (adapter?: LoggerAdapter): Logger => {
+  const adapterInstance = adapter ?? new PinoLoggerAdapter();
+
+  return {
+    log: (message: string, input?: LoggerInput) =>
+      adapterInstance.log(message, input),
+    info: (message: string, input?: LoggerInput) =>
+      adapterInstance.info(message, input),
+    trace: (message: string, input?: LoggerInput) =>
+      adapterInstance.trace(message, input),
+    warn: (message: string, input?: LoggerInput) =>
+      adapterInstance.warn(message, input),
+    error: (message: string, input?: LoggerInput) =>
+      adapterInstance.error(message, input),
+    fatal: (message: string, input?: LoggerInput) =>
+      adapterInstance.fatal(message, input),
+  };
+};
+
+/**
+ * Default logger instance with Pino adapter.
+ * Provides structured JSON logging ready for Prometheus, OpenTelemetry, and log aggregation.
+ *
+ * For custom adapters, use `createLogger()`:
+ * ```typescript
+ * import { createLogger, ConsoleLoggerAdapter } from '@sentzunhat/zacatl';
+ * const cliLogger = createLogger(new ConsoleLoggerAdapter());
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { logger } from '@sentzunhat/zacatl';
+ *
+ * logger.info('Application started');
+ * logger.error('Request failed', {
+ *   data: { userId: 123, endpoint: '/api/users' },
+ *   details: { statusCode: 500 }
+ * });
+ * ```
+ */
+export const logger: Logger = createLogger();