@sentzunhat/zacatl 0.0.13 → 0.0.20

package/build/utils/base64.d.ts

@@ -0,0 +1,3 @@
+export declare const encodeBase64: (input: string) => string;
+export declare const decodeBase64: (input: string) => string;
+//# sourceMappingURL=base64.d.ts.map

package/build/utils/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"./src/","sources":["utils/base64.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAE5C,CAAC;AAOF,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAE5C,CAAC"}

package/build/utils/base64.js

@@ -0,0 +1,7 @@
+export const encodeBase64 = (input) => {
+    return Buffer.from(input, "utf-8").toString("base64");
+};
+export const decodeBase64 = (input) => {
+    return Buffer.from(input, "base64").toString("utf-8");
+};
+//# sourceMappingURL=base64.js.map

package/build/utils/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"./src/","sources":["utils/base64.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAa,EAAU,EAAE;IACpD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACxD,CAAC,CAAC;AAOF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAa,EAAU,EAAE;IACpD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AACxD,CAAC,CAAC","sourcesContent":["/**\n * Encodes a string to Base64 format.\n * @param input - The string to be encoded.\n * @returns The Base64-encoded string.\n */\nexport const encodeBase64 = (input: string): string => {\n  return Buffer.from(input, \"utf-8\").toString(\"base64\");\n};\n\n/**\n * Decodes a Base64-encoded string.\n * @param input - The Base64 string to be decoded.\n * @returns The decoded string.\n */\nexport const decodeBase64 = (input: string): string => {\n  return Buffer.from(input, \"base64\").toString(\"utf-8\");\n};\n"]}

package/build/utils/hmac.d.ts

@@ -0,0 +1,2 @@
+export declare const generateHmac: (message: string, secretKey: string) => string;
+//# sourceMappingURL=hmac.d.ts.map

package/build/utils/hmac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.d.ts","sourceRoot":"./src/","sources":["utils/hmac.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,EAAE,WAAW,MAAM,KAAG,MAIjE,CAAC"}

package/build/utils/hmac.js

@@ -0,0 +1,7 @@
+import { createHmac } from "crypto";
+export const generateHmac = (message, secretKey) => {
+    const hmac = createHmac("sha256", secretKey);
+    hmac.update(message);
+    return hmac.digest("hex");
+};
+//# sourceMappingURL=hmac.js.map

package/build/utils/hmac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.js","sourceRoot":"./src/","sources":["utils/hmac.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAQpC,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,OAAe,EAAE,SAAiB,EAAU,EAAE;IACzE,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACrB,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC,CAAC","sourcesContent":["import { createHmac } from \"crypto\";\n\n/**\n * Function to generate HMAC using a secret key\n * @param message - The message to be hashed\n * @param secretKey - The secret key used for HMAC\n * @returns The HMAC digest in hexadecimal format\n */\nexport const generateHmac = (message: string, secretKey: string): string => {\n  const hmac = createHmac(\"sha256\", secretKey);\n  hmac.update(message);\n  return hmac.digest(\"hex\");\n};\n"]}

package/build/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./base64";
+export * from "./hmac";
+//# sourceMappingURL=index.d.ts.map

package/build/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"./src/","sources":["utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC"}

package/build/utils/index.js

@@ -0,0 +1,3 @@
+export * from "./base64";
+export * from "./hmac";
+//# sourceMappingURL=index.js.map

package/build/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"./src/","sources":["utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC","sourcesContent":["export * from \"./base64\";\nexport * from \"./hmac\";\n"]}

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "@sentzunhat/zacatl",
-  "main": "src/index.ts",
-  "module": "src/index.ts",
-  "version": "0.0.13",
+  "type": "module",
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "version": "0.0.20",
+  "packageManager": "npm@10.9.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/sentzunhat/zacatl.git"
   },
   "description": "A modular, high-performance TypeScript microservice framework for Node.js, featuring layered architecture, dependency injection, and robust validation for building scalable APIs and distributed systems.",
+  "engines": {
+    "node": ">=24.0.0",
+    "npm": ">=10.0.0"
+  },
+  "volta": {
+    "node": "24.0.0"
+  },
   "keywords": [
     "typescript",
     "microservice",
@@ -50,47 +60,77 @@
   "bugs": {
     "url": "https://github.com/sentzunhat/zacatl/issues"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "start": "npx tsx src/index.ts --project ./tsconfig.json",
     "build": "tsc --project tsconfig.json",
+    "build:watch": "tsc --project tsconfig.json --watch",
     "test": "NODE_ENV=test ENV=test vitest run",
+    "test:watch": "NODE_ENV=test ENV=test vitest",
     "test:coverage": "npm run test -- --coverage",
     "type:check": "tsc -p ./tsconfig.json && tsc -p test/tsconfig.json",
     "lint": "DEBUG=eslint:cli-engine bun eslint .",
     "publish:latest": "npm i && npm run test && npm run test:coverage && npm run type:check && npm run lint && npm run build && npm publish --access public --tag latest"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.24.0",
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.1",
+    "@types/bun": "^1.3.6",
     "@types/config": "^3.3.5",
     "@types/i18n": "^0.13.12",
-    "@types/node": "^22.7.4",
+    "@types/i18next": "^13.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.10.1",
     "@types/sequelize": "^4.28.20",
     "@types/uuid": "^10.0.0",
-    "@typescript-eslint/parser": "^8.29.0",
-    "@vitest/coverage-istanbul": "^3.1.1",
-    "eslint": "^9.20.1",
-    "knip": "^5.47.0",
-    "tsx": "^4.19.1",
-    "typescript": "^5.6.2",
-    "typescript-eslint": "^8.29.0",
-    "vitest": "^3.1.1"
+    "@typescript-eslint/parser": "^8.48.1",
+    "@vitest/coverage-istanbul": "^4.0.15",
+    "eslint": "^9.39.1",
+    "knip": "^5.71.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.48.1",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   },
   "license": "MIT",
+  "files": [
+    "build",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "dependencies": {
-    "@fastify/http-proxy": "^11.1.2",
-    "config": "^4.0.0",
-    "fastify": "^5.3.3",
-    "fastify-type-provider-zod": "^4.0.2",
-    "i18n": "^0.15.1",
-    "mongodb-memory-server": "^10.1.4",
-    "mongoose": "^8.15.0",
-    "sequelize": "^6.37.5",
-    "pino": "^9.7.0",
-    "pino-pretty": "^13.0.0",
+    "@fastify/http-proxy": "^11.4.1",
+    "@fastify/static": "^8.3.0",
+    "@types/express": "^5.0.6",
+    "config": "^4.1.1",
+    "express": "^5.2.1",
+    "fastify": "^5.6.2",
+    "fastify-type-provider-zod": "^6.1.0",
+    "http-proxy-middleware": "^3.0.5",
+    "i18n": "^0.15.3",
+    "i18next": "^25.8.0",
+    "js-yaml": "^4.1.1",
+    "mongodb-memory-server": "^10.4.1",
+    "mongoose": "^9.0.1",
+    "pino": "^10.3.0",
+    "pino-pretty": "^13.1.3",
     "reflect-metadata": "^0.2.2",
+    "sequelize": "^6.37.7",
     "tsyringe": "^4.10.0",
-    "uuid": "^11.1.0",
-    "zod": "^3.25.28"
+    "uuid": "^13.0.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "better-sqlite3": "^12.6.2"
   }
 }

package/src/configuration/app-config.ts

@@ -0,0 +1,24 @@
+/**
+ * Application-wide configuration via node-config
+ * Loads from config/ directory with environment-specific overrides
+ */
+
+import config from "config";
+
+type ConfigInput = {
+  SERVICE_NAME: string;
+  NODE_ENV: string;
+  APP_VERSION: string;
+  APP_ENV: string;
+  CONNECTION_STRING: string;
+};
+
+/**
+ * Get application configuration value from node-config
+ * Reads from config/default.{json,yaml} + config/{NODE_ENV}.{json,yaml}
+ * @param name - Configuration key
+ * @returns Configuration value
+ */
+export const getConfigOrThrow = <T>(name: keyof ConfigInput): T => {
+  return config.get<T>(name);
+};

package/src/configuration/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Configuration module
+ * Provides explicit YAML and JSON config loaders + legacy node-config wrapper
+ */
+
+export type { ConfigFormat, ConfigLoader, LoadedConfig } from "./types";
+
+export { JSONLoader, createJSONLoader } from "./loaders/json-loader";
+export { YAMLLoader, createYAMLLoader } from "./loaders/yaml-loader";
+
+export { getLoader, loadConfig, loadConfigFromPaths } from "./loader";
+
+export {
+  validateConfig,
+  validateLoadedConfig,
+  safeValidateConfig,
+} from "./validation";
+
+// Application-wide configuration (via node-config)
+export { getConfigOrThrow } from "./app-config";

package/src/configuration/loader-factory.ts

@@ -0,0 +1 @@
+export { getLoader, loadConfig, loadConfigFromPaths } from "./loader";

package/src/configuration/loader.ts

@@ -0,0 +1,70 @@
+import { existsSync } from "fs";
+import type { ZodSchema } from "zod";
+import { JSONLoader } from "./loaders/json-loader";
+import { YAMLLoader } from "./loaders/yaml-loader";
+import type { ConfigLoader, ConfigFormat, LoadedConfig } from "./types";
+import { validateConfig } from "./validation";
+
+/**
+ * Get loader for a specific format (explicit selection)
+ * Similar to ORM adapter pattern - you choose which format to use
+ */
+export const getLoader = <T = unknown>(
+  format: ConfigFormat,
+): ConfigLoader<T> => {
+  switch (format) {
+    case "json":
+      return new JSONLoader<T>();
+    case "yaml":
+    case "yml":
+      return new YAMLLoader<T>();
+    default:
+      throw new Error(`Unsupported config format: ${format}`);
+  }
+};
+
+/**
+ * Load configuration with explicit format selection
+ * @param filePath - Path to config file
+ * @param format - Config format ('json', 'yaml', or 'yml')
+ * @param schema - Optional Zod schema for validation
+ * @returns Loaded configuration with metadata
+ */
+export const loadConfig = <T = unknown>(
+  filePath: string,
+  format: ConfigFormat,
+  schema?: ZodSchema<T>,
+): LoadedConfig<T> => {
+  if (!existsSync(filePath)) {
+    throw new Error(`Config file not found: ${filePath}`);
+  }
+
+  const loader = getLoader<T>(format);
+  const rawData = loader.load(filePath);
+
+  const data = schema ? validateConfig(rawData, schema) : (rawData as T);
+
+  return {
+    data,
+    filePath,
+    format,
+  };
+};
+
+/**
+ * Try to load config from multiple paths with explicit format
+ * Returns first found config or throws if none exist
+ */
+export const loadConfigFromPaths = <T = unknown>(
+  paths: Array<{ path: string; format: ConfigFormat }>,
+  schema?: ZodSchema<T>,
+): LoadedConfig<T> => {
+  for (const { path, format } of paths) {
+    if (existsSync(path)) {
+      return loadConfig<T>(path, format, schema);
+    }
+  }
+
+  const pathsList = paths.map((p) => `${p.path} (${p.format})`).join(", ");
+  throw new Error(`No config file found in any of these paths: ${pathsList}`);
+};

package/src/configuration/loaders/index.ts

@@ -0,0 +1,2 @@
+export { JSONLoader, createJSONLoader } from "./json-loader";
+export { YAMLLoader, createYAMLLoader } from "./yaml-loader";

package/src/configuration/loaders/json-loader.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import type { ConfigLoader, ConfigFormat } from "../types";
+
+/**
+ * JSON configuration file loader
+ * Supports standard JSON files with comments stripped
+ */
+export class JSONLoader<T = unknown> implements ConfigLoader<T> {
+  readonly extensions: readonly ConfigFormat[] = ["json"] as const;
+
+  load(filePath: string): T {
+    const resolvedPath = resolve(filePath);
+    const content = readFileSync(resolvedPath, "utf-8");
+    return this.parse(content);
+  }
+
+  parse(content: string): T {
+    // Remove comments (// and /* */) for JSONC support
+    const cleanContent = content
+      .replace(/\/\*[\s\S]*?\*\//g, "") // Remove /* */ comments
+      .replace(/\/\/.*/g, ""); // Remove // comments
+
+    return JSON.parse(cleanContent) as T;
+  }
+}
+
+/**
+ * Factory function to create a JSON loader instance
+ */
+export const createJSONLoader = <T = unknown>(): JSONLoader<T> =>
+  new JSONLoader<T>();

package/src/configuration/loaders/yaml-loader.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import { load } from "js-yaml";
+import type { ConfigLoader, ConfigFormat } from "../types";
+
+/**
+ * YAML configuration file loader
+ * Supports both .yaml and .yml extensions
+ */
+export class YAMLLoader<T = unknown> implements ConfigLoader<T> {
+  readonly extensions: readonly ConfigFormat[] = ["yaml", "yml"] as const;
+
+  load(filePath: string): T {
+    const resolvedPath = resolve(filePath);
+    const content = readFileSync(resolvedPath, "utf-8");
+    return this.parse(content);
+  }
+
+  parse(content: string): T {
+    const result = load(content);
+    if (result === null || result === undefined) {
+      throw new Error("YAML file is empty or invalid");
+    }
+    return result as T;
+  }
+}
+
+/**
+ * Factory function to create a YAML loader instance
+ */
+export const createYAMLLoader = <T = unknown>(): YAMLLoader<T> =>
+  new YAMLLoader<T>();

package/src/configuration/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Configuration loader types and interfaces
+ */
+
+export type ConfigFormat = "json" | "yaml" | "yml";
+
+export interface ConfigLoader<T = unknown> {
+  /**
+   * Load configuration from a file path
+   * @param filePath - Absolute or relative path to config file
+   * @returns Parsed configuration object
+   */
+  load(filePath: string): T;
+
+  /**
+   * Load configuration from a string
+   * @param content - Raw configuration content
+   * @returns Parsed configuration object
+   */
+  parse(content: string): T;
+
+  /**
+   * Supported file extensions for this loader
+   */
+  readonly extensions: readonly ConfigFormat[];
+}
+
+export interface LoadedConfig<T = unknown> {
+  data: T;
+  filePath: string;
+  format: ConfigFormat;
+}

package/src/configuration/validation.ts

@@ -0,0 +1,50 @@
+import type { ZodSchema } from "zod";
+import type { LoadedConfig } from "./types";
+
+/**
+ * Validate configuration data against a Zod schema
+ * @param data - Raw configuration data
+ * @param schema - Zod schema to validate against
+ * @returns Validated and typed configuration
+ */
+export const validateConfig = <T>(data: unknown, schema: ZodSchema<T>): T => {
+  return schema.parse(data);
+};
+
+/**
+ * Validate loaded configuration with a Zod schema
+ * Returns validated data with preserved metadata
+ */
+export const validateLoadedConfig = <T>(
+  loaded: LoadedConfig<unknown>,
+  schema: ZodSchema<T>,
+): LoadedConfig<T> => {
+  const validatedData = validateConfig(loaded.data, schema);
+
+  return {
+    data: validatedData,
+    filePath: loaded.filePath,
+    format: loaded.format,
+  };
+};
+
+/**
+ * Safe validation that returns success/error result
+ */
+export const safeValidateConfig = <T>(
+  data: unknown,
+  schema: ZodSchema<T>,
+):
+  | { success: true; data: T }
+  | { success: false; error: { issues: unknown[] } } => {
+  const result = schema.safeParse(data);
+
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+
+  return {
+    success: false,
+    error: { issues: result.error.issues },
+  };
+};

package/src/dependency-injection/container.ts

@@ -0,0 +1,92 @@
+import "reflect-metadata";
+import { container as tsyringeContainer } from "tsyringe";
+import type { DependencyContainer, InjectionToken } from "tsyringe";
+
+/**
+ * Standalone DI container decoupled from microservice architecture.
+ * Automatically used by Service architecture - typically no manual registration needed.
+ *
+ * For advanced use cases, you can register dependencies manually:
+ *
+ * @example
+ * ```typescript
+ * import { registerDependency, resolveDependency } from '@sentzunhat/zacatl';
+ *
+ * // Manual registration (advanced use case)
+ * class CustomService { ... }
+ * registerDependency('CustomService', CustomService);
+ *
+ * // Resolve manually
+ * const service = resolveDependency<CustomService>('CustomService');
+ * ```
+ *
+ * Preferred approach (automatic registration through Service):
+ * ```typescript
+ * const service = new Service({
+ *   architecture: {
+ *     domain: { providers: [CustomService] }
+ *   }
+ * });
+ * ```
+ */
+
+/**
+ * Get the global DI container instance
+ */
+export const getContainer = (): DependencyContainer => {
+  return tsyringeContainer;
+};
+
+/**
+ * Register a dependency in the container
+ *
+ * @param token - Unique identifier for the dependency
+ * @param implementation - Class or value to register
+ */
+export const registerDependency = <T>(
+  token: InjectionToken<T>,
+  implementation: new (...args: unknown[]) => T,
+): void => {
+  tsyringeContainer.register(token, { useClass: implementation });
+};
+
+/**
+ * Register a singleton dependency (shared instance)
+ *
+ * @param token - Unique identifier for the dependency
+ * @param implementation - Class to register as singleton
+ */
+export const registerSingleton = <T>(
+  token: InjectionToken<T>,
+  implementation: new (...args: unknown[]) => T,
+): void => {
+  tsyringeContainer.registerSingleton(token, implementation);
+};
+
+/**
+ * Register a value (instance) in the container
+ *
+ * @param token - Unique identifier for the dependency
+ * @param value - Instance to register
+ */
+export const registerValue = <T>(token: InjectionToken<T>, value: T): void => {
+  tsyringeContainer.register(token, { useValue: value });
+};
+
+/**
+ * Resolve a dependency from the container
+ *
+ * @param token - Unique identifier for the dependency
+ * @returns Resolved instance
+ */
+export const resolveDependency = <T>(token: InjectionToken<T>): T => {
+  return tsyringeContainer.resolve(token);
+};
+
+/**
+ * Clear all registrations (useful for testing)
+ */
+export const clearContainer = (): void => {
+  tsyringeContainer.clearInstances();
+  tsyringeContainer.reset();
+};

package/src/dependency-injection/index.ts

@@ -0,0 +1 @@
+export * from "./container";

package/src/error/custom.ts

@@ -41,10 +41,19 @@ export class CustomError extends Error {
   public readonly error?: Optional<Error>;
   public readonly time: Date;
   public readonly id: string;
+  public readonly correlationId: string;
 
-  constructor({ message, code, reason, metadata, error }: CustomErrorArgs) {
+  constructor({
+    message,
+    code,
+    reason,
+    metadata,
+    error,
+    correlationId,
+  }: CustomErrorArgs & { correlationId?: string }) {
     super(message);
     this.id = uuidv4();
+    this.correlationId = correlationId || this.id;
     this.custom = true;
     this.name = this.constructor.name;
     this.code = code;
@@ -57,4 +66,46 @@ export class CustomError extends Error {
       Error.captureStackTrace(this, this.constructor);
     }
   }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      reason: this.reason,
+      metadata: this.metadata,
+      error: this.error
+        ? {
+            name: this.error.name,
+            message: this.error.message,
+            stack: this.error.stack,
+          }
+        : undefined,
+      time: this.time.toISOString(),
+      id: this.id,
+      correlationId: this.correlationId,
+      stack: this.stack,
+      custom: this.custom,
+    };
+  }
+
+  public override toString(): string {
+    return (
+      `[` +
+      this.time.toISOString() +
+      `] ` +
+      this.name +
+      `: ` +
+      this.message +
+      `\nCorrelationId: ` +
+      this.correlationId +
+      (this.code ? `\nCode: ` + this.code : "") +
+      (this.reason ? `\nReason: ` + this.reason : "") +
+      (this.metadata
+        ? `\nMetadata: ` + JSON.stringify(this.metadata, null, 2)
+        : "") +
+      (this.error ? `\nCaused by: ` + this.error.toString() : "") +
+      (this.stack ? `\nStack: ` + this.stack : "")
+    );
+  }
 }

package/src/examples/index.ts

@@ -0,0 +1,2 @@
+export * from "./providers";
+export * from "./repositories";