@sentzunhat/zacatl 0.0.14 → 0.0.20

package/src/examples/providers/filesystem-provider.ts

@@ -0,0 +1,198 @@
+/**
+ * Example: FileSystem Provider Implementation
+ *
+ * Handles reading and writing configuration files (YAML, JSON, CSV)
+ * Useful for CLI applications that manage config files
+ *
+ * Installation: npm install js-yaml
+ *
+ * @example
+ * ```typescript
+ * const fsProvider = new FileSystemProvider();
+ * const config = await fsProvider.readYAML('~/.config/app/config.yaml');
+ * await fsProvider.writeJSON('~/.config/app/state.json', state);
+ * ```
+ */
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { CustomError } from "../../error";
+
+export interface FileSystemProviderConfig {
+  encoding?: BufferEncoding;
+}
+
+/**
+ * Expand ~/ to home directory path
+ */
+const expandUserPath = (filePath: string): string => {
+  if (filePath.startsWith("~/")) {
+    return filePath.replace("~", homedir());
+  }
+  return filePath;
+};
+
+/**
+ * FileSystem provider for configuration management
+ * Supports YAML, JSON, and plain text files
+ */
+export class FileSystemProvider {
+  private encoding: BufferEncoding;
+
+  constructor(config: FileSystemProviderConfig = {}) {
+    this.encoding = config.encoding || "utf-8";
+  }
+
+  /**
+   * Read YAML file
+   */
+  readYAML = (filePath: string): Record<string, unknown> => {
+    const path = expandUserPath(filePath);
+
+    try {
+      if (!existsSync(path)) {
+        throw new CustomError({
+          message: `File not found: ${filePath}`,
+          code: 404,
+          reason: "file does not exist",
+        });
+      }
+
+      const yaml = require("js-yaml"); // Lazy load
+      const content = readFileSync(path, this.encoding);
+      return yaml.load(content) as Record<string, unknown>;
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to read YAML file: ${filePath}`,
+        code: 500,
+        reason: "file read error",
+        error: error as Error,
+        metadata: { filePath },
+      });
+    }
+  };
+
+  /**
+   * Read JSON file
+   */
+  readJSON = (filePath: string): unknown => {
+    const path = expandUserPath(filePath);
+
+    try {
+      if (!existsSync(path)) {
+        throw new CustomError({
+          message: `File not found: ${filePath}`,
+          code: 404,
+          reason: "file does not exist",
+        });
+      }
+
+      const content = readFileSync(path, this.encoding);
+      return JSON.parse(content);
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to read JSON file: ${filePath}`,
+        code: 500,
+        reason: "file read error",
+        error: error as Error,
+        metadata: { filePath },
+      });
+    }
+  };
+
+  /**
+   * Read plain text file
+   */
+  readText = (filePath: string): string => {
+    const path = expandUserPath(filePath);
+
+    try {
+      if (!existsSync(path)) {
+        throw new CustomError({
+          message: `File not found: ${filePath}`,
+          code: 404,
+          reason: "file does not exist",
+        });
+      }
+
+      return readFileSync(path, this.encoding);
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to read text file: ${filePath}`,
+        code: 500,
+        reason: "file read error",
+        error: error as Error,
+        metadata: { filePath },
+      });
+    }
+  };
+
+  /**
+   * Write YAML file
+   */
+  writeYAML = (filePath: string, data: Record<string, unknown>): void => {
+    const path = expandUserPath(filePath);
+
+    try {
+      const yaml = require("js-yaml"); // Lazy load
+      const content = yaml.dump(data);
+      writeFileSync(path, content, this.encoding);
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to write YAML file: ${filePath}`,
+        code: 500,
+        reason: "file write error",
+        error: error as Error,
+        metadata: { filePath },
+      });
+    }
+  };
+
+  /**
+   * Write JSON file
+   */
+  writeJSON = (filePath: string, data: unknown, pretty = true): void => {
+    const path = expandUserPath(filePath);
+
+    try {
+      const content = pretty
+        ? JSON.stringify(data, null, 2)
+        : JSON.stringify(data);
+      writeFileSync(path, content, this.encoding);
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to write JSON file: ${filePath}`,
+        code: 500,
+        reason: "file write error",
+        error: error as Error,
+        metadata: { filePath },
+      });
+    }
+  };
+
+  /**
+   * Write plain text file
+   */
+  writeText = (filePath: string, content: string): void => {
+    const path = expandUserPath(filePath);
+
+    try {
+      writeFileSync(path, content, this.encoding);
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to write text file: ${filePath}`,
+        code: 500,
+        reason: "file write error",
+        error: error as Error,
+        metadata: { filePath },
+      });
+    }
+  };
+
+  /**
+   * Check if file exists
+   */
+  exists(filePath: string): boolean {
+    const path = expandUserPath(filePath);
+    return existsSync(path);
+  }
+}

package/src/examples/providers/index.ts

@@ -0,0 +1,6 @@
+import { ProcessProvider } from "./process-provider";
+import { FileSystemProvider } from "./filesystem-provider";
+
+export { ProcessProvider, FileSystemProvider };
+export type { ProcessProviderConfig, CommandResult } from "./process-provider";
+export type { FileSystemProviderConfig } from "./filesystem-provider";

package/src/examples/providers/process-provider.ts

@@ -0,0 +1,150 @@
+/**
+ * ProcessProvider
+ * Handles execution of shell commands and scripts
+ * Useful for CLI tools that need to execute system commands (SSH, Docker, etc.)
+ */
+import { exec, spawn } from "child_process";
+import { promisify } from "util";
+import { CustomError } from "../../error";
+
+const execAsync = promisify(exec);
+
+export interface ProcessProviderConfig {
+  shell?: string;
+  timeout?: number; // milliseconds
+}
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  success: boolean;
+}
+
+export class ProcessProvider {
+  private shell: string;
+  private timeout: number;
+
+  constructor(config: ProcessProviderConfig = {}) {
+    this.shell = config.shell || "/bin/bash";
+    this.timeout = config.timeout || 30000; // 30 seconds default
+  }
+
+  /**
+   * Execute a shell command and return result
+   */
+  async execute(command: string): Promise<CommandResult> {
+    try {
+      const { stdout, stderr } = await execAsync(command, {
+        timeout: this.timeout,
+        shell: this.shell,
+      });
+
+      return {
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        exitCode: 0,
+        success: true,
+      };
+    } catch (error: unknown) {
+      const err = error as any;
+
+      throw new CustomError({
+        message: `Command execution failed: ${command}`,
+        code: 500,
+        reason: "process execution error",
+        error: err,
+        metadata: {
+          command,
+          stdout: err.stdout || "",
+          stderr: err.stderr || "",
+        },
+      });
+    }
+  }
+
+  /**
+   * Execute a command and return result with exit code
+   */
+  async executeWithStatus(command: string): Promise<CommandResult> {
+    return new Promise((resolve) => {
+      exec(
+        command,
+        { timeout: this.timeout, shell: this.shell },
+        (error, stdout, stderr) => {
+          resolve({
+            stdout: stdout.trim(),
+            stderr: stderr.trim(),
+            exitCode: error?.code || 0,
+            success: !error,
+          });
+        },
+      );
+    });
+  }
+
+  /**
+   * Stream output from a long-running command
+   * Useful for real-time output from deployments
+   */
+  async executeStream(
+    command: string,
+    onStdout?: (data: string) => void,
+    onStderr?: (data: string) => void,
+  ): Promise<CommandResult> {
+    return new Promise((resolve, reject) => {
+      try {
+        const child = spawn(command, [], {
+          shell: this.shell,
+          timeout: this.timeout,
+        });
+
+        let stdout = "";
+        let stderr = "";
+
+        child.stdout.on("data", (data) => {
+          const text = data.toString();
+          stdout += text;
+          onStdout?.(text);
+        });
+
+        child.stderr.on("data", (data) => {
+          const text = data.toString();
+          stderr += text;
+          onStderr?.(text);
+        });
+
+        child.on("close", (code) => {
+          resolve({
+            stdout: stdout.trim(),
+            stderr: stderr.trim(),
+            exitCode: code || 0,
+            success: code === 0,
+          });
+        });
+
+        child.on("error", (error) => {
+          reject(
+            new CustomError({
+              message: `Process error: ${command}`,
+              code: 500,
+              reason: "process stream error",
+              error,
+              metadata: { command, stderr },
+            }),
+          );
+        });
+      } catch (error: unknown) {
+        reject(
+          new CustomError({
+            message: `Failed to spawn process: ${command}`,
+            code: 500,
+            reason: "process spawn error",
+            error: error as Error,
+            metadata: { command },
+          }),
+        );
+      }
+    });
+  }
+}

package/src/examples/repositories/index.ts

@@ -0,0 +1,3 @@
+import { SQLiteRepository } from "./sqlite-repository";
+
+export { SQLiteRepository };

package/src/examples/repositories/sqlite-repository.ts

@@ -0,0 +1,170 @@
+/**
+ * Example: SQLite Repository Implementation
+ *
+ * Demonstrates how to implement IRepository<T> for SQLite with strong typing.
+ * Use this pattern for any persistent data source: PostgreSQL, MySQL, Redis, etc.
+ *
+ * Installation: npm install better-sqlite3 @types/better-sqlite3
+ *
+ * @example
+ * ```typescript
+ * import Database from "better-sqlite3";
+ *
+ * interface User { id: string; name: string; email: string; }
+ *
+ * class UserRepository extends SQLiteRepository<User> {
+ *   constructor(db: Database.Database) {
+ *     super(db, 'users');
+ *   }
+ * }
+ *
+ * // Initialize and register through Service
+ * const db = new Database('./data.db');
+ * const service = new Service({
+ *   architecture: {
+ *     infrastructure: { repositories: [UserRepository] }
+ *   }
+ * });
+ * ```
+ */
+import type Database from "better-sqlite3";
+import { IRepository } from "../../service/architecture/infrastructure/repository";
+import { CustomError } from "../../error";
+
+/**
+ * Generic SQLite repository implementation
+ * Extend this class and pass your database instance and table name
+ */
+export abstract class SQLiteRepository<
+  T extends Record<string, unknown>,
+> implements IRepository<T> {
+  protected readonly db: Database.Database;
+  protected readonly tableName: string;
+
+  /**
+   * @param db - Better-sqlite3 database instance
+   * @param tableName - Table to query against
+   */
+  constructor(db: Database.Database, tableName: string) {
+    this.db = db;
+    this.tableName = tableName;
+  }
+
+  async findById(id: string): Promise<T | null> {
+    try {
+      const stmt = this.db.prepare(
+        `SELECT * FROM ${this.tableName} WHERE id = ?`,
+      );
+      const result = stmt.get(id) as T | undefined;
+      return result || null;
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to find record by ID: ${id}`,
+        code: 500,
+        reason: "database query error",
+        error: error as Error,
+        metadata: { id, table: this.tableName },
+      });
+    }
+  }
+
+  async findMany(filter?: Record<string, unknown>): Promise<T[]> {
+    try {
+      if (!filter || Object.keys(filter).length === 0) {
+        const stmt = this.db.prepare(`SELECT * FROM ${this.tableName}`);
+        return stmt.all() as T[];
+      }
+
+      const keys = Object.keys(filter);
+      const conditions = keys.map((k) => `${k} = ?`).join(" AND ");
+      const values = keys.map((k) => filter[k]);
+
+      const stmt = this.db.prepare(
+        `SELECT * FROM ${this.tableName} WHERE ${conditions}`,
+      );
+      return stmt.all(...values) as T[];
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to find records`,
+        code: 500,
+        reason: "database query error",
+        error: error as Error,
+        metadata: { table: this.tableName, filter },
+      });
+    }
+  }
+
+  async create(data: Partial<T>): Promise<T> {
+    try {
+      const keys = Object.keys(data);
+      const placeholders = keys.map(() => "?").join(",");
+      const values = keys.map((k) => data[k as keyof typeof data]);
+
+      const stmt = this.db.prepare(
+        `INSERT INTO ${this.tableName} (${keys.join(",")}) VALUES (${placeholders})`,
+      );
+      stmt.run(...values);
+
+      // Return the created record (simplified—assumes id is auto-generated)
+      return data as T;
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to create record`,
+        code: 500,
+        reason: "database insertion error",
+        error: error as Error,
+        metadata: { table: this.tableName, data },
+      });
+    }
+  }
+
+  async update(id: string, data: Partial<T>): Promise<T | null> {
+    try {
+      const keys = Object.keys(data);
+      const sets = keys.map((k) => `${k} = ?`).join(",");
+      const values = [...keys.map((k) => data[k as keyof typeof data]), id];
+
+      const stmt = this.db.prepare(
+        `UPDATE ${this.tableName} SET ${sets} WHERE id = ?`,
+      );
+      stmt.run(...values);
+
+      return this.findById(id);
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to update record: ${id}`,
+        code: 500,
+        reason: "database update error",
+        error: error as Error,
+        metadata: { id, table: this.tableName },
+      });
+    }
+  }
+
+  async delete(id: string): Promise<boolean> {
+    try {
+      const stmt = this.db.prepare(
+        `DELETE FROM ${this.tableName} WHERE id = ?`,
+      );
+      const result = stmt.run(id);
+      return (result.changes || 0) > 0;
+    } catch (error: unknown) {
+      throw new CustomError({
+        message: `Failed to delete record: ${id}`,
+        code: 500,
+        reason: "database deletion error",
+        error: error as Error,
+        metadata: { id, table: this.tableName },
+      });
+    }
+  }
+
+  async exists(id: string): Promise<boolean> {
+    try {
+      const record = await this.findById(id);
+      return record !== null;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/index.ts

@@ -2,6 +2,33 @@ export * from "./optionals";
 export * from "./configuration";
 export * from "./utils";
 export * from "./error";
-export * from "./micro-service";
-export { MicroService } from "./micro-service";
+export * from "./dependency-injection";
+export * from "./service";
+export { Service } from "./service";
+export type { ConfigService } from "./service";
 export * from "./logs";
+export * from "./runtime";
+export * from "./localization";
+
+// Re-export infrastructure with ORM types
+export * from "./service/architecture/infrastructure";
+
+// Re-export server types for convenience
+export {
+  ServerType,
+  ServerVendor,
+  DatabaseVendor,
+  HandlersType,
+} from "./service/architecture/platform/server/server";
+export type { ConfigServer } from "./service/architecture/platform/server/server";
+
+// Re-export commonly used third-party packages
+export { container } from "tsyringe";
+export type { DependencyContainer } from "tsyringe";
+
+// Re-export Zod for validation
+export { z } from "zod";
+export type { ZodSchema, ZodType, ZodError } from "zod";
+
+// Note: TypeScript utility types (Partial, Required, Readonly, etc.)
+// are globally available and don't need re-export

package/src/locales/en.json

@@ -1,9 +1 @@
-{
-  "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/locales/fr.json

@@ -1,9 +1 @@
-{
-  "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/adapters/index.ts

@@ -0,0 +1,90 @@
+import fs from "fs";
+import path from "path";
+import type { I18nAdapter } from "../types";
+
+/**
+ * Filesystem-based i18n adapter.
+ * Loads translations from JSON files organized as: localesDir/language.json
+ *
+ * @example
+ * const adapter = new FilesystemAdapter('./src/localization/locales');
+ */
+export class FilesystemAdapter implements I18nAdapter {
+  private localesDir: string;
+
+  constructor(localesDir: string) {
+    this.localesDir = localesDir;
+  }
+
+  init(): void {
+    if (!fs.existsSync(this.localesDir)) {
+      throw new Error(`Locales directory not found: ${this.localesDir}`);
+    }
+  }
+
+  loadResources(
+    language: string,
+    _namespace: string = "translation",
+  ): Record<string, unknown> | null {
+    const filePath = path.join(this.localesDir, `${language}.json`);
+
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+
+    try {
+      const content = fs.readFileSync(filePath, "utf-8");
+      return JSON.parse(content);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Failed to load translations from ${filePath}: ${errorMessage}`,
+      );
+    }
+  }
+}
+
+/**
+ * Memory-based i18n adapter.
+ * Stores translations in-memory; useful for testing and embedded scenarios.
+ *
+ * @example
+ * const adapter = new MemoryAdapter({
+ *   en: { translation: { greeting: 'Hello' } }
+ * });
+ */
+export class MemoryAdapter implements I18nAdapter {
+  private resources: Record<string, Record<string, Record<string, unknown>>>;
+
+  constructor(
+    resources: Record<string, Record<string, Record<string, unknown>>> = {},
+  ) {
+    this.resources = resources;
+  }
+
+  loadResources(
+    language: string,
+    namespace: string = "translation",
+  ): Record<string, unknown> | null {
+    return this.resources[language]?.[namespace] ?? null;
+  }
+
+  saveResources(
+    language: string,
+    namespace: string,
+    resources: Record<string, unknown>,
+  ): void {
+    if (!this.resources[language]) {
+      this.resources[language] = {};
+    }
+    this.resources[language]![namespace] = resources;
+  }
+
+  /**
+   * Get all stored resources (for testing/inspection).
+   */
+  getAll(): Record<string, Record<string, Record<string, unknown>>> {
+    return { ...this.resources };
+  }
+}

package/src/localization/index.ts

@@ -0,0 +1,16 @@
+export type { I18nAdapter, I18nConfig, I18nInstance } from "./types";
+
+export {
+  createI18n,
+  createI18nAsync,
+  setGlobalI18n,
+  getI18nOrThrow,
+} from "./localization";
+
+export { FilesystemAdapter, MemoryAdapter } from "./adapters";
+
+export {
+  I18nConfigSchema,
+  validateI18nConfig,
+  safeValidateI18nConfig,
+} from "./validation";

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."
+  }
+}