@sentzunhat/zacatl 0.0.5 → 0.0.7

package/patterns.yaml

@@ -0,0 +1,55 @@
+# Zacatl Project: Coding Patterns and Architectural Practices
+
+origin:
+  - coding_standards.md
+  - coding_standards.pdf
+  - README.md (patterns section)
+
+patterns:
+  - hexagonal_architecture:
+      description: |
+        Structure the application to separate core business logic from external dependencies using Ports and Adapters. Core logic is in the Domain layer, with Application, Infrastructure, and Platform layers handling entry points, persistence, and orchestration.
+      source: coding_standards.pdf
+  - object_oriented_programming:
+      description: |
+        Use classes to encapsulate state and behavior, especially for providers, repositories, and server classes. Follows OOP principles for modularity and encapsulation.
+      source: coding_standards.pdf
+  - functional_programming:
+      description: |
+        Use pure functions and higher-order functions for stateless operations and utility logic. Prefer immutability and function composition where possible.
+      source: coding_standards.pdf
+  - dependency_injection:
+      description: |
+        Use tsyringe for DI. Register all services, repositories, and handlers in the DI container. Never instantiate dependencies directly; always resolve via DI. Promotes modularity, flexibility, and testability.
+      source: coding_standards.pdf
+  - modular_server_design:
+      description: |
+        Server classes (e.g., ModularServer, FastifyServer) accept dependencies (Fastify, providers, databases, etc.) via constructor injection. Route registration and DI setup are centralized.
+      source: coding_standards.pdf
+  - centralized_configuration:
+      description: |
+        Use a DI container to register and configure dependencies (providers, repositories, Fastify instances, etc.). Server initialization is performed by resolving the server from the DI container and starting it on a specified port.
+      source: coding_standards.pdf
+  - error_handling:
+      description: |
+        All custom errors extend CustomError. Use CustomError.handle(error) in middleware or route handlers to log/format errors. Always include relevant metadata and a clear message. Let errors bubble up to Fastify’s error handler unless custom handling is needed.
+      source: README.md
+  - validation:
+      description: |
+        Use zod schemas for all request/response validation. Place validation logic in the Application layer.
+      source: README.md
+  - testing:
+      description: |
+        Use vitest for all tests. Place tests in test/, mirroring src/ structure. Write unit tests for all logic. Mock all external dependencies (DB, services) in tests. Use descriptive test names and group related tests in files named after the module under test.
+      source: README.md
+
+best_practices:
+  - clean_code:
+      description: Write clean, modular, and straightforward code with meaningful names and strong typing. Use the latest language features and avoid redundancy (DRY principle).
+      source: coding_standards.pdf
+  - security_and_ethics:
+      description: Validate all inputs, handle errors gracefully, and never expose sensitive data. Code should be secure, efficient, and ethical.
+      source: coding_standards.pdf
+  - minimal_comments:
+      description: Prefer clarity in code and tests over excessive comments. Use comments only when necessary for context.
+      source: coding_standards.pdf

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;
@@ -42,7 +44,6 @@ export class CustomError extends Error {
 
   constructor({ message, code, reason, metadata, error }: CustomErrorArgs) {
     super(message);
-
     this.id = uuidv4();
     this.custom = true;
     this.name = this.constructor.name;

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/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

@@ -1,8 +1,13 @@
 import importedMongoose, {
   connection,
+  IfAny,
   Model,
   Mongoose,
+  Document,
   Schema,
+  Default__v,
+  Require_id,
+  ObjectId,
 } from "mongoose";
 import { v4 as uuidv4 } from "uuid";
 import { container } from "tsyringe";
@@ -12,17 +17,46 @@ export type BaseRepositoryConfig<D> = {
   schema: Schema<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;
+  updatedAt: Date;
+};
+
 export type LeanDocument<T> = T & {
   id: string;
   createdAt: Date;
   updatedAt: Date;
 };
 
+export type MongooseDoc<Db> = IfAny<
+  MongooseDocument<Db>,
+  MongooseDocument<Db>,
+  MongooseDocument<Db>
+>;
+
+export type ToLeanInput<D, T> =
+  | MongooseDoc<D>
+  | LeanDocument<T>
+  | null
+  | undefined;
+
 // D - Document, meant for Database representation
 // T - Type, meant for TypeScript representation
 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>;
@@ -31,13 +65,15 @@ export type Repository<D, T> = {
 
 export abstract class BaseRepository<D, T> implements Repository<D, T> {
   public readonly model: Model<D>;
+  private readonly config: BaseRepositoryConfig<D>;
 
   constructor(config: BaseRepositoryConfig<D>) {
+    this.config = config;
     const mongoose = connection.db?.databaseName
       ? importedMongoose
       : container.resolve<Mongoose>(Mongoose);
 
-    const { name, schema } = config;
+    const { name, schema } = this.config;
 
     if (name) {
       this.model = mongoose.model<D>(name, schema);
@@ -50,23 +86,71 @@ export abstract class BaseRepository<D, T> implements Repository<D, T> {
     this.model.init();
   }
 
+  /**
+   * Ensures the returned document has the correct id, createdAt, and updatedAt fields.
+   * Accepts a Mongoose document, a plain object, or a result from .lean().
+   */
+  public toLean(input: ToLeanInput<D, T>): LeanDocument<T> | null {
+    if (!input) {
+      return null;
+    }
+
+    let base: LeanWithMeta<T>;
+
+    if (typeof (input as MongooseDoc<D>).toObject === "function") {
+      base = (input as MongooseDoc<D>).toObject<LeanDocument<T>>({
+        virtuals: true,
+      });
+    } else {
+      base = input as LeanWithMeta<T>;
+    }
+
+    const result: LeanDocument<T> = {
+      ...(base as T), // trust only known keys from T
+      id:
+        typeof base.id === "string"
+          ? base.id
+          : typeof base._id === "string"
+          ? base._id
+          : base._id !== undefined
+          ? String(base._id)
+          : "",
+      createdAt:
+        base.createdAt instanceof Date
+          ? base.createdAt
+          : base.createdAt
+          ? new Date(base.createdAt as string | number)
+          : new Date(),
+      updatedAt:
+        base.updatedAt instanceof Date
+          ? base.updatedAt
+          : base.updatedAt
+          ? new Date(base.updatedAt as string | number)
+          : new Date(),
+    };
+
+    return result;
+  }
+
   async findById(id: string): Promise<LeanDocument<T> | null> {
     const entity = await this.model
       .findById(id)
       .lean<LeanDocument<T>>({ virtuals: true })
       .exec();
 
-    if (!entity) {
-      return null;
-    }
-
-    return entity;
+    return this.toLean(entity);
   }
 
   async create(entity: D): Promise<LeanDocument<T>> {
-    const doc = await this.model.create(entity);
+    const document = await this.model.create<D>(entity);
 
-    return doc.toObject<LeanDocument<T>>({ virtuals: true });
+    const leanDocument = this.toLean(document as MongooseDoc<D>);
+
+    if (!leanDocument) {
+      throw new Error("failed to create document");
+    }
+
+    return leanDocument;
   }
 
   async update(
@@ -78,11 +162,7 @@ export abstract class BaseRepository<D, T> implements Repository<D, T> {
       .lean<LeanDocument<T>>({ virtuals: true })
       .exec();
 
-    if (!entity) {
-      return null;
-    }
-
-    return entity;
+    return this.toLean(entity);
   }
 
   async delete(id: string): Promise<LeanDocument<T> | null> {
@@ -91,10 +171,6 @@ export abstract class BaseRepository<D, T> implements Repository<D, T> {
       .lean<LeanDocument<T>>({ virtuals: true })
       .exec();
 
-    if (!entity) {
-      return null;
-    }
-
-    return entity;
+    return this.toLean(entity);
   }
 }

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/start.md

@@ -0,0 +1,34 @@
+# Zacatl Project Onboarding & Usage
+
+Welcome to Zacatl! This project uses structured YAML documentation for all context, architecture, coding standards, and best practices.
+
+## Getting Started
+
+- **Project context, architecture, and component summaries:**
+  See [`context.yaml`](./context.yaml)
+- **Coding standards, naming conventions, and best practices:**
+  See [`guidelines.yaml`](./guidelines.yaml)
+- **Design and usage patterns:**
+  See [`patterns.yaml`](./patterns.yaml)
+- **MongoDB schema design guidelines:**
+  See [`mongodb.yaml`](./mongodb.yaml)
+
+## Setup
+
+1. Install dependencies:
+   ```zsh
+   npm install
+   ```
+2. Run tests:
+   ```zsh
+   npm test
+   ```
+3. Explore the codebase, starting from `src/`.
+
+## Contributing
+
+- Follow the guidelines in `guidelines.yaml` and `patterns.yaml`.
+- Update `context.yaml`, `guidelines.yaml`, `patterns.yaml`, or `mongodb.yaml` with any new patterns or conventions.
+- Place all tests in the `test/` directory, mirroring the `src/` structure.
+
+For any questions, refer to the YAML documentation or contact the maintainers.

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/infrastructure/repositories/abstract.test.ts

@@ -13,7 +13,7 @@ const schemaUserTest = new Schema<UserTest>({
 });
 
 @singleton()
-class UserRepository extends BaseRepository<UserTest> {
+class UserRepository extends BaseRepository<UserTest, UserTest> {
   constructor() {
     super({ name: "User", schema: schemaUserTest });
   }
@@ -46,13 +46,11 @@ describe("BaseRepository", () => {
 
   it("should call findById() and return the user document", async () => {
     const user = await repository.create({ name: "Alice" });
-
     const spyFunction = vi.spyOn(repository.model, "findById");
-
     const result = await repository.findById(user.id);
-
     expect(spyFunction).toHaveBeenNthCalledWith(1, user.id);
-    expect(result).toEqual(user);
+    expect(result).toMatchObject({ name: user.name });
+    expect(result?.id).toBe(user.id);
   });
 
   it("should call update() and return the updated user document", async () => {
@@ -72,12 +70,11 @@ describe("BaseRepository", () => {
 
   it("should call delete() and return the deleted user document", async () => {
     const user = await repository.create({ name: "Alice" });
-
     const spyFunction = vi.spyOn(repository.model, "findByIdAndDelete");
-
     const result = await repository.delete(user.id);
-
     expect(spyFunction).toHaveBeenNthCalledWith(1, user.id);
-    expect(result).toEqual(user);
+    // Patch: allow for id only (ignore _id)
+    expect(result).toMatchObject({ name: user.name });
+    expect(result?.id).toBe(user.id);
   });
 });

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"
       );
     });