@sentzunhat/zacatl 0.0.14 → 0.0.21

package/src/{micro-service/architecture/platform/service/service.ts → service/architecture/platform/server/server.ts}

@@ -1,25 +1,27 @@
-import proxy from "@fastify/http-proxy";
 import { FastifyInstance } from "fastify";
-import { ZodTypeProvider } from "fastify-type-provider-zod";
 import { container } from "tsyringe";
 import { Mongoose } from "mongoose";
 import { Sequelize } from "sequelize";
+import { Express } from "express";
 
 import { HookHandler, RouteHandler } from "../../application";
 import { CustomError } from "../../../../error";
 import { Optional } from "../../../../optionals";
+import { ServerAdapter } from "./server-adapter";
+import { FastifyAdapter } from "./adapters/fastify-adapter";
+import { ExpressAdapter } from "./adapters/express-adapter";
+import { PageModule } from "../page";
 
-export enum ServiceType {
+export enum ServerType {
   SERVER = "SERVER",
   GATEWAY = "GATEWAY",
 }
 
 export enum ServerVendor {
   FASTIFY = "FASTIFY",
+  EXPRESS = "EXPRESS",
 }
 
-type ServerInstance = FastifyInstance;
-
 type ProxyGateway = {
   upstream: string;
   prefix?: string;
@@ -29,10 +31,10 @@ type ProxiesGateway = Array<ProxyGateway>;
 
 type GatewayService = { proxies: ProxiesGateway };
 
-type ServiceServer = {
-  type: ServiceType;
+type HttpServerConfig = {
+  type: ServerType;
   vendor: ServerVendor;
-  instance: ServerInstance;
+  instance: unknown;
   gateway?: GatewayService;
 };
 
@@ -58,10 +60,18 @@ type DatabaseServer = {
   onDatabaseConnected?: OnDatabaseConnectedFunction;
 };
 
-export type ConfigService = {
+type ServerPageConfig = {
+  devServerUrl?: string;
+  staticDir?: string;
+  customRegister?: (server: unknown) => Promise<void> | void;
+  apiPrefix?: string;
+};
+
+export type ConfigServer = {
   name: string;
-  server: ServiceServer;
+  server: HttpServerConfig;
   databases: Array<DatabaseServer>;
+  page?: ServerPageConfig;
 };
 
 export enum HandlersType {
@@ -71,53 +81,6 @@ export enum HandlersType {
 
 type Handlers = RouteHandler | HookHandler;
 
-export const strategiesForServerVendor = {
-  [ServerVendor.FASTIFY]: {
-    handlers: {
-      [HandlersType.ROUTE]: (
-        server: FastifyInstance,
-        handler: Handlers
-      ): void => {
-        const route = handler as RouteHandler;
-
-        server.withTypeProvider<ZodTypeProvider>().route({
-          url: route.url,
-          method: route.method,
-          schema: route.schema,
-          handler: route.execute.bind(route),
-        });
-
-        // console.info(`registered route: ${route.method} ${route.url}`);
-      },
-      [HandlersType.HOOK]: (
-        server: FastifyInstance,
-        handler: Handlers
-      ): void => {
-        const hook = handler as HookHandler;
-
-        server.addHook(hook.name, hook.execute.bind(hook));
-
-        // console.info(`registered hook: ${hook.name}`);
-      },
-    },
-    server: {
-      [ServiceType.SERVER]: (_: ServerInstance) => {},
-      [ServiceType.GATEWAY]: (
-        instance: ServerInstance,
-        proxies?: ProxiesGateway
-      ) => {
-        proxies?.forEach((proxyConf) => {
-          instance.register(proxy, {
-            upstream: proxyConf.upstream,
-            ...(proxyConf.prefix ? { prefix: proxyConf.prefix } : {}),
-            http2: false, // Optional: configuration specific to your needs.
-          });
-        });
-      },
-    },
-  },
-};
-
 export const strategiesForDatabaseVendor = {
   [DatabaseVendor.MONGOOSE]: async (input: {
     serviceName: string;
@@ -188,41 +151,48 @@ type RegisterHandlersInput = {
   handlersType: HandlersType;
 };
 
-type ServicePort = {
+type ServerPort = {
   start: (input: StartInput) => Promise<void>;
   registerHandlers: (input: RegisterHandlersInput) => Promise<void>;
 };
 
-export class Service implements ServicePort {
+export class Server implements ServerPort {
   private name: string;
-  private server: ServiceServer;
+  private server: HttpServerConfig;
   private databases: Array<DatabaseServer>;
+  private page?: ServerPageConfig | undefined;
+  private adapter: ServerAdapter;
 
-  constructor({ name, server, databases }: ConfigService) {
+  constructor({ name, server, databases, page }: ConfigServer) {
     this.name = name;
     this.server = server;
     this.databases = databases;
+    this.page = page;
+
+    if (this.server.vendor === ServerVendor.FASTIFY) {
+      this.adapter = new FastifyAdapter(
+        this.server.instance as FastifyInstance,
+      );
+    } else if (this.server.vendor === ServerVendor.EXPRESS) {
+      this.adapter = new ExpressAdapter(this.server.instance as Express);
+    } else {
+      throw new Error(`Unsupported server vendor: ${this.server.vendor}`);
+    }
   }
 
   public async registerHandlers(input: RegisterHandlersInput): Promise<void> {
     const { handlers, handlersType } = input;
 
-    const registerHandlersFunction =
-      strategiesForServerVendor[this.server.vendor].handlers[handlersType];
-
-    if (!registerHandlersFunction) {
-      throw new CustomError({
-        message: `service vendor ${this.server.vendor} is not supported for ${handlersType} registration`,
-        code: 500,
-        reason: "service vendor not supported",
-        metadata: { vendor: this.server.vendor },
-      });
-    }
-
     await Promise.all(
       handlers.map(async (handler) => {
         try {
-          registerHandlersFunction(this.server.instance, handler);
+          if (handlersType === HandlersType.ROUTE) {
+            this.adapter.registerRoute(handler as RouteHandler);
+          } else if (handlersType === HandlersType.HOOK) {
+            this.adapter.registerHook(handler as HookHandler);
+          } else {
+            throw new Error(`Handler type ${handlersType} is not supported`);
+          }
         } catch (error: unknown) {
           throw new CustomError({
             message: `failed to register ${handlersType}: ${handler.constructor.name}`,
@@ -232,7 +202,7 @@ export class Service implements ServicePort {
             metadata: { handler: handler.constructor.name },
           });
         }
-      })
+      }),
     );
   }
 
@@ -290,29 +260,25 @@ export class Service implements ServicePort {
   }
 
   private async configureServer(): Promise<void> {
-    const configureServerFunction =
-      strategiesForServerVendor[this.server.vendor].server[this.server.type];
-
-    if (!configureServerFunction) {
-      throw new CustomError({
-        message: `service vendor ${this.server.vendor} is not supported for server configuration`,
-        code: 500,
-        reason: "service vendor not supported",
-        metadata: { service: { name: this.name, vendor: this.server.vendor } },
+    if (
+      this.server.type === ServerType.GATEWAY &&
+      this.server.gateway?.proxies
+    ) {
+      this.server.gateway.proxies.forEach((proxyConf) => {
+        this.adapter.registerProxy({
+          upstream: proxyConf.upstream,
+          prefix: proxyConf.prefix || "/",
+          http2: false,
+        });
       });
     }
-
-    configureServerFunction(this.server.instance, this.server.gateway?.proxies);
   }
 
   private async startServer(input: StartInput): Promise<void> {
     const { port } = input;
 
     try {
-      await this.server.instance.listen({
-        host: "0.0.0.0",
-        port: port,
-      });
+      await this.adapter.listen(port);
     } catch (error: unknown) {
       throw new CustomError({
         message: `failed to start service "${this.name}"`,
@@ -330,11 +296,28 @@ export class Service implements ServicePort {
     }
   }
 
+  private async configurePageModule(): Promise<void> {
+    if (!this.page) {
+      return;
+    }
+
+    const { apiPrefix, ...pageProps } = this.page;
+
+    const pageModule = new PageModule({
+      root: process.cwd(),
+      page: pageProps,
+      ...(apiPrefix ? { apiPrefix } : {}),
+    });
+
+    await pageModule.register(this.adapter);
+  }
+
   private async configure(input: StartInput): Promise<void> {
     const { port } = input;
 
     // await this.configureDatabases();
     await this.configureServer();
+    await this.configurePageModule();
     await this.startServer({ port });
   }
 

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

@@ -0,0 +1,63 @@
+import { Application, ConfigApplication } from "../application";
+import { ConfigDomain, Domain } from "../domain";
+import { ConfigInfrastructure, Infrastructure } from "../infrastructure";
+import { ConfigServer, HandlersType, Server } from "./server/server";
+import type { Optional } from "../../../optionals";
+
+export type ConfigService = {
+  architecture: {
+    application?: Optional<ConfigApplication>;
+    domain: ConfigDomain;
+    infrastructure: ConfigInfrastructure;
+    server?: Optional<ConfigServer>;
+  };
+};
+
+export class Service {
+  private application?: Optional<Application>;
+  private domain: Domain;
+  private infrastructure: Infrastructure;
+  private server?: Optional<Server>;
+
+  constructor(config: ConfigService) {
+    const { architecture } = config;
+    const { application, domain, infrastructure, server } = architecture;
+
+    this.application = application ? new Application(application) : undefined;
+    this.domain = new Domain(domain);
+    this.infrastructure = new Infrastructure(infrastructure);
+    this.server = server ? new Server(server) : undefined;
+  }
+
+  public async start(input?: { port?: number }): Promise<void> {
+    // Configure databases if server is provided
+    if (this.server) {
+      await this.server.configureDatabases();
+    }
+
+    // Start infrastructure (repositories)
+    this.infrastructure.start();
+
+    // Start domain (providers)
+    await this.domain.start();
+
+    // Start application (routes/hooks) if provided
+    if (this.application) {
+      this.application.start();
+    }
+
+    // Register handlers and start server if provided
+    if (this.server && this.application) {
+      this.server.registerHandlers({
+        handlers: this.application.routeHandlers,
+        handlersType: HandlersType.ROUTE,
+      });
+      this.server.registerHandlers({
+        handlers: this.application.hookHandlers,
+        handlersType: HandlersType.HOOK,
+      });
+
+      await this.server.start({ port: input?.port ?? 3000 });
+    }
+  }
+}

package/context.yaml

@@ -1,151 +0,0 @@
-# Zacatl Project: Structured Context
-
-components:
-  - name: MicroService
-    type: class
-    file: src/micro-service/architecture/platform/micro-service.ts
-    description: |
-      The main orchestrator for the microservice. Bootstraps Application, Domain, Infrastructure, and Service layers. Handles startup, dependency registration, and handler registration.
-    methods:
-      - name: constructor
-        description: Initializes all architecture layers from config.
-      - name: start
-        description: Starts the service, configures databases, registers handlers, and launches the HTTP server.
-    dependencies:
-      - Application
-      - Domain
-      - Infrastructure
-      - Service
-
-  - name: Application
-    type: class
-    file: src/micro-service/architecture/application/application.ts
-    description: |
-      Handles HTTP entry points (REST), validation, and delegates to domain logic. Registers route and hook handlers using DI.
-    methods:
-      - name: constructor
-        description: Configures i18n and stores entry point config.
-      - name: start
-        description: Registers and stores REST hook and route handlers.
-    dependencies:
-      - AbstractArchitecture
-      - HookHandler
-      - RouteHandler
-
-  - name: Infrastructure
-    type: class
-    file: src/micro-service/architecture/infrastructure/infrastructure.ts
-    description: |
-      Registers and manages repositories (e.g., MongoDB) for persistence. Uses DI for repository registration.
-    methods:
-      - name: constructor
-        description: Stores repository config.
-      - name: start
-        description: Registers repositories in DI container.
-    dependencies:
-      - AbstractArchitecture
-
-  - name: BaseRepository
-    type: abstract class
-    file: src/micro-service/architecture/infrastructure/repositories/abstract.ts
-    description: |
-      Abstract base for MongoDB repositories. Handles model creation, lazy initialization, and CRUD methods. Ensures returned documents have an id field.
-    methods:
-      - name: constructor
-        description: Sets up Mongoose model and schema.
-      - name: findById
-        description: Finds a document by id and returns a lean object with id.
-      - name: create
-        description: Creates a new document and returns a lean object with id.
-      - name: update
-        description: Updates a document by id and returns a lean object with id.
-      - name: delete
-        description: Deletes a document by id and returns a lean object with id.
-    dependencies:
-      - mongoose
-      - tsyringe
-
-  - name: AbstractArchitecture
-    type: abstract class
-    file: src/micro-service/architecture/architecture.ts
-    description: |
-      Provides generic dependency registration helpers for all architecture layers. Enforces a start() contract.
-    methods:
-      - name: registerDependencies
-        description: Registers an array of classes in the DI container.
-      - name: registerAndStoreDependencies
-        description: Registers classes and stores resolved instances in a provided array.
-      - name: start
-        description: Abstract method to be implemented by subclasses.
-    dependencies:
-      - tsyringe
-
-  - name: CustomError
-    type: class
-    file: src/error/custom.ts
-    description: |
-      Base class for all custom errors. Supports metadata, error codes, and unique IDs. Used for structured error handling.
-    methods:
-      - name: constructor
-        description: Initializes error with message, code, reason, metadata, and stack trace.
-
-  - name: getConfigOrThrow
-    type: function
-    file: src/configuration.ts
-    description: |
-      Retrieves configuration values from the config system. Throws if missing.
-
-  - name: defaultLogger
-    type: object
-    file: src/logs.ts
-    description: |
-      Pino-based logger configured with environment and service metadata. Used for structured logging.
-
-  - name: Utility Exports
-    type: module
-    file: src/utils/index.ts
-    description: |
-      Exports utility functions (e.g., base64, hmac) for use throughout the codebase.
-
-layers:
-  - name: Platform
-    description: Bootstraps the app, configures DI, starts the server.
-    files:
-      - src/micro-service/architecture/platform/micro-service.ts
-      - src/micro-service/architecture/platform/service/service.ts
-  - name: Application
-    description: Handles HTTP requests, validation, delegates to domain logic.
-    files:
-      - src/micro-service/architecture/application/application.ts
-      - src/micro-service/architecture/application/entry-points/rest/route-handlers/
-      - src/micro-service/architecture/application/entry-points/rest/hook-handlers/
-  - name: Domain
-    description: Pure business rules, models, and logic (no infrastructure deps).
-    files:
-      - src/micro-service/architecture/domain/
-  - name: Infrastructure
-    description: Persistence (MongoDB repositories), external service integration.
-    files:
-      - src/micro-service/architecture/infrastructure/repositories/
-      - src/micro-service/architecture/infrastructure/infrastructure.ts
-
-patterns:
-  - Dependency Injection: All services, repositories, and handlers are registered in the DI container (tsyringe). Never instantiate dependencies directly.
-  - Error Handling: Custom error classes extend CustomError. Errors are thrown and bubble up to Fastify's error handler unless custom handling is needed.
-  - Validation: All request/response validation uses zod schemas.
-  - Testing: All business logic, handlers, and utilities are unit tested using vitest. Tests mirror the src/ structure.
-
-config:
-  - Localization: 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
-      - APP_VERSION: Application version
-      - APP_ENV: Application environment
-
-testing:
-  - All tests are in test/unit/, mirroring src/ structure.
-  - Uses vitest for all tests.
-  - Mocks external dependencies (DB, services) in tests.
-  - Test helpers in test/unit/helpers/.

package/eslint.config.mjs

@@ -1,59 +0,0 @@
-import { FlatCompat } from "@eslint/eslintrc";
-import js from "@eslint/js";
-import tseslint from "typescript-eslint";
-import tsEslintParser from "@typescript-eslint/parser";
-import path from "path";
-import { fileURLToPath } from "url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-const compat = new FlatCompat({
-  baseDirectory: __dirname, // optional; default: process.cwd()
-  resolvePluginsRelativeTo: __dirname, // optional
-  recommendedConfig: js.configs.recommended, // optional unless you're using "eslint:recommended"
-  allConfig: js.configs.all, // optional unless you're using "eslint:all"
-});
-
-export default [
-  {
-    ignores: [
-      "README.md",
-      "package-lock.json",
-      "package.json",
-      "tsconfig.json",
-      "bun.lockb",
-      "build/**/*",
-      "report/**/*",
-      "eslint.config.mjs",
-      "vite.config.mjs",
-      "LICENSE",
-      "Dockerfile",
-      "config/**/*",
-      "doc/**/*",
-      "locales/**/*",
-    ],
-  },
-  {
-    files: ["src/*.ts"],
-    languageOptions: {
-      parser: tsEslintParser,
-      parserOptions: {
-        project: "./tsconfig.json",
-      },
-      globals: {
-        __dirname: "readonly",
-        process: "readonly",
-        console: "readonly",
-      },
-    },
-    plugins: {
-      "@typescript-eslint": tseslint,
-    },
-    rules: {
-      "no-unused-vars": "off",
-    },
-  },
-  js.configs.recommended,
-  ...compat.config({}),
-];

package/guidelines.yaml

@@ -1,74 +0,0 @@
-# Zacatl Project: Coding Guidelines & Best Practices
-
-naming:
-  file_folder:
-    - Use lowercase and hyphens (e.g., user-repository.ts, route-handlers/)
-  variables:
-    - Use meaningful, descriptive names
-  classes:
-    - Use PascalCase for class names
-  functions:
-    - Use camelCase for function and method names
-
-style:
-  - Write clean, modular, and straightforward code
-  - Use strong typing and TypeScript generics where appropriate
-  - Prefer async/await for asynchronous code
-  - Keep functions short, focused, and readable
-  - Prefer clarity over excessive comments; use tests to document behavior
-  - Avoid code duplication (DRY principle); extract reusable logic into utils/ or shared services
-  - Use modern TypeScript/ES features
-
-architecture:
-  - Follow layered (hexagonal) architecture: Platform → Application → Domain → Infrastructure
-  - Strict separation of concerns between layers
-  - Application: Handles HTTP, validation, delegates to domain
-  - Domain: Pure business logic, no infrastructure dependencies
-  - Infrastructure: Persistence, external integrations
-  - Platform: Bootstraps, configures DI, starts server
-
-patterns:
-  dependency_injection:
-    - Use tsyringe for all DI
-    - Register all services, repositories, and handlers in the DI container
-    - Never instantiate dependencies directly; always resolve via DI
-  error_handling:
-    - All custom errors extend CustomError (src/error/custom.ts)
-    - Use CustomError.handle(error) in middleware or route handlers to log/format errors
-    - Always include relevant metadata and a clear message in error instances
-    - Throw errors for exceptional cases; do not return error objects
-    - Let errors bubble up to Fastify’s error handler unless custom handling is needed
-  validation:
-    - Use zod schemas for all request/response validation
-  testing:
-    - 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
-    - Run tests using the vitest CLI
-  documentation:
-    - Update context.yaml and guidelines.yaml with any new patterns, conventions, or architectural changes
-    - Document new features, patterns, or conventions in YAML, not Markdown
-
-mongodb:
-  - Define all schemas in infrastructure/repositories/
-  - Embed related data for performance when possible
-  - Keep schemas minimal and use concise property names
-  - Use references for large or independent data
-  - Ensure documents stay well below MongoDB’s 16MB limit
-  - Define indexes for frequently queried fields
-  - Use Mongoose and zod for schema and runtime validation
-  - Consider schema versioning for breaking changes
-
-extending:
-  - Add new features by creating new handlers, services, or repositories in the appropriate layer
-  - Register all new classes in the DI container
-  - Write tests for all new logic
-  - Update context.yaml and guidelines.yaml with new patterns or conventions
-
-security:
-  - Validate all inputs
-  - Handle errors gracefully
-  - Never expose sensitive data
-  - Sanitize and validate all external data

package/mongodb.yaml

@@ -1,29 +0,0 @@
-# Zacatl Project: MongoDB Schema Design Guidelines
-
-origin: mongodb_schema_design_guidelines.md
-source: MongoDB_schema_design_guidelines.pdf
-
-principles:
-  - favor_embedding:
-      rule: Embed related data within a single document when possible to improve performance by reducing the need for joins/queries.
-      rationale: Embedded documents ensure related data is retrieved together, enhancing read performance for one-to-few/one-to-many relationships.
-  - minimalism_and_simplicity:
-      rule: Design schemas with simplicity and minimalism. Use nested objects to reflect natural data hierarchies.
-      rationale: Minimal schemas are easier to understand, maintain, and scale.
-  - property_naming:
-      rule: Use single-word property names when possible; otherwise, limit to two words.
-      rationale: Short, concise property names reduce errors and improve readability.
-  - document_size_and_cardinality:
-      rule: Keep document size within MongoDB’s 16MB limit. Avoid embedding data that could grow unbounded (high-cardinality relationships).
-      rationale: Large documents degrade performance and complicate replication/backup. Use references for large/independent data.
-  - lifecycle_consistency:
-      rule: Embed data only if it shares a lifecycle with the parent document. Use references if embedded data is accessed/updated independently.
-      rationale: Aligning lifecycles ensures consistent, predictable schema behavior.
-
-flexibility:
-  - These guidelines are best practices and should be adapted to specific application requirements and data access patterns.
-  - The recommendation for concise property names is flexible, but clarity and consistency are critical.
-
-conclusion:
-  - Following these guidelines will help ensure MongoDB schemas are optimized for performance, maintainability, and scalability.
-  - Adapt as needed for your application’s needs.