@cosmneo/onion-lasagna 0.1.0

package/dist/validation-error.type-kD4_qNZ9.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Centralized registry of all error codes used across the application.
+ *
+ * Error codes are grouped by architectural layer to maintain clear boundaries
+ * and make it easy to identify where an error originated.
+ *
+ * @example Using error codes in custom errors
+ * ```typescript
+ * import { ErrorCodes } from '@cosmneo/onion-lasagna/backend/core/global';
+ *
+ * throw new NotFoundError({
+ *   message: 'User not found',
+ *   code: ErrorCodes.App.NOT_FOUND,
+ * });
+ * ```
+ *
+ * @example Checking error codes programmatically
+ * ```typescript
+ * if (error.code === ErrorCodes.App.NOT_FOUND) {
+ *   // Handle not found case
+ * }
+ * ```
+ */
+declare const ErrorCodes: {
+    /**
+     * Domain layer error codes.
+     * Used for business rule violations and invariant failures.
+     */
+    readonly Domain: {
+        /** Generic domain error */
+        readonly DOMAIN_ERROR: "DOMAIN_ERROR";
+        /** Business invariant was violated */
+        readonly INVARIANT_VIOLATION: "INVARIANT_VIOLATION";
+        /** Aggregate was partially loaded (missing required relations) */
+        readonly PARTIAL_LOAD: "PARTIAL_LOAD";
+    };
+    /**
+     * Application layer (use case) error codes.
+     * Used for orchestration failures and business operation errors.
+     */
+    readonly App: {
+        /** Generic use case error */
+        readonly USE_CASE_ERROR: "USE_CASE_ERROR";
+        /** Requested resource was not found */
+        readonly NOT_FOUND: "NOT_FOUND";
+        /** Resource state conflict (e.g., duplicate, already exists) */
+        readonly CONFLICT: "CONFLICT";
+        /** Request is valid but cannot be processed due to business rules */
+        readonly UNPROCESSABLE: "UNPROCESSABLE";
+    };
+    /**
+     * Infrastructure layer error codes.
+     * Used for data access, external services, and I/O failures.
+     */
+    readonly Infra: {
+        /** Generic infrastructure error */
+        readonly INFRA_ERROR: "INFRA_ERROR";
+        /** Database operation failed */
+        readonly DB_ERROR: "DB_ERROR";
+        /** Network connectivity or communication error */
+        readonly NETWORK_ERROR: "NETWORK_ERROR";
+        /** Operation timed out */
+        readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+        /** External/third-party service error */
+        readonly EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR";
+    };
+    /**
+     * Presentation layer error codes.
+     * Used for controller, request handling, and authorization errors.
+     */
+    readonly Presentation: {
+        /** Generic controller error */
+        readonly CONTROLLER_ERROR: "CONTROLLER_ERROR";
+        /** Request denied due to authorization failure */
+        readonly ACCESS_DENIED: "ACCESS_DENIED";
+        /** Request validation failed (malformed input) */
+        readonly INVALID_REQUEST: "INVALID_REQUEST";
+    };
+    /**
+     * Global/cross-cutting error codes.
+     * Used for validation and other cross-layer concerns.
+     */
+    readonly Global: {
+        /** Object/schema validation failed */
+        readonly OBJECT_VALIDATION_ERROR: "OBJECT_VALIDATION_ERROR";
+    };
+};
+/**
+ * Type representing all possible domain error codes.
+ */
+type DomainErrorCode = (typeof ErrorCodes.Domain)[keyof typeof ErrorCodes.Domain];
+/**
+ * Type representing all possible application error codes.
+ */
+type AppErrorCode = (typeof ErrorCodes.App)[keyof typeof ErrorCodes.App];
+/**
+ * Type representing all possible infrastructure error codes.
+ */
+type InfraErrorCode = (typeof ErrorCodes.Infra)[keyof typeof ErrorCodes.Infra];
+/**
+ * Type representing all possible presentation error codes.
+ */
+type PresentationErrorCode = (typeof ErrorCodes.Presentation)[keyof typeof ErrorCodes.Presentation];
+/**
+ * Type representing all possible global error codes.
+ */
+type GlobalErrorCode = (typeof ErrorCodes.Global)[keyof typeof ErrorCodes.Global];
+/**
+ * Union type of all error codes across all layers.
+ *
+ * Use this when you need to accept any valid error code.
+ *
+ * @example
+ * ```typescript
+ * function logError(code: ErrorCode, message: string) {
+ *   console.error(`[${code}] ${message}`);
+ * }
+ * ```
+ */
+type ErrorCode = DomainErrorCode | AppErrorCode | InfraErrorCode | PresentationErrorCode | GlobalErrorCode;
+
+/**
+ * Base error class for all application errors with a machine-readable code.
+ *
+ * Abstract class that extends the native `Error` with:
+ * - A `code` property for programmatic error handling
+ * - Optional `cause` for error chaining (ES2022 compatible)
+ * - A `fromError` static factory pattern for error transformation
+ *
+ * **Why abstract:** Prevents non-declarative error usage. All errors must
+ * be explicitly defined as subclasses to ensure consistent error taxonomy.
+ *
+ * @example Subclass implementation
+ * ```typescript
+ * class DbError extends InfraError {
+ *   static override fromError(cause: unknown): DbError {
+ *     return new DbError({
+ *       message: cause instanceof Error ? cause.message : 'Database error',
+ *       cause,
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Usage with wrapErrorAsync
+ * ```typescript
+ * await wrapErrorAsync(
+ *   () => this.db.query(...),
+ *   DbError.fromError,
+ * );
+ * ```
+ */
+declare abstract class CodedError extends Error {
+    /** Machine-readable error code for programmatic handling. */
+    readonly code: ErrorCode | string;
+    /**
+     * Creates a new CodedError instance.
+     *
+     * @param options - Error configuration
+     * @param options.message - Human-readable error message
+     * @param options.code - Machine-readable error code from ErrorCodes registry or custom string
+     * @param options.cause - Optional underlying error that caused this error
+     */
+    constructor({ message, code, cause, }: {
+        message: string;
+        code: ErrorCode | string;
+        cause?: unknown;
+    });
+    /**
+     * Factory method to create a typed error from a caught error.
+     *
+     * Subclasses should override this to provide proper error transformation.
+     * Designed for use with {@link wrapErrorAsync} and {@link wrapError}.
+     *
+     * @param _cause - The original caught error
+     * @returns A new CodedError instance
+     * @throws {Error} If not overridden by subclass
+     *
+     * @example
+     * ```typescript
+     * class NotFoundError extends UseCaseError {
+     *   static override fromError(cause: unknown): NotFoundError {
+     *     return new NotFoundError({
+     *       message: 'Resource not found',
+     *       cause,
+     *     });
+     *   }
+     * }
+     * ```
+     */
+    static fromError(_cause: unknown): CodedError;
+}
+
+interface ValidationError {
+    field: string;
+    message: string;
+}
+
+export { type AppErrorCode as A, CodedError as C, type DomainErrorCode as D, ErrorCodes as E, type GlobalErrorCode as G, type InfraErrorCode as I, type PresentationErrorCode as P, type ValidationError as V, type ErrorCode as a };

package/package.json

@@ -0,0 +1,191 @@
+{
+  "name": "@cosmneo/onion-lasagna",
+  "version": "0.1.0",
+  "description": "Enterprise-grade TypeScript library for building backend applications with hexagonal/onion architecture",
+  "type": "module",
+  "license": "UNLICENSED",
+  "author": "Cosmneo",
+  "homepage": "https://onion-lasagna.cosmneo.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cosmneo/onion-lasagna.git",
+    "directory": "packages/onion-lasagna"
+  },
+  "bugs": {
+    "url": "https://github.com/Cosmneo/onion-lasagna/issues"
+  },
+  "keywords": [
+    "hexagonal-architecture",
+    "onion-architecture",
+    "clean-architecture",
+    "ddd",
+    "domain-driven-design",
+    "typescript",
+    "backend",
+    "enterprise",
+    "value-objects",
+    "entities",
+    "aggregates",
+    "use-cases",
+    "ports-and-adapters",
+    "hono",
+    "nestjs",
+    "elysia",
+    "fastify",
+    "zod",
+    "arktype",
+    "valibot",
+    "typebox"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@nestjs/common": "^11.1.10",
+    "@nestjs/core": "^11.1.10",
+    "@sinclair/typebox": "^0.34.41",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "arktype": "^2.1.29",
+    "elysia": "^1.2",
+    "express": "^5.2.1",
+    "fastify": "^5",
+    "hono": "^4",
+    "rxjs": "^7.8.2",
+    "tsup": "^8.5.1",
+    "uuid": "^13.0.0",
+    "valibot": "^1.2.0",
+    "vitest": "^4.0.16",
+    "zod": "^4.2.1"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.1.10",
+    "@nestjs/core": "^11.1.10",
+    "@sinclair/typebox": "^0.34.41",
+    "arktype": "^2.1.29",
+    "elysia": "^1.2",
+    "fastify": "^5",
+    "hono": "^4",
+    "typescript": "^5",
+    "uuid": "^13.0.0",
+    "valibot": "^1.2.0",
+    "zod": "^4.2.1"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "@sinclair/typebox": {
+      "optional": true
+    },
+    "arktype": {
+      "optional": true
+    },
+    "elysia": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "valibot": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "bun run build"
+  },
+  "exports": {
+    "./backend/core/onion-layers": {
+      "types": "./dist/backend/core/onion-layers.d.ts",
+      "import": "./dist/backend/core/onion-layers.js",
+      "require": "./dist/backend/core/onion-layers.cjs",
+      "default": "./dist/backend/core/onion-layers.js"
+    },
+    "./backend/core/global": {
+      "types": "./dist/backend/core/global.d.ts",
+      "import": "./dist/backend/core/global.js",
+      "require": "./dist/backend/core/global.cjs",
+      "default": "./dist/backend/core/global.js"
+    },
+    "./backend/core/presentation": {
+      "types": "./dist/backend/core/presentation.d.ts",
+      "import": "./dist/backend/core/presentation.js",
+      "require": "./dist/backend/core/presentation.cjs",
+      "default": "./dist/backend/core/presentation.js"
+    },
+    "./backend/core/validators/zod": {
+      "types": "./dist/backend/core/validators/zod.d.ts",
+      "import": "./dist/backend/core/validators/zod.js",
+      "require": "./dist/backend/core/validators/zod.cjs",
+      "default": "./dist/backend/core/validators/zod.js"
+    },
+    "./backend/core/validators/arktype": {
+      "types": "./dist/backend/core/validators/arktype.d.ts",
+      "import": "./dist/backend/core/validators/arktype.js",
+      "require": "./dist/backend/core/validators/arktype.cjs",
+      "default": "./dist/backend/core/validators/arktype.js"
+    },
+    "./backend/core/validators/valibot": {
+      "types": "./dist/backend/core/validators/valibot.d.ts",
+      "import": "./dist/backend/core/validators/valibot.js",
+      "require": "./dist/backend/core/validators/valibot.cjs",
+      "default": "./dist/backend/core/validators/valibot.js"
+    },
+    "./backend/core/validators/typebox": {
+      "types": "./dist/backend/core/validators/typebox.d.ts",
+      "import": "./dist/backend/core/validators/typebox.js",
+      "require": "./dist/backend/core/validators/typebox.cjs",
+      "default": "./dist/backend/core/validators/typebox.js"
+    },
+    "./backend/frameworks/hono": {
+      "types": "./dist/backend/frameworks/hono.d.ts",
+      "import": "./dist/backend/frameworks/hono.js",
+      "require": "./dist/backend/frameworks/hono.cjs",
+      "default": "./dist/backend/frameworks/hono.js"
+    },
+    "./backend/frameworks/nestjs": {
+      "types": "./dist/backend/frameworks/nestjs.d.ts",
+      "import": "./dist/backend/frameworks/nestjs.js",
+      "require": "./dist/backend/frameworks/nestjs.cjs",
+      "default": "./dist/backend/frameworks/nestjs.js"
+    },
+    "./backend/frameworks/elysia": {
+      "types": "./dist/backend/frameworks/elysia.d.ts",
+      "import": "./dist/backend/frameworks/elysia.js",
+      "require": "./dist/backend/frameworks/elysia.cjs",
+      "default": "./dist/backend/frameworks/elysia.js"
+    },
+    "./backend/frameworks/fastify": {
+      "types": "./dist/backend/frameworks/fastify.d.ts",
+      "import": "./dist/backend/frameworks/fastify.js",
+      "require": "./dist/backend/frameworks/fastify.cjs",
+      "default": "./dist/backend/frameworks/fastify.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}