@venizia/ignis-kernel 0.2.0-0

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

@@ -0,0 +1,255 @@
+import { BaseHelper, EnvironmentNames, LogLevels, MessageCode } from '@venizia/ignis-helpers/core';
+import { HTTP, toJsonSafe } from '@venizia/ignis-helpers/common';
+import { REQUEST_ID_KEY } from '../common/index.js';
+import { isDatabaseClientError, isRetryableDatabaseError } from './database.handler.js';
+import { ApplicationErrorTypes, DATABASE_RETRYABLE_ERROR_CODE, DATABASE_RETRYABLE_ERROR_MESSAGE, } from './definition.js';
+import { formatZodError } from './zod.handler.js';
+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 = 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.
+ */
+export class BaseAppErrorMiddleware extends 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 !EnvironmentNames.DEVELOPMENT_ENVS.has(env.toLowerCase());
+    }
+    classify(opts) {
+        const { error, dbError } = opts;
+        if (dbError.isClientError) {
+            return ApplicationErrorTypes.DATABASE_CLIENT;
+        }
+        if (isRetryableDatabaseError({ error })) {
+            return ApplicationErrorTypes.DATABASE_RETRYABLE;
+        }
+        if ('statusCode' in error) {
+            return ApplicationErrorTypes.INTENTIONAL;
+        }
+        return 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 ??
+            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 = isDatabaseClientError({ error, isProduction });
+        const type = this.classify({ error, dbError });
+        switch (type) {
+            case ApplicationErrorTypes.DATABASE_CLIENT: {
+                return this.build({
+                    error,
+                    type,
+                    statusCode: 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 ApplicationErrorTypes.DATABASE_RETRYABLE: {
+                return this.build({
+                    error,
+                    type,
+                    statusCode: HTTP.ResultCodes.RS_4.Conflict,
+                    message: DATABASE_RETRYABLE_ERROR_MESSAGE,
+                    messageCode: DATABASE_RETRYABLE_ERROR_CODE,
+                });
+            }
+            case ApplicationErrorTypes.INTENTIONAL: {
+                return this.build({
+                    error,
+                    type,
+                    statusCode: error.statusCode,
+                    message: error.message,
+                });
+            }
+            default: {
+                return this.build({
+                    error,
+                    type: ApplicationErrorTypes.UNEXPECTED,
+                    statusCode: 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' && LogLevels.isValid(candidate)) {
+            return candidate;
+        }
+        return 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 === 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 === ApplicationErrorTypes.UNEXPECTED
+                ? this.unexpectedStackFrames
+                : this.intentionalStackFrames,
+        }));
+    }
+    value() {
+        return async (error, context) => {
+            const requestId = context.get(REQUEST_ID_KEY);
+            const isProduction = this.isProduction({ context, error, requestId });
+            if (error.name === 'ZodError') {
+                const rs = 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);
+        };
+    }
+}
+//# sourceMappingURL=app-error.middleware.js.map

package/dist/esm/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/esm/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/esm/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/esm/base/middlewares/app-error/database.handler.js

@@ -0,0 +1,39 @@
+import { DATABASE_CLIENT_ERROR_FALLBACK_MESSAGE, DATABASE_CLIENT_ERROR_MESSAGES, POSTGRES_CLIENT_ERROR_CLASSES, POSTGRES_RETRYABLE_ERROR_CODES, } from './definition.js';
+/** 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 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' || !POSTGRES_CLIENT_ERROR_CLASSES.includes(code.slice(0, 2))) {
+        return { isClientError: false };
+    }
+    const baseMessage = DATABASE_CLIENT_ERROR_MESSAGES[code] ?? 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'),
+    };
+};
+/** True for a transient, retryable transaction conflict (serialization failure / deadlock - SQLSTATE 40001 / 40P01) -> HTTP 409: the client can retry the same request. */
+export const isRetryableDatabaseError = (opts) => {
+    const dbError = opts.error;
+    const code = [dbError.code, dbError.cause?.code].find(Boolean);
+    return typeof code === 'string' && POSTGRES_RETRYABLE_ERROR_CODES.includes(code);
+};
+//# sourceMappingURL=database.handler.js.map

package/dist/esm/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,OAAO,EACL,sCAAsC,EACtC,8BAA8B,EAC9B,6BAA6B,EAC7B,8BAA8B,GAC/B,MAAM,cAAc,CAAC;AAGtB,wMAAwM;AACxM,MAAM,CAAC,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,6BAA6B,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,8BAA8B,CAAC,IAAI,CAAC,IAAI,sCAAsC,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;AAEF,2KAA2K;AAC3K,MAAM,CAAC,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,8BAA8B,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACnF,CAAC,CAAC"}

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

@@ -0,0 +1,85 @@
+import { CoreErrorCodes } from '../../../common/error-codes.js';
+/** 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 const 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. */
+export const POSTGRES_CLIENT_ERROR_CLASSES = ['22', '23', '44'];
+/** Human-readable message per specific SQLSTATE code. */
+export const DATABASE_CLIENT_ERROR_MESSAGES = {
+    // Class 22 - Data Exception
+    [PostgresErrorCodes.DATA_EXCEPTION]: 'Invalid data value',
+    [PostgresErrorCodes.STRING_DATA_TOO_LONG]: 'String data too long',
+    [PostgresErrorCodes.NUMERIC_VALUE_OUT_OF_RANGE]: 'Numeric value out of range',
+    [PostgresErrorCodes.NULL_VALUE_NOT_ALLOWED]: 'Null value not allowed',
+    [PostgresErrorCodes.INVALID_DATETIME_FORMAT]: 'Invalid date/time format',
+    [PostgresErrorCodes.DATETIME_FIELD_OVERFLOW]: 'Date/time field value out of range',
+    [PostgresErrorCodes.INVALID_TIME_ZONE_DISPLACEMENT_VALUE]: 'Invalid time zone displacement value',
+    [PostgresErrorCodes.SUBSTRING_ERROR]: 'Substring error',
+    [PostgresErrorCodes.DIVISION_BY_ZERO]: 'Division by zero',
+    [PostgresErrorCodes.INVALID_PARAMETER_VALUE]: 'Invalid parameter value',
+    [PostgresErrorCodes.INVALID_ESCAPE_SEQUENCE]: 'Invalid escape sequence',
+    [PostgresErrorCodes.STRING_DATA_LENGTH_MISMATCH]: 'String data length mismatch',
+    [PostgresErrorCodes.DUPLICATE_JSON_OBJECT_KEY_VALUE]: 'Duplicate JSON object key',
+    [PostgresErrorCodes.INVALID_JSON_TEXT]: 'Invalid JSON text',
+    [PostgresErrorCodes.FLOATING_POINT_EXCEPTION]: 'Floating point exception',
+    [PostgresErrorCodes.INVALID_TEXT_REPRESENTATION]: 'Invalid text representation',
+    [PostgresErrorCodes.INVALID_BINARY_REPRESENTATION]: 'Invalid binary representation',
+    [PostgresErrorCodes.UNTRANSLATABLE_CHARACTER]: 'Untranslatable character',
+    // Class 23 - Integrity Constraint Violation
+    [PostgresErrorCodes.INTEGRITY_CONSTRAINT_VIOLATION]: 'Integrity constraint violation',
+    [PostgresErrorCodes.RESTRICT_VIOLATION]: 'Restrict constraint violation',
+    [PostgresErrorCodes.NOT_NULL_VIOLATION]: 'Not null constraint violation',
+    [PostgresErrorCodes.FOREIGN_KEY_VIOLATION]: 'Foreign key constraint violation',
+    [PostgresErrorCodes.UNIQUE_VIOLATION]: 'Unique constraint violation',
+    [PostgresErrorCodes.CHECK_VIOLATION]: 'Check constraint violation',
+    [PostgresErrorCodes.EXCLUSION_VIOLATION]: 'Exclusion constraint violation',
+    // Class 44 - WITH CHECK OPTION Violation
+    [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. */
+export 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 const POSTGRES_RETRYABLE_ERROR_CODES = [
+    '40001', // serialization_failure
+    '40P01', // deadlock_detected
+];
+/** Safe, generic message + stable code for a retryable DB conflict (never leaks internals). */
+export const DATABASE_RETRYABLE_ERROR_MESSAGE = 'The request conflicted with a concurrent operation; please retry.';
+export const DATABASE_RETRYABLE_ERROR_CODE = CoreErrorCodes.DATABASE_CONFLICT;
+/** The branch a thrown value takes through the handler. */
+export class ApplicationErrorTypes {
+    static { this.DATABASE_CLIENT = 'database-client'; }
+    static { this.DATABASE_RETRYABLE = 'database-retryable'; }
+    static { this.INTENTIONAL = 'intentional'; }
+    static { this.UNEXPECTED = 'unexpected'; }
+}
+//# sourceMappingURL=definition.js.map

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

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

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

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

package/dist/esm/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,cAAc,wBAAwB,CAAC"}

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

@@ -0,0 +1,32 @@
+import type { TConstValue } from '@venizia/ignis-helpers/common';
+import type { ApplicationErrorTypes } from './definition.js';
+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

package/dist/esm/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,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,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;AAED,MAAM,MAAM,qBAAqB,GAAG,WAAW,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE9E,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC1E,qFAAqF;IACrF,IAAI,EAAE,qBAAqB,CAAC;CAC7B"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,28 @@
+import type { HTTPResponseError } from 'hono/types';
+/** Formats a ZodError into the 422 validation response. */
+export declare const formatZodError: (opts: {
+    isProduction: boolean;
+    requestId: string;
+    url: string;
+    path: string;
+    error: Error | HTTPResponseError;
+}) => {
+    statusCode: 422;
+    response: {
+        message: string;
+        statusCode: 422;
+        normalized: {
+            text: string;
+            code: string;
+            args: {};
+        };
+        requestId: string;
+        details: {
+            url: string;
+            path: string;
+            stack: string | undefined;
+            cause: unknown;
+        };
+    };
+};
+//# sourceMappingURL=zod.handler.d.ts.map

package/dist/esm/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":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAgBpD,2DAA2D;AAC3D,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;;;;;;;;;;;;;;;;;;CAmDA,CAAC"}

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

@@ -0,0 +1,59 @@
+import { MessageCode } from '@venizia/ignis-helpers/core';
+import { HTTP } from '@venizia/ignis-helpers/common';
+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. */
+export const formatZodError = (opts) => {
+    const { isProduction, requestId, url, path, error } = opts;
+    const statusCode = HTTP.ResultCodes.RS_4.UnprocessableEntity;
+    let validationErrors;
+    try {
+        validationErrors = JSON.parse(error.message);
+    }
+    catch {
+        validationErrors = error;
+    }
+    const issues = Array.isArray(validationErrors) ? validationErrors : null;
+    // Prefer the first issue with a custom `params.code`, else its raw Zod code.
+    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;
+    }
+    // A ZodError we could not parse into issues yields no code of its own; the response still carries one, so no error response is ever missing the field a client branches on.
+    const resolvedMessageCode = MessageCode.resolve(messageCode);
+    return {
+        statusCode,
+        response: {
+            message,
+            statusCode,
+            // `args` is empty: a Zod issue carries no interpolation values - per-field detail is in `details.cause`.
+            normalized: { text: message, code: resolvedMessageCode, args: {} },
+            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,
+            },
+        },
+    };
+};
+//# sourceMappingURL=zod.handler.js.map