@constructive-io/errors 0.3.0

package/index.d.ts

@@ -0,0 +1,9 @@
+export * from './classify';
+export * from './error';
+export * from './factory';
+export * from './format';
+export * from './interpolate';
+export * from './parse';
+export * from './pg';
+export * from './registry';
+export * from './types';

package/index.js

@@ -0,0 +1,25 @@
+"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("./classify"), exports);
+__exportStar(require("./error"), exports);
+__exportStar(require("./factory"), exports);
+__exportStar(require("./format"), exports);
+__exportStar(require("./interpolate"), exports);
+__exportStar(require("./parse"), exports);
+__exportStar(require("./pg"), exports);
+__exportStar(require("./registry"), exports);
+__exportStar(require("./types"), exports);

package/interpolate.d.ts

@@ -0,0 +1,6 @@
+import type { ErrorContext } from './types';
+/**
+ * Replace `{{key}}` placeholders in a template with values from `context`.
+ * Missing keys render as an empty string.
+ */
+export declare function interpolate(template: string, context?: ErrorContext): string;

package/interpolate.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.interpolate = interpolate;
+const PLACEHOLDER = /\{\{\s*(\w+)\s*\}\}/g;
+/**
+ * Replace `{{key}}` placeholders in a template with values from `context`.
+ * Missing keys render as an empty string.
+ */
+function interpolate(template, context = {}) {
+    return template.replace(PLACEHOLDER, (_match, key) => {
+        const value = context[key];
+        return value === undefined || value === null ? '' : String(value);
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@constructive-io/errors",
+  "version": "0.3.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "Canonical Constructive error system: registry, codes, i18n messages, and cross-source (PostgreSQL/GraphQL/client) parsing. Zero runtime dependencies.",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
+  },
+  "keywords": [
+    "errors",
+    "error-codes",
+    "i18n",
+    "constructive",
+    "postgresql",
+    "graphql"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "makage": "^0.3.0",
+    "ts-node": "^10.9.2"
+  },
+  "gitHead": "bb3269d48cdf2bc8f361bdd79b4833c921c13ec3"
+}

package/parse.d.ts

@@ -0,0 +1,30 @@
+import { ConstructiveError } from './error';
+import type { ParsedError } from './types';
+/**
+ * Normalize an error from any source (a {@link ConstructiveError}, a node-postgres
+ * `DatabaseError`, a GraphQL error or `{ errors: [...] }` wrapper, a plain
+ * `Error`, or a string) into a canonical {@link ParsedError}.
+ *
+ * Resolution order for the code:
+ * 1. structured `DETAIL` JSON (`{ code, context }`) — Constructive's DB transport
+ * 2. GraphQL `extensions.code`
+ * 3. a leading ALL_CAPS token in the message (legacy DB `RAISE`), with any
+ *    `(arg, arg)` positional args mapped onto named context via the registry
+ * 4. native SQLSTATE constraint mapping (23505 → `UNIQUE_VIOLATION`, …)
+ *
+ * Classification trusts an explicit `class` provided by the producer — the
+ * database transport's `DETAIL.class` or the server's `extensions.class` — when
+ * present, since that source is authoritative for the raise site (and correctly
+ * classifies codes not yet in the registry). It falls back to `classify(code)`
+ * (registry lookup, unknown ⇒ `internal`) only when no explicit class is given.
+ */
+export declare function parse(error: unknown): ParsedError;
+/**
+ * Normalize any error into a throwable {@link ConstructiveError}.
+ *
+ * Delegates to {@link parse} for code/context/class recovery, then resolves a
+ * localized message from the registry catalogs (falling back to the source
+ * error's raw message when the code is unknown) and the registry's HTTP hint.
+ * Codes that could not be resolved become `UNKNOWN_ERROR` (internal).
+ */
+export declare function toError(error: unknown, locale?: string): ConstructiveError;

package/parse.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parse = parse;
+exports.toError = toError;
+const classify_1 = require("./classify");
+const error_1 = require("./error");
+const format_1 = require("./format");
+const pg_1 = require("./pg");
+const registry_1 = require("./registry");
+/** Leading ALL_CAPS token, optionally followed by `(arg, arg)` positional args. */
+const CODE_TOKEN = /^([A-Z][A-Z0-9_]+)(?:\s*\((.*)\))?\s*$/;
+/** Narrow an arbitrary value to a valid {@link ErrorClass}, else `null`. */
+function toErrorClass(value) {
+    return value === 'public' || value === 'internal' ? value : null;
+}
+function getMessage(error) {
+    if (typeof error === 'string')
+        return error;
+    if (error instanceof Error)
+        return error.message;
+    if (error && typeof error === 'object' && typeof error.message === 'string') {
+        return error.message;
+    }
+    return String(error);
+}
+/** Pull GraphQL-shaped fields, including the `{ errors: [...] }` request wrapper. */
+function extractGraphqlLike(error) {
+    if (!error || typeof error !== 'object')
+        return null;
+    const e = error;
+    const fromNode = (node) => {
+        if (!node)
+            return null;
+        const extensions = node.extensions;
+        const out = {};
+        if (typeof node.message === 'string')
+            out.message = node.message;
+        if (extensions && typeof extensions.code === 'string')
+            out.extensionsCode = extensions.code;
+        if (extensions && extensions.context && typeof extensions.context === 'object') {
+            out.extensionsContext = extensions.context;
+        }
+        if (extensions) {
+            const cls = toErrorClass(extensions.class);
+            if (cls)
+                out.extensionsClass = cls;
+        }
+        return out.message || out.extensionsCode ? out : null;
+    };
+    if (Array.isArray(e.errors) && e.errors.length > 0) {
+        const first = fromNode(e.errors[0]);
+        if (first)
+            return first;
+    }
+    return fromNode(e);
+}
+function parseDetailJson(detail) {
+    if (!detail)
+        return null;
+    const trimmed = detail.trim();
+    if (!trimmed.startsWith('{'))
+        return null;
+    try {
+        const obj = JSON.parse(trimmed);
+        if (obj && typeof obj.code === 'string') {
+            const context = obj.context && typeof obj.context === 'object' ? obj.context : {};
+            return { code: obj.code, context, class: toErrorClass(obj.class) };
+        }
+    }
+    catch {
+        // not structured json — fall through
+    }
+    return null;
+}
+function coerce(value) {
+    if (value === '')
+        return value;
+    const num = Number(value);
+    return Number.isNaN(num) ? value : num;
+}
+/** Map legacy positional args (`CODE (a, b)`) onto named context keys. */
+function mapPositional(code, args) {
+    if (args.length === 0)
+        return {};
+    const positional = (0, registry_1.getDefinition)(code)?.positional;
+    if (!positional || positional.length === 0) {
+        return { args: args.join(', ') };
+    }
+    const context = {};
+    positional.forEach((key, i) => {
+        if (i < args.length)
+            context[key] = coerce(args[i]);
+    });
+    return context;
+}
+function parseMessageCode(message) {
+    const m = message.trim().match(CODE_TOKEN);
+    if (!m)
+        return null;
+    return { code: m[1], args: m[2] !== undefined ? m[2].split(',').map((s) => s.trim()).filter(Boolean) : [] };
+}
+/**
+ * Normalize an error from any source (a {@link ConstructiveError}, a node-postgres
+ * `DatabaseError`, a GraphQL error or `{ errors: [...] }` wrapper, a plain
+ * `Error`, or a string) into a canonical {@link ParsedError}.
+ *
+ * Resolution order for the code:
+ * 1. structured `DETAIL` JSON (`{ code, context }`) — Constructive's DB transport
+ * 2. GraphQL `extensions.code`
+ * 3. a leading ALL_CAPS token in the message (legacy DB `RAISE`), with any
+ *    `(arg, arg)` positional args mapped onto named context via the registry
+ * 4. native SQLSTATE constraint mapping (23505 → `UNIQUE_VIOLATION`, …)
+ *
+ * Classification trusts an explicit `class` provided by the producer — the
+ * database transport's `DETAIL.class` or the server's `extensions.class` — when
+ * present, since that source is authoritative for the raise site (and correctly
+ * classifies codes not yet in the registry). It falls back to `classify(code)`
+ * (registry lookup, unknown ⇒ `internal`) only when no explicit class is given.
+ */
+function parse(error) {
+    if (error instanceof error_1.ConstructiveError) {
+        return {
+            code: error.code,
+            context: error.context ?? {},
+            class: error.errorClass,
+            known: Boolean((0, registry_1.getDefinition)(error.code)),
+            rawMessage: error.message,
+            originalError: error
+        };
+    }
+    const pg = (0, pg_1.extractPgErrorFields)(error);
+    const gql = extractGraphqlLike(error);
+    const rawMessage = gql?.message ?? getMessage(error);
+    const sqlState = pg?.code;
+    let code = null;
+    let context = {};
+    let explicitClass = null;
+    const detail = parseDetailJson(pg?.detail);
+    if (detail) {
+        code = detail.code;
+        context = { ...detail.context };
+        explicitClass = detail.class;
+    }
+    if (!code && gql?.extensionsCode) {
+        code = gql.extensionsCode;
+        if (gql.extensionsContext)
+            context = { ...gql.extensionsContext };
+        if (gql.extensionsClass)
+            explicitClass = gql.extensionsClass;
+    }
+    if (!code) {
+        const parsedMsg = parseMessageCode(gql?.message ?? rawMessage);
+        if (parsedMsg && parsedMsg.code !== pg_1.RAISE_EXCEPTION_SQLSTATE) {
+            code = parsedMsg.code;
+            context = mapPositional(parsedMsg.code, parsedMsg.args);
+        }
+    }
+    if ((!code || code === pg_1.RAISE_EXCEPTION_SQLSTATE) && sqlState && pg_1.SQLSTATE_TO_CODE[sqlState]) {
+        code = pg_1.SQLSTATE_TO_CODE[sqlState];
+        if (pg?.constraint)
+            context.constraint = pg.constraint;
+        if (pg?.table)
+            context.table = pg.table;
+        if (pg?.column)
+            context.column = pg.column;
+    }
+    if (code === pg_1.RAISE_EXCEPTION_SQLSTATE)
+        code = null;
+    return {
+        code,
+        context,
+        class: explicitClass ?? (0, classify_1.classify)(code),
+        known: Boolean(code && (0, registry_1.getDefinition)(code)),
+        rawMessage,
+        sqlState,
+        originalError: error
+    };
+}
+/**
+ * Normalize any error into a throwable {@link ConstructiveError}.
+ *
+ * Delegates to {@link parse} for code/context/class recovery, then resolves a
+ * localized message from the registry catalogs (falling back to the source
+ * error's raw message when the code is unknown) and the registry's HTTP hint.
+ * Codes that could not be resolved become `UNKNOWN_ERROR` (internal).
+ */
+function toError(error, locale) {
+    if (error instanceof error_1.ConstructiveError)
+        return error;
+    const parsed = parse(error);
+    const code = parsed.code ?? 'UNKNOWN_ERROR';
+    const def = (0, registry_1.getDefinition)(code);
+    const message = parsed.known
+        ? (0, format_1.format)(code, parsed.context, locale)
+        : parsed.rawMessage || (0, format_1.format)(code, parsed.context, locale);
+    return new error_1.ConstructiveError({
+        code,
+        message,
+        errorClass: parsed.class,
+        http: def?.http ?? 500,
+        context: parsed.context
+    });
+}

package/pg.d.ts

@@ -0,0 +1,14 @@
+import type { PgErrorFields } from './types';
+/**
+ * PostgreSQL SQLSTATE codes for the native constraint violations we surface as
+ * public Constructive codes.
+ */
+export declare const SQLSTATE_TO_CODE: Record<string, string>;
+/** SQLSTATE for a user-raised `RAISE EXCEPTION` without an explicit ERRCODE. */
+export declare const RAISE_EXCEPTION_SQLSTATE = "P0001";
+/**
+ * Extract extended PostgreSQL error fields from an error-like object. Returns
+ * `null` when the value does not look like a pg error (no `code`/`detail`/
+ * `where`).
+ */
+export declare function extractPgErrorFields(err: unknown): PgErrorFields | null;

package/pg.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAISE_EXCEPTION_SQLSTATE = exports.SQLSTATE_TO_CODE = void 0;
+exports.extractPgErrorFields = extractPgErrorFields;
+/**
+ * PostgreSQL SQLSTATE codes for the native constraint violations we surface as
+ * public Constructive codes.
+ */
+exports.SQLSTATE_TO_CODE = {
+    23505: 'UNIQUE_VIOLATION',
+    23503: 'FOREIGN_KEY_VIOLATION',
+    23502: 'NOT_NULL_VIOLATION',
+    23514: 'CHECK_VIOLATION',
+    '23P01': 'EXCLUSION_VIOLATION'
+};
+/** SQLSTATE for a user-raised `RAISE EXCEPTION` without an explicit ERRCODE. */
+exports.RAISE_EXCEPTION_SQLSTATE = 'P0001';
+/**
+ * Extract extended PostgreSQL error fields from an error-like object. Returns
+ * `null` when the value does not look like a pg error (no `code`/`detail`/
+ * `where`).
+ */
+function extractPgErrorFields(err) {
+    if (!err || typeof err !== 'object')
+        return null;
+    const e = err;
+    if (!e.code && !e.detail && !e.where)
+        return null;
+    const fields = {};
+    const assign = (key) => {
+        const value = e[key];
+        if (typeof value === 'string')
+            fields[key] = value;
+    };
+    [
+        'code',
+        'detail',
+        'hint',
+        'where',
+        'position',
+        'internalPosition',
+        'internalQuery',
+        'schema',
+        'table',
+        'column',
+        'dataType',
+        'constraint',
+        'file',
+        'line',
+        'routine'
+    ].forEach(assign);
+    return fields;
+}

package/registry.d.ts

@@ -0,0 +1,147 @@
+import type { ErrorContext, ErrorDefinition } from './types';
+export { type DefinedError, defineError } from './define';
+/**
+ * The curated Constructive error registry.
+ *
+ * These entries carry refined, typed context and hand-written copy for the
+ * codes that matter most (public auth/limit codes with real dashboard copy,
+ * native PostgreSQL constraint codes, and the pgpm CLI codes). They OVERRIDE
+ * the generated entries in {@link generatedRegistry} — every constructive-db
+ * code is present via generation; these just refine a subset.
+ */
+export declare const registry: {
+    readonly ACCOUNT_EXISTS: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly ACCOUNT_NOT_FOUND: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly NO_ACCOUNT_EXISTS: import("./define").DefinedError<{
+        userId?: string;
+    }>;
+    readonly INVALID_CREDENTIALS: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly INCORRECT_PASSWORD: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly ACCOUNT_LOCKED_EXCEED_ATTEMPTS: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly ACCOUNT_DISABLED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly PASSWORD_INSECURE: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly PASSWORD_LEN: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly EMAIL_NOT_VERIFIED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly SIGN_UP_DISABLED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly USER_NOT_AUTHENTICATED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly ACCOUNT_LOCKED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly USER_NOT_FOUND: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly NO_PRIMARY_EMAIL: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly NO_CREDENTIALS: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly BAD_SIGNIN: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly SSO_SIGN_IN_DISABLED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly SSO_SIGN_UP_DISABLED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly SSO_ACCOUNT_NOT_FOUND: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly MAGIC_LINK_SIGN_IN_DISABLED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly MAGIC_LINK_SIGN_UP_DISABLED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly EMAIL_OTP_SIGN_IN_DISABLED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly INVALID_PUBLIC_KEY: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly INVALID_MESSAGE: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly INVALID_SIGNATURE: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly UPLOAD_MIMETYPE: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly SINGLETON_TABLE: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly INVITE_NOT_FOUND: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly INVITE_LIMIT: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly INVITE_EMAIL_NOT_FOUND: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly UNAUTHENTICATED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly FORBIDDEN: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly STEP_UP_REQUIRED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly MFA_REQUIRED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly INVALID_TOKEN: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly LIMIT_REACHED: import("./define").DefinedError<{
+        resource?: string;
+        limit?: number;
+    }>;
+    readonly RATE_LIMITED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly NETWORK_ERROR: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly TIMEOUT_ERROR: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly BAD_USER_INPUT: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly VALIDATION_FAILED: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly UNKNOWN_ERROR: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly UNIQUE_VIOLATION: import("./define").DefinedError<{
+        constraint?: string;
+        table?: string;
+    }>;
+    readonly FOREIGN_KEY_VIOLATION: import("./define").DefinedError<{
+        constraint?: string;
+        table?: string;
+    }>;
+    readonly NOT_NULL_VIOLATION: import("./define").DefinedError<{
+        column?: string;
+        table?: string;
+    }>;
+    readonly CHECK_VIOLATION: import("./define").DefinedError<{
+        constraint?: string;
+        table?: string;
+    }>;
+    readonly EXCLUSION_VIOLATION: import("./define").DefinedError<{
+        constraint?: string;
+        table?: string;
+    }>;
+    readonly NOT_FOUND: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly MODULE_NOT_FOUND: import("./define").DefinedError<{
+        name: string;
+    }>;
+    readonly INTERNAL_FAILURE: import("./define").DefinedError<{
+        details: string;
+    }>;
+    readonly CONTEXT_MISSING: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly NOT_IN_WORKSPACE: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly NOT_IN_WORKSPACE_MODULE: import("./define").DefinedError<import("./types").EmptyContext>;
+    readonly DEPLOYMENT_FAILED: import("./define").DefinedError<{
+        type: "Deployment" | "Revert" | "Verify";
+        module: string;
+    }>;
+    readonly UNSUPPORTED_TYPE_HINT: import("./define").DefinedError<{
+        typeHint: string;
+    }>;
+    readonly BAD_FILE_NAME: import("./define").DefinedError<{
+        name: string;
+    }>;
+    readonly UNKNOWN_COMMAND: import("./define").DefinedError<{
+        cmd: string;
+    }>;
+    readonly CHANGE_NOT_FOUND: import("./define").DefinedError<{
+        change: string;
+        plan?: string;
+    }>;
+    readonly TAG_NOT_FOUND: import("./define").DefinedError<{
+        tag: string;
+        project?: string;
+    }>;
+    readonly PATH_NOT_FOUND: import("./define").DefinedError<{
+        path: string;
+        type: "module" | "workspace" | "file";
+    }>;
+    readonly OPERATION_FAILED: import("./define").DefinedError<{
+        operation: string;
+        target?: string;
+        reason?: string;
+    }>;
+    readonly PLAN_PARSE_ERROR: import("./define").DefinedError<{
+        planPath: string;
+        errors: string;
+    }>;
+    readonly CIRCULAR_DEPENDENCY: import("./define").DefinedError<{
+        module: string;
+        dependency: string;
+    }>;
+    readonly INVALID_NAME: import("./define").DefinedError<{
+        name: string;
+        type: "tag" | "change" | "module";
+        rules?: string;
+    }>;
+    readonly WORKSPACE_OPERATION_ERROR: import("./define").DefinedError<{
+        operation: string;
+    }>;
+    readonly FILE_NOT_FOUND: import("./define").DefinedError<{
+        filePath: string;
+        type?: string;
+    }>;
+};
+export type Registry = typeof registry;
+export type RegistryCode = keyof Registry;
+/** Look up a definition by code (from anywhere, not just typed keys). */
+export declare function getDefinition(code: string): ErrorDefinition<ErrorContext> | undefined;
+/** Every registered code (curated + generated). */
+export declare function allCodes(): string[];