@sentzunhat/zacatl 0.0.0-alpha.9 → 0.0.2

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.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/sentzunhat/zacatl.git"

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