@sentzunhat/zacatl 0.0.6 → 0.0.8

package/README.md

@@ -1,42 +1,128 @@
 # Zacatl Microservice Framework
 
-A blazing fast, modular TypeScript microservice framework for Node.js, designed for rapid development of high-performance APIs and distributed systems. Zacatl enforces a clean, layered architecture, robust typing, and seamless collaboration between human and AI contributors.
+[![npm version](https://img.shields.io/npm/v/@sentzunhat/zacatl.svg)](https://www.npmjs.com/package/@sentzunhat/zacatl)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/)
 
----
+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.
 
-## 1. How Humans and AI Agents Can Contribute
+## Table of Contents
 
-- **Read the docs:** Always review `guidelines.yaml`, `context.yaml`, and `patterns.yaml` before making changes.
-- **Follow conventions:** Use dependency injection (`tsyringe`), maintain modularity, and respect the layered architecture.
-- **Testing:** All logic must be unit tested (`vitest`). Place tests in `test/unit/`, mirroring the `src/` structure.
-- **Documentation:** Update YAML docs with new patterns, features, or conventions. AI agents should parse YAML for context.
-- **Register everything:** All services, repositories, and handlers must be registered in the DI container.
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Project Structure](#project-structure)
+- [Core Concepts](#core-concepts)
+- [Configuration](#configuration)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [Documentation](#documentation)
+- [License](#license)
 
----
+## Overview
+
+Zacatl is a TypeScript-first microservice framework that enforces clean, layered (hexagonal) architecture with strict separation of concerns. It's designed for rapid development of robust APIs and distributed systems, with built-in support for dependency injection, validation, and seamless collaboration between human and AI contributors.
+
+## Key Features
+
+- **🏗️ Layered Architecture**: Clean separation with Application, Domain, Infrastructure, and Platform layers
+- **💉 Dependency Injection**: Built-in DI container using `tsyringe` for better modularity
+- **⚡ High Performance**: Built on Fastify for maximum speed and efficiency
+- **🔍 Type Safety**: Full TypeScript support with strict typing and generics
+- **✅ Validation**: Request/response validation using Zod schemas
+- **🧪 Testing**: Comprehensive testing with Vitest and clear test structure
+- **📊 MongoDB Support**: Built-in repository pattern with Mongoose integration
+- **🌐 Internationalization**: Multi-language support with i18n
+- **🚀 Production Ready**: Error handling, logging, and monitoring built-in
+
+## Installation
+
+Install Zacatl using npm:
+
+```bash
+npm install @sentzunhat/zacatl
+```
+
+Or with yarn:
+
+```bash
+yarn add @sentzunhat/zacatl
+```
+
+## Quick Start
+
+Here's a minimal example to get you started:
+
+```typescript
+import Fastify from "fastify";
+import { MicroService } from "@sentzunhat/zacatl";
+
+const fastifyApp = Fastify();
+
+const microservice = new MicroService({
+  architecture: {
+    application: {
+      entryPoints: {
+        rest: {
+          hookHandlers: [], // Add hook handler classes
+          routeHandlers: [], // Add route handler classes
+        },
+      },
+    },
+    domain: { providers: [] }, // Add domain provider classes
+    infrastructure: { repositories: [] }, // Add repository classes
+    service: {
+      name: "my-service",
+      server: {
+        type: "SERVER",
+        vendor: "FASTIFY",
+        instance: fastifyApp,
+      },
+      databases: [
+        // Example for MongoDB:
+        // {
+        //   vendor: "MONGOOSE",
+        //   instance: new Mongoose(),
+        //   connectionString: "mongodb://localhost/mydb",
+        // }
+      ],
+    },
+  },
+});
 
-## 2. Project Structure & Layer Overview
+await microservice.start({ port: 9000 });
+```
+
+For a complete example with route handlers, see our [examples](./examples) directory.
+
+## Project Structure
 
 ```
 src/
-  configuration.ts         # App configuration (env, settings)
-  logs.ts                  # Logging utilities
-  optionals.ts             # Optional helpers/utilities
-  error/                   # Custom error classes (BadRequest, NotFound, etc.)
-  locales/                 # Localization files (en.json, fr.json, ...)
-  micro-service/
-    architecture/
-      application/         # Entry points, route/hook handlers, validation
-      domain/              # Business logic, models, providers, services
-      infrastructure/      # DB repositories, adapters
-      platform/            # Service orchestration, DI setup
-    index.ts               # Microservice layer entry
-  utils/                   # Utility functions (base64, hmac, etc.)
+├── configuration.ts         # App configuration and environment settings
+├── logs.ts                  # Structured logging with Pino
+├── optionals.ts             # Optional utility types and helpers
+├── error/                   # Custom error classes (BadRequest, NotFound, etc.)
+├── locales/                 # Internationalization files (en.json, fr.json)
+├── micro-service/
+│   └── architecture/
+│       ├── application/     # HTTP entry points, validation, route handlers
+│       ├── domain/          # Business logic, models, services (pure)
+│       ├── infrastructure/  # Database repositories, external adapters
+│       └── platform/        # Service orchestration, DI setup, startup
+└── utils/                   # Utility functions (base64, hmac, etc.)
+
+test/
+└── unit/                    # Unit tests mirroring src/ structure
 ```
 
-- **Application:** Handles HTTP entry points, validation, and delegates to domain logic.
-- **Domain:** Pure business logic, models, and providers. No infrastructure dependencies.
-- **Infrastructure:** Persistence (MongoDB repositories), adapters, and external integrations.
-- **Platform:** Bootstraps the app, configures DI, and starts the server.
+### Layer Responsibilities
+
+- **Application Layer**: Handles HTTP requests, validation, and delegates to domain logic
+- **Domain Layer**: Contains pure business logic, models, and services (no infrastructure dependencies)
+- **Infrastructure Layer**: Manages persistence (MongoDB repositories) and external integrations
+- **Platform Layer**: Bootstraps the application, configures DI container, and starts the server
 
 ---
 

package/package.json

@@ -2,12 +2,43 @@
   "name": "@sentzunhat/zacatl",
   "main": "src/index.ts",
   "module": "src/index.ts",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "repository": {
     "type": "git",
     "url": "https://github.com/sentzunhat/zacatl.git"
   },
-  "description": "",
+  "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.",
+  "keywords": [
+    "typescript",
+    "microservice",
+    "microservices",
+    "framework",
+    "nodejs",
+    "dependency-injection",
+    "hexagonal-architecture",
+    "layered-architecture",
+    "clean-architecture",
+    "fastify",
+    "mongodb",
+    "mongoose",
+    "zod",
+    "validation",
+    "vitest",
+    "testing",
+    "api",
+    "rest-api",
+    "backend",
+    "server",
+    "enterprise",
+    "scalable",
+    "modular",
+    "tsyringe",
+    "pino",
+    "logging",
+    "i18n",
+    "internationalization",
+    "artisan"
+  ],
   "author": "Diego Beltran <beltrd@gmail.com> (https://sentzunhat.com)",
   "contributors": [
     {

package/src/error/custom.ts

@@ -14,7 +14,9 @@ export type HttpStatusCode =
   | 502 // Bad Gateway
   | 503; // Service Unavailable;
 
-export type ErrorCode = Optional<HttpStatusCode | string>;
+export type StatusCodeString = "invalid";
+
+export type ErrorCode = Optional<HttpStatusCode | StatusCodeString>;
 
 export interface CustomErrorsArgs {
   message: string;

package/src/micro-service/architecture/application/entry-points/rest/common/handler.ts

@@ -1,11 +1,10 @@
-import { z } from "zod";
 import { FastifyReply } from "fastify";
 
 import { Request } from "./request";
 
 export type Handler<
   TBody,
-  TQuerystring = z.ZodSchema<Record<string, string>>,
+  TQuerystring = Record<string, string>,
   TParams = void
 > = (
   request: Request<TBody, TQuerystring, TParams>,

package/src/micro-service/architecture/application/entry-points/rest/common/request.ts

@@ -1,17 +1,16 @@
-import { z } from "zod";
 import { IncomingMessage } from "http";
 import { FastifySchema, FastifyRequest, RawServerBase } from "fastify";
 
 export type Request<
   TBody,
-  TQuerystring = z.ZodSchema<Record<string, string>>,
+  TQuerystring = Record<string, string>,
   TParams = void
 > = FastifyRequest<
   {
     Body: TBody;
     Querystring: TQuerystring;
     Params: TParams;
-    Headers: z.ZodSchema<Record<string, string>>;
+    Headers: Record<string, string>;
   },
   RawServerBase,
   IncomingMessage,

package/src/micro-service/architecture/application/entry-points/rest/route-handlers/abstract.ts

@@ -5,6 +5,20 @@ import { HTTPMethods, FastifySchema, FastifyReply } from "fastify";
 import { RouteHandler } from "./route-handler";
 import { Request } from "../common/request";
 
+export type RouteSchema<
+  TBody = void,
+  TQuerystring = Record<string, string>,
+  TParams = Record<string, string>,
+  THeaders = Record<string, string>,
+  TResponse = void
+> = {
+  body?: z.ZodSchema<TBody>;
+  querystring?: z.ZodSchema<TQuerystring>;
+  params?: z.ZodSchema<TParams>;
+  headers?: z.ZodSchema<THeaders>;
+  response?: z.ZodSchema<TResponse>;
+};
+
 export type AbstractRouteHandlerConstructor = {
   url: string;
   method: HTTPMethods;
@@ -15,9 +29,9 @@ export type HandlerOutput<TResponse> = TResponse;
 
 export abstract class AbstractRouteHandler<
   TBody = void,
-  TQuerystring = z.ZodSchema<Record<string, string>>,
+  TQuerystring = Record<string, string>,
   TResponse = void,
-  TParams = void
+  TParams = Record<string, string>
 > implements RouteHandler<TBody, TQuerystring, TParams>
 {
   public url: string;

package/src/micro-service/architecture/application/entry-points/rest/route-handlers/get-route-handler.ts

@@ -1,6 +1,4 @@
-import { z } from "zod";
 import { FastifySchema } from "fastify";
-
 import { AbstractRouteHandler } from "./abstract";
 
 export type GetRouteHandlerConstructor = {
@@ -9,9 +7,9 @@ export type GetRouteHandlerConstructor = {
 };
 
 export abstract class GetRouteHandler<
-  TBody = never,
-  TResponse = never,
-  TQuerystring = z.ZodSchema<Record<string, string>>,
+  TBody = void,
+  TQuerystring = Record<string, string>,
+  TResponse = void,
   TParams = void
 > extends AbstractRouteHandler<TBody, TQuerystring, TResponse, TParams> {
   constructor(args: GetRouteHandlerConstructor) {

package/src/micro-service/architecture/application/entry-points/rest/route-handlers/post-route-handler.ts

@@ -1,6 +1,4 @@
-import { z } from "zod";
 import { FastifySchema } from "fastify";
-
 import { AbstractRouteHandler } from "./abstract";
 
 export type PostRouteHandlerConstructor = {
@@ -9,10 +7,10 @@ export type PostRouteHandlerConstructor = {
 };
 
 export abstract class PostRouteHandler<
-  TBody = never,
-  TResponse = never,
-  TQuerystring = z.ZodSchema<Record<string, string>>,
-  TParams = void
+  TBody = unknown,
+  TResponse = unknown,
+  TQuerystring = Record<string, string>,
+  TParams = Record<string, string>
 > extends AbstractRouteHandler<TBody, TQuerystring, TResponse, TParams> {
   constructor(args: PostRouteHandlerConstructor) {
     super({

package/src/micro-service/architecture/application/entry-points/rest/route-handlers/route-handler.ts

@@ -1,11 +1,10 @@
-import { z } from "zod";
 import { FastifySchema, HTTPMethods } from "fastify";
 
 import { Handler } from "../common/handler";
 
 export type RouteHandler<
   TBody = void,
-  TQuerystring = z.ZodSchema<Record<string, string>>,
+  TQuerystring = Record<string, string>,
   TParams = void
 > = {
   url: string;

package/src/micro-service/architecture/infrastructure/repositories/abstract.ts

@@ -7,6 +7,7 @@ import importedMongoose, {
   Schema,
   Default__v,
   Require_id,
+  ObjectId,
 } from "mongoose";
 import { v4 as uuidv4 } from "uuid";
 import { container } from "tsyringe";
@@ -18,6 +19,14 @@ export type BaseRepositoryConfig<D> = {
 
 export type WithMongooseMeta<T> = Default__v<Require_id<T>>;
 
+export type MongooseDocument<Db> = Document<
+  ObjectId,
+  {},
+  Db,
+  Record<string, string>
+> &
+  WithMongooseMeta<Db>;
+
 export type LeanWithMeta<T> = WithMongooseMeta<T> & {
   id: string;
   createdAt: Date;
@@ -31,9 +40,9 @@ export type LeanDocument<T> = T & {
 };
 
 export type MongooseDoc<Db> = IfAny<
-  Db,
-  unknown,
-  Document<unknown, {}, Db, {}> & WithMongooseMeta<Db>
+  MongooseDocument<Db>,
+  MongooseDocument<Db>,
+  MongooseDocument<Db>
 >;
 
 export type ToLeanInput<D, T> =
@@ -47,6 +56,7 @@ export type ToLeanInput<D, T> =
 export type Repository<D, T> = {
   model: Model<D>;
 
+  toLean(input: ToLeanInput<D, T>): LeanDocument<T> | null;
   findById(id: string): Promise<LeanDocument<T> | null>;
   create(entity: D): Promise<LeanDocument<T>>;
   update(id: string, update: Partial<D>): Promise<LeanDocument<T> | null>;
@@ -62,12 +72,15 @@ export abstract class BaseRepository<D, T> implements Repository<D, T> {
     const mongoose = connection.db?.databaseName
       ? importedMongoose
       : container.resolve<Mongoose>(Mongoose);
+
     const { name, schema } = this.config;
+
     if (name) {
       this.model = mongoose.model<D>(name, schema);
     } else {
       this.model = mongoose.model<D>(uuidv4(), schema);
     }
+
     this.model.createCollection();
     this.model.createIndexes();
     this.model.init();
@@ -77,20 +90,17 @@ export abstract class BaseRepository<D, T> implements Repository<D, T> {
    * Ensures the returned document has the correct id, createdAt, and updatedAt fields.
    * Accepts a Mongoose document, a plain object, or a result from .lean().
    */
-  private toLean(input: ToLeanInput<D, T>): LeanDocument<T> | null {
+  public toLean(input: ToLeanInput<D, T>): LeanDocument<T> | null {
     if (!input) {
       return null;
     }
 
     let base: LeanWithMeta<T>;
 
-    if (
-      Object.prototype.hasOwnProperty.call(input, "toObject") &&
-      typeof (input as unknown as { toObject: unknown }).toObject === "function"
-    ) {
-      base = (
-        input as Document<unknown, {}, D, {}> & WithMongooseMeta<D>
-      ).toObject<LeanDocument<T>>({ virtuals: true });
+    if (typeof (input as MongooseDoc<D>).toObject === "function") {
+      base = (input as MongooseDoc<D>).toObject<LeanDocument<T>>({
+        virtuals: true,
+      });
     } else {
       base = input as LeanWithMeta<T>;
     }
@@ -132,11 +142,15 @@ export abstract class BaseRepository<D, T> implements Repository<D, T> {
   }
 
   async create(entity: D): Promise<LeanDocument<T>> {
-    const doc = await this.model.create(entity);
+    const document = await this.model.create<D>(entity);
 
-    doc.toObject();
+    const leanDocument = this.toLean(document as MongooseDoc<D>);
+
+    if (!leanDocument) {
+      throw new Error("failed to create document");
+    }
 
-    return this.toLean(doc)!;
+    return leanDocument;
   }
 
   async update(

package/src/micro-service/architecture/platform/service/service.ts

@@ -206,6 +206,10 @@ export class Service implements ServicePort {
   }
 
   public async configureDatabases(): Promise<void> {
+    if (!this.databases || this.databases.length === 0) {
+      return; // No databases to configure
+    }
+
     for (const database of this.databases) {
       const strategy = strategiesForDatabaseVendor[database.vendor];
 

package/test/unit/micro-service/architecture/application/application.test.ts

@@ -16,7 +16,14 @@ class DummyHookHandler implements HookHandler {
   async execute(_: FastifyRequest): Promise<void> {}
 }
 
-class DummyRouteHandler extends AbstractRouteHandler {
+import { FastifyReply } from "fastify";
+
+class DummyRouteHandler extends AbstractRouteHandler<
+  void, // Body
+  Record<string, string>, // Querystring
+  void, // Params
+  void // Response
+> {
   constructor() {
     super({
       url: "/",
@@ -25,7 +32,17 @@ class DummyRouteHandler extends AbstractRouteHandler {
     });
   }
 
-  handler(_: Request<void, {}>): void | Promise<void> {}
+  handler(
+    _: Request<
+      void, // Body
+      Record<string, string>, // Querystring
+      void // Params
+    >,
+    __: FastifyReply
+  ): void | Promise<void> {
+    // Dummy implementation
+    return;
+  }
 }
 
 const fakeConfig: ConfigApplication = {

package/test/unit/micro-service/architecture/application/entry-points/rest/route-handlers/abstract.test.ts

@@ -10,9 +10,29 @@ import {
   Request,
 } from "../../../../../../../../src/micro-service/architecture/application";
 
-class TestRouteHandler extends AbstractRouteHandler<unknown, string, unknown> {
-  async handler(_: unknown, __: unknown): Promise<string> {
-    return "Test Data";
+class TestRouteHandler extends AbstractRouteHandler<
+  void, // Body
+  Record<string, string>, // Querystring
+  void, // Params
+  void // Response
+> {
+  constructor() {
+    super({
+      url: "/",
+      schema: {},
+      method: "GET",
+    });
+  }
+
+  handler(
+    _: Request<
+      void, // Body
+      Record<string, string>, // Querystring
+      void // Params
+    >
+  ): void | Promise<void> {
+    // Dummy implementation
+    return;
   }
 }
 
@@ -20,15 +40,15 @@ describe("AbstractRouteHandler", () => {
   it("executes the handler and sends the proper response", async () => {
     vi.spyOn(i18n, "__").mockReturnValue("Default success");
 
-    const fakeRequest = createFakeFastifyRequest() as Request<unknown, string>;
+    const fakeRequest = createFakeFastifyRequest() as Request<
+      void, // Body
+      Record<string, string>, // Querystring
+      void // Params
+    >;
 
     const fakeReply: any = createFakeFastifyReply();
 
-    const testHandler = new TestRouteHandler({
-      url: "/test",
-      method: "GET",
-      schema: {},
-    });
+    const testHandler = new TestRouteHandler();
 
     await testHandler.execute(fakeRequest, fakeReply);
 
@@ -36,7 +56,7 @@ describe("AbstractRouteHandler", () => {
     expect(fakeReply.send).toHaveBeenCalledWith({
       ok: true,
       message: "Default success",
-      data: "Test Data",
+      data: undefined,
     });
   });
 });

package/test/unit/micro-service/architecture/application/entry-points/rest/route-handlers/post-route-handler.test.ts

@@ -10,9 +10,17 @@ import {
   createFakeFastifyRequest,
 } from "../../../../../../helpers/common/common";
 
-class TestPostRouteHandler extends PostRouteHandler<unknown, string, unknown> {
-  async handler(_: unknown, __: unknown): Promise<string> {
-    return "Test POST response";
+class TestPostRouteHandler extends PostRouteHandler<{}, {}, {}, {}> {
+  constructor() {
+    super({
+      url: "/post-test",
+      schema: {}, // Use an empty schema for test purposes.
+    });
+  }
+
+  handler(_: Request<{}, {}, {}>): {} | Promise<{}> {
+    // Dummy implementation
+    return {};
   }
 }
 
@@ -20,12 +28,9 @@ describe("PostRouteHandler", () => {
   it("executes POST handler and sends proper response", async () => {
     vi.spyOn(i18n, "__").mockReturnValue("Default success POST");
 
-    const testHandler = new TestPostRouteHandler({
-      url: "/post-test",
-      schema: {}, // Use an empty schema for test purposes.
-    });
+    const testHandler = new TestPostRouteHandler();
 
-    const fakeRequest = createFakeFastifyRequest() as Request<unknown, string>;
+    const fakeRequest = createFakeFastifyRequest() as Request<{}, {}, {}>;
     const fakeReply = createFakeFastifyReply();
 
     await testHandler.execute(fakeRequest, fakeReply);
@@ -34,7 +39,7 @@ describe("PostRouteHandler", () => {
     expect(fakeReply.send).toHaveBeenCalledWith({
       ok: true,
       message: "Default success POST",
-      data: "Test POST response",
+      data: {},
     });
   });
 });

package/test/unit/micro-service/architecture/platform/service/service.test.ts

@@ -146,6 +146,8 @@ describe("Service", () => {
       const port = 3000;
       const service = new Service(config);
 
+      await service.configureDatabases();
+
       await service.start({ port });
 
       expect(
@@ -184,15 +186,13 @@ describe("Service", () => {
     });
 
     it("should throw an error if database configuration fails", async () => {
-      const port = 3000;
-
       strategiesForDatabaseVendor[DatabaseVendor.MONGOOSE] = originalDbStrategy;
 
       fakeMongoose.connect.mockRejectedValue(new Error("db connect failed"));
 
       const service = new Service(config);
 
-      await expect(service.start({ port })).rejects.toThrow(
+      await expect(service.configureDatabases()).rejects.toThrow(
         "failed to configure database for service"
       );
     });