@kuckit/domain 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+//#region src/entities/user.d.ts
+/**
+ * User domain entity
+ * Pure TypeScript type with no dependencies
+ */
+interface User {
+  readonly id: string;
+  readonly name: string;
+  readonly email: string;
+  readonly emailVerified: boolean;
+  readonly permissions: readonly string[];
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+//#endregion
+//#region src/ports/user-repository.d.ts
+/**
+ * Repository port (interface) for user persistence
+ * Infrastructure layer will implement this
+ */
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  save(user: User): Promise<void>;
+}
+//#endregion
+//#region src/ports/clock.d.ts
+/**
+ * Clock port for time-related operations
+ * Enables testing with fixed time
+ */
+interface Clock {
+  now(): Date;
+}
+declare class SystemClock implements Clock {
+  now(): Date;
+}
+//#endregion
+//#region src/ports/logger.d.ts
+/**
+ * Logger port - structured logging for Loki/Prometheus
+ * Loki-compatible: labels and structured fields in meta
+ */
+interface Logger {
+  debug: (message: string, meta?: LogContext) => void;
+  info: (message: string, meta?: LogContext) => void;
+  warn: (message: string, meta?: LogContext) => void;
+  error: (message: string, meta?: LogContext | Error) => void;
+}
+/**
+ * Structured log context (Loki labels)
+ */
+interface LogContext {
+  requestId?: string;
+  userId?: string;
+  feature?: string;
+  [key: string]: any;
+}
+//#endregion
+//#region src/ports/event-publisher.d.ts
+/**
+ * Event publisher port
+ * Used by use cases to publish domain events
+ *
+ * Note: This is a simplified interface for use case dependencies.
+ * The actual EventBus in infrastructure is more feature-rich.
+ */
+interface EventPublisher {
+  /**
+   * Publish a domain event
+   * @param eventName Event name (e.g., 'user.created')
+   * @param payload Event payload data
+   * @param aggregateId The aggregate ID (e.g., userId)
+   */
+  publish(eventName: string, payload: Record<string, any>, aggregateId: string): Promise<void>;
+  /**
+   * Subscribe to events (for event handlers in infrastructure)
+   * @param eventName The event name to listen for
+   * @param handler The handler function
+   * @returns Unsubscribe function
+   */
+  subscribe(eventName: string, handler: (payload: Record<string, any>) => Promise<void> | void): () => void;
+}
+//#endregion
+//#region src/ports/cache.d.ts
+/**
+ * Cache store port interface
+ * Defines contract for caching implementations
+ */
+interface CacheStore {
+  /**
+   * Get a value from cache
+   * @param key Cache key
+   * @returns Cached value or undefined if not found or expired
+   */
+  get<T>(key: string): Promise<T | undefined>;
+  /**
+   * Set a value in cache
+   * @param key Cache key
+   * @param value Value to cache
+   * @param ttlMs Time to live in milliseconds (undefined = no expiration)
+   */
+  set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+  /**
+   * Delete a value from cache
+   * @param key Cache key
+   */
+  del(key: string): Promise<void>;
+  /**
+   * Clear all values from cache
+   */
+  clear(): Promise<void>;
+  /**
+   * Check if a key exists in cache
+   * @param key Cache key
+   */
+  has(key: string): Promise<boolean>;
+}
+//#endregion
+//#region src/ports/rate-limiter.d.ts
+/**
+ * Rate limiter store port interface
+ * Uses token bucket algorithm for rate limiting
+ */
+interface RateLimiterStore {
+  /**
+   * Check if a request should be allowed
+   * @param key Rate limit key (per-user, per-IP, etc)
+   * @param capacity Bucket capacity (max tokens)
+   * @param refillPerSecond Number of tokens to refill per second
+   * @returns Object with allowed flag and reset time if rate limited
+   */
+  checkLimit(key: string, capacity: number, refillPerSecond: number): Promise<{
+    allowed: boolean;
+    tokensRemaining: number;
+    resetAt: Date;
+  }>;
+  /**
+   * Reset rate limit for a key
+   * @param key Rate limit key
+   */
+  reset(key: string): Promise<void>;
+  /**
+   * Clear all rate limit data
+   */
+  clear(): Promise<void>;
+}
+//#endregion
+//#region src/errors/index.d.ts
+/**
+ * Application error codes (domain-level)
+ */
+declare enum ErrorCode {
+  USER_NOT_FOUND = "USER_NOT_FOUND",
+  USER_ALREADY_EXISTS = "USER_ALREADY_EXISTS",
+  INVALID_EMAIL = "INVALID_EMAIL",
+  UNAUTHORIZED = "UNAUTHORIZED",
+  FORBIDDEN = "FORBIDDEN",
+  SESSION_EXPIRED = "SESSION_EXPIRED",
+  INVALID_INPUT = "INVALID_INPUT",
+  VALIDATION_ERROR = "VALIDATION_ERROR",
+  RATE_LIMITED = "RATE_LIMITED",
+  NOT_FOUND = "NOT_FOUND",
+  CONFLICT = "CONFLICT",
+  INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR",
+}
+/**
+ * Severity levels for error classification
+ */
+declare enum ErrorSeverity {
+  LOW = "LOW",
+  // Client error, expected
+  MEDIUM = "MEDIUM",
+  // Unexpected but recoverable
+  HIGH = "HIGH",
+  // System error, requires attention
+  CRITICAL = "CRITICAL",
+}
+/**
+ * Application error base class
+ */
+declare class AppError extends Error {
+  readonly code: ErrorCode;
+  readonly severity: ErrorSeverity;
+  readonly statusCode: number;
+  readonly meta: Record<string, any>;
+  constructor(code: ErrorCode, message: string, options?: {
+    statusCode?: number;
+    severity?: ErrorSeverity;
+    meta?: Record<string, any>;
+  });
+  toJSON(): {
+    name: string;
+    code: ErrorCode;
+    message: string;
+    severity: ErrorSeverity;
+    statusCode: number;
+    meta: Record<string, any>;
+  };
+}
+/**
+ * Helper functions to create specific errors
+ */
+declare const notFound: (resource: string, meta?: Record<string, any>) => AppError;
+declare const unauthorized: (reason: string, meta?: Record<string, any>) => AppError;
+declare const forbidden: (reason: string, meta?: Record<string, any>) => AppError;
+declare const validationError: (message: string, meta?: Record<string, any>) => AppError;
+declare const conflict: (message: string, meta?: Record<string, any>) => AppError;
+declare const internalError: (message: string, meta?: Record<string, any>) => AppError;
+//#endregion
+//#region src/events/types.d.ts
+/**
+ * Event-driven architecture types
+ *
+ * Event names follow 'module.action' pattern: 'user.created', 'user.updated'
+ * All events are strongly typed through EventMap
+ */
+/**
+ * Event metadata included with every domain event
+ */
+interface EventMeta {
+  /** Unique identifier for this event */
+  readonly eventId: string;
+  /** Timestamp when event occurred */
+  readonly occurredAt: Date;
+  /** Event schema version for migrations */
+  readonly version: number;
+  /** Aggregate ID (e.g., userId for user events) */
+  readonly aggregateId: string;
+  /** Correlation ID for tracing across services */
+  readonly correlationId: string;
+}
+/**
+ * Base domain event type
+ * All domain events extend this interface
+ */
+interface DomainEvent<TName extends string = string, TPayload extends Record<string, any> = Record<string, any>> {
+  /** Event name in 'module.action' format */
+  readonly name: TName;
+  /** Event payload (action-specific data) */
+  readonly payload: TPayload;
+  /** Event metadata (standard for all events) */
+  readonly meta: EventMeta;
+}
+/**
+ * Event map definition - extend this to add typed events
+ * Maps event names to their payload types
+ *
+ * Example:
+ * interface EventMap {
+ *   'user.created': { userId: string; email: string }
+ *   'user.updated': { userId: string; name: string }
+ * }
+ */
+interface EventMap {
+  [key: string]: Record<string, any>;
+}
+/**
+ * Valid event names derived from EventMap
+ */
+type EventName = keyof EventMap & string;
+/**
+ * Typed domain event for a specific event name
+ */
+type TypedDomainEvent<TName extends EventName = EventName> = DomainEvent<TName, EventMap[TName]>;
+//#endregion
+//#region src/events/event-bus.d.ts
+/**
+ * Event handler function
+ * Handles a specific event type
+ * Should not throw; errors are caught and logged
+ */
+type EventHandler<TName extends EventName = EventName> = (event: TypedDomainEvent<TName>) => void | Promise<void>;
+/**
+ * Event bus interface
+ * Handles publishing domain events and managing subscriptions
+ */
+interface EventBus {
+  /**
+   * Publish event synchronously
+   * Awaits all handlers to complete before returning
+   * Errors in handlers are caught and logged, don't block others
+   *
+   * @param event The domain event to publish
+   */
+  publish<TName extends EventName>(event: TypedDomainEvent<TName>): Promise<void>;
+  /**
+   * Publish event asynchronously
+   * Uses queueMicrotask to defer execution, returns immediately
+   * Errors in handlers are caught and logged
+   *
+   * @param event The domain event to publish
+   */
+  publishAsync<TName extends EventName>(event: TypedDomainEvent<TName>): void;
+  /**
+   * Subscribe to specific event type
+   * Returns unsubscribe function to remove handler
+   *
+   * @param eventName Event name to subscribe to (e.g., 'user.created')
+   * @param handler Event handler function
+   * @returns Unsubscribe function
+   */
+  subscribe<TName extends EventName>(eventName: TName, handler: EventHandler<TName>): () => void;
+  /**
+   * Subscribe to all events
+   *
+   * @param handler Event handler function
+   * @returns Unsubscribe function
+   */
+  subscribeAll(handler: EventHandler): () => void;
+}
+//#endregion
+export { AppError, CacheStore, Clock, DomainEvent, ErrorCode, ErrorSeverity, EventBus, EventHandler, EventMap, EventMeta, EventName, EventPublisher, LogContext, Logger, RateLimiterStore, SystemClock, TypedDomainEvent, User, UserRepository, conflict, forbidden, internalError, notFound, unauthorized, validationError };

package/dist/index.js

@@ -0,0 +1,101 @@
+//#region src/ports/clock.ts
+var SystemClock = class {
+	now() {
+		return /* @__PURE__ */ new Date();
+	}
+};
+
+//#endregion
+//#region src/errors/index.ts
+/**
+* Application error codes (domain-level)
+*/
+let ErrorCode = /* @__PURE__ */ function(ErrorCode$1) {
+	ErrorCode$1["USER_NOT_FOUND"] = "USER_NOT_FOUND";
+	ErrorCode$1["USER_ALREADY_EXISTS"] = "USER_ALREADY_EXISTS";
+	ErrorCode$1["INVALID_EMAIL"] = "INVALID_EMAIL";
+	ErrorCode$1["UNAUTHORIZED"] = "UNAUTHORIZED";
+	ErrorCode$1["FORBIDDEN"] = "FORBIDDEN";
+	ErrorCode$1["SESSION_EXPIRED"] = "SESSION_EXPIRED";
+	ErrorCode$1["INVALID_INPUT"] = "INVALID_INPUT";
+	ErrorCode$1["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+	ErrorCode$1["RATE_LIMITED"] = "RATE_LIMITED";
+	ErrorCode$1["NOT_FOUND"] = "NOT_FOUND";
+	ErrorCode$1["CONFLICT"] = "CONFLICT";
+	ErrorCode$1["INTERNAL_SERVER_ERROR"] = "INTERNAL_SERVER_ERROR";
+	return ErrorCode$1;
+}({});
+/**
+* Severity levels for error classification
+*/
+let ErrorSeverity = /* @__PURE__ */ function(ErrorSeverity$1) {
+	ErrorSeverity$1["LOW"] = "LOW";
+	ErrorSeverity$1["MEDIUM"] = "MEDIUM";
+	ErrorSeverity$1["HIGH"] = "HIGH";
+	ErrorSeverity$1["CRITICAL"] = "CRITICAL";
+	return ErrorSeverity$1;
+}({});
+/**
+* Application error base class
+*/
+var AppError = class AppError extends Error {
+	code;
+	severity;
+	statusCode;
+	meta;
+	constructor(code, message, options = {}) {
+		super(message);
+		this.name = "AppError";
+		this.code = code;
+		this.severity = options.severity || ErrorSeverity.MEDIUM;
+		this.statusCode = options.statusCode || 500;
+		this.meta = options.meta || {};
+		Object.setPrototypeOf(this, AppError.prototype);
+	}
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			severity: this.severity,
+			statusCode: this.statusCode,
+			meta: this.meta
+		};
+	}
+};
+/**
+* Helper functions to create specific errors
+*/
+const notFound = (resource, meta) => new AppError(ErrorCode.NOT_FOUND, `${resource} not found`, {
+	statusCode: 404,
+	severity: ErrorSeverity.LOW,
+	meta
+});
+const unauthorized = (reason, meta) => new AppError(ErrorCode.UNAUTHORIZED, reason, {
+	statusCode: 401,
+	severity: ErrorSeverity.LOW,
+	meta
+});
+const forbidden = (reason, meta) => new AppError(ErrorCode.FORBIDDEN, reason, {
+	statusCode: 403,
+	severity: ErrorSeverity.LOW,
+	meta
+});
+const validationError = (message, meta) => new AppError(ErrorCode.VALIDATION_ERROR, message, {
+	statusCode: 400,
+	severity: ErrorSeverity.LOW,
+	meta
+});
+const conflict = (message, meta) => new AppError(ErrorCode.CONFLICT, message, {
+	statusCode: 409,
+	severity: ErrorSeverity.LOW,
+	meta
+});
+const internalError = (message, meta) => new AppError(ErrorCode.INTERNAL_SERVER_ERROR, message, {
+	statusCode: 500,
+	severity: ErrorSeverity.HIGH,
+	meta
+});
+
+//#endregion
+export { AppError, ErrorCode, ErrorSeverity, SystemClock, conflict, forbidden, internalError, notFound, unauthorized, validationError };

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@kuckit/domain",
+	"version": "1.0.0",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./src/*.ts",
+			"default": "./src/*.ts"
+		}
+	},
+	"publishConfig": {
+		"main": "dist/index.js",
+		"types": "dist/index.d.ts",
+		"exports": {
+			".": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			},
+			"./*": {
+				"types": "./dist/*.d.ts",
+				"default": "./dist/*.js"
+			}
+		}
+	},
+	"scripts": {
+		"build": "tsdown"
+	},
+	"devDependencies": {
+		"tsdown": "catalog:"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './entities'
+export * from './ports'
+export * from './errors'
+export * from './events'