@sentzunhat/zacatl 0.0.14 → 0.0.21

package/src/service/architecture/infrastructure/repositories/types.ts

@@ -0,0 +1,125 @@
+import {
+  Document,
+  Model as MongooseModel,
+  Schema,
+  Default__v,
+  Require_id,
+  ObjectId,
+  IfAny,
+} from "mongoose";
+import { Model as SequelizeModel, ModelStatic, Model } from "sequelize";
+
+/**
+ * Enum for supported ORM types
+ */
+export enum ORMType {
+  Mongoose = "mongoose",
+  Sequelize = "sequelize",
+}
+
+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;
+
+/**
+ * Configuration for Mongoose-based repository
+ * @template D - Database document type
+ */
+export type MongooseRepositoryConfig<D = unknown> = {
+  readonly type: ORMType.Mongoose;
+  readonly name?: string;
+  readonly schema: Schema<D>;
+};
+
+/**
+ * Configuration for Sequelize-based repository
+ * @template D - Sequelize Model type (must extend Model)
+ */
+export type SequelizeRepositoryConfig<D extends Model = Model> = {
+  readonly type: ORMType.Sequelize;
+  readonly model: ModelStatic<D>;
+};
+
+/**
+ * Discriminated union of all repository configuration types
+ * @template D - Database/Model type
+ */
+export type BaseRepositoryConfig<D = unknown> =
+  | MongooseRepositoryConfig<D>
+  | SequelizeRepositoryConfig<Model>;
+
+export type Repository<D, I, O> = {
+  model: MongooseModel<D> | ModelStatic<SequelizeModel<any, any>>;
+
+  toLean(input: unknown): O | null;
+  findById(id: string): Promise<O | null>;
+  create(entity: I): Promise<O>;
+  update(id: string, update: Partial<I>): Promise<O | null>;
+  delete(id: string): Promise<O | null>;
+};
+
+/**
+ * ORM Adapter Interface - Defines the contract for ORM-specific implementations
+ * This enables pluggable ORM support without circular dependencies
+ */
+export interface ORMAdapter<D, I, O> {
+  /**
+   * Get the underlying ORM model
+   */
+  readonly model: MongooseModel<D> | ModelStatic<any>;
+
+  /**
+   * Transform database entity to plain lean object
+   */
+  toLean(input: unknown): O | null;
+
+  /**
+   * Find entity by ID
+   */
+  findById(id: string): Promise<O | null>;
+
+  /**
+   * Create new entity
+   */
+  create(entity: I): Promise<O>;
+
+  /**
+   * Update existing entity
+   */
+  update(id: string, update: Partial<I>): Promise<O | null>;
+
+  /**
+   * Delete entity by ID
+   */
+  delete(id: string): Promise<O | null>;
+}

package/src/service/architecture/infrastructure/repository-interface.ts

@@ -0,0 +1,35 @@
+/**
+ * Generic repository interface for any data source (Mongoose, Redis, SQL, etc.)
+ * Allows flexible persistence without tying to a specific ORM
+ */
+export interface IRepository<T> {
+  /**
+   * Find a single record by ID
+   */
+  findById(id: string): Promise<T | null>;
+
+  /**
+   * Find multiple records with optional filtering
+   */
+  findMany(filter?: Record<string, unknown>): Promise<T[]>;
+
+  /**
+   * Create a new record
+   */
+  create(data: Partial<T>): Promise<T>;
+
+  /**
+   * Update an existing record
+   */
+  update(id: string, data: Partial<T>): Promise<T | null>;
+
+  /**
+   * Delete a record
+   */
+  delete(id: string): Promise<boolean>;
+
+  /**
+   * Check if a record exists
+   */
+  exists(id: string): Promise<boolean>;
+}

package/src/service/architecture/infrastructure/repository.ts

@@ -0,0 +1,75 @@
+/**
+ * IRepository<T> - Generic Repository Interface
+ *
+ * Provides a standard contract for data persistence across any source:
+ * - SQL databases (SQLite, PostgreSQL, MySQL)
+ * - NoSQL databases (MongoDB, Redis)
+ * - File systems (JSON, YAML, CSV)
+ * - Message queues
+ * - External APIs
+ *
+ * Implement this interface for your specific data source and register through Service architecture.
+ *
+ * @example
+ * ```typescript
+ * class UserRepository implements IRepository<User> {
+ *   async findById(id: string): Promise<User | null> { ... }
+ *   async findMany(filter?: Record<string, unknown>): Promise<User[]> { ... }
+ *   async create(data: Partial<User>): Promise<User> { ... }
+ *   async update(id: string, data: Partial<User>): Promise<User | null> { ... }
+ *   async delete(id: string): Promise<boolean> { ... }
+ *   async exists(id: string): Promise<boolean> { ... }
+ * }
+ *
+ * // Register through Service
+ * const service = new Service({
+ *   architecture: {
+ *     infrastructure: { repositories: [UserRepository] }
+ *   }
+ * });
+ * ```
+ */
+export interface IRepository<T> {
+  /**
+   * Find a single record by unique identifier
+   * @param id - Unique identifier
+   * @returns Record or null if not found
+   */
+  findById(id: string): Promise<T | null>;
+
+  /**
+   * Find multiple records with optional filtering
+   * @param filter - Key-value pairs to filter by (AND logic)
+   * @returns Array of records (empty if none match)
+   */
+  findMany(filter?: Record<string, unknown>): Promise<T[]>;
+
+  /**
+   * Create a new record
+   * @param data - Partial record data
+   * @returns Created record with all fields populated
+   */
+  create(data: Partial<T>): Promise<T>;
+
+  /**
+   * Update an existing record
+   * @param id - Record identifier
+   * @param data - Partial data to update
+   * @returns Updated record or null if not found
+   */
+  update(id: string, data: Partial<T>): Promise<T | null>;
+
+  /**
+   * Delete a record
+   * @param id - Record identifier
+   * @returns True if deleted, false if not found
+   */
+  delete(id: string): Promise<boolean>;
+
+  /**
+   * Check if a record exists
+   * @param id - Record identifier
+   * @returns True if exists, false otherwise
+   */
+  exists(id: string): Promise<boolean>;
+}

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

@@ -0,0 +1,5 @@
+export * from "./server";
+export * from "./service";
+export { Service } from "./service";
+export type { ConfigService } from "./service";
+export * from "./page";

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

@@ -0,0 +1 @@
+export * from "./page";

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

@@ -0,0 +1,52 @@
+import { ServerAdapter } from "../server/server-adapter";
+import path from "path";
+import fs from "fs";
+import { logger } from "../../../../logs";
+
+export type PageModuleConfig = {
+  root: string;
+  page: {
+    devServerUrl?: string;
+    staticDir?: string;
+    customRegister?: (server: unknown) => Promise<void> | void;
+  };
+  apiPrefix?: string;
+};
+
+export class PageModule {
+  constructor(private config: PageModuleConfig) {}
+
+  public async register(adapter: ServerAdapter): Promise<void> {
+    const { devServerUrl, staticDir, customRegister } = this.config.page;
+    const apiPrefix = this.config.apiPrefix || "/api";
+
+    if (customRegister) {
+      await customRegister(adapter.getRawServer());
+      return;
+    }
+
+    if (devServerUrl) {
+      adapter.registerProxy({
+        upstream: devServerUrl,
+        prefix: "/",
+        rewritePrefix: "/",
+        http2: false,
+      });
+    } else if (staticDir) {
+      const absoluteStaticDir = path.resolve(this.config.root, staticDir);
+      if (!fs.existsSync(absoluteStaticDir)) {
+        logger.warn(
+          `Static directory ${absoluteStaticDir} does not exist. Skipping static file serving.`,
+        );
+        return;
+      }
+
+      adapter.serveStatic({
+        root: absoluteStaticDir,
+        prefix: "/",
+      });
+
+      adapter.registerSpaFallback(apiPrefix, absoluteStaticDir);
+    }
+  }
+}

package/src/service/architecture/platform/server/adapters/express-adapter.ts

@@ -0,0 +1,112 @@
+import { Express, Request, Response, NextFunction } from "express";
+import { createProxyMiddleware } from "http-proxy-middleware";
+import express from "express";
+import { logger } from "../../../../../logs";
+import { ServerAdapter, ProxyConfig, StaticConfig } from "../server-adapter";
+import { HookHandler, RouteHandler } from "../../../application";
+
+export class ExpressAdapter implements ServerAdapter {
+  constructor(private server: Express) {}
+
+  registerRoute(handler: RouteHandler): void {
+    const method = handler.method.toLowerCase();
+    // Fastify uses :param, Express uses :param.
+    // Fastify might use wildcard *, Express uses *.
+    const url = handler.url;
+
+    (this.server as any)[method](
+      url,
+      async (req: Request, res: Response, next: NextFunction) => {
+        try {
+          // Basic Zod Validation Shim
+          // We assume handler.schema follows the structure { body?: ZodSchema, querystring?: ZodSchema, params?: ZodSchema }
+          const schema = handler.schema as any;
+
+          if (schema) {
+            if (schema.body) {
+              req.body = await schema.body.parseAsync(req.body);
+            }
+            if (schema.querystring) {
+              req.query = await schema.querystring.parseAsync(req.query);
+            }
+            if (schema.params) {
+              req.params = await schema.params.parseAsync(req.params);
+            }
+          }
+
+          const result = await handler.execute(req as any, res as any);
+
+          if (!res.headersSent && result !== undefined) {
+            res.json(result);
+          }
+        } catch (err) {
+          next(err);
+        }
+      },
+    );
+  }
+
+  registerHook(handler: HookHandler): void {
+    // Map Fastify hooks to Express middleware
+    // onRequest -> app.use
+    if (handler.name === "onRequest" || handler.name === "preHandler") {
+      this.server.use(async (req, res, next) => {
+        try {
+          await handler.execute(req as any, res as any);
+          next();
+        } catch (err) {
+          next(err);
+        }
+      });
+    } else {
+      logger.warn(
+        `Hook ${handler.name} is not fully supported in ExpressAdapter yet.`,
+      );
+    }
+  }
+
+  registerProxy(config: ProxyConfig): void {
+    this.server.use(
+      config.prefix,
+      createProxyMiddleware({
+        target: config.upstream,
+        changeOrigin: true,
+        ...(config.rewritePrefix
+          ? { pathRewrite: { [`^${config.prefix}`]: config.rewritePrefix } }
+          : {}),
+      }),
+    );
+  }
+
+  serveStatic(config: StaticConfig): void {
+    this.server.use(config.prefix || "/", express.static(config.root));
+  }
+
+  registerSpaFallback(apiPrefix: string, staticDir: string): void {
+    this.server.use((req, res, _next) => {
+      if (req.path.startsWith(apiPrefix)) {
+        res.status(404).json({
+          code: 404,
+          error: "Not Found",
+          message: `Route ${req.method}:${req.path} not found`,
+        });
+      } else {
+        res.sendFile("index.html", { root: staticDir });
+      }
+    });
+  }
+
+  async listen(port: number): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.server
+        .listen(port, "0.0.0.0", () => {
+          resolve();
+        })
+        .on("error", reject);
+    });
+  }
+
+  getRawServer(): any {
+    return this.server;
+  }
+}

package/src/service/architecture/platform/server/adapters/fastify-adapter.ts

@@ -0,0 +1,61 @@
+import { FastifyInstance } from "fastify";
+import { ZodTypeProvider } from "fastify-type-provider-zod";
+import proxy from "@fastify/http-proxy";
+import fastifyStatic from "@fastify/static";
+import { ServerAdapter, ProxyConfig, StaticConfig } from "../server-adapter";
+import { HookHandler, RouteHandler } from "../../../application";
+
+export class FastifyAdapter implements ServerAdapter {
+  constructor(private server: FastifyInstance) {}
+
+  registerRoute(handler: RouteHandler): void {
+    this.server.withTypeProvider<ZodTypeProvider>().route({
+      url: handler.url,
+      method: handler.method,
+      schema: handler.schema,
+      handler: handler.execute.bind(handler),
+    });
+  }
+
+  registerHook(handler: HookHandler): void {
+    this.server.addHook(handler.name, handler.execute.bind(handler));
+  }
+
+  registerProxy(config: ProxyConfig): void {
+    this.server.register(proxy, {
+      upstream: config.upstream,
+      prefix: config.prefix,
+      ...(config.rewritePrefix ? { rewritePrefix: config.rewritePrefix } : {}),
+      ...(config.http2 !== undefined ? { http2: config.http2 } : {}),
+    });
+  }
+
+  serveStatic(config: StaticConfig): void {
+    this.server.register(fastifyStatic, {
+      root: config.root,
+      ...(config.prefix ? { prefix: config.prefix } : {}),
+    });
+  }
+
+  registerSpaFallback(apiPrefix: string, staticDir: string): void {
+    this.server.setNotFoundHandler(async (request, reply) => {
+      if (request.raw.url?.startsWith(apiPrefix)) {
+        reply.status(404).send({
+          code: 404,
+          error: "Not Found",
+          message: `Route ${request.method}:${request.url} not found`,
+        });
+      } else {
+        reply.sendFile("index.html", staticDir);
+      }
+    });
+  }
+
+  async listen(port: number): Promise<void> {
+    await this.server.listen({ host: "0.0.0.0", port });
+  }
+
+  getRawServer(): any {
+    return this.server;
+  }
+}

package/src/service/architecture/platform/server/adapters/index.ts

@@ -0,0 +1,2 @@
+export * from "./fastify-adapter";
+export * from "./express-adapter";

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

@@ -0,0 +1 @@
+export * from "./server";

package/src/service/architecture/platform/server/server-adapter.ts

@@ -0,0 +1,23 @@
+import { HookHandler, RouteHandler } from "../../application";
+
+export type ProxyConfig = {
+  upstream: string;
+  prefix: string;
+  rewritePrefix?: string;
+  http2?: boolean;
+};
+
+export type StaticConfig = {
+  root: string;
+  prefix?: string;
+};
+
+export interface ServerAdapter {
+  registerRoute(handler: RouteHandler): void;
+  registerHook(handler: HookHandler): void;
+  registerProxy(config: ProxyConfig): void;
+  serveStatic(config: StaticConfig): void;
+  registerSpaFallback(apiPrefix: string, staticDir: string): void;
+  listen(port: number): Promise<void>;
+  getRawServer(): any;
+}