@sentzunhat/zacatl 0.0.14 → 0.0.21

package/patterns.yaml

@@ -1,55 +0,0 @@
-# Zacatl Project: Coding Patterns and Architectural Practices
-
-origin:
-  - coding_standards.md
-  - coding_standards.pdf
-  - README.md (patterns section)
-
-patterns:
-  - hexagonal_architecture:
-      description: |
-        Structure the application to separate core business logic from external dependencies using Ports and Adapters. Core logic is in the Domain layer, with Application, Infrastructure, and Platform layers handling entry points, persistence, and orchestration.
-      source: coding_standards.pdf
-  - object_oriented_programming:
-      description: |
-        Use classes to encapsulate state and behavior, especially for providers, repositories, and server classes. Follows OOP principles for modularity and encapsulation.
-      source: coding_standards.pdf
-  - functional_programming:
-      description: |
-        Use pure functions and higher-order functions for stateless operations and utility logic. Prefer immutability and function composition where possible.
-      source: coding_standards.pdf
-  - dependency_injection:
-      description: |
-        Use tsyringe for DI. Register all services, repositories, and handlers in the DI container. Never instantiate dependencies directly; always resolve via DI. Promotes modularity, flexibility, and testability.
-      source: coding_standards.pdf
-  - modular_server_design:
-      description: |
-        Server classes (e.g., ModularServer, FastifyServer) accept dependencies (Fastify, providers, databases, etc.) via constructor injection. Route registration and DI setup are centralized.
-      source: coding_standards.pdf
-  - centralized_configuration:
-      description: |
-        Use a DI container to register and configure dependencies (providers, repositories, Fastify instances, etc.). Server initialization is performed by resolving the server from the DI container and starting it on a specified port.
-      source: coding_standards.pdf
-  - error_handling:
-      description: |
-        All custom errors extend CustomError. Use CustomError.handle(error) in middleware or route handlers to log/format errors. Always include relevant metadata and a clear message. Let errors bubble up to Fastify’s error handler unless custom handling is needed.
-      source: README.md
-  - validation:
-      description: |
-        Use zod schemas for all request/response validation. Place validation logic in the Application layer.
-      source: README.md
-  - testing:
-      description: |
-        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.
-      source: README.md
-
-best_practices:
-  - clean_code:
-      description: Write clean, modular, and straightforward code with meaningful names and strong typing. Use the latest language features and avoid redundancy (DRY principle).
-      source: coding_standards.pdf
-  - security_and_ethics:
-      description: Validate all inputs, handle errors gracefully, and never expose sensitive data. Code should be secure, efficient, and ethical.
-      source: coding_standards.pdf
-  - minimal_comments:
-      description: Prefer clarity in code and tests over excessive comments. Use comments only when necessary for context.
-      source: coding_standards.pdf

package/src/configuration.ts

@@ -1,13 +0,0 @@
-import config from "config";
-
-type ConfigInput = {
-  SERVICE_NAME: string;
-  NODE_ENV: string;
-  APP_VERSION: string;
-  APP_ENV: string;
-  CONNECTION_STRING: string;
-};
-
-export const getConfigOrThrow = <T>(name: keyof ConfigInput): T => {
-  return config.get<T>(name);
-};

package/src/logs.ts

@@ -1,77 +0,0 @@
-import pino from "pino";
-
-import { getConfigOrThrow } from "./configuration";
-
-const defaultLogger: pino.BaseLogger = pino({
-  level: process.env["LOG_LEVEL"] ?? "info",
-  transport: {
-    target: "pino-pretty",
-    options: {
-      colorize: true,
-    },
-  },
-  formatters: {
-    bindings: (bindings) => {
-      return {
-        unique: bindings["pid"],
-        service: getConfigOrThrow<string>("SERVICE_NAME"),
-        environment: getConfigOrThrow<string>("NODE_ENV"),
-        app: {
-          version: getConfigOrThrow<string>("APP_VERSION"),
-          environment: getConfigOrThrow<string>("APP_ENV"),
-        },
-        host: bindings["hostname"],
-      };
-    },
-    level: (label) => {
-      return { level: label.toLocaleLowerCase() };
-    },
-  },
-});
-
-export type LoggerInput =
-  | {
-      data?: unknown;
-      details?: unknown;
-    }
-  | undefined;
-
-const logger = {
-  log: (message: string, input?: LoggerInput): void => {
-    console.log(message, {
-      data: input?.data,
-      details: input?.details,
-    });
-  },
-
-  info: (message: string, input?: LoggerInput): void => {
-    defaultLogger.info({ data: input?.data, details: input?.details }, message);
-  },
-
-  trace: (message: string, input?: LoggerInput): void => {
-    defaultLogger.trace(
-      { data: input?.data, details: input?.details },
-      message
-    );
-  },
-
-  warn: (message: string, input?: LoggerInput): void => {
-    defaultLogger.warn({ data: input?.data, details: input?.details }, message);
-  },
-
-  error: (message: string, input?: LoggerInput): void => {
-    defaultLogger.error(
-      { data: input?.data, details: input?.details },
-      message
-    );
-  },
-
-  fatal: (message: string, input?: LoggerInput): void => {
-    defaultLogger.fatal(
-      { data: input?.data, details: input?.details },
-      message
-    );
-  },
-};
-
-export { defaultLogger, logger };

package/src/micro-service/architecture/domain/domain.ts

@@ -1,19 +0,0 @@
-import { AbstractArchitecture, Constructor } from "../architecture";
-
-export type ConfigDomain = {
-  providers: Array<Constructor>;
-};
-
-export class Domain extends AbstractArchitecture {
-  private config: ConfigDomain;
-
-  constructor(config: ConfigDomain) {
-    super();
-
-    this.config = config;
-  }
-
-  public start(): void {
-    this.registerDependencies(this.config.providers);
-  }
-}

package/src/micro-service/architecture/domain/index.ts

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

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

@@ -1,90 +0,0 @@
-import { Model as MongooseModel } from "mongoose";
-import { ModelCtor } from "sequelize";
-import {
-  BaseRepositoryConfig,
-  Repository,
-  LeanDocument,
-  ToLeanInput,
-  MongooseRepositoryConfig,
-} from "./types";
-import { MongooseRepository } from "./mongoose";
-import { SequelizeRepository } from "./sequelize";
-
-export * from "./types";
-
-export abstract class BaseRepository<D, T> implements Repository<D, T> {
-  private implementation: Repository<D, T>;
-
-  constructor(config: BaseRepositoryConfig<D>) {
-    if (config.type === "mongoose") {
-      this.implementation = new MongooseRepository(config);
-    } else if (config.type === "sequelize") {
-      this.implementation = new SequelizeRepository(
-        config as any
-      ) as unknown as Repository<D, T>;
-    } else {
-      // Backward compatibility: if type is missing but schema is present, assume Mongoose
-      if ((config as any).schema) {
-        const mongooseConfig: MongooseRepositoryConfig<D> = {
-          type: "mongoose",
-          name: (config as any).name,
-          schema: (config as any).schema,
-        };
-        this.implementation = new MongooseRepository(mongooseConfig);
-      } else {
-        throw new Error(
-          "Invalid repository configuration: 'type' must be 'mongoose' or 'sequelize'"
-        );
-      }
-    }
-  }
-
-  get model(): MongooseModel<D> | ModelCtor<any> {
-    return this.implementation.model;
-  }
-
-  public isMongoose(): boolean {
-    return this.implementation instanceof MongooseRepository;
-  }
-
-  public isSequelize(): boolean {
-    return this.implementation instanceof SequelizeRepository;
-  }
-
-  public getMongooseModel(): MongooseModel<D> {
-    if (!this.isMongoose()) {
-      throw new Error("Repository is not using Mongoose");
-    }
-    return this.implementation.model as MongooseModel<D>;
-  }
-
-  public getSequelizeModel(): ModelCtor<any> {
-    if (!this.isSequelize()) {
-      throw new Error("Repository is not using Sequelize");
-    }
-    return this.implementation.model as ModelCtor<any>;
-  }
-
-  public toLean(input: ToLeanInput<D, T>): LeanDocument<T> | null {
-    return this.implementation.toLean(input);
-  }
-
-  async findById(id: string): Promise<LeanDocument<T> | null> {
-    return this.implementation.findById(id);
-  }
-
-  async create(entity: D): Promise<LeanDocument<T>> {
-    return this.implementation.create(entity);
-  }
-
-  async update(
-    id: string,
-    update: Partial<D>
-  ): Promise<LeanDocument<T> | null> {
-    return this.implementation.update(id, update);
-  }
-
-  async delete(id: string): Promise<LeanDocument<T> | null> {
-    return this.implementation.delete(id);
-  }
-}

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

@@ -1,124 +0,0 @@
-import importedMongoose, { connection, Model, Mongoose } from "mongoose";
-import { v4 as uuidv4 } from "uuid";
-import { container } from "tsyringe";
-import {
-  Repository,
-  MongooseRepositoryConfig,
-  LeanDocument,
-  ToLeanInput,
-  LeanWithMeta,
-  MongooseDoc,
-} from "./types";
-
-export class MongooseRepository<D, T> implements Repository<D, T> {
-  public readonly model: Model<D>;
-  private readonly config: MongooseRepositoryConfig<D>;
-
-  constructor(config: MongooseRepositoryConfig<D>) {
-    this.config = config;
-    const mongoose = connection.db?.databaseName
-      ? importedMongoose
-      : container.resolve<Mongoose>(Mongoose);
-
-    const { name, schema } = this.config;
-
-    if (name) {
-      this.model = mongoose.model<D>(name, schema);
-    } else {
-      this.model = mongoose.model<D>(uuidv4(), schema);
-    }
-
-    this.model.createCollection();
-    this.model.createIndexes();
-    this.model.init();
-  }
-
-  public toLean(input: ToLeanInput<D, T>): LeanDocument<T> | null {
-    if (!input) {
-      return null;
-    }
-
-    let base: LeanWithMeta<T>;
-
-    if (
-      input &&
-      typeof input === "object" &&
-      "toObject" in input &&
-      typeof (input as any).toObject === "function"
-    ) {
-      base = (input as any).toObject({
-        virtuals: true,
-      }) as LeanWithMeta<T>;
-    } else {
-      base = input as LeanWithMeta<T>;
-    }
-
-    const result: LeanDocument<T> = {
-      ...(base as T),
-      id:
-        typeof base.id === "string"
-          ? base.id
-          : typeof base._id === "string"
-          ? base._id
-          : base._id !== undefined
-          ? String(base._id)
-          : "",
-      createdAt:
-        base.createdAt instanceof Date
-          ? base.createdAt
-          : base.createdAt
-          ? new Date(base.createdAt as string | number)
-          : new Date(),
-      updatedAt:
-        base.updatedAt instanceof Date
-          ? base.updatedAt
-          : base.updatedAt
-          ? new Date(base.updatedAt as string | number)
-          : new Date(),
-    };
-
-    return result;
-  }
-
-  async findById(id: string): Promise<LeanDocument<T> | null> {
-    const entity = await this.model
-      .findById(id)
-      .lean<LeanDocument<T>>({ virtuals: true })
-      .exec();
-
-    return this.toLean(entity);
-  }
-
-  async create(entity: D): Promise<LeanDocument<T>> {
-    const document = await this.model.create<D>(entity);
-
-    const leanDocument = this.toLean(document as MongooseDoc<D>);
-
-    if (!leanDocument) {
-      throw new Error("failed to create document");
-    }
-
-    return leanDocument;
-  }
-
-  async update(
-    id: string,
-    update: Partial<D>
-  ): Promise<LeanDocument<T> | null> {
-    const entity = await this.model
-      .findByIdAndUpdate(id, update, { new: true })
-      .lean<LeanDocument<T>>({ virtuals: true })
-      .exec();
-
-    return this.toLean(entity);
-  }
-
-  async delete(id: string): Promise<LeanDocument<T> | null> {
-    const entity = await this.model
-      .findByIdAndDelete(id)
-      .lean<LeanDocument<T>>({ virtuals: true })
-      .exec();
-
-    return this.toLean(entity);
-  }
-}

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

@@ -1,70 +0,0 @@
-import { Model, ModelCtor } from "sequelize";
-import { Repository, SequelizeRepositoryConfig, LeanDocument } from "./types";
-
-export class SequelizeRepository<D extends Model, T>
-  implements Repository<D, T>
-{
-  public readonly model: ModelCtor<D>;
-
-  constructor(config: SequelizeRepositoryConfig<D>) {
-    this.model = config.model;
-  }
-
-  public toLean(input: any): LeanDocument<T> | null {
-    if (!input) return null;
-    const plain = input instanceof Model ? input.get({ plain: true }) : input;
-
-    // Ensure id, createdAt, updatedAt exist and are correct types
-    // This assumes the model has these fields.
-    return {
-      ...(plain as T),
-      id: String(plain.id || plain._id || ""),
-      createdAt: plain.createdAt ? new Date(plain.createdAt) : new Date(),
-      updatedAt: plain.updatedAt ? new Date(plain.updatedAt) : new Date(),
-    } as LeanDocument<T>;
-  }
-
-  async findById(id: string): Promise<LeanDocument<T> | null> {
-    const entity = await this.model.findByPk(id);
-    return this.toLean(entity);
-  }
-
-  async create(entity: D): Promise<LeanDocument<T>> {
-    const document = await this.model.create(entity as any);
-    return this.toLean(document) as LeanDocument<T>;
-  }
-
-  async update(
-    id: string,
-    update: Partial<D>
-  ): Promise<LeanDocument<T> | null> {
-    const [affectedCount] = await this.model.update(update as any, {
-      where: { id } as any,
-    });
-
-    if (affectedCount === 0) {
-      return null;
-    }
-
-    return this.findById(id);
-  }
-
-  async delete(id: string): Promise<LeanDocument<T> | null> {
-    const entity = await this.findById(id);
-    if (!entity) return null;
-
-    await this.model.destroy({
-      where: { id } as any,
-    });
-
-    return entity;
-  }
-}
-[
-  {
-    type: "image",
-    payload: {
-      attachment_id: "{{ $json.propertyName }}",
-    },
-  },
-];

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

@@ -1,69 +0,0 @@
-import {
-  Document,
-  Model as MongooseModel,
-  Schema,
-  Default__v,
-  Require_id,
-  ObjectId,
-  IfAny,
-} from "mongoose";
-import { Model as SequelizeModel, ModelCtor, Model } from "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;
-
-export type MongooseRepositoryConfig<D> = {
-  type: "mongoose";
-  name?: string;
-  schema: Schema<D>;
-};
-
-export type SequelizeRepositoryConfig<D extends Model> = {
-  type: "sequelize";
-  model: ModelCtor<D>;
-};
-
-export type BaseRepositoryConfig<D> =
-  | MongooseRepositoryConfig<D>
-  | SequelizeRepositoryConfig<D extends Model ? D : never>;
-
-export type Repository<D, T> = {
-  model: MongooseModel<D> | ModelCtor<SequelizeModel<any, any>>;
-
-  toLean(input: any): LeanDocument<T> | null;
-  findById(id: string): Promise<LeanDocument<T> | null>;
-  create(entity: D): Promise<LeanDocument<T>>;
-  update(id: string, update: Partial<D>): Promise<LeanDocument<T> | null>;
-  delete(id: string): Promise<LeanDocument<T> | null>;
-};

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

@@ -1,2 +0,0 @@
-export * from "./service";
-export * from "./micro-service";

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

@@ -1,53 +0,0 @@
-import { Application, ConfigApplication } from "../application";
-import { ConfigDomain, Domain } from "../domain";
-import { ConfigInfrastructure, Infrastructure } from "../infrastructure";
-import { ConfigService, HandlersType, Service } from "./service/service";
-
-export type ConfigMicroService = {
-  architecture: {
-    application: ConfigApplication;
-    domain: ConfigDomain;
-    infrastructure: ConfigInfrastructure;
-    service: ConfigService;
-  };
-};
-
-export class MicroService {
-  private application: Application;
-  private domain: Domain;
-  private infrastructure: Infrastructure;
-  private service: Service;
-
-  constructor(config: ConfigMicroService) {
-    const { architecture } = config;
-    const { application, domain, infrastructure, service } = architecture;
-
-    this.application = new Application(application);
-    this.domain = new Domain(domain);
-    this.infrastructure = new Infrastructure(infrastructure);
-    this.service = new Service(service);
-  }
-
-  public async start(input: { port: number }): Promise<void> {
-    const { port } = input;
-
-    await this.service.configureDatabases();
-
-    this.infrastructure.start();
-
-    this.domain.start();
-
-    this.application.start();
-
-    this.service.registerHandlers({
-      handlers: this.application.routeHandlers,
-      handlersType: HandlersType.ROUTE,
-    });
-    this.service.registerHandlers({
-      handlers: this.application.hookHandlers,
-      handlersType: HandlersType.HOOK,
-    });
-
-    await this.service.start({ port });
-  }
-}

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

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

package/start.md

@@ -1,34 +0,0 @@
-# Zacatl Project Onboarding & Usage
-
-Welcome to Zacatl! This project uses structured YAML documentation for all context, architecture, coding standards, and best practices.
-
-## Getting Started
-
-- **Project context, architecture, and component summaries:**
-  See [`context.yaml`](./context.yaml)
-- **Coding standards, naming conventions, and best practices:**
-  See [`guidelines.yaml`](./guidelines.yaml)
-- **Design and usage patterns:**
-  See [`patterns.yaml`](./patterns.yaml)
-- **MongoDB schema design guidelines:**
-  See [`mongodb.yaml`](./mongodb.yaml)
-
-## Setup
-
-1. Install dependencies:
-   ```zsh
-   npm install
-   ```
-2. Run tests:
-   ```zsh
-   npm test
-   ```
-3. Explore the codebase, starting from `src/`.
-
-## Contributing
-
-- Follow the guidelines in `guidelines.yaml` and `patterns.yaml`.
-- Update `context.yaml`, `guidelines.yaml`, `patterns.yaml`, or `mongodb.yaml` with any new patterns or conventions.
-- Place all tests in the `test/` directory, mirroring the `src/` structure.
-
-For any questions, refer to the YAML documentation or contact the maintainers.

package/test/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "../",
-    "noEmit": true
-  },
-  "include": ["./**/*.ts"],
-  "exclude": ["node_modules", "build", "coverage"]
-}

package/test/unit/helpers/common/common.ts

@@ -1,32 +0,0 @@
-import { FastifyRequest } from "fastify";
-
-export const createFakeFastifyRequest = (): Partial<FastifyRequest> => ({
-  id: "req-1",
-  params: {},
-  // raw: {},
-  query: {},
-  headers: {},
-  // log: {
-  //   info: vi.fn(),
-  //   error: vi.fn(),
-  // },
-  server: {} as any,
-  body: {},
-  // If your code calls these methods, stub them as needed.
-  getValidationFunction: vi.fn(),
-  compileValidationSchema: vi.fn(),
-  validateInput: vi.fn(),
-});
-
-// Create a fake FastifyReply object. It mocks the 'code' and 'send' methods.
-export const createFakeFastifyReply = () => {
-  const reply: any = {
-    code: vi.fn().mockImplementation(function (this: any, code: number) {
-      // Save the code for potential additional assertions.
-      this.calledCode = code;
-      return this;
-    }),
-    send: vi.fn().mockResolvedValue(undefined),
-  };
-  return reply;
-};

package/test/unit/helpers/common/logger.ts

@@ -1,8 +0,0 @@
-export const logger = {
-  log: (input: {
-    level: "info" | "error" | "warn" | "debug";
-    action: string;
-    msg: string;
-  }): void =>
-    console[input.level](`🧪 [${input.action}] unit tests - ${input.msg}`),
-};