@venizia/ignis 0.0.9-9 → 0.0.9

package/README.md

@@ -10,7 +10,7 @@
 [![Hono](https://img.shields.io/badge/Hono-4.x-E36002.svg?style=flat-square&logo=hono&logoColor=white)](https://hono.dev/)
 [![Drizzle ORM](https://img.shields.io/badge/Drizzle_ORM-0.45-C5F74F.svg?style=flat-square)](https://orm.drizzle.team/)
 
-Ignis brings together the structured, enterprise development experience of **LoopBack 4** with the blazing speed and simplicity of **Hono**, giving you the best of both worlds: decorator-based DI, repository pattern, DataSource abstraction, component system, boot conventions — running on Hono's ~140k req/s engine with Drizzle ORM's type-safe SQL.
+IGNIS brings together the structured, enterprise development experience of **LoopBack 4** with the blazing speed and simplicity of **Hono**, giving you the best of both worlds: decorator-based DI, repository pattern, DataSource abstraction, component system, boot conventions - running on Hono's ~140k req/s engine with Drizzle ORM's type-safe SQL.
 
 [Installation](#installation) • [Quick Start](#quick-start) • [API Reference](#controllers) • [Documentation](https://venizia-ai.github.io/ignis)
 
@@ -34,7 +34,7 @@ Ignis brings together the structured, enterprise development experience of **Loo
 ```typescript
 import {
   BaseApplication,       // Your app extends this
-  BaseController,        // Controllers extend this
+  BaseRestController,        // Controllers extend this
   DefaultCRUDRepository, // Repositories extend this
   BaseEntity,            // Models extend this
   BaseDataSource,        // DataSources extend this
@@ -200,14 +200,14 @@ export class UserRepository extends PersistableRepository<typeof User.schema> {
 ```typescript
 // controllers/user.controller.ts
 import {
-  BaseController, controller, get, post,
+  BaseRestController, controller, get, post,
   inject, jsonContent, jsonResponse, HTTP, TRouteContext,
 } from '@venizia/ignis';
 import { z } from '@hono/zod-openapi';
 import { UserRepository } from '../repositories/user.repository';
 
 @controller({ path: '/users' })
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
   constructor(
     @inject({ key: 'repositories.UserRepository' }) private userRepo: UserRepository,
   ) {
@@ -276,7 +276,7 @@ export class Application extends BaseApplication {
   }
 
   getAppInfo(): IApplicationInfo {
-    return { name: 'My App', version: '1.0.0', description: 'My Ignis application' };
+    return { name: 'My App', version: '1.0.0', description: 'My IGNIS application' };
   }
 
   staticConfigure() {}
@@ -437,7 +437,7 @@ Runtime-aware: uses `hono/bun` `serveStatic` on Bun, `@hono/node-server/serve-st
 
 ### Runtime Detection
 
-Ignis auto-detects the runtime and starts the server accordingly:
+IGNIS auto-detects the runtime and starts the server accordingly:
 
 ```typescript
 // Bun (default)
@@ -499,9 +499,9 @@ interface IApplicationInfo {
 
 ## Controllers
 
-### BaseController
+### BaseRestController
 
-All controllers extend `BaseController`, which provides:
+All controllers extend `BaseRestController`, which provides:
 
 - An `OpenAPIHono` router instance
 - Route registration methods (`defineRoute`, `bindRoute`, `defineJSXRoute`)
@@ -510,7 +510,7 @@ All controllers extend `BaseController`, which provides:
 - Zod-based request validation with automatic 422 error responses
 
 ```typescript
-abstract class BaseController extends AbstractController {
+abstract class BaseRestController extends AbstractController {
   // Register routes -- override this method
   abstract binding(): ValueOrPromise<void>;
 
@@ -536,7 +536,7 @@ Use `@get`, `@post`, `@put`, `@patch`, `@del`, or the generic `@api` decorators.
 
 ```typescript
 @controller({ path: '/products' })
-class ProductController extends BaseController {
+class ProductController extends BaseRestController {
   constructor(
     @inject({ key: 'repositories.ProductRepository' }) private productRepo: ProductRepository,
     @inject({ key: 'services.InventoryService' }) private inventoryService: InventoryService,
@@ -2167,7 +2167,7 @@ const UserController = ControllerFactory.defineCrudController({
 
 // Route-level (via decorators)
 @controller({ path: '/products' })
-class ProductController extends BaseController {
+class ProductController extends BaseRestController {
   @get({
     configs: {
       path: '/',
@@ -2573,7 +2573,7 @@ export class UserService extends BaseService {
 
 // controllers/user.controller.ts
 @controller({ path: '/users' })
-export class UserController extends BaseController {
+export class UserController extends BaseRestController {
   constructor(
     @inject({ key: 'services.UserService' }) private userService: UserService,
     @inject({ key: 'repositories.UserRepository' }) private userRepo: UserRepository,
@@ -2783,9 +2783,9 @@ describe('UserController', () => {
 
 ## Documentation
 
-- [Ignis Repository](https://github.com/VENIZIA-AI/ignis)
-- [Getting Started](https://github.com/VENIZIA-AI/ignis/blob/main/packages/docs/wiki/get-started/index.md)
-- [Core Concepts](https://github.com/VENIZIA-AI/ignis/blob/main/packages/docs/wiki/get-started/core-concepts/application.md)
+- [IGNIS Repository](https://github.com/VENIZIA-AI/ignis)
+- [Getting Started](https://github.com/VENIZIA-AI/ignis/blob/main/docs/wiki/content/get-started/index.md)
+- [Core Concepts](https://github.com/VENIZIA-AI/ignis/blob/main/docs/wiki/content/get-started/core-concepts/application.md)
 - [Examples](https://github.com/VENIZIA-AI/ignis/tree/main/examples/vert)
 
 ---

package/dist/base/middlewares/app-error/app-error.middleware.d.ts

@@ -0,0 +1,15 @@
+import { Logger } from '@venizia/ignis-helpers';
+import { ErrorHandler } from 'hono/types';
+/**
+ * Application error handler (Hono `onError`). Routes each error to the right shape:
+ * - ZodError → 422 via {@link formatZodError}
+ * - DB client error (class 22/23/44) → 400 via {@link isDatabaseClientError}
+ * - Transient DB conflict (40001/40P01) → 409 via {@link isRetryableDatabaseError}
+ * - Intentional domain error (`getError`) → its own status/message
+ * - Anything else → 500 (generic message in production)
+ */
+export declare const appErrorHandler: (opts: {
+    logger: Logger;
+    rootKey?: string;
+}) => ErrorHandler;
+//# sourceMappingURL=app-error.middleware.d.ts.map

package/dist/base/middlewares/app-error/app-error.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error.middleware.d.ts","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/app-error.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ1C;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,iBAqFzE,CAAC"}

package/dist/base/middlewares/app-error/app-error.middleware.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appErrorHandler = void 0;
+const ignis_helpers_1 = require("@venizia/ignis-helpers");
+const request_spy_1 = require("../request-spy");
+const database_handler_1 = require("./database.handler");
+const definition_1 = require("./definition");
+const zod_handler_1 = require("./zod.handler");
+const DEFAULT_INTERNAL_ERROR_MESSAGE = 'Internal Server Error';
+/**
+ * Application error handler (Hono `onError`). Routes each error to the right shape:
+ * - ZodError → 422 via {@link formatZodError}
+ * - DB client error (class 22/23/44) → 400 via {@link isDatabaseClientError}
+ * - Transient DB conflict (40001/40P01) → 409 via {@link isRetryableDatabaseError}
+ * - Intentional domain error (`getError`) → its own status/message
+ * - Anything else → 500 (generic message in production)
+ */
+const appErrorHandler = (opts) => {
+    const { logger = console, rootKey = null } = opts;
+    const mw = async (error, context) => {
+        const requestId = context.get(request_spy_1.RequestSpyMiddleware.REQUEST_ID_KEY);
+        logger.error('[onError][%s] REQUEST ERROR | path: %s | method: %s | url: %s | Error: %j', requestId, context.req.path, context.req.method, context.req.url, error);
+        const { NODE_ENV } = process.env;
+        const env = context.env?.NODE_ENV || NODE_ENV;
+        const isProduction = env?.toLowerCase() === ignis_helpers_1.Environment.PRODUCTION;
+        const statusCode = 'statusCode' in error ? error.statusCode : ignis_helpers_1.HTTP.ResultCodes.RS_5.InternalServerError;
+        const messageCode = 'messageCode' in error ? error.messageCode : undefined;
+        if (error.name === 'ZodError') {
+            const rs = (0, zod_handler_1.formatZodError)({
+                isProduction,
+                requestId,
+                url: context.req.url,
+                path: context.req.path,
+                error,
+            });
+            return context.json(rootKey ? { [rootKey]: rs.response } : rs.response, rs.statusCode);
+        }
+        // Classify DB errors: client (400), transient/retryable conflict (409 Conflict), else server.
+        const dbError = (0, database_handler_1.isDatabaseClientError)({ error, isProduction });
+        const isRetryable = !dbError.isClientError && (0, database_handler_1.isRetryableDatabaseError)({ error });
+        let resolvedStatusCode = statusCode;
+        if (dbError.isClientError) {
+            resolvedStatusCode = ignis_helpers_1.HTTP.ResultCodes.RS_4.BadRequest;
+        }
+        else if (isRetryable) {
+            resolvedStatusCode = ignis_helpers_1.HTTP.ResultCodes.RS_4.Conflict;
+        }
+        let resolvedMessage = error.message;
+        let resolvedMessageCode = messageCode;
+        if (dbError.isClientError && dbError.message) {
+            resolvedMessage = dbError.message;
+        }
+        else if (isRetryable) {
+            // Transient conflict (deadlock / serialization failure) — safe generic message + retryable code.
+            resolvedMessage = definition_1.DATABASE_RETRYABLE_ERROR_MESSAGE;
+            resolvedMessageCode = definition_1.DATABASE_RETRYABLE_ERROR_CODE;
+        }
+        else if (isProduction && !('statusCode' in error)) {
+            // Unexpected server error (uncaught throw, non-client DB error, connection failure): never
+            // leak the raw message in production — it may carry SQL, schema names, or connection details.
+            resolvedMessage = DEFAULT_INTERNAL_ERROR_MESSAGE;
+        }
+        const rs = {
+            message: resolvedMessage,
+            messageCode: resolvedMessageCode,
+            statusCode: resolvedStatusCode,
+            requestId,
+            extra: 'extra' in error ? error?.extra : undefined,
+            details: {
+                url: context.req.url,
+                path: context.req.path,
+                stack: !isProduction ? error.stack : undefined,
+                cause: !isProduction ? error.cause : undefined,
+            },
+        };
+        return context.json(rootKey ? { [rootKey]: rs } : rs, resolvedStatusCode);
+    };
+    return mw;
+};
+exports.appErrorHandler = appErrorHandler;
+//# sourceMappingURL=app-error.middleware.js.map

package/dist/base/middlewares/app-error/app-error.middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error.middleware.js","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/app-error.middleware.ts"],"names":[],"mappings":"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"}

package/dist/base/middlewares/app-error/database.handler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Checks if error is a database constraint error caused by the request (SQLSTATE class 22/23/44)
+ * and should return HTTP 400. In production the detail/table/constraint context is suppressed so
+ * no row values or schema internals leak; in non-production it is appended to aid debugging.
+ */
+export declare const isDatabaseClientError: (opts: {
+    error: Error;
+    isProduction: boolean;
+}) => {
+    isClientError: boolean;
+    message?: string;
+};
+/**
+ * Checks if error is a transient, retryable DB transaction conflict (serialization failure /
+ * deadlock — SQLSTATE 40001 / 40P01). These map to HTTP 409: the client can retry the same request.
+ */
+export declare const isRetryableDatabaseError: (opts: {
+    error: Error;
+}) => boolean;
+//# sourceMappingURL=database.handler.d.ts.map

package/dist/base/middlewares/app-error/database.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.handler.d.ts","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/database.handler.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM;IAC1C,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,OAAO,CAAC;CACvB,KAAG;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAyC7C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,KAAG,OAIjE,CAAC"}

package/dist/base/middlewares/app-error/database.handler.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRetryableDatabaseError = exports.isDatabaseClientError = void 0;
+const definition_1 = require("./definition");
+/**
+ * Checks if error is a database constraint error caused by the request (SQLSTATE class 22/23/44)
+ * and should return HTTP 400. In production the detail/table/constraint context is suppressed so
+ * no row values or schema internals leak; in non-production it is appended to aid debugging.
+ */
+const isDatabaseClientError = (opts) => {
+    const { error, isProduction } = opts;
+    const dbError = error;
+    const cause = dbError.cause;
+    const code = dbError.code || cause?.code;
+    // Only SQLSTATE classes caused by the request — 22 (data exception) and 23 (integrity violation) —
+    // are client errors. Anything else (e.g. class 42 syntax/undefined-column, 53 resources) stays 500.
+    // A missing or non-string code (e.g. a gRPC numeric code) is treated as non-client and must never
+    // crash this last-resort handler.
+    if (typeof code !== 'string' || !definition_1.POSTGRES_CLIENT_ERROR_CLASSES.includes(code.slice(0, 2))) {
+        return { isClientError: false };
+    }
+    const baseMessage = definition_1.DATABASE_CLIENT_ERROR_MESSAGES[code] ?? definition_1.DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE;
+    // In production, expose ONLY the generic base message. `detail` can echo row values
+    // (e.g. "Key (email)=(a@b.com) already exists") and `table`/`constraint` reveal schema internals.
+    if (isProduction) {
+        return { isClientError: true, message: baseMessage };
+    }
+    // Non-production: append driver-provided context to aid debugging.
+    const lines = [baseMessage];
+    if (cause?.detail) {
+        lines.push(`Detail: ${cause.detail}`);
+    }
+    if (cause?.table) {
+        lines.push(`Table: ${cause.table}`);
+    }
+    if (cause?.constraint) {
+        lines.push(`Constraint: ${cause.constraint}`);
+    }
+    return {
+        isClientError: true,
+        message: lines.join('\n'),
+    };
+};
+exports.isDatabaseClientError = isDatabaseClientError;
+/**
+ * Checks if error is a transient, retryable DB transaction conflict (serialization failure /
+ * deadlock — SQLSTATE 40001 / 40P01). These map to HTTP 409: the client can retry the same request.
+ */
+const isRetryableDatabaseError = (opts) => {
+    const dbError = opts.error;
+    const code = dbError.code || dbError.cause?.code;
+    return typeof code === 'string' && definition_1.POSTGRES_RETRYABLE_ERROR_CODES.includes(code);
+};
+exports.isRetryableDatabaseError = isRetryableDatabaseError;
+//# sourceMappingURL=database.handler.js.map

package/dist/base/middlewares/app-error/database.handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.handler.js","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/database.handler.ts"],"names":[],"mappings":";;;AAAA,6CAKsB;AAGtB;;;;GAIG;AACI,MAAM,qBAAqB,GAAG,CAAC,IAGrC,EAAgD,EAAE;IACjD,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IACrC,MAAM,OAAO,GAAG,KAAuB,CAAC;IACxC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,KAAK,EAAE,IAAI,CAAC;IAEzC,mGAAmG;IACnG,oGAAoG;IACpG,kGAAkG;IAClG,kCAAkC;IAClC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,0CAA6B,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IAED,MAAM,WAAW,GACf,2CAA8B,CAAC,IAAI,CAAC,IAAI,mDAAsC,CAAC;IAEjF,oFAAoF;IACpF,kGAAkG;IAClG,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IACvD,CAAC;IAED,mEAAmE;IACnE,MAAM,KAAK,GAAG,CAAC,WAAW,CAAC,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,WAAW,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,KAAK,EAAE,KAAK,EAAE,CAAC;QACjB,KAAK,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,KAAK,EAAE,UAAU,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,eAAe,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,OAAO;QACL,aAAa,EAAE,IAAI;QACnB,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;KAC1B,CAAC;AACJ,CAAC,CAAC;AA5CW,QAAA,qBAAqB,yBA4ChC;AAEF;;;GAGG;AACI,MAAM,wBAAwB,GAAG,CAAC,IAAsB,EAAW,EAAE;IAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,KAAuB,CAAC;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC;IACjD,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,2CAA8B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACnF,CAAC,CAAC;AAJW,QAAA,wBAAwB,4BAInC"}

package/dist/base/middlewares/app-error/definition.d.ts

@@ -0,0 +1,59 @@
+/**
+ * PostgreSQL SQLSTATE error codes that represent a CLIENT error (HTTP 400) — i.e. caused by the
+ * request/data — rather than a server fault. Grouped by SQLSTATE class.
+ * @see https://www.postgresql.org/docs/current/errcodes-appendix.html
+ */
+export declare const PostgresErrorCodes: {
+    readonly DATA_EXCEPTION: "22000";
+    readonly STRING_DATA_TOO_LONG: "22001";
+    readonly NUMERIC_VALUE_OUT_OF_RANGE: "22003";
+    readonly NULL_VALUE_NOT_ALLOWED: "22004";
+    readonly INVALID_DATETIME_FORMAT: "22007";
+    readonly DATETIME_FIELD_OVERFLOW: "22008";
+    readonly INVALID_TIME_ZONE_DISPLACEMENT_VALUE: "22009";
+    readonly SUBSTRING_ERROR: "22011";
+    readonly DIVISION_BY_ZERO: "22012";
+    readonly INVALID_PARAMETER_VALUE: "22023";
+    readonly INVALID_ESCAPE_SEQUENCE: "22025";
+    readonly STRING_DATA_LENGTH_MISMATCH: "22026";
+    readonly DUPLICATE_JSON_OBJECT_KEY_VALUE: "22030";
+    readonly INVALID_JSON_TEXT: "22032";
+    readonly FLOATING_POINT_EXCEPTION: "22P01";
+    readonly INVALID_TEXT_REPRESENTATION: "22P02";
+    readonly INVALID_BINARY_REPRESENTATION: "22P03";
+    readonly UNTRANSLATABLE_CHARACTER: "22P05";
+    readonly INTEGRITY_CONSTRAINT_VIOLATION: "23000";
+    readonly RESTRICT_VIOLATION: "23001";
+    readonly NOT_NULL_VIOLATION: "23502";
+    readonly FOREIGN_KEY_VIOLATION: "23503";
+    readonly UNIQUE_VIOLATION: "23505";
+    readonly CHECK_VIOLATION: "23514";
+    readonly EXCLUSION_VIOLATION: "23P01";
+    readonly WITH_CHECK_OPTION_VIOLATION: "44000";
+};
+/**
+ * SQLSTATE classes (first two chars) whose errors are caused by the client request and therefore
+ * map to HTTP 400. Any code in these classes — even one without a specific message below — is
+ * treated as a client error and uses {@link DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE}.
+ *
+ * Deliberately excluded (remain server errors / 500): class 42 (syntax, undefined column/table —
+ * application/SQL bugs), 53 (insufficient resources), 0A (feature not supported), 25 (invalid
+ * transaction state), 28 (DB authorization), 21 (cardinality), 54 (program limits). Class 40
+ * (serialization_failure / deadlock_detected) is transient/retryable and is intentionally NOT a
+ * 400 — it warrants dedicated 409/503 + retry handling rather than being treated as client input.
+ */
+export declare const POSTGRES_CLIENT_ERROR_CLASSES: readonly string[];
+/** Human-readable message per specific SQLSTATE code. */
+export declare const DATABASE_CLIENT_ERROR_MESSAGES: Record<string, string>;
+/** Fallback message for a client-class (22/23/44) error that has no specific message above. */
+export declare const DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE = "Invalid database request";
+/**
+ * SQLSTATE codes for transient, retryable transaction conflicts (→ HTTP 409 Conflict). The client
+ * can safely retry the same request: the transaction lost a concurrency race rather than sending
+ * bad input (not 400) or hitting a server bug (not 500). Retrying usually succeeds.
+ */
+export declare const POSTGRES_RETRYABLE_ERROR_CODES: readonly string[];
+/** Safe, generic message + stable code for a retryable DB conflict (never leaks internals). */
+export declare const DATABASE_RETRYABLE_ERROR_MESSAGE = "The request conflicted with a concurrent operation; please retry.";
+export declare const DATABASE_RETRYABLE_ERROR_CODE = "database.conflict";
+//# sourceMappingURL=definition.d.ts.map

package/dist/base/middlewares/app-error/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/definition.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BrB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAAuB,CAAC;AAEnF,yDAAyD;AACzD,eAAO,MAAM,8BAA8B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA8BjE,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,sCAAsC,6BAA6B,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAG3D,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,gCAAgC,sEACwB,CAAC;AACtE,eAAO,MAAM,6BAA6B,sBAAsB,CAAC"}

package/dist/base/middlewares/app-error/definition.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DATABASE_RETRYABLE_ERROR_CODE = exports.DATABASE_RETRYABLE_ERROR_MESSAGE = exports.POSTGRES_RETRYABLE_ERROR_CODES = exports.DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE = exports.DATABASE_CLIENT_ERROR_MESSAGES = exports.POSTGRES_CLIENT_ERROR_CLASSES = exports.PostgresErrorCodes = void 0;
+/**
+ * PostgreSQL SQLSTATE error codes that represent a CLIENT error (HTTP 400) — i.e. caused by the
+ * request/data — rather than a server fault. Grouped by SQLSTATE class.
+ * @see https://www.postgresql.org/docs/current/errcodes-appendix.html
+ */
+exports.PostgresErrorCodes = {
+    // Class 22 — Data Exception (malformed / out-of-range values)
+    DATA_EXCEPTION: '22000',
+    STRING_DATA_TOO_LONG: '22001',
+    NUMERIC_VALUE_OUT_OF_RANGE: '22003',
+    NULL_VALUE_NOT_ALLOWED: '22004',
+    INVALID_DATETIME_FORMAT: '22007',
+    DATETIME_FIELD_OVERFLOW: '22008',
+    INVALID_TIME_ZONE_DISPLACEMENT_VALUE: '22009',
+    SUBSTRING_ERROR: '22011',
+    DIVISION_BY_ZERO: '22012',
+    INVALID_PARAMETER_VALUE: '22023',
+    INVALID_ESCAPE_SEQUENCE: '22025',
+    STRING_DATA_LENGTH_MISMATCH: '22026',
+    DUPLICATE_JSON_OBJECT_KEY_VALUE: '22030',
+    INVALID_JSON_TEXT: '22032',
+    FLOATING_POINT_EXCEPTION: '22P01',
+    INVALID_TEXT_REPRESENTATION: '22P02',
+    INVALID_BINARY_REPRESENTATION: '22P03',
+    UNTRANSLATABLE_CHARACTER: '22P05',
+    // Class 23 — Integrity Constraint Violation
+    INTEGRITY_CONSTRAINT_VIOLATION: '23000',
+    RESTRICT_VIOLATION: '23001',
+    NOT_NULL_VIOLATION: '23502',
+    FOREIGN_KEY_VIOLATION: '23503',
+    UNIQUE_VIOLATION: '23505',
+    CHECK_VIOLATION: '23514',
+    EXCLUSION_VIOLATION: '23P01',
+    // Class 44 — WITH CHECK OPTION Violation (row written through an updatable view fails its CHECK)
+    WITH_CHECK_OPTION_VIOLATION: '44000',
+};
+/**
+ * SQLSTATE classes (first two chars) whose errors are caused by the client request and therefore
+ * map to HTTP 400. Any code in these classes — even one without a specific message below — is
+ * treated as a client error and uses {@link DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE}.
+ *
+ * Deliberately excluded (remain server errors / 500): class 42 (syntax, undefined column/table —
+ * application/SQL bugs), 53 (insufficient resources), 0A (feature not supported), 25 (invalid
+ * transaction state), 28 (DB authorization), 21 (cardinality), 54 (program limits). Class 40
+ * (serialization_failure / deadlock_detected) is transient/retryable and is intentionally NOT a
+ * 400 — it warrants dedicated 409/503 + retry handling rather than being treated as client input.
+ */
+exports.POSTGRES_CLIENT_ERROR_CLASSES = ['22', '23', '44'];
+/** Human-readable message per specific SQLSTATE code. */
+exports.DATABASE_CLIENT_ERROR_MESSAGES = {
+    // Class 22 — Data Exception
+    [exports.PostgresErrorCodes.DATA_EXCEPTION]: 'Invalid data value',
+    [exports.PostgresErrorCodes.STRING_DATA_TOO_LONG]: 'String data too long',
+    [exports.PostgresErrorCodes.NUMERIC_VALUE_OUT_OF_RANGE]: 'Numeric value out of range',
+    [exports.PostgresErrorCodes.NULL_VALUE_NOT_ALLOWED]: 'Null value not allowed',
+    [exports.PostgresErrorCodes.INVALID_DATETIME_FORMAT]: 'Invalid date/time format',
+    [exports.PostgresErrorCodes.DATETIME_FIELD_OVERFLOW]: 'Date/time field value out of range',
+    [exports.PostgresErrorCodes.INVALID_TIME_ZONE_DISPLACEMENT_VALUE]: 'Invalid time zone displacement value',
+    [exports.PostgresErrorCodes.SUBSTRING_ERROR]: 'Substring error',
+    [exports.PostgresErrorCodes.DIVISION_BY_ZERO]: 'Division by zero',
+    [exports.PostgresErrorCodes.INVALID_PARAMETER_VALUE]: 'Invalid parameter value',
+    [exports.PostgresErrorCodes.INVALID_ESCAPE_SEQUENCE]: 'Invalid escape sequence',
+    [exports.PostgresErrorCodes.STRING_DATA_LENGTH_MISMATCH]: 'String data length mismatch',
+    [exports.PostgresErrorCodes.DUPLICATE_JSON_OBJECT_KEY_VALUE]: 'Duplicate JSON object key',
+    [exports.PostgresErrorCodes.INVALID_JSON_TEXT]: 'Invalid JSON text',
+    [exports.PostgresErrorCodes.FLOATING_POINT_EXCEPTION]: 'Floating point exception',
+    [exports.PostgresErrorCodes.INVALID_TEXT_REPRESENTATION]: 'Invalid text representation',
+    [exports.PostgresErrorCodes.INVALID_BINARY_REPRESENTATION]: 'Invalid binary representation',
+    [exports.PostgresErrorCodes.UNTRANSLATABLE_CHARACTER]: 'Untranslatable character',
+    // Class 23 — Integrity Constraint Violation
+    [exports.PostgresErrorCodes.INTEGRITY_CONSTRAINT_VIOLATION]: 'Integrity constraint violation',
+    [exports.PostgresErrorCodes.RESTRICT_VIOLATION]: 'Restrict constraint violation',
+    [exports.PostgresErrorCodes.NOT_NULL_VIOLATION]: 'Not null constraint violation',
+    [exports.PostgresErrorCodes.FOREIGN_KEY_VIOLATION]: 'Foreign key constraint violation',
+    [exports.PostgresErrorCodes.UNIQUE_VIOLATION]: 'Unique constraint violation',
+    [exports.PostgresErrorCodes.CHECK_VIOLATION]: 'Check constraint violation',
+    [exports.PostgresErrorCodes.EXCLUSION_VIOLATION]: 'Exclusion constraint violation',
+    // Class 44 — WITH CHECK OPTION Violation
+    [exports.PostgresErrorCodes.WITH_CHECK_OPTION_VIOLATION]: 'View check option violation',
+};
+/** Fallback message for a client-class (22/23/44) error that has no specific message above. */
+exports.DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE = 'Invalid database request';
+/**
+ * SQLSTATE codes for transient, retryable transaction conflicts (→ HTTP 409 Conflict). The client
+ * can safely retry the same request: the transaction lost a concurrency race rather than sending
+ * bad input (not 400) or hitting a server bug (not 500). Retrying usually succeeds.
+ */
+exports.POSTGRES_RETRYABLE_ERROR_CODES = [
+    '40001', // serialization_failure
+    '40P01', // deadlock_detected
+];
+/** Safe, generic message + stable code for a retryable DB conflict (never leaks internals). */
+exports.DATABASE_RETRYABLE_ERROR_MESSAGE = 'The request conflicted with a concurrent operation; please retry.';
+exports.DATABASE_RETRYABLE_ERROR_CODE = 'database.conflict';
+//# sourceMappingURL=definition.js.map

package/dist/base/middlewares/app-error/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/definition.ts"],"names":[],"mappings":"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"}

package/dist/base/middlewares/app-error/index.d.ts

@@ -0,0 +1,2 @@
+export * from './app-error.middleware';
+//# sourceMappingURL=index.d.ts.map

package/dist/base/middlewares/app-error/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/dist/{components/auth/authorize/models/abilities → base/middlewares/app-error}/index.js

@@ -14,6 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./string-action.model"), exports);
-__exportStar(require("./string-resource.model"), exports);
+__exportStar(require("./app-error.middleware"), exports);
 //# sourceMappingURL=index.js.map

package/dist/base/middlewares/app-error/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC"}

package/dist/base/middlewares/app-error/types.d.ts

@@ -0,0 +1,18 @@
+export interface IDatabaseError extends Error {
+    code?: string;
+    cause?: {
+        code?: string;
+        detail?: string;
+        table?: string;
+        constraint?: string;
+    };
+}
+export interface IZodIssueLike {
+    path: Array<string | number>;
+    message: string;
+    code?: string;
+    params?: Record<string, unknown>;
+    expected?: unknown;
+    received?: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/base/middlewares/app-error/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAe,SAAQ,KAAK;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/base/middlewares/app-error/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/base/middlewares/app-error/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/types.ts"],"names":[],"mappings":""}

package/dist/base/middlewares/app-error/zod.handler.d.ts

@@ -0,0 +1,28 @@
+import { HTTPResponseError } from 'hono/types';
+/**
+ * Formats a ZodError into the 422 validation response. Top-level `messageCode`/`message` come from
+ * the first issue that defines a custom `params.code`, else the first issue's raw Zod code; the full
+ * per-issue list stays under `details.cause`.
+ */
+export declare const formatZodError: (opts: {
+    isProduction: boolean;
+    requestId: string;
+    url: string;
+    path: string;
+    error: Error | HTTPResponseError;
+}) => {
+    statusCode: 422;
+    response: {
+        message: string;
+        messageCode: string | undefined;
+        statusCode: 422;
+        requestId: string;
+        details: {
+            url: string;
+            path: string;
+            stack: string | undefined;
+            cause: unknown;
+        };
+    };
+};
+//# sourceMappingURL=zod.handler.d.ts.map

package/dist/base/middlewares/app-error/zod.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.handler.d.ts","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/zod.handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAgB/C;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM;IACnC,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,GAAG,iBAAiB,CAAC;CAClC;;;;;;;;;;;;;;CAgDA,CAAC"}

package/dist/base/middlewares/app-error/zod.handler.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatZodError = void 0;
+const ignis_helpers_1 = require("@venizia/ignis-helpers");
+const DEFAULT_VALIDATION_MESSAGE = 'ValidationError';
+/** Returns a schema-author-supplied code (`issue.params.code`) when it is a non-empty string. */
+const extractIssueCode = (opts) => {
+    const paramsCode = opts.issue?.params?.code;
+    if (typeof paramsCode === 'string' && paramsCode.length > 0) {
+        return paramsCode;
+    }
+    return undefined;
+};
+/**
+ * Formats a ZodError into the 422 validation response. Top-level `messageCode`/`message` come from
+ * the first issue that defines a custom `params.code`, else the first issue's raw Zod code; the full
+ * per-issue list stays under `details.cause`.
+ */
+const formatZodError = (opts) => {
+    const { isProduction, requestId, url, path, error } = opts;
+    const statusCode = ignis_helpers_1.HTTP.ResultCodes.RS_4.UnprocessableEntity;
+    let validationErrors;
+    try {
+        validationErrors = JSON.parse(error.message);
+    }
+    catch {
+        validationErrors = error;
+    }
+    const issues = Array.isArray(validationErrors) ? validationErrors : null;
+    // Top-level messageCode/message: prefer the first issue with a custom `params.code`;
+    // else fall back to the first issue's raw Zod code; else keep the generic message.
+    let messageCode;
+    let message = DEFAULT_VALIDATION_MESSAGE;
+    if (issues && issues.length > 0) {
+        const primaryIssue = issues.find(issue => extractIssueCode({ issue }) !== undefined) ?? issues[0];
+        messageCode = extractIssueCode({ issue: primaryIssue }) ?? primaryIssue.code;
+        message = primaryIssue.message;
+    }
+    return {
+        statusCode,
+        response: {
+            message,
+            messageCode,
+            statusCode,
+            requestId,
+            details: {
+                url,
+                path,
+                stack: !isProduction ? error.stack : undefined,
+                cause: issues
+                    ? issues.map(el => ({
+                        path: el.path.join('.') || 'root',
+                        message: el.message,
+                        code: el.code,
+                        expected: el.expected,
+                        received: el.received,
+                    }))
+                    : validationErrors,
+            },
+        },
+    };
+};
+exports.formatZodError = formatZodError;
+//# sourceMappingURL=zod.handler.js.map

package/dist/base/middlewares/app-error/zod.handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod.handler.js","sourceRoot":"","sources":["../../../../src/base/middlewares/app-error/zod.handler.ts"],"names":[],"mappings":";;;AAAA,0DAA8C;AAI9C,MAAM,0BAA0B,GAAG,iBAAiB,CAAC;AAErD,iGAAiG;AACjG,MAAM,gBAAgB,GAAG,CAAC,IAA8B,EAAE,EAAE;IAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC;IAE5C,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF;;;;GAIG;AACI,MAAM,cAAc,GAAG,CAAC,IAM9B,EAAE,EAAE;IACH,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IAC3D,MAAM,UAAU,GAAG,oBAAI,CAAC,WAAW,CAAC,IAAI,CAAC,mBAAmB,CAAC;IAE7D,IAAI,gBAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,gBAAgB,GAAG,KAAK,CAAC;IAC3B,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAE,gBAAoC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE9F,qFAAqF;IACrF,mFAAmF;IACnF,IAAI,WAA+B,CAAC;IACpC,IAAI,OAAO,GAAG,0BAA0B,CAAC;IAEzC,IAAI,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,YAAY,GAChB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,gBAAgB,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,SAAS,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;QAC/E,WAAW,GAAG,gBAAgB,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC;QAC7E,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC;IACjC,CAAC;IAED,OAAO;QACL,UAAU;QACV,QAAQ,EAAE;YACR,OAAO;YACP,WAAW;YACX,UAAU;YACV,SAAS;YACT,OAAO,EAAE;gBACP,GAAG;gBACH,IAAI;gBACJ,KAAK,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;gBAC9C,KAAK,EAAE,MAAM;oBACX,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;wBAChB,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,MAAM;wBACjC,OAAO,EAAE,EAAE,CAAC,OAAO;wBACnB,IAAI,EAAE,EAAE,CAAC,IAAI;wBACb,QAAQ,EAAE,EAAE,CAAC,QAAQ;wBACrB,QAAQ,EAAE,EAAE,CAAC,QAAQ;qBACtB,CAAC,CAAC;oBACL,CAAC,CAAC,gBAAgB;aACrB;SACF;KACF,CAAC;AACJ,CAAC,CAAC;AAtDW,QAAA,cAAc,kBAsDzB"}