@sentzunhat/zacatl 0.0.14 → 0.0.21

package/src/logs/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Input structure for logger methods
+ */
+export type LoggerInput =
+  | {
+      data?: unknown;
+      details?: unknown;
+    }
+  | undefined;
+
+/**
+ * Logger interface that wraps Pino with structured logging
+ */
+export interface Logger {
+  log: (message: string, input?: LoggerInput) => void;
+  info: (message: string, input?: LoggerInput) => void;
+  trace: (message: string, input?: LoggerInput) => void;
+  warn: (message: string, input?: LoggerInput) => void;
+  error: (message: string, input?: LoggerInput) => void;
+  fatal: (message: string, input?: LoggerInput) => void;
+}
+
+/**
+ * Logger adapter interface - implement this to create custom log transports
+ * (Winston, Bunyan, Console, CloudWatch, etc.)
+ */
+export interface LoggerAdapter {
+  log: (message: string, input?: LoggerInput) => void;
+  info: (message: string, input?: LoggerInput) => void;
+  trace: (message: string, input?: LoggerInput) => void;
+  warn: (message: string, input?: LoggerInput) => void;
+  error: (message: string, input?: LoggerInput) => void;
+  fatal: (message: string, input?: LoggerInput) => void;
+}
+
+/**
+ * Re-export Pino types for convenience
+ */
+export type { LoggerOptions as PinoLoggerConfig } from "pino";
+
+/**
+ * Adapter type identifier for built-in adapters
+ */
+export type LoggerAdapterType = "pino" | "console";

package/src/orm-exports.ts

@@ -0,0 +1,23 @@
+/**
+ * Re-export ORM dependencies for convenience
+ * These are included as dependencies (currently) for backward compatibility
+ * Future versions may move them to pure peer dependencies
+ */
+
+// Mongoose exports - full re-export
+export {
+  default as mongoose,
+  Mongoose,
+  Schema,
+  Model,
+  Document,
+  connect,
+  connection,
+} from "mongoose";
+
+// Sequelize exports - full re-export
+export { Sequelize, Model as SequelizeModel, DataTypes, Op } from "sequelize";
+
+// Type-only exports for convenience
+export type { Model as MongooseModel } from "mongoose";
+export type { ModelStatic, Options as SequelizeOptions } from "sequelize";

package/src/runtime/detector.ts

@@ -0,0 +1,61 @@
+import type { RuntimeInfo, RuntimeType } from "./types";
+
+/**
+ * Detects the current JavaScript runtime environment
+ * @returns Runtime information including type and version
+ */
+export const detectRuntime = (): RuntimeInfo => {
+  let type: RuntimeType = "unknown";
+  let version: string | undefined = undefined;
+
+  // Check for Bun
+  if (typeof Bun !== "undefined") {
+    type = "bun";
+    version = Bun.version;
+  }
+  // Check for Node.js
+  else if (typeof process !== "undefined" && process.versions?.node) {
+    type = "node";
+    version = process.versions.node;
+  }
+
+  const result: RuntimeInfo = {
+    type,
+    isBun: type === "bun",
+    isNode: type === "node",
+  };
+
+  if (version !== undefined) {
+    result.version = version;
+  }
+
+  return result;
+};
+
+/**
+ * Check if the current runtime is Bun
+ * @returns true if running on Bun
+ */
+export const isBun = (): boolean => typeof Bun !== "undefined";
+
+/**
+ * Check if the current runtime is Node.js
+ * @returns true if running on Node.js
+ */
+export const isNode = (): boolean =>
+  typeof Bun === "undefined" &&
+  typeof process !== "undefined" &&
+  !!process.versions?.node;
+
+/**
+ * Get the current runtime type
+ * @returns The detected runtime type
+ */
+export const getRuntimeType = (): RuntimeType => detectRuntime().type;
+
+/**
+ * Get the current runtime version
+ * @returns The runtime version string or undefined
+ */
+export const getRuntimeVersion = (): string | undefined =>
+  detectRuntime().version;

package/src/runtime/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./detector";

package/src/runtime/types.ts

@@ -0,0 +1,18 @@
+/**
+ * Supported JavaScript runtimes
+ */
+export type RuntimeType = "node" | "bun" | "unknown";
+
+/**
+ * Runtime detection result
+ */
+export interface RuntimeInfo {
+  /** The detected runtime type */
+  type: RuntimeType;
+  /** Runtime version string (if available) */
+  version?: string;
+  /** Whether the runtime is Bun */
+  isBun: boolean;
+  /** Whether the runtime is Node.js */
+  isNode: boolean;
+}

package/src/{micro-service → service}/architecture/application/entry-points/rest/route-handlers/abstract.ts

@@ -3,14 +3,16 @@ import { z } from "zod";
 import { HTTPMethods, FastifySchema, FastifyReply } from "fastify";
 
 import { RouteHandler } from "./route-handler";
-import { Request } from "../common/request";
+import type { Request } from "../common/request";
+
+export type { Request } from "../common/request";
 
 export type RouteSchema<
   TBody = void,
   TQuerystring = void,
   TParams = void,
   THeaders = void,
-  TResponse = void
+  TResponse = void,
 > = {
   body?: z.ZodSchema<TBody>;
   querystring?: z.ZodSchema<TQuerystring>;
@@ -32,9 +34,8 @@ export abstract class AbstractRouteHandler<
   TQuerystring = void,
   TResponse = void,
   TParams = void,
-  THeaders = void
-> implements RouteHandler<TBody, TQuerystring, TParams, THeaders>
-{
+  THeaders = void,
+> implements RouteHandler<TBody, TQuerystring, TParams, THeaders> {
   public url: string;
   public method: HTTPMethods;
   public schema: FastifySchema;
@@ -47,12 +48,12 @@ export abstract class AbstractRouteHandler<
 
   abstract handler(
     request: Request<TBody, TQuerystring, TParams, THeaders>,
-    reply: FastifyReply
+    reply: FastifyReply,
   ): Promise<HandlerOutput<TResponse>> | HandlerOutput<TResponse>;
 
   public async execute(
     request: Request<TBody, TQuerystring, TParams, THeaders>,
-    reply: FastifyReply
+    reply: FastifyReply,
   ): Promise<void> {
     const response = await this.handler(request, reply);
 

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

@@ -1,6 +1,8 @@
 import { FastifySchema } from "fastify";
 import { AbstractRouteHandler } from "./abstract";
 
+export type { Request } from "./abstract";
+
 export type PostRouteHandlerConstructor = {
   url: string;
   schema: FastifySchema;
@@ -10,7 +12,7 @@ export abstract class PostRouteHandler<
   TBody = void,
   TResponse = void,
   TQuerystring = void,
-  TParams = void
+  TParams = void,
 > extends AbstractRouteHandler<TBody, TQuerystring, TResponse, TParams> {
   constructor(args: PostRouteHandlerConstructor) {
     super({

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

@@ -0,0 +1,36 @@
+import { AbstractArchitecture, Constructor } from "../architecture";
+import { Provider } from "./provider";
+import { container } from "tsyringe";
+
+export type ConfigDomain = {
+  providers: Array<Constructor>;
+};
+
+export class Domain extends AbstractArchitecture {
+  private config: ConfigDomain;
+  private providers: Array<Provider> = [];
+
+  constructor(config: ConfigDomain) {
+    super();
+
+    this.config = config;
+  }
+
+  public async start(): Promise<void> {
+    this.registerDependencies(this.config.providers);
+
+    // Auto-start providers that implement the start method
+    for (const ProviderClass of this.config.providers) {
+      if (container.isRegistered(ProviderClass.name)) {
+        const provider = container.resolve(ProviderClass.name) as Provider;
+        if (
+          provider instanceof Provider &&
+          typeof provider.start === "function"
+        ) {
+          await provider.start();
+          this.providers.push(provider);
+        }
+      }
+    }
+  }
+}

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

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

package/src/service/architecture/domain/provider.ts

@@ -0,0 +1,9 @@
+export abstract class Provider<T = unknown> {
+  protected config: T;
+
+  constructor(config: T) {
+    this.config = config;
+  }
+
+  public abstract start(): Promise<void>;
+}

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

@@ -0,0 +1,48 @@
+export * from "./repositories";
+export * from "./infrastructure";
+
+// Re-export Mongoose for user convenience
+// Users can import directly from @sentzunhat/zacatl instead of installing mongoose
+export {
+  Schema,
+  Model,
+  Types,
+  connect,
+  connection,
+  createConnection,
+} from "mongoose";
+
+export type {
+  Document,
+  SchemaDefinition,
+  SchemaOptions,
+  SchemaTypeOptions,
+  Connection,
+  Mongoose,
+  ObjectId,
+  UpdateQuery,
+  QueryOptions,
+  PopulateOptions,
+  HydratedDocument,
+  InferSchemaType,
+} from "mongoose";
+
+// Re-export Sequelize for user convenience
+// Users can import directly from @sentzunhat/zacatl instead of installing sequelize
+export { DataTypes, Sequelize, Model as SequelizeModelClass } from "sequelize";
+
+export type {
+  ModelStatic,
+  QueryInterface,
+  Transaction,
+  Options as SequelizeOptions,
+  ModelAttributes,
+  ModelOptions,
+  FindOptions,
+  CreateOptions,
+  UpdateOptions,
+  DestroyOptions,
+  WhereOptions,
+  Order,
+  Includeable,
+} from "sequelize";

package/src/service/architecture/infrastructure/orm/adapter-loader.ts

@@ -0,0 +1,52 @@
+import type { Model } from "sequelize";
+import type {
+  MongooseRepositoryConfig,
+  SequelizeRepositoryConfig,
+  ORMAdapter,
+} from "../repositories/types";
+
+/**
+ * Loads MongooseAdapter dynamically - only when needed
+ * Throws helpful error if mongoose is not installed
+ */
+export function loadMongooseAdapter<D, I, O>(
+  config: MongooseRepositoryConfig<D>,
+): ORMAdapter<D, I, O> {
+  try {
+    // Dynamic import - only loads when Mongoose is actually used
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const adapters =
+      require("./adapters/mongoose-adapter") as typeof import("./adapters/mongoose-adapter");
+    return new adapters.MongooseAdapter<D, I, O>(config);
+  } catch (error: any) {
+    if (error.code === "MODULE_NOT_FOUND") {
+      throw new Error(
+        "Mongoose is not installed. Install it with: npm install mongoose",
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Loads SequelizeAdapter dynamically - only when needed
+ * Throws helpful error if sequelize is not installed
+ */
+export function loadSequelizeAdapter<D extends Model, I, O>(
+  config: SequelizeRepositoryConfig<D>,
+): ORMAdapter<D, I, O> {
+  try {
+    // Dynamic import - only loads when Sequelize is actually used
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const adapters =
+      require("./adapters/sequelize-adapter") as typeof import("./adapters/sequelize-adapter");
+    return new adapters.SequelizeAdapter<D, I, O>(config);
+  } catch (error: any) {
+    if (error.code === "MODULE_NOT_FOUND") {
+      throw new Error(
+        "Sequelize is not installed. Install it with: npm install sequelize",
+      );
+    }
+    throw error;
+  }
+}

package/src/service/architecture/infrastructure/orm/adapters/mongoose-adapter.ts

@@ -0,0 +1,133 @@
+import type { Model as MongooseModel } from "mongoose";
+import { Mongoose } from "mongoose";
+import { v4 as uuidv4 } from "uuid";
+import { container } from "tsyringe";
+import type {
+  MongooseRepositoryConfig,
+  ORMAdapter,
+  LeanWithMeta,
+} from "../../repositories/types";
+
+/**
+ * MongooseAdapter - Handles Mongoose-specific ORM operations
+ *
+ * Provides consistent interface for repository layer with:
+ * - Document transformation
+ * - ID normalization
+ * - Timestamp management
+ * - Connection instance from DI container
+ */
+export class MongooseAdapter<D, I, O> implements ORMAdapter<D, I, O> {
+  public readonly model: MongooseModel<D>;
+  private readonly config: MongooseRepositoryConfig<D>;
+
+  constructor(config: MongooseRepositoryConfig<D>) {
+    this.config = config;
+    // Get mongoose instance from DI container - allows per-database configuration
+    // Connection strings should be set up before repository instantiation
+    const mongoose = 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: unknown): O | null {
+    if (!input) {
+      return null;
+    }
+
+    let base: LeanWithMeta<O>;
+
+    if (
+      input &&
+      typeof input === "object" &&
+      "toObject" in input &&
+      typeof (input as unknown as Record<string, unknown>)["toObject"] ===
+        "function"
+    ) {
+      base = (
+        input as unknown as {
+          toObject: (opt: any) => LeanWithMeta<O>;
+        }
+      ).toObject({
+        virtuals: true,
+      }) as LeanWithMeta<O>;
+    } else {
+      base = input as LeanWithMeta<O>;
+    }
+
+    const result: O = {
+      ...(base as O),
+      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(),
+    } as O;
+
+    return result;
+  }
+
+  async findById(id: string): Promise<O | null> {
+    const entity = await this.model
+      .findById(id)
+      .lean<O>({ virtuals: true })
+      .exec();
+
+    return this.toLean(entity);
+  }
+
+  async create(entity: I): Promise<O> {
+    const document = await this.model.create(entity as any);
+
+    const leanDocument = this.toLean(document);
+
+    if (!leanDocument) {
+      throw new Error("failed to create document");
+    }
+
+    return leanDocument;
+  }
+
+  async update(id: string, update: Partial<I>): Promise<O | null> {
+    const entity = await this.model
+      .findByIdAndUpdate(id, update as any, { new: true })
+      .lean<O>({ virtuals: true })
+      .exec();
+
+    return this.toLean(entity);
+  }
+
+  async delete(id: string): Promise<O | null> {
+    const entity = await this.model
+      .findByIdAndDelete(id)
+      .lean<O>({ virtuals: true })
+      .exec();
+
+    return this.toLean(entity);
+  }
+}

package/src/service/architecture/infrastructure/orm/adapters/sequelize-adapter.ts

@@ -0,0 +1,75 @@
+import { Model, ModelStatic } from "sequelize";
+import type {
+  SequelizeRepositoryConfig,
+  ORMAdapter,
+} from "../../repositories/types";
+
+/**
+ * SequelizeAdapter - Handles Sequelize-specific ORM operations
+ *
+ * This adapter wraps Sequelize model operations and provides a consistent
+ * interface for the repository layer. It handles plain object transformation,
+ * ID normalization, and timestamp management.
+ */
+export class SequelizeAdapter<D extends Model, I, O> implements ORMAdapter<
+  D,
+  I,
+  O
+> {
+  public readonly model: ModelStatic<D>;
+
+  constructor(config: SequelizeRepositoryConfig<D>) {
+    this.model = config.model;
+  }
+
+  public toLean(input: unknown): O | null {
+    if (!input) return null;
+    const plain =
+      input instanceof Model ? input.get({ plain: true }) : (input as O);
+
+    // Ensure id, createdAt, updatedAt exist and are correct types
+    return {
+      ...(plain as O),
+      id: String((plain as any).id || (plain as any)._id || ""),
+      createdAt: (plain as any).createdAt
+        ? new Date((plain as any).createdAt)
+        : new Date(),
+      updatedAt: (plain as any).updatedAt
+        ? new Date((plain as any).updatedAt)
+        : new Date(),
+    } as O;
+  }
+
+  async findById(id: string): Promise<O | null> {
+    const entity = await this.model.findByPk(id);
+    return this.toLean(entity);
+  }
+
+  async create(entity: I): Promise<O> {
+    const document = await this.model.create(entity as any);
+    return this.toLean(document) as O;
+  }
+
+  async update(id: string, update: Partial<I>): Promise<O | 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<O | null> {
+    const entity = await this.findById(id);
+    if (!entity) return null;
+
+    await this.model.destroy({
+      where: { id } as any,
+    });
+
+    return entity;
+  }
+}

package/src/service/architecture/infrastructure/orm/index.ts

@@ -0,0 +1,2 @@
+export * from "./adapters/mongoose-adapter";
+export * from "./adapters/sequelize-adapter";

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

@@ -0,0 +1,112 @@
+import type { Model as MongooseModel } from "mongoose";
+import type { Model, ModelStatic } from "sequelize";
+import {
+  BaseRepositoryConfig,
+  Repository,
+  MongooseRepositoryConfig,
+  SequelizeRepositoryConfig,
+  ORMAdapter,
+  ORMType,
+} from "./types";
+import {
+  loadMongooseAdapter,
+  loadSequelizeAdapter,
+} from "../orm/adapter-loader";
+
+export * from "./types";
+
+/**
+ * Type guard to check if config is for Mongoose
+ */
+const isMongooseConfig = <D>(
+  config: BaseRepositoryConfig<D>,
+): config is MongooseRepositoryConfig<D> => {
+  return config.type === ORMType.Mongoose;
+};
+
+/**
+ * Type guard to check if config is for Sequelize
+ */
+const isSequelizeConfig = <D extends Model>(
+  config: BaseRepositoryConfig<D>,
+): config is SequelizeRepositoryConfig<D> => {
+  return config.type === ORMType.Sequelize;
+};
+
+/**
+ * BaseRepository - Abstract base class for all repositories
+ *
+ * Supports multiple ORMs (Mongoose, Sequelize) through adapter pattern.
+ * Adapters are lazy-loaded - only the ORM you use gets imported.
+ * This allows projects to install only one ORM without unused dependencies.
+ */
+export abstract class BaseRepository<D, I, O> implements Repository<D, I, O> {
+  private adapter: ORMAdapter<D, I, O>;
+  private readonly ormType: ORMType;
+
+  constructor(config: BaseRepositoryConfig<D>) {
+    this.ormType = config.type;
+
+    if (isMongooseConfig<D>(config)) {
+      this.adapter = loadMongooseAdapter<D, I, O>(config);
+    } else if (isSequelizeConfig(config)) {
+      // Type assertion needed here because D could be either Mongoose or Sequelize model
+      this.adapter = loadSequelizeAdapter<Model, I, O>(config) as ORMAdapter<
+        D,
+        I,
+        O
+      >;
+    } else {
+      const exhaustive: never = config;
+      throw new Error(
+        `Invalid repository configuration. Received: ${JSON.stringify(exhaustive)}`,
+      );
+    }
+  }
+
+  get model(): MongooseModel<D> | ModelStatic<any> {
+    return this.adapter.model;
+  }
+
+  public isMongoose(): boolean {
+    return this.ormType === ORMType.Mongoose;
+  }
+
+  public isSequelize(): boolean {
+    return this.ormType === ORMType.Sequelize;
+  }
+
+  public getMongooseModel(): MongooseModel<D> {
+    if (!this.isMongoose()) {
+      throw new Error("Repository is not using Mongoose");
+    }
+    return this.adapter.model as MongooseModel<D>;
+  }
+
+  public getSequelizeModel(): ModelStatic<any> {
+    if (!this.isSequelize()) {
+      throw new Error("Repository is not using Sequelize");
+    }
+    return this.adapter.model as ModelStatic<any>;
+  }
+
+  public toLean(input: unknown): O | null {
+    return this.adapter.toLean(input);
+  }
+
+  async findById(id: string): Promise<O | null> {
+    return this.adapter.findById(id);
+  }
+
+  async create(entity: I): Promise<O> {
+    return this.adapter.create(entity);
+  }
+
+  async update(id: string, update: Partial<I>): Promise<O | null> {
+    return this.adapter.update(id, update);
+  }
+
+  async delete(id: string): Promise<O | null> {
+    return this.adapter.delete(id);
+  }
+}