@emkodev/emkore 1.0.3

package/src/common/pattern/unit-of-work.ts

@@ -0,0 +1,78 @@
+/**
+ * Unit of Work Pattern
+ *
+ * Maintains a list of objects affected by a business transaction and coordinates
+ * writing out changes and resolving concurrency problems.
+ *
+ * This interface provides the minimal contract for transaction boundaries.
+ * Implementations can extend this with additional tracking capabilities:
+ *
+ * - Change tracking: registerNew(), registerDirty(), registerDeleted()
+ * - Identity map: registerClean() to prevent loading duplicates
+ * - Batching: Accumulate changes and apply them in a single operation
+ * - Optimistic locking: Track versions for concurrent modifications
+ *
+ * Examples of implementations:
+ * - SQL: Use database transactions (BEGIN/COMMIT/ROLLBACK)
+ * - REST APIs: Batch requests or implement compensating transactions
+ * - Document DBs: Use sessions or batch operations
+ * - Event Sourcing: Collect events and append to stream on commit
+ * - In-Memory: Track changes in collections, restore on rollback
+ *
+ * @see https://martinfowler.com/eaaCatalog/unitOfWork.html
+ */
+export interface UnitOfWork {
+  readonly tenantId: string;
+
+  /**
+   * Commits all changes made within this unit of work.
+   * Should be atomic - either all changes succeed or none do.
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Discards all changes made within this unit of work.
+   * Should restore state to before the unit of work began.
+   */
+  rollback(): Promise<void>;
+
+  // Optional methods that implementations might want to add:
+
+  /**
+   * Track a newly created entity for insertion
+   */
+  registerNew?(entity: unknown): void;
+
+  /**
+   * Track a modified entity for update
+   */
+  registerDirty?(entity: unknown): void;
+
+  /**
+   * Track an entity for deletion
+   */
+  registerDeleted?(entity: unknown): void;
+
+  /**
+   * Track a clean (unmodified) entity to prevent duplicate loads
+   */
+  registerClean?(entity: unknown): void;
+
+  /**
+   * Check if the unit of work has any pending changes
+   */
+  hasChanges?(): boolean;
+
+  /**
+   * Get a repository that participates in this unit of work
+   * @param type - Repository class constructor or identifier
+   */
+  getRepository?<T = unknown>(type: unknown): T;
+}
+
+export interface UnitOfWorkFactory {
+  transaction<T>(
+    tenantId: string,
+    body: (uow: UnitOfWork) => Promise<T>,
+  ): Promise<T>;
+}

package/src/common/platform/env.ts

@@ -0,0 +1,38 @@
+/**
+ * Cross-platform environment variable access
+ * Works in Deno, Node.js, and browsers (with fallbacks)
+ */
+
+// Type-safe access to global objects for cross-platform compatibility
+declare const Deno: { env: { get(key: string): string | undefined } } | undefined;
+declare const process: { env: Record<string, string | undefined> } | undefined;
+
+/**
+ * Get environment variable value
+ * @param key Environment variable name
+ * @returns Value or undefined if not found
+ */
+export function getEnv(key: string): string | undefined {
+  // Deno
+  if (typeof Deno !== "undefined" && Deno.env?.get) {
+    return Deno.env.get(key);
+  }
+
+  // Node.js
+  if (typeof process !== "undefined" && process?.env) {
+    return process.env[key];
+  }
+
+  // Browser/Worker fallback - no environment variables
+  return undefined;
+}
+
+/**
+ * Get environment variable with default value
+ * @param key Environment variable name
+ * @param defaultValue Default value if not found
+ * @returns Value or default
+ */
+export function getEnvOrDefault(key: string, defaultValue: string): string {
+  return getEnv(key) ?? defaultValue;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Use Case Registry System
+ *
+ * Provides types and utilities for auto-discovery and registration
+ * of use cases in dynamic routing systems.
+ */
+
+import type { UnitOfWorkFactory } from "../pattern/unit-of-work.ts";
+import type { Usecase } from "../abstract.usecase.ts";
+import type { Permission } from "../type/permission.type.ts";
+import type { ApiDefinition } from "../llm/api-definition.type.ts";
+
+export interface UseCaseRegistryEntry<
+  TInput = unknown,
+  TOutput = unknown,
+  TUowFactory extends UnitOfWorkFactory = UnitOfWorkFactory,
+> {
+  action: string;
+  resource: string;
+  createInteractor: () => Promise<Usecase<TInput, TOutput>>;
+  createUowFactory: () => Promise<TUowFactory>;
+  requiredPermissions: Permission[];
+  apiDefinition?: ApiDefinition;
+}
+
+export class UseCaseRegistryHelpers {
+  /**
+   * Get the name for a registry entry
+   */
+  static getName(entry: UseCaseRegistryEntry): string {
+    return `${entry.action}_${entry.resource}`;
+  }
+
+  /**
+   * Get the HTTP method for a registry entry
+   */
+  static getHttpMethod(
+    entry: UseCaseRegistryEntry,
+  ): "GET" | "POST" | "PUT" | "PATCH" | "DELETE" {
+    switch (entry.action) {
+      case "create":
+        return "POST";
+      case "retrieve":
+      case "list":
+      case "count":
+        return "GET";
+      case "update":
+        return "PATCH";
+      case "delete":
+      case "bulkDelete":
+        return "DELETE";
+      default:
+        return "POST";
+    }
+  }
+
+  /**
+   * Get the API path for a registry entry
+   */
+  static getPath(entry: UseCaseRegistryEntry): string {
+    const basePath = `/api/v1/${entry.resource}`;
+
+    switch (entry.action) {
+      case "create":
+        return basePath;
+      case "retrieve":
+      case "update":
+      case "delete":
+        return `${basePath}/:id`;
+      case "list":
+        return basePath;
+      case "count":
+        return `${basePath}/count`;
+      case "bulkDelete":
+        return `${basePath}/bulk`;
+      default:
+        return `${basePath}/${entry.action}`;
+    }
+  }
+}

package/src/common/type/interceptor-context.type.ts

@@ -0,0 +1,25 @@
+import type { Actor } from "../abstract.actor.ts";
+import type { UsecaseName } from "../abstract.usecase.ts";
+import type { Permission } from "./permission.type.ts";
+import type { Metadata } from "./metadata.type.ts";
+
+export interface InterceptorContext {
+  readonly actor: Actor;
+  readonly usecaseName: UsecaseName;
+  readonly requiredPermissions: Permission[];
+  readonly metadata: Metadata;
+}
+
+export function createInterceptorContext(
+  actor: Actor,
+  usecaseName: UsecaseName,
+  requiredPermissions: Permission[],
+  metadata: Metadata = {},
+): InterceptorContext {
+  return {
+    actor,
+    usecaseName,
+    requiredPermissions,
+    metadata,
+  };
+}

package/src/common/type/json-schema.type.ts

@@ -0,0 +1,80 @@
+/**
+ * JSON Schema types for validation and API definitions.
+ * Based on JSON Schema Draft-07 specification.
+ */
+
+export type JsonSchemaType =
+  | "string"
+  | "number"
+  | "boolean"
+  | "object"
+  | "array"
+  | "null"
+  | "integer";
+
+export interface JsonSchema {
+  readonly type?: JsonSchemaType | JsonSchemaType[];
+  readonly properties?: Record<string, JsonSchema>;
+  readonly items?: JsonSchema;
+  readonly required?: string[];
+  readonly enum?: readonly unknown[];
+  readonly const?: unknown;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly format?: string;
+  readonly description?: string;
+  readonly default?: unknown;
+  readonly nullable?: boolean;
+  readonly anyOf?: JsonSchema[];
+  readonly allOf?: JsonSchema[];
+  readonly oneOf?: JsonSchema[];
+  readonly not?: JsonSchema;
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly uniqueItems?: boolean;
+  readonly minProperties?: number;
+  readonly maxProperties?: number;
+  readonly multipleOf?: number;
+  readonly exclusiveMinimum?: boolean | number;
+  readonly exclusiveMaximum?: boolean | number;
+}
+
+export type JsonSchemaProperties = Record<string, JsonSchema>;
+
+/**
+ * Mutable version of JsonSchema for building schemas dynamically.
+ */
+export interface MutableJsonSchema {
+  type?: JsonSchemaType | JsonSchemaType[];
+  properties?: Record<string, MutableJsonSchema>;
+  items?: MutableJsonSchema | JsonSchema;
+  required?: string[] | boolean;
+  enum?: unknown[];
+  const?: unknown;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  description?: string;
+  default?: unknown;
+  nullable?: boolean;
+  anyOf?: JsonSchema[];
+  allOf?: JsonSchema[];
+  oneOf?: JsonSchema[];
+  not?: JsonSchema;
+  additionalProperties?: boolean | JsonSchema;
+  minItems?: number;
+  maxItems?: number;
+  uniqueItems?: boolean;
+  minProperties?: number;
+  maxProperties?: number;
+  multipleOf?: number;
+  exclusiveMinimum?: boolean | number;
+  exclusiveMaximum?: boolean | number;
+}

package/src/common/type/json.type.ts

@@ -0,0 +1,5 @@
+export type JSONValue = string | number | boolean | null | JSON | JSONArray;
+export interface JSON {
+  [key: string]: JSONValue;
+}
+export interface JSONArray extends Array<JSONValue> {}

package/src/common/type/lowercase.type.ts

@@ -0,0 +1,48 @@
+/**
+ * Type-level utility to enforce lowercase string literals in const arrays.
+ *
+ * This prevents developers from accidentally using uppercase enum values,
+ * ensuring consistency with kebab-case naming conventions.
+ *
+ * @example
+ * ```typescript
+ * // ✅ CORRECT - lowercase values
+ * const USER_STATUS = ["new", "requires-review"] as const satisfies LowercaseArray;
+ *
+ * // ❌ COMPILE ERROR - uppercase detected
+ * const USER_STATUS = ["NEW", "REQUIRES_REVIEW"] as const satisfies LowercaseArray;
+ *
+ * // ✅ CORRECT - with type extraction
+ * const USER_STATUS = ["new", "active", "archived"] as const satisfies LowercaseArray;
+ * type UserStatus = typeof USER_STATUS[number]; // "new" | "active" | "archived"
+ * ```
+ */
+
+/**
+ * Ensures a string type contains only lowercase characters, numbers, and hyphens.
+ * Produces a compile-time error if uppercase letters are detected.
+ */
+export type Lowercase<T extends string> = T extends
+  `${infer First}${infer Rest}`
+  ? First extends Uppercase<First>
+    ? First extends Lowercase<First> ? `${First}${Lowercase<Rest>}` // Numbers, hyphens, special chars
+    : never // Uppercase letter detected - ERROR
+  : `${First}${Lowercase<Rest>}` // Lowercase letter - OK
+  : T; // Empty string or base case
+
+/**
+ * Enforces that all elements in a readonly array are lowercase strings.
+ * Use with `satisfies` keyword for compile-time validation.
+ */
+export type LowercaseArray = readonly Lowercase<string>[];
+
+/**
+ * Helper type to validate and extract union type from a lowercase const array.
+ *
+ * @example
+ * ```typescript
+ * const STATUSES = ["new", "in-progress", "done"] as const satisfies LowercaseArray;
+ * type Status = LowercaseArrayUnion<typeof STATUSES>; // "new" | "in-progress" | "done"
+ * ```
+ */
+export type LowercaseArrayUnion<T extends LowercaseArray> = T[number];

package/src/common/type/metadata.type.ts

@@ -0,0 +1,5 @@
+/**
+ * Metadata type for storing additional context information.
+ * Allows any JSON-serializable values including primitives and arrays.
+ */
+export type Metadata = Record<string, unknown>;