@venizia/ignis-kernel 0.2.0-0

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

@@ -0,0 +1,76 @@
+import type { ILogger } from '@venizia/ignis-helpers/core';
+import { BaseHelper } from '@venizia/ignis-helpers/core';
+import type { IProvider } from '@venizia/ignis-inversion';
+import type { ErrorHandler } from 'hono/types';
+/** How a thrown error is rendered into the log line. Must never throw - a throw inside the error handler turns a handled failure into an unhandled one. */
+export type TErrorLogFormatter = (opts: {
+    error: unknown;
+    messageCode?: string;
+    extra?: Record<string, unknown>;
+    includeStack?: boolean;
+    maxStackFrames?: number;
+}) => string;
+/**
+ * Hono `onError`: ZodError -> 422, DB client error -> 400, retryable conflict -> 409, `getError` ->
+ * its own status, else 500. Browser-pure: the two reads that need a host - the ambient environment
+ * name and the error formatter - are constructor OPTIONS, not methods to subclass.
+ *
+ * They were hooks once, and three subclasses existed to answer them and nothing else. A class seam
+ * is also unreachable from application code, so the browser example had to fake the environment with
+ * a Hono middleware assigning `context.env`. `@venizia/ignis`'s `AppErrorMiddleware` now just
+ * supplies `process.env.NODE_ENV` and `ErrorPrettier` as options.
+ */
+export declare class BaseAppErrorMiddleware extends BaseHelper implements IProvider<ErrorHandler> {
+    private rootKey;
+    private intentionalStackFrames;
+    private unexpectedStackFrames;
+    /**
+     * How this host reads its ambient environment name, and the ONE option that says whether it has
+     * one at all: absent means it does not (a browser), so an unresolved name is by design; present
+     * but returning `undefined` means a host that should have one is misconfigured. Either way
+     * {@link isProduction} fails closed.
+     *
+     * A function, not a string: `process.env.NODE_ENV` has to be read per request, since a test - and
+     * a `--env-file` reload - can change it after the middleware is built.
+     */
+    private readonly environment?;
+    /** Replaces {@link renderErrorForLog} - `@venizia/ignis` passes `ErrorPrettier`, which reaches `node:util` and so cannot live here. */
+    private readonly formatErrorOverride?;
+    constructor(opts?: {
+        logger?: ILogger;
+        rootKey?: string;
+        intentionalStackFrames?: number;
+        unexpectedStackFrames?: number;
+        environment?: () => string | undefined;
+        formatError?: TErrorLogFormatter;
+    });
+    /** Renders a thrown error for the log, through the `formatError` option when one was given. */
+    protected formatError(opts: {
+        error: unknown;
+        messageCode?: string;
+        extra?: Record<string, unknown>;
+        includeStack?: boolean;
+        maxStackFrames?: number;
+    }): string;
+    /**
+     * The default log rendering: pure and deliberately small, so the whole middleware stays
+     * browser-pure.
+     *
+     * Must never throw, cycles included: a throw inside the error handler turns a handled failure
+     * into an unhandled one.
+     */
+    private renderErrorForLog;
+    private withRootKey;
+    /** Fail-closed: an unset or unrecognized env is production. */
+    private isProduction;
+    private classify;
+    /** An ApplicationError's `normalized` is authoritative - a `transform` may have reworded `text`. */
+    private build;
+    private resolve;
+    /** A throw site may set `logLevel` via `getError`; anything unset or malformed logs at `error`. */
+    private resolveLogLevel;
+    /** The one place a thrown error reaches the log - called once the status is known, so it carries it. */
+    private logError;
+    value(): ErrorHandler;
+}
+//# sourceMappingURL=app-error.middleware.d.ts.map

package/dist/cjs/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,KAAK,EAAE,OAAO,EAAa,MAAM,6BAA6B,CAAC;AAEtE,OAAO,EAAE,UAAU,EAA4C,MAAM,6BAA6B,CAAC;AAEnG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,YAAY,CAAC;AAiBlE,2JAA2J;AAC3J,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,KAAK,MAAM,CAAC;AA8Cb;;;;;;;;;GASG;AACH,qBAAa,sBAAuB,SAAQ,UAAW,YAAW,SAAS,CAAC,YAAY,CAAC;IACvF,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,qBAAqB,CAAS;IAEtC;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAA2B;IAExD,uIAAuI;IACvI,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAqB;gBAE9C,IAAI,CAAC,EAAE;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,sBAAsB,CAAC,EAAE,MAAM,CAAC;QAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAC/B,WAAW,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;QACvC,WAAW,CAAC,EAAE,kBAAkB,CAAC;KAClC;IAgBD,+FAA+F;IAC/F,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE;QAC1B,KAAK,EAAE,OAAO,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GAAG,MAAM;IAIV;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAuCzB,OAAO,CAAC,WAAW;IAInB,+DAA+D;IAC/D,OAAO,CAAC,YAAY;IAgCpB,OAAO,CAAC,QAAQ;IAkBhB,oGAAoG;IACpG,OAAO,CAAC,KAAK;IAsBb,OAAO,CAAC,OAAO;IA+Cf,mGAAmG;IACnG,OAAO,CAAC,eAAe;IAUvB,wGAAwG;IACxG,OAAO,CAAC,QAAQ;IAgChB,KAAK,IAAI,YAAY;CAiDtB"}

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

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAppErrorMiddleware = void 0;
+const core_1 = require("@venizia/ignis-helpers/core");
+const common_1 = require("@venizia/ignis-helpers/common");
+const common_2 = require("../common");
+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';
+/** An intentional error's throw site is still worth naming; its caller chain is framework plumbing, so it gets a smaller budget than an unexpected one. */
+const DEFAULT_INTENTIONAL_STACK_FRAMES = 5;
+const DEFAULT_UNEXPECTED_STACK_FRAMES = 10;
+/**
+ * Renders a value into one log-safe fragment.
+ *
+ * Redaction is not optional here. This runs on `extra`, which is whatever a throw site chose to
+ * attach - `getError({ extra: { apiKey } })` is a shape applications write - and in a Worker this
+ * fragment lands in the browser console. `toJsonSafe` masks secret-shaped keys; a hand-rolled
+ * `JSON.stringify` does not, and the server path has always redacted.
+ *
+ * The BigInt replacer stays: `toJsonSafe` leaves BigInt intact and `JSON.stringify` refuses it, so
+ * without this a single BigInt would collapse the whole fragment to the marker below. Anything else
+ * it refuses yields that marker rather than a throw - this is the last-resort error handler, where a
+ * throw turns a handled failure into an unhandled one.
+ */
+const renderValue = (opts) => {
+    const { value } = opts;
+    if (typeof value === 'string') {
+        return value;
+    }
+    const safe = (0, common_1.toJsonSafe)({ value });
+    try {
+        return JSON.stringify(safe) ?? String(value);
+    }
+    catch {
+        // A replacer is 6x the cost of plain stringify and deopts every key, so it is installed only
+        // once BigInt has actually thrown - the case it exists for, and the rare one.
+        try {
+            const rendered = JSON.stringify(safe, (_key, entry) => typeof entry === 'bigint' ? entry.toString() : entry);
+            return rendered ?? String(value);
+        }
+        catch {
+            // Not a swallowed failure: this marker IS the report, and it lands in the log line the caller
+            // is building.
+            return '[unrenderable]';
+        }
+    }
+};
+/**
+ * Hono `onError`: ZodError -> 422, DB client error -> 400, retryable conflict -> 409, `getError` ->
+ * its own status, else 500. Browser-pure: the two reads that need a host - the ambient environment
+ * name and the error formatter - are constructor OPTIONS, not methods to subclass.
+ *
+ * They were hooks once, and three subclasses existed to answer them and nothing else. A class seam
+ * is also unreachable from application code, so the browser example had to fake the environment with
+ * a Hono middleware assigning `context.env`. `@venizia/ignis`'s `AppErrorMiddleware` now just
+ * supplies `process.env.NODE_ENV` and `ErrorPrettier` as options.
+ */
+class BaseAppErrorMiddleware extends core_1.BaseHelper {
+    constructor(opts) {
+        // `new.target`, not a literal: a subclass logs under its own name, so `@venizia/ignis`'s
+        // `AppErrorMiddleware` keeps the scope it has always logged under.
+        super({ scope: new.target.name });
+        this.rootKey = opts?.rootKey;
+        this.intentionalStackFrames = opts?.intentionalStackFrames ?? DEFAULT_INTENTIONAL_STACK_FRAMES;
+        this.unexpectedStackFrames = opts?.unexpectedStackFrames ?? DEFAULT_UNEXPECTED_STACK_FRAMES;
+        this.environment = opts?.environment;
+        this.formatErrorOverride = opts?.formatError;
+        if (opts?.logger) {
+            this.logger = opts.logger;
+        }
+    }
+    /** Renders a thrown error for the log, through the `formatError` option when one was given. */
+    formatError(opts) {
+        return (this.formatErrorOverride ?? (o => this.renderErrorForLog(o)))(opts);
+    }
+    /**
+     * The default log rendering: pure and deliberately small, so the whole middleware stays
+     * browser-pure.
+     *
+     * Must never throw, cycles included: a throw inside the error handler turns a handled failure
+     * into an unhandled one.
+     */
+    renderErrorForLog(opts) {
+        const { error, messageCode, extra, includeStack = true, maxStackFrames } = opts;
+        const thrown = error;
+        const lines = [];
+        if (typeof thrown?.name === 'string') {
+            lines.push(`name: ${thrown.name}`);
+        }
+        lines.push(`message: ${typeof thrown?.message === 'string' ? thrown.message : renderValue({ value: error })}`);
+        if (messageCode) {
+            lines.push(`code: ${messageCode}`);
+        }
+        if (extra && Object.keys(extra).length > 0) {
+            lines.push(`extra: ${renderValue({ value: extra })}`);
+        }
+        if (includeStack && typeof thrown?.stack === 'string') {
+            const frames = thrown.stack.split('\n').filter(line => line.trimStart().startsWith('at '));
+            const capped = maxStackFrames === undefined ? frames : frames.slice(0, maxStackFrames);
+            if (capped.length > 0) {
+                lines.push(`stack:\n${capped.join('\n')}`);
+            }
+        }
+        return lines.map(line => `- ${line}`).join('\n');
+    }
+    withRootKey(payload) {
+        return this.rootKey ? { [this.rootKey]: payload } : payload;
+    }
+    /** Fail-closed: an unset or unrecognized env is production. */
+    isProduction(opts) {
+        const { context, error, requestId } = opts;
+        const env = [context.env?.NODE_ENV, this.environment?.()].find(Boolean);
+        if (!env) {
+            // Only a host that HAS an ambient environment can be misconfigured about it. In a browser the
+            // absence is by design, and shouting it at error level on every request buries the error the
+            // reader is actually looking at. Both paths still sanitize.
+            if (this.environment) {
+                this.logger.error('[%s] INVALID ENV IDENTIFIER | env: %s | path: %s | method: %s | url: %s\n%s', requestId, env, context.req.path, context.req.method, context.req.url, this.formatError({ error }));
+            }
+            else {
+                this.logger.debug('[%s] No ambient environment - sanitizing as production | path: %s | set NODE_ENV on the Hono env binding to opt out', requestId, context.req.path);
+            }
+            return true;
+        }
+        return !core_1.EnvironmentNames.DEVELOPMENT_ENVS.has(env.toLowerCase());
+    }
+    classify(opts) {
+        const { error, dbError } = opts;
+        if (dbError.isClientError) {
+            return definition_1.ApplicationErrorTypes.DATABASE_CLIENT;
+        }
+        if ((0, database_handler_1.isRetryableDatabaseError)({ error })) {
+            return definition_1.ApplicationErrorTypes.DATABASE_RETRYABLE;
+        }
+        if ('statusCode' in error) {
+            return definition_1.ApplicationErrorTypes.INTENTIONAL;
+        }
+        return definition_1.ApplicationErrorTypes.UNEXPECTED;
+    }
+    /** An ApplicationError's `normalized` is authoritative - a `transform` may have reworded `text`. */
+    build(opts) {
+        const { error, statusCode, message, type, messageCode } = opts;
+        // Fallback for a FOREIGN error that sets its own code; an ApplicationError reports via `normalized`.
+        const code = messageCode ??
+            core_1.MessageCode.resolve('messageCode' in error ? error.messageCode : undefined);
+        const normalized = 'normalized' in error
+            ? error.normalized
+            : { text: message, code, args: {} };
+        return { statusCode, message, normalized, type };
+    }
+    resolve(opts) {
+        const { error, isProduction } = opts;
+        const dbError = (0, database_handler_1.isDatabaseClientError)({ error, isProduction });
+        const type = this.classify({ error, dbError });
+        switch (type) {
+            case definition_1.ApplicationErrorTypes.DATABASE_CLIENT: {
+                return this.build({
+                    error,
+                    type,
+                    statusCode: common_1.HTTP.ResultCodes.RS_4.BadRequest,
+                    // The fallback is unreachable today; it keeps the driver's raw text from ever surfacing.
+                    message: dbError.message ?? DEFAULT_INTERNAL_ERROR_MESSAGE,
+                });
+            }
+            case definition_1.ApplicationErrorTypes.DATABASE_RETRYABLE: {
+                return this.build({
+                    error,
+                    type,
+                    statusCode: common_1.HTTP.ResultCodes.RS_4.Conflict,
+                    message: definition_1.DATABASE_RETRYABLE_ERROR_MESSAGE,
+                    messageCode: definition_1.DATABASE_RETRYABLE_ERROR_CODE,
+                });
+            }
+            case definition_1.ApplicationErrorTypes.INTENTIONAL: {
+                return this.build({
+                    error,
+                    type,
+                    statusCode: error.statusCode,
+                    message: error.message,
+                });
+            }
+            default: {
+                return this.build({
+                    error,
+                    type: definition_1.ApplicationErrorTypes.UNEXPECTED,
+                    statusCode: common_1.HTTP.ResultCodes.RS_5.InternalServerError,
+                    // Never leak a raw message - it may carry SQL, schema names or connection details.
+                    message: isProduction ? DEFAULT_INTERNAL_ERROR_MESSAGE : error.message,
+                });
+            }
+        }
+    }
+    /** A throw site may set `logLevel` via `getError`; anything unset or malformed logs at `error`. */
+    resolveLogLevel(opts) {
+        const candidate = opts.error.logLevel;
+        if (typeof candidate === 'string' && core_1.LogLevels.isValid(candidate)) {
+            return candidate;
+        }
+        return core_1.LogLevels.ERROR;
+    }
+    /** The one place a thrown error reaches the log - called once the status is known, so it carries it. */
+    logError(opts) {
+        const { error, context, requestId, statusCode, messageCode, type } = opts;
+        this.logger.log(this.resolveLogLevel({ error }), '[%s] REQUEST ERROR | %s | %s %s\n%s', requestId, statusCode, context.req.method, context.req.url, this.formatError({
+            error,
+            // The default code means "no code" - logging it on every error would be a noise line.
+            messageCode: messageCode === core_1.MessageCode.DEFAULT ? undefined : messageCode,
+            extra: 'extra' in error ? error.extra : undefined,
+            includeStack: true,
+            // An intentional error still needs its throw site; it just does not need the caller chain behind it.
+            maxStackFrames: type === definition_1.ApplicationErrorTypes.UNEXPECTED
+                ? this.unexpectedStackFrames
+                : this.intentionalStackFrames,
+        }));
+    }
+    value() {
+        return async (error, context) => {
+            const requestId = context.get(common_2.REQUEST_ID_KEY);
+            const isProduction = this.isProduction({ context, error, requestId });
+            if (error.name === 'ZodError') {
+                const rs = (0, zod_handler_1.formatZodError)({
+                    isProduction,
+                    requestId,
+                    url: context.req.url,
+                    path: context.req.path,
+                    error,
+                });
+                this.logError({
+                    error,
+                    context,
+                    requestId,
+                    statusCode: rs.statusCode,
+                    messageCode: rs.response.normalized.code,
+                });
+                return context.json(this.withRootKey(rs.response), rs.statusCode);
+            }
+            const { statusCode, message, normalized, type } = this.resolve({ error, isProduction });
+            this.logError({ error, context, requestId, statusCode, messageCode: normalized.code, type });
+            const rs = {
+                message,
+                statusCode,
+                normalized,
+                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(this.withRootKey(rs), statusCode);
+        };
+    }
+}
+exports.BaseAppErrorMiddleware = BaseAppErrorMiddleware;
+//# sourceMappingURL=app-error.middleware.js.map

package/dist/cjs/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/cjs/base/middlewares/app-error/database.handler.d.ts

@@ -0,0 +1,13 @@
+/** True for a database error caused by the request (SQLSTATE class 22/23/44) -> HTTP 400; in production the detail/table/constraint context is suppressed so no row values or schema internals leak. */
+export declare const isDatabaseClientError: (opts: {
+    error: Error;
+    isProduction: boolean;
+}) => {
+    isClientError: boolean;
+    message?: string;
+};
+/** True for a transient, retryable transaction conflict (serialization failure / deadlock - SQLSTATE 40001 / 40P01) -> 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/cjs/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,wMAAwM;AACxM,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;CAqC7C,CAAC;AAEF,2KAA2K;AAC3K,eAAO,MAAM,wBAAwB,GAAI,MAAM;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,KAAG,OAIjE,CAAC"}

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

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRetryableDatabaseError = exports.isDatabaseClientError = void 0;
+const definition_1 = require("./definition");
+/** True for a database error caused by the request (SQLSTATE class 22/23/44) -> HTTP 400; in production the detail/table/constraint context is suppressed so no row values or schema internals leak. */
+const isDatabaseClientError = (opts) => {
+    const { error, isProduction } = opts;
+    const dbError = error;
+    const cause = dbError.cause;
+    const code = [dbError.code, cause?.code].find(Boolean);
+    // Only request-caused SQLSTATE classes are client errors; a missing or non-string code (e.g. a gRPC numeric one) is 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 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;
+/** True for a transient, retryable transaction conflict (serialization failure / deadlock - SQLSTATE 40001 / 40P01) -> HTTP 409: the client can retry the same request. */
+const isRetryableDatabaseError = (opts) => {
+    const dbError = opts.error;
+    const code = [dbError.code, dbError.cause?.code].find(Boolean);
+    return typeof code === 'string' && definition_1.POSTGRES_RETRYABLE_ERROR_CODES.includes(code);
+};
+exports.isRetryableDatabaseError = isRetryableDatabaseError;
+//# sourceMappingURL=database.handler.js.map

package/dist/cjs/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,wMAAwM;AACjM,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,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEvD,8KAA8K;IAC9K,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,qIAAqI;IACrI,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;AAxCW,QAAA,qBAAqB,yBAwChC;AAEF,2KAA2K;AACpK,MAAM,wBAAwB,GAAG,CAAC,IAAsB,EAAW,EAAE;IAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,KAAuB,CAAC;IAC7C,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC/D,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,2CAA8B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACnF,CAAC,CAAC;AAJW,QAAA,wBAAwB,4BAInC"}

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

@@ -0,0 +1,48 @@
+/** PostgreSQL SQLSTATE codes representing a CLIENT error (HTTP 400) - caused by the request/data, not a server fault. @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) mapped to HTTP 400; codes without a specific message use {@link DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE}. Deliberately excluded (stay 500): 42, 53, 0A, 25, 28, 21, 54; class 40 is transient/retryable, NOT a 400. */
+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) - the transaction lost a concurrency race, not bad input (400) and not a server bug (500). */
+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: string;
+/** The branch a thrown value takes through the handler. */
+export declare class ApplicationErrorTypes {
+    static readonly DATABASE_CLIENT = "database-client";
+    static readonly DATABASE_RETRYABLE = "database-retryable";
+    static readonly INTENTIONAL = "intentional";
+    static readonly UNEXPECTED = "unexpected";
+}
+//# sourceMappingURL=definition.d.ts.map

package/dist/cjs/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":"AACA,6LAA6L;AAC7L,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BrB,CAAC;AAEX,4PAA4P;AAC5P,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,6KAA6K;AAC7K,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAG3D,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,gCAAgC,sEACwB,CAAC;AACtE,eAAO,MAAM,6BAA6B,QAAmC,CAAC;AAE9E,2DAA2D;AAC3D,qBAAa,qBAAqB;IAChC,MAAM,CAAC,QAAQ,CAAC,eAAe,qBAAqB;IACpD,MAAM,CAAC,QAAQ,CAAC,kBAAkB,wBAAwB;IAC1D,MAAM,CAAC,QAAQ,CAAC,WAAW,iBAAiB;IAC5C,MAAM,CAAC,QAAQ,CAAC,UAAU,gBAAgB;CAC3C"}

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

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApplicationErrorTypes = 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;
+const error_codes_1 = require("../../../common/error-codes");
+/** PostgreSQL SQLSTATE codes representing a CLIENT error (HTTP 400) - caused by the request/data, not a server fault. @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) mapped to HTTP 400; codes without a specific message use {@link DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE}. Deliberately excluded (stay 500): 42, 53, 0A, 25, 28, 21, 54; class 40 is transient/retryable, NOT a 400. */
+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) - the transaction lost a concurrency race, not bad input (400) and not a server bug (500). */
+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 = error_codes_1.CoreErrorCodes.DATABASE_CONFLICT;
+/** The branch a thrown value takes through the handler. */
+class ApplicationErrorTypes {
+    static { this.DATABASE_CLIENT = 'database-client'; }
+    static { this.DATABASE_RETRYABLE = 'database-retryable'; }
+    static { this.INTENTIONAL = 'intentional'; }
+    static { this.UNEXPECTED = 'unexpected'; }
+}
+exports.ApplicationErrorTypes = ApplicationErrorTypes;
+//# sourceMappingURL=definition.js.map

package/dist/cjs/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/cjs/base/middlewares/app-error/index.d.ts

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

package/dist/cjs/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/cjs/base/middlewares/app-error/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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("./app-error.middleware"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/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/cjs/base/middlewares/app-error/types.d.ts

@@ -0,0 +1,32 @@
+import type { TConstValue } from '@venizia/ignis-helpers/common';
+import type { ApplicationErrorTypes } from './definition';
+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;
+}
+export type TApplicationErrorType = TConstValue<typeof ApplicationErrorTypes>;
+export interface IResolvedApplicationError {
+    statusCode: number;
+    message: string;
+    normalized: {
+        text: string;
+        code: string;
+        args: Record<string, unknown>;
+    };
+    /** Drives whether the log carries a stack - only an UNEXPECTED failure needs one. */
+    type: TApplicationErrorType;
+}
+//# sourceMappingURL=types.d.ts.map