@sentzunhat/zacatl 0.0.0-alpha.9 → 0.0.3

package/README.md

@@ -1,64 +1,67 @@
-# zacatl
+# Zacatl
 
-A blazing fast, minimal, and straightforward microservice framework for Node.js, designed for rapid development of high-performance APIs and distributed systems.
+[![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/)
 
-## Project Description
+A blazing fast, minimal, and straightforward microservice framework for Node.js, designed for rapid development of high-performance APIs and distributed systems. Zacatl provides a clean, modular architecture with robust typing support, letting you focus on business logic instead of infrastructure concerns.
 
-**zacatl** (published as `@sentzunhat/zacatl`) is a TypeScript-first microservice library that enables you to bootstrap robust, scalable services with minimal configuration. Built on top of Fastify and Mongoose, it provides a modular architecture for defining application logic, infrastructure, and service orchestration, while supporting advanced features like dependency injection, localization, and flexible error handling.
+## Table of Contents
 
-## Features
-
-- **Fastify-based HTTP server**: Ultra-fast routing and extensibility.
-- **Mongoose integration**: Easy MongoDB data modeling and repository pattern.
-- **Modular architecture**: Clean separation of application, domain, infrastructure, and platform layers.
-- **Dependency injection**: Powered by `tsyringe` for testability and flexibility.
-- **Gateway support**: Proxy requests to upstream services with minimal setup.
-- **Internationalization (i18n)**: Built-in support for multiple locales.
-- **Comprehensive error handling**: Custom error classes and route error utilities.
-- **Type-safe route and hook handlers**: Strongly-typed REST entry points using Zod and Fastify.
-- **Testing utilities**: Vitest configuration and helpers for fast, isolated unit tests.
-
-## Architecture Overview
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [API Reference](#api-reference)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
 
-The framework is organized into the following layers:
-
-- **Application**: Defines REST entry points (routes and hooks) and configures i18n.
-- **Domain**: Registers business logic providers.
-- **Infrastructure**: Manages repositories and external dependencies.
-- **Platform**: Orchestrates service startup, database connections, and server/gateway configuration.
+## Features
 
-Each layer is extensible and testable, supporting clean code and maintainability.
+- **Fastify-based HTTP server**: Ultra-fast routing and extensibility
+- **Mongoose integration**: Easy MongoDB data modeling and repository pattern
+- **Modular architecture**: Clean separation of application, domain, infrastructure, and platform layers
+- **Dependency injection**: Powered by `tsyringe` for testability and flexibility
+- **Gateway support**: Proxy requests to upstream services with minimal setup
+- **Internationalization (i18n)**: Built-in support for multiple locales
+- **Comprehensive error handling**: Custom error classes and route error utilities
+- **Type-safe route handlers**: Strongly-typed REST entry points using Zod and Fastify
+- **Testing utilities**: Vitest configuration and helpers for fast, isolated unit tests
 
 ## Installation
 
 ```bash
-bun install
-# or
 npm install @sentzunhat/zacatl
+# or
+yarn add @sentzunhat/zacatl
+# or
+bun install @sentzunhat/zacatl
 ```
 
 ## Usage
 
-Here's how to quickly spin up a microservice:
+### Basic Setup
 
-```ts
+```typescript
 import Fastify from "fastify";
 import { MicroService } from "@sentzunhat/zacatl";
 
 const fastifyApp = Fastify();
 
-const microServer = new MicroService({
+const microservice = new MicroService({
   architecture: {
     application: {
       entryPoints: {
         rest: {
-          hookHandlers: [], // Add your hook handler classes here
-          routeHandlers: [], // Add your route handler classes here
+          hookHandlers: [], // Add hook handler classes
+          routeHandlers: [], // Add route handler classes
         },
       },
     },
-    domain: { providers: [] }, // Add your domain provider classes here
-    infrastructure: { repositories: [] }, // Add your repository classes here
+    domain: { providers: [] }, // Add domain provider classes
+    infrastructure: { repositories: [] }, // Add repository classes
     service: {
       name: "my-service",
       server: {
@@ -78,43 +81,134 @@ const microServer = new MicroService({
   },
 });
 
-microServer.start({ port: 9000 });
+await microservice.start({ port: 9000 });
+```
+
+### Creating Route Handlers
+
+```typescript
+import { z } from "zod";
+import { GetRouteHandler } from "@sentzunhat/zacatl";
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+class GetUserHandler extends GetRouteHandler<unknown, User, unknown> {
+  constructor() {
+    super({
+      url: "/users/:id",
+      schema: {
+        response: {
+          200: UserSchema,
+        },
+      },
+    });
+  }
+
+  async handler(request, reply): Promise<User> {
+    const userId = request.params.id;
+    // Fetch user from database, etc.
+    return {
+      id: userId,
+      name: "John Doe",
+      email: "john@example.com",
+    };
+  }
+}
+```
+
+### Database Integration
+
+```typescript
+import { Schema } from "mongoose";
+import { singleton } from "tsyringe";
+import { BaseRepository } from "@sentzunhat/zacatl";
+
+interface Product {
+  name: string;
+  price: number;
+  description: string;
+}
+
+const productSchema = new Schema<Product>({
+  name: { type: String, required: true },
+  price: { type: Number, required: true },
+  description: { type: String, required: true },
+});
+
+@singleton()
+export class ProductRepository extends BaseRepository<Product> {
+  constructor() {
+    super({ name: "Product", schema: productSchema });
+  }
+
+  async findByName(name: string) {
+    return this.model.findOne({ name }).exec();
+  }
+}
 ```
 
+## Architecture
+
+The framework is organized into four main layers:
+
+- **Application**: REST entry points (routes and hooks) and i18n configuration
+- **Domain**: Business logic providers and services
+- **Infrastructure**: Repositories and external dependencies
+- **Platform**: Service startup, database connections, and server configuration
+
+Each layer is designed to be extensible and testable, supporting clean code principles.
+
 ## Configuration
 
-- **Localization**: Place your locale JSON files in `src/locales/` (e.g., `en.json`, `fr.json`).
-- **Environment Variables**: Configure your database connection strings and other settings as needed.
-- **Custom Handlers**: Implement route and hook handlers by extending the provided abstract classes.
+- **Localization**: Place locale JSON files in `src/locales/` (e.g., `en.json`)
+- **Environment Variables**:
+  - `SERVICE_NAME` - Service name
+  - `NODE_ENV` - Environment (development, production, test)
+  - `CONNECTION_STRING` - Database connection string
+
+## API Reference
+
+### Core Components
+
+- `MicroService`: Central orchestrator for all architecture layers
+- `AbstractRouteHandler`: Base class for all route handlers
+- `BaseRepository`: Base class for MongoDB repositories
+- `CustomError`: Base class for typed error handling
 
 ## Testing
 
-Run all unit tests with coverage:
+Run tests with:
 
 ```bash
-bun run test
-# or
 npm run test
+# or
+npm run test:coverage
 ```
 
-Test configuration uses Vitest with in-memory MongoDB for fast, isolated tests.
-
-## API Reference
-
-- **Application Layer**: See `src/micro-service/architecture/application/`
-- **Domain Layer**: See `src/micro-service/architecture/domain/`
-- **Infrastructure Layer**: See `src/micro-service/architecture/infrastructure/`
-- **Platform Layer**: See `src/micro-service/architecture/platform/`
-- **Error Handling**: See `src/error/` for custom error classes and utilities.
+Test configuration uses Vitest with in-memory MongoDB for isolated tests.
 
 ## Contributing
 
-Contributions are welcome! If you find this software useful and make improvements, please consider submitting a pull request. See the [LICENSE](./LICENSE) for details.
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b feature/amazing-feature`
+3. Commit your changes: `git commit -m 'Add some amazing feature'`
+4. Push to the branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
 
 ## License
 
-MIT License © 2025 sentzunhat
+MIT License © 2025 Sentzunhat - See the [LICENSE](./LICENSE) file for details.
 
 ---
 
-**zacatl** is built for speed, simplicity, and extensibility. For questions, issues, or feature requests, please open an issue on [GitHub](https://github.com/sentzunhat/zacatl).
+Built by [Diego Beltran](https://sentzunhat.com) with [Fastify](https://fastify.io/), [Mongoose](https://mongoosejs.com/), and [tsyringe](https://github.com/microsoft/tsyringe).
+
+For questions or issues, please visit [GitHub](https://github.com/sentzunhat/zacatl/issues).

package/package.json

@@ -2,7 +2,7 @@
   "name": "@sentzunhat/zacatl",
   "main": "src/index.ts",
   "module": "src/index.ts",
-  "version": "0.0.0-alpha.9",
+  "version": "0.0.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/sentzunhat/zacatl.git"

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

@@ -1,10 +1,8 @@
 import importedMongoose, {
   connection,
   Model,
-  Document,
   Mongoose,
   Schema,
-  Types,
 } from "mongoose";
 import { v4 as uuidv4 } from "uuid";
 import { container } from "tsyringe";
@@ -14,26 +12,23 @@ export type BaseRepositoryConfig<T> = {
   schema: Schema<T>;
 };
 
-export type TDocument<T> = Document<Types.ObjectId, {}, T> &
-  T & {
-    id: string;
-  };
-
-export type TRequiredId<T> = T & {
-  _id: Types.ObjectId;
+export type LeanDocument<T> = T & {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
 };
 
 export type Repository<T> = {
   model: Model<T>;
 
-  findById(id: string): Promise<TDocument<T> | null>;
-  create(entity: T): Promise<TDocument<T>>;
-  update(id: string, entity: Partial<T>): Promise<TDocument<T> | null>;
-  delete(id: string): Promise<TDocument<T> | null>;
+  findById(id: string): Promise<LeanDocument<T> | null>;
+  create(entity: T): Promise<LeanDocument<T>>;
+  update(id: string, update: Partial<T>): Promise<LeanDocument<T> | null>;
+  delete(id: string): Promise<LeanDocument<T> | null>;
 };
 
 export abstract class BaseRepository<T> implements Repository<T> {
-  public model: Model<T>;
+  public readonly model: Model<T>;
 
   constructor(config: BaseRepositoryConfig<T>) {
     const mongoose = connection.db?.databaseName
@@ -53,59 +48,51 @@ export abstract class BaseRepository<T> implements Repository<T> {
     this.model.init();
   }
 
-  /**
-   * Transforms a Mongoose document into a plain entity object.
-   */
-  protected toEntity(doc: TDocument<T>): TRequiredId<T> {
-    // We call the built-in toObject method and cast to T.
-    return doc.toObject<TDocument<T>>({ virtuals: true }) as TRequiredId<T>;
-  }
-
-  async findById(id: string): Promise<TDocument<T> | null> {
-    const foundEntity = await this.model.findById<TDocument<T>>(id).exec();
+  async findById(id: string): Promise<LeanDocument<T> | null> {
+    const entity = await this.model
+      .findById(id)
+      .lean<LeanDocument<T>>({ virtuals: true })
+      .exec();
 
-    if (!foundEntity) {
+    if (!entity) {
       return null;
     }
 
-    return foundEntity.toObject<TDocument<T>>({
-      virtuals: true,
-    });
+    return entity;
   }
 
-  async create(entity: T): Promise<TDocument<T>> {
-    const createdEntity = await this.model.create<TDocument<T>>(entity);
+  async create(entity: T): Promise<LeanDocument<T>> {
+    const doc = await this.model.create(entity);
 
-    return createdEntity.toObject<TDocument<T>>({
-      virtuals: true,
-    });
+    return doc.toObject<LeanDocument<T>>({ virtuals: true });
   }
 
-  async update(id: string, entity: Partial<T>): Promise<TDocument<T> | null> {
-    const updatedEntity = await this.model
-      .findByIdAndUpdate<TDocument<T>>(id, entity, { new: true })
+  async update(
+    id: string,
+    update: Partial<T>
+  ): Promise<LeanDocument<T> | null> {
+    const entity = await this.model
+      .findByIdAndUpdate(id, update, { new: true })
+      .lean<LeanDocument<T>>({ virtuals: true })
       .exec();
 
-    if (!updatedEntity) {
+    if (!entity) {
       return null;
     }
 
-    return updatedEntity.toObject<TDocument<T>>({
-      virtuals: true,
-    });
+    return entity;
   }
 
-  async delete(id: string): Promise<TDocument<T> | null> {
-    const deletedEntity = await this.model
-      .findByIdAndDelete<TDocument<T>>(id)
+  async delete(id: string): Promise<LeanDocument<T> | null> {
+    const entity = await this.model
+      .findByIdAndDelete(id)
+      .lean<LeanDocument<T>>({ virtuals: true })
       .exec();
 
-    if (!deletedEntity) {
+    if (!entity) {
       return null;
     }
 
-    return deletedEntity.toObject<TDocument<T>>({
-      virtuals: true,
-    });
+    return entity;
   }
 }

package/src/utils/base64.ts

@@ -15,13 +15,3 @@ export const encodeBase64 = (input: string): string => {
 export const decodeBase64 = (input: string): string => {
   return Buffer.from(input, "base64").toString("utf-8");
 };
-
-/**
- * Encodes a token by prefixing it with "Bearer " and converting it to Base64 format.
- *
- * @param token - The raw token string to encode.
- * @returns The Base64-encoded token string with the "Bearer " prefix.
- */
-export const encodeToken = (token: string): string => {
-  return encodeBase64(`Bearer ${token}`);
-};

package/src/nullable.ts

@@ -1 +0,0 @@
-export type Nullable<T> = T | undefined;

package/src/stringify.ts

@@ -1,11 +0,0 @@
-const stringify = (input: any): string => {
-  if (Array.isArray(input)) {
-    return input.map(stringify).join("");
-  } else if (typeof input === "object" && input !== null) {
-    return Object.values(input).map(stringify).join("");
-  } else {
-    return input;
-  }
-};
-
-export { stringify };

package/src/summarize.ts

@@ -1,23 +0,0 @@
-// const summarize = async ({ context }: { context: string }): Promise<string> => {
-//   const { env, pipeline } = await import("@xenova/transformers");
-
-//   // cacheDir
-//   env.cacheDir = "./.cache";
-
-//   // Specify a custom location for models (defaults to '/models/').
-//   env.localModelPath = "./.models/";
-
-//   // Create a text-generation pipeline
-//   const generator = await pipeline(
-//     "text2text-generation",
-//     "Xenova/LaMini-Flan-T5-783M"
-//   );
-
-//   const result = (await generator(`Summarize the following text: ${context}.`, {
-//     max_new_tokens: 250,
-//   })) as { generated_text: string }[];
-
-//   return result[0]?.generated_text ?? "";
-// };
-
-// export { summarize };