@sentzunhat/zacatl 0.0.0-alpha.7 → 0.0.0-alpha.9

package/README.md

@@ -1,40 +1,120 @@
 # zacatl
 
-blazing fast minimal straightforward library
+A blazing fast, minimal, and straightforward microservice framework for Node.js, designed for rapid development of high-performance APIs and distributed systems.
 
-# @sentzunhat/library
+## Project Description
 
-**Blazing Fast Microservice Framework**
+**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.
 
-## Go Fast with minimal setup!
+## Features
 
-This library lets you bootstrap high-performance microservices in record time using Fastify, Mongoose, and other battle-tested technologies. Designed for speed and simplicity, it allows you to spin up gateway services, handle routes, and manage infrastructure seamlessly.
+- **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.
 
-With just a few lines of code, you can configure your services, connect databases, and proxy requests—while keeping the flexibility to scale with more advanced configurations. Whether you're building lightweight APIs or complex distributed systems, this framework has you covered.
+## Architecture Overview
 
-### Get started
+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.
+
+Each layer is extensible and testable, supporting clean code and maintainability.
+
+## Installation
+
+```bash
+bun install
+# or
+npm install @sentzunhat/zacatl
+```
+
+## Usage
+
+Here's how to quickly spin up a microservice:
 
 ```ts
 import Fastify from "fastify";
-import { MicroService } from "@sentzunhat/library";
+import { MicroService } from "@sentzunhat/zacatl";
 
-const fastifyApp = Fastify({});
+const fastifyApp = Fastify();
 
 const microServer = new MicroService({
-  service: { name: "my-service", server: { instance: fastifyApp } },
+  architecture: {
+    application: {
+      entryPoints: {
+        rest: {
+          hookHandlers: [], // Add your hook handler classes here
+          routeHandlers: [], // Add your route handler classes here
+        },
+      },
+    },
+    domain: { providers: [] }, // Add your domain provider classes here
+    infrastructure: { repositories: [] }, // Add your repository classes here
+    service: {
+      name: "my-service",
+      server: {
+        type: "SERVER",
+        vendor: "FASTIFY",
+        instance: fastifyApp,
+      },
+      databases: [
+        // Example for MongoDB:
+        // {
+        //   vendor: "MONGOOSE",
+        //   instance: new Mongoose(),
+        //   connectionString: "mongodb://localhost/mydb",
+        // }
+      ],
+    },
+  },
 });
 
 microServer.start({ port: 9000 });
 ```
 
-To install dependencies:
+## Configuration
 
-```bash
-bun install
-```
+- **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.
+
+## Testing
 
-To run:
+Run all unit tests with coverage:
 
 ```bash
-bun run src/index.ts
+bun run test
+# or
+npm run test
 ```
+
+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.
+
+## 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.
+
+## License
+
+MIT License © 2025 sentzunhat
+
+---
+
+**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).

package/package.json

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

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

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

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

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