@emkodev/emkore 1.0.3

package/src/common/abstract.repository.ts

@@ -0,0 +1,162 @@
+import type { Dto } from "./abstract.entity.ts";
+
+/**
+ * Base filter type for repository queries.
+ *
+ * Extracts business fields from DTO (excludes id, ownerId, createdAt, updatedAt, deletedAt)
+ * and adds back the base fields with appropriate query types:
+ * - ownerId: exact match filtering
+ * - createdAt/updatedAt/deletedAt: range-based date filtering
+ *
+ * @template TDto - The DTO type to create a filter for
+ */
+export type BaseFilter<TDto extends Dto> = Omit<TDto, keyof Dto> & {
+  readonly ownerId?: string;
+  readonly createdAt?: { from?: Date; to?: Date };
+  readonly updatedAt?: { from?: Date; to?: Date };
+  readonly deletedAt?: { from?: Date; to?: Date };
+};
+
+/**
+ * Base repository interface defining common CRUD operations for DTOs.
+ *
+ * @template T - The DTO type this repository works with, must extend Dto
+ * @template F - The filter type for queries, defaults to Partial<T>
+ */
+export abstract class Repository<T extends Dto, F = Partial<T>> {
+  /**
+   * Creates a new DTO in the repository.
+   * @param dto - The DTO to create
+   * @returns Promise resolving to the created DTO
+   * @throws ValidationException if DTO data is invalid
+   * @throws EntityAlreadyExistsException if DTO with same ID already exists
+   * @throws DatabaseException on database operation failure
+   */
+  abstract create(dto: T): Promise<T>;
+
+  /**
+   * Retrieves a DTO by ID.
+   * @param id - The DTO ID
+   * @returns Promise resolving to the found DTO
+   * @throws ValidationException if ID is invalid
+   * @throws EntityNotFoundException if DTO not found
+   * @throws DatabaseException on database operation failure
+   */
+  abstract retrieve(id: string): Promise<T>;
+
+  /**
+   * Updates an existing DTO.
+   * @param dto - The DTO to update
+   * @returns Promise resolving to the updated DTO
+   * @throws ValidationException if DTO data is invalid
+   * @throws EntityNotFoundException if DTO not found
+   * @throws DatabaseException on database operation failure
+   */
+  abstract update(dto: T): Promise<T>;
+
+  /**
+   * Deletes a DTO by ID.
+   * @param id - The DTO ID
+   * @returns Promise resolving when deletion is complete
+   * @throws ValidationException if ID is invalid
+   * @throws EntityNotFoundException if DTO not found
+   * @throws DatabaseException on database operation failure
+   */
+  abstract delete(id: string): Promise<void>;
+
+  /**
+   * Lists DTOs with pagination and filtering.
+   * @param options - Query options including filter, pagination
+   * @returns Promise resolving to list of DTOs
+   * @throws ValidationException if query parameters are invalid
+   * @throws DatabaseException on database operation failure
+   */
+  abstract list(options?: {
+    filter?: Partial<F>;
+    limit?: number;
+    offset?: number;
+    sortBy?: string;
+    sortOrder?: "asc" | "desc";
+  }): Promise<T[]>;
+
+  /**
+   * Counts DTOs with filtering.
+   * @param filter - Optional filter criteria
+   * @returns Promise resolving to DTO count
+   * @throws ValidationException if filter parameters are invalid
+   * @throws DatabaseException on database operation failure
+   */
+  abstract count(filter?: Partial<F>): Promise<number>;
+
+  /**
+   * Checks if a DTO exists by ID.
+   * Default implementation uses retrieve and catches EntityNotFoundException.
+   * Can be overridden for more efficient implementation.
+   * @param id - The DTO ID
+   * @returns Promise resolving to boolean existence check
+   */
+  async exists(id: string): Promise<boolean> {
+    try {
+      await this.retrieve(id);
+      return true;
+    } catch (error) {
+      if (error instanceof Error && error.name === "EntityNotFoundException") {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Deletes multiple DTOs by IDs in a single transaction.
+   * Default implementation calls delete for each ID.
+   * Should be overridden for batch operations in production repositories.
+   * @param ids - Array of DTO IDs to delete
+   * @returns Promise resolving to number of DTOs actually deleted
+   */
+  async bulkDelete(ids: string[]): Promise<number> {
+    let deletedCount = 0;
+    for (const id of ids) {
+      try {
+        await this.delete(id);
+        deletedCount++;
+      } catch (error) {
+        // Log error but continue with other deletions
+        console.error(`Failed to delete DTO ${id}:`, error);
+      }
+    }
+    return deletedCount;
+  }
+
+  /**
+   * Creates multiple DTOs in a single transaction.
+   * Default implementation calls create for each DTO.
+   * Should be overridden for batch operations in production repositories.
+   * @param dtos - Array of DTOs to create
+   * @returns Promise resolving to array of created DTOs
+   */
+  async bulkCreate(dtos: T[]): Promise<T[]> {
+    const created: T[] = [];
+    for (const dto of dtos) {
+      const result = await this.create(dto);
+      created.push(result);
+    }
+    return created;
+  }
+
+  /**
+   * Updates multiple DTOs in a single transaction.
+   * Default implementation calls update for each DTO.
+   * Should be overridden for batch operations in production repositories.
+   * @param dtos - Array of DTOs to update
+   * @returns Promise resolving to array of updated DTOs
+   */
+  async bulkUpdate(dtos: T[]): Promise<T[]> {
+    const updated: T[] = [];
+    for (const dto of dtos) {
+      const result = await this.update(dto);
+      updated.push(result);
+    }
+    return updated;
+  }
+}

package/src/common/abstract.usecase.ts

@@ -0,0 +1,113 @@
+import type { Actor } from "./abstract.actor.ts";
+import type { Interceptor } from "./abstract.interceptor.ts";
+import { createInterceptorContext } from "./type/interceptor-context.type.ts";
+import type { ApiDefinition } from "./llm/api-definition.type.ts";
+import type { Permission } from "./type/permission.type.ts";
+
+export type UsecaseName = readonly [Lowercase<string>, Lowercase<string>];
+
+export abstract class Usecase<Input, Output> {
+  /* This is necessary for Permissions management and code generation. */
+  abstract readonly usecaseName: UsecaseName;
+
+  /* API definition schema makes it possible to generate API docs, MCP tools, JSON-RPC definitions. It also make it possible for business people to describe the Usecase in more or less plain text.   */
+  abstract readonly apiDefinition: ApiDefinition;
+
+  /* Global interceptors are applied to each Interactor (Usecases implementation). Could be used for logging, sanitization, auth, etc. */
+  private static readonly _globalInterceptors = new Set<
+    // deno-lint-ignore no-explicit-any
+    Interceptor<any, any>
+  >();
+
+  /* Local interceptors are applied ONLY to the interactors instances you explicitly called .use() for.  */
+  private readonly _localInterceptors = new Set<Interceptor<Input, Output>>();
+
+  /* Global interceptors registry. call `Usecase.use(...)` to add one or more interceptors. */
+  // deno-lint-ignore no-explicit-any
+  static use(interceptors: Interceptor<any, any>[]): void {
+    interceptors.forEach((interceptor) =>
+      this._globalInterceptors.add(interceptor)
+    );
+  }
+
+  /* Global interceptors registry. Instantiate the desired interactor and call `interactor.use(...)` to add one or more interceptors. */
+  use(interceptors: Interceptor<Input, Output>[]): void {
+    interceptors.forEach((interceptor) =>
+      this._localInterceptors.add(interceptor)
+    );
+  }
+
+  /* Call this method in your code. It will call `_execute` internally, which in turn must be implemented by your Interactors.    */
+  async execute(actor: Actor, input: Input): Promise<Output> {
+    const context = createInterceptorContext(
+      actor,
+      this.usecaseName,
+      this.requiredPermissions,
+      {},
+    );
+
+    try {
+      let processedInput = input;
+
+      // Global interceptors beforeExecute
+      for (const interceptor of Usecase._globalInterceptors) {
+        if (interceptor.beforeExecute) {
+          processedInput = await interceptor.beforeExecute(
+            processedInput,
+            context,
+          );
+        }
+      }
+
+      // Local interceptors beforeExecute
+      for (const interceptor of this._localInterceptors) {
+        if (interceptor.beforeExecute) {
+          processedInput = await interceptor.beforeExecute(
+            processedInput,
+            context,
+          );
+        }
+      }
+
+      let output = await this._execute(actor, processedInput);
+
+      // Local interceptors afterExecute (reversed)
+      for (const interceptor of [...this._localInterceptors].reverse()) {
+        if (interceptor.afterExecute) {
+          output = await interceptor.afterExecute(output, context);
+        }
+      }
+
+      // Global interceptors afterExecute (reversed)
+      for (const interceptor of [...Usecase._globalInterceptors].reverse()) {
+        if (interceptor.afterExecute) {
+          output = await interceptor.afterExecute(output, context);
+        }
+      }
+
+      return output;
+    } catch (error) {
+      // Local interceptors onError (reversed)
+      for (const interceptor of [...this._localInterceptors].reverse()) {
+        if (interceptor.onError) {
+          await interceptor.onError(error as Error, context);
+        }
+      }
+
+      // Global interceptors onError (reversed)
+      for (const interceptor of [...Usecase._globalInterceptors].reverse()) {
+        if (interceptor.onError) {
+          await interceptor.onError(error as Error, context);
+        }
+      }
+
+      throw error;
+    }
+  }
+
+  /* DO NOT call this method directly. DO implement it in your Interactors. */
+  protected abstract _execute(actor: Actor, input: Input): Promise<Output>;
+
+  /* Define the permissions required for this usecase. Return empty array if no permissions needed. */
+  abstract get requiredPermissions(): Permission[];
+}

package/src/common/config/config-registry.ts

@@ -0,0 +1,190 @@
+import { ValidationError } from "../validation/validators.ts";
+import { ValidationResult } from "../validation/validation-result.ts";
+import type { ConfigSection } from "./config-section.ts";
+
+/**
+ * 12-Factor App compliant configuration registry.
+ *
+ * Features:
+ * - Modular: Register only the config sections you need
+ * - Environment-based: All values from environment variables
+ * - No hardcoded environments: No dev/staging/prod classes
+ * - Composable: Build your configuration dynamically
+ *
+ * @example
+ * ```typescript
+ * const config = new ConfigRegistry();
+ *
+ * // Register only what you need
+ * config.register("database", new DatabaseConfig());
+ * config.register("logging", new LoggingConfig());
+ *
+ * // Validate all sections
+ * const result = config.validate();
+ * if (!result.isValid) {
+ *   throw new Error(`Config validation failed: ${result.errors.join(", ")}`);
+ * }
+ *
+ * // Access config sections
+ * const db = config.get<DatabaseConfig>("database");
+ * ```
+ */
+export class ConfigRegistry {
+  private readonly sections = new Map<string, ConfigSection>();
+  private _validated = false;
+
+  /**
+   * Register a configuration section
+   * @param name Unique name for this section
+   * @param section The configuration section to register
+   */
+  register(name: string, section: ConfigSection): void {
+    if (this.sections.has(name)) {
+      throw new Error(`Configuration section '${name}' is already registered`);
+    }
+    this.sections.set(name, section);
+    this._validated = false; // Reset validation state
+  }
+
+  /**
+   * Get a configuration section by name
+   * @param name The name of the section to retrieve
+   * @returns The config section or undefined if not found
+   */
+  get<T extends ConfigSection>(name: string): T | undefined {
+    return this.sections.get(name) as T | undefined;
+  }
+
+  /**
+   * Get a configuration section by name, throwing if not found
+   * @param name The name of the section to retrieve
+   * @returns The config section
+   * @throws Error if section not found
+   */
+  require<T extends ConfigSection>(name: string): T {
+    const section = this.get<T>(name);
+    if (!section) {
+      throw new Error(`Required configuration section '${name}' not found`);
+    }
+    return section;
+  }
+
+  /**
+   * Check if a configuration section is registered
+   * @param name The name of the section to check
+   */
+  has(name: string): boolean {
+    return this.sections.has(name);
+  }
+
+  /**
+   * Remove a configuration section
+   * @param name The name of the section to remove
+   */
+  unregister(name: string): boolean {
+    const result = this.sections.delete(name);
+    if (result) {
+      this._validated = false;
+    }
+    return result;
+  }
+
+  /**
+   * Get all registered section names
+   */
+  getSectionNames(): string[] {
+    return Array.from(this.sections.keys());
+  }
+
+  /**
+   * Validate all registered configuration sections
+   * @returns ValidationResult with any errors found
+   */
+  validate(): ValidationResult {
+    const errors: ValidationError[] = [];
+
+    for (const [name, section] of this.sections) {
+      const sectionErrors = section.validate();
+      // Add section name context to errors
+      for (const error of sectionErrors) {
+        errors.push(
+          new ValidationError(`[${name}] ${error.message}`),
+        );
+      }
+    }
+
+    this._validated = errors.length === 0;
+    return new ValidationResult(
+      errors.length === 0,
+      errors.map((e) => e.message),
+    );
+  }
+
+  /**
+   * Check if configuration has been validated successfully
+   */
+  get isValidated(): boolean {
+    return this._validated;
+  }
+
+  /**
+   * Initialize the configuration (validate and throw if invalid)
+   * @throws Error if validation fails
+   */
+  initialize(): void {
+    const result = this.validate();
+    if (!result.isValid) {
+      throw new Error(
+        `Configuration validation failed:\n${result.errors.join("\n")}`,
+      );
+    }
+  }
+
+  /**
+   * Convert all sections to a plain object for serialization/debugging
+   */
+  toMap(): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (const [name, section] of this.sections) {
+      result[name] = section.toMap();
+    }
+    return result;
+  }
+
+  /**
+   * Clear all registered sections
+   */
+  clear(): void {
+    this.sections.clear();
+    this._validated = false;
+  }
+
+  /**
+   * Create a ConfigRegistry from environment variables with auto-detection.
+   * Detects which configs to load based on presence of marker env vars.
+   *
+   * @example
+   * ```typescript
+   * // Auto-detect and load configs based on environment
+   * const config = ConfigRegistry.fromEnvironment({
+   *   database: () => Deno.env.get("DATABASE_HOST") ? new DatabaseConfig() : undefined,
+   *   cache: () => Deno.env.get("REDIS_HOST") ? new RedisConfig() : undefined,
+   *   logging: () => new LoggingConfig(), // Always include
+   * });
+   * ```
+   */
+  static fromEnvironment(
+    detectors: Record<string, () => ConfigSection | undefined>,
+  ): ConfigRegistry {
+    const registry = new ConfigRegistry();
+
+    for (const [name, detector] of Object.entries(detectors)) {
+      const section = detector();
+      if (section) {
+        registry.register(name, section);
+      }
+    }
+
+    return registry;
+  }
+}

package/src/common/config/config-section.ts

@@ -0,0 +1,106 @@
+import type { ValidationError } from "../validation/validators.ts";
+import { getEnv, getEnvOrDefault } from "../platform/env.ts";
+
+/**
+ * Base interface for configuration sections.
+ * Each section is responsible for:
+ * - Loading its values from environment variables
+ * - Validating its configuration
+ * - Providing a serializable representation
+ */
+export interface ConfigSection {
+  /**
+   * Validate this configuration section
+   * @returns Array of validation errors, empty if valid
+   */
+  validate(): ValidationError[];
+
+  /**
+   * Convert to a plain object for serialization/debugging
+   */
+  toMap(): Record<string, unknown>;
+}
+
+/**
+ * Base class providing common functionality for config sections
+ */
+export abstract class BaseConfigSection implements ConfigSection {
+  abstract validate(): ValidationError[];
+  abstract toMap(): Record<string, unknown>;
+
+  /**
+   * Helper to get required environment variable
+   */
+  protected getRequiredEnv(key: string): string {
+    const value = getEnv(key);
+    if (!value) {
+      throw new Error(`Required environment variable ${key} is not set`);
+    }
+    return value;
+  }
+
+  /**
+   * Helper to get optional environment variable with default
+   */
+  protected getEnvString(key: string, defaultValue: string): string {
+    return getEnvOrDefault(key, defaultValue);
+  }
+
+  /**
+   * Helper to parse integer from environment variable
+   */
+  protected getEnvInt(key: string, defaultValue: number): number {
+    const value = getEnv(key);
+    if (!value) return defaultValue;
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? defaultValue : parsed;
+  }
+
+  /**
+   * Helper to parse boolean from environment variable
+   */
+  protected getEnvBool(key: string, defaultValue: boolean): boolean {
+    const value = getEnv(key);
+    if (!value) return defaultValue;
+    return value.toLowerCase() === "true" || value === "1";
+  }
+
+  /**
+   * Helper to parse duration from environment variable
+   * Supports: 30s, 5m, 2h, 1d
+   */
+  protected getEnvDuration(key: string, defaultValue: number): number {
+    const value = getEnv(key);
+    if (!value) return defaultValue;
+
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(value.toLowerCase());
+    if (!match) return defaultValue;
+
+    const amount = parseInt(match[1]!, 10);
+    const unit = match[2];
+
+    switch (unit) {
+      case "ms":
+        return amount;
+      case "s":
+        return amount * 1000;
+      case "m":
+        return amount * 60 * 1000;
+      case "h":
+        return amount * 60 * 60 * 1000;
+      case "d":
+        return amount * 24 * 60 * 60 * 1000;
+      default:
+        return defaultValue;
+    }
+  }
+
+  /**
+   * Helper to parse comma-separated list from environment variable
+   */
+  protected getEnvList(key: string, defaultValue: string[] = []): string[] {
+    const value = getEnv(key);
+    if (!value) return defaultValue;
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }
+}

package/src/common/exception/authorization-exception.ts

@@ -0,0 +1,28 @@
+import type { Metadata } from "../type/metadata.type.ts";
+
+export class AuthorizationException extends Error {
+  public readonly details: Metadata;
+
+  constructor(message: string, details: Metadata = {}) {
+    super(message);
+    this.name = "AuthorizationException";
+    this.details = details;
+  }
+
+  static insufficientPermissions(options: {
+    actorId: string;
+    resource: string;
+    action: string;
+    missingPermissions: string[];
+  }): AuthorizationException {
+    return new AuthorizationException(
+      `Actor ${options.actorId} lacks required permissions for ${options.action} on ${options.resource}`,
+      {
+        actorId: options.actorId,
+        resource: options.resource,
+        action: options.action,
+        missingPermissions: options.missingPermissions,
+      },
+    );
+  }
+}

package/src/common/exception/repository-exception.ts

@@ -0,0 +1,46 @@
+export abstract class RepositoryException extends Error {
+  constructor(message: string, override readonly cause?: Error) {
+    super(message);
+    this.name = "RepositoryException";
+  }
+}
+
+export class NetworkException extends RepositoryException {
+  constructor(
+    message: string,
+    public readonly statusCode?: number,
+    public readonly responseBody?: string,
+    cause?: Error,
+  ) {
+    super(message, cause);
+    this.name = "NetworkException";
+  }
+}
+
+export class ValidationException extends RepositoryException {
+  constructor(message: string, cause?: Error) {
+    super(message, cause);
+    this.name = "ValidationException";
+  }
+}
+
+export class EntityNotFoundException extends RepositoryException {
+  constructor(message: string, cause?: Error) {
+    super(message, cause);
+    this.name = "EntityNotFoundException";
+  }
+}
+
+export class EntityAlreadyExistsException extends RepositoryException {
+  constructor(message: string, cause?: Error) {
+    super(message, cause);
+    this.name = "EntityAlreadyExistsException";
+  }
+}
+
+export class DatabaseException extends RepositoryException {
+  constructor(message: string, cause?: Error) {
+    super(message, cause);
+    this.name = "DatabaseException";
+  }
+}