@constructive-io/errors 0.3.0

package/registry.js

@@ -0,0 +1,474 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registry = exports.defineError = void 0;
+exports.getDefinition = getDefinition;
+exports.allCodes = allCodes;
+const define_1 = require("./define");
+const registry_generated_1 = require("./generated/registry.generated");
+var define_2 = require("./define");
+Object.defineProperty(exports, "defineError", { enumerable: true, get: function () { return define_2.defineError; } });
+/**
+ * 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.
+ */
+exports.registry = {
+    // ===========================================================================
+    // Auth / account (public) — copy sourced from dashboard auth-errors.ts
+    // ===========================================================================
+    ACCOUNT_EXISTS: (0, define_1.defineError)({
+        code: 'ACCOUNT_EXISTS',
+        class: 'public',
+        http: 409,
+        message: 'An account with this email already exists. Please sign in or use a different email.'
+    }),
+    ACCOUNT_NOT_FOUND: (0, define_1.defineError)({
+        code: 'ACCOUNT_NOT_FOUND',
+        class: 'public',
+        http: 404,
+        message: 'No account was found.'
+    }),
+    NO_ACCOUNT_EXISTS: (0, define_1.defineError)({
+        code: 'NO_ACCOUNT_EXISTS',
+        class: 'public',
+        http: 404,
+        message: 'No account exists for this user.'
+    }),
+    INVALID_CREDENTIALS: (0, define_1.defineError)({
+        code: 'INVALID_CREDENTIALS',
+        class: 'public',
+        http: 401,
+        message: 'Invalid email or password.'
+    }),
+    INCORRECT_PASSWORD: (0, define_1.defineError)({
+        code: 'INCORRECT_PASSWORD',
+        class: 'public',
+        http: 401,
+        message: 'The password you entered is incorrect. Please try again.'
+    }),
+    ACCOUNT_LOCKED_EXCEED_ATTEMPTS: (0, define_1.defineError)({
+        code: 'ACCOUNT_LOCKED_EXCEED_ATTEMPTS',
+        class: 'public',
+        http: 423,
+        message: 'Your account has been temporarily locked due to too many failed login attempts. Please try again later or reset your password.'
+    }),
+    ACCOUNT_DISABLED: (0, define_1.defineError)({
+        code: 'ACCOUNT_DISABLED',
+        class: 'public',
+        http: 403,
+        message: 'Your account has been disabled. Please contact support for assistance.'
+    }),
+    PASSWORD_INSECURE: (0, define_1.defineError)({
+        code: 'PASSWORD_INSECURE',
+        class: 'public',
+        http: 400,
+        message: 'This password is not secure enough. Please choose a stronger password.'
+    }),
+    PASSWORD_LEN: (0, define_1.defineError)({
+        code: 'PASSWORD_LEN',
+        class: 'public',
+        http: 400,
+        message: 'Password must be between 8 and 63 characters long.'
+    }),
+    EMAIL_NOT_VERIFIED: (0, define_1.defineError)({
+        code: 'EMAIL_NOT_VERIFIED',
+        class: 'public',
+        http: 403,
+        message: 'Please verify your email address to continue.'
+    }),
+    SIGN_UP_DISABLED: (0, define_1.defineError)({
+        code: 'SIGN_UP_DISABLED',
+        class: 'public',
+        http: 403,
+        message: 'Sign-up is currently disabled.'
+    }),
+    // ===========================================================================
+    // Auth / account (public) — migrated from the server graphile SAFE_ERROR_CODES
+    // allowlist so the registry (not a hand-maintained set) is the source of truth
+    // for what is user-facing.
+    // ===========================================================================
+    USER_NOT_AUTHENTICATED: (0, define_1.defineError)({
+        code: 'USER_NOT_AUTHENTICATED',
+        class: 'public',
+        http: 401,
+        message: 'You must be signed in to do that.'
+    }),
+    ACCOUNT_LOCKED: (0, define_1.defineError)({
+        code: 'ACCOUNT_LOCKED',
+        class: 'public',
+        http: 423,
+        message: 'Your account is locked. Please try again later or reset your password.'
+    }),
+    USER_NOT_FOUND: (0, define_1.defineError)({
+        code: 'USER_NOT_FOUND',
+        class: 'public',
+        http: 404,
+        message: 'No matching user was found.'
+    }),
+    NO_PRIMARY_EMAIL: (0, define_1.defineError)({
+        code: 'NO_PRIMARY_EMAIL',
+        class: 'public',
+        http: 400,
+        message: 'No primary email address is set for this account.'
+    }),
+    NO_CREDENTIALS: (0, define_1.defineError)({
+        code: 'NO_CREDENTIALS',
+        class: 'public',
+        http: 400,
+        message: 'No credentials were provided.'
+    }),
+    BAD_SIGNIN: (0, define_1.defineError)({
+        code: 'BAD_SIGNIN',
+        class: 'public',
+        http: 401,
+        message: 'Sign in failed. Please check your credentials and try again.'
+    }),
+    // ===========================================================================
+    // Auth method toggles (public) — app-level allow_* settings
+    // ===========================================================================
+    SSO_SIGN_IN_DISABLED: (0, define_1.defineError)({
+        code: 'SSO_SIGN_IN_DISABLED',
+        class: 'public',
+        http: 403,
+        message: 'Single sign-on is not enabled for sign in.'
+    }),
+    SSO_SIGN_UP_DISABLED: (0, define_1.defineError)({
+        code: 'SSO_SIGN_UP_DISABLED',
+        class: 'public',
+        http: 403,
+        message: 'Single sign-on is not enabled for sign up.'
+    }),
+    SSO_ACCOUNT_NOT_FOUND: (0, define_1.defineError)({
+        code: 'SSO_ACCOUNT_NOT_FOUND',
+        class: 'public',
+        http: 404,
+        message: 'No single sign-on account was found.'
+    }),
+    MAGIC_LINK_SIGN_IN_DISABLED: (0, define_1.defineError)({
+        code: 'MAGIC_LINK_SIGN_IN_DISABLED',
+        class: 'public',
+        http: 403,
+        message: 'Magic link sign in is disabled.'
+    }),
+    MAGIC_LINK_SIGN_UP_DISABLED: (0, define_1.defineError)({
+        code: 'MAGIC_LINK_SIGN_UP_DISABLED',
+        class: 'public',
+        http: 403,
+        message: 'Magic link sign up is disabled.'
+    }),
+    EMAIL_OTP_SIGN_IN_DISABLED: (0, define_1.defineError)({
+        code: 'EMAIL_OTP_SIGN_IN_DISABLED',
+        class: 'public',
+        http: 403,
+        message: 'Email one-time-code sign in is disabled.'
+    }),
+    // ===========================================================================
+    // PublicKeySignature / uploads / misc (public) — migrated from the allowlist
+    // ===========================================================================
+    INVALID_PUBLIC_KEY: (0, define_1.defineError)({
+        code: 'INVALID_PUBLIC_KEY',
+        class: 'public',
+        http: 400,
+        message: 'The public key is invalid.'
+    }),
+    INVALID_MESSAGE: (0, define_1.defineError)({
+        code: 'INVALID_MESSAGE',
+        class: 'public',
+        http: 400,
+        message: 'The message is invalid.'
+    }),
+    INVALID_SIGNATURE: (0, define_1.defineError)({
+        code: 'INVALID_SIGNATURE',
+        class: 'public',
+        http: 401,
+        message: 'The signature is invalid.'
+    }),
+    UPLOAD_MIMETYPE: (0, define_1.defineError)({
+        code: 'UPLOAD_MIMETYPE',
+        class: 'public',
+        http: 415,
+        message: 'This file type is not allowed.'
+    }),
+    SINGLETON_TABLE: (0, define_1.defineError)({
+        code: 'SINGLETON_TABLE',
+        class: 'public',
+        http: 409,
+        message: 'Only one record is allowed for this resource.'
+    }),
+    // ===========================================================================
+    // Invites (public)
+    // ===========================================================================
+    INVITE_NOT_FOUND: (0, define_1.defineError)({
+        code: 'INVITE_NOT_FOUND',
+        class: 'public',
+        http: 404,
+        message: 'The invitation code is invalid or has expired. Please check the code or request a new invitation.'
+    }),
+    INVITE_LIMIT: (0, define_1.defineError)({
+        code: 'INVITE_LIMIT',
+        class: 'public',
+        http: 429,
+        message: 'This invitation has reached its usage limit. Please request a new invitation.'
+    }),
+    INVITE_EMAIL_NOT_FOUND: (0, define_1.defineError)({
+        code: 'INVITE_EMAIL_NOT_FOUND',
+        class: 'public',
+        http: 404,
+        message: 'This email is not associated with the invitation. Please use the email address the invitation was sent to.'
+    }),
+    // ===========================================================================
+    // Authorization / step-up (public)
+    // ===========================================================================
+    UNAUTHENTICATED: (0, define_1.defineError)({
+        code: 'UNAUTHENTICATED',
+        class: 'public',
+        http: 401,
+        message: 'You must be signed in to do that.'
+    }),
+    FORBIDDEN: (0, define_1.defineError)({
+        code: 'FORBIDDEN',
+        class: 'public',
+        http: 403,
+        message: 'You do not have permission to do that.'
+    }),
+    STEP_UP_REQUIRED: (0, define_1.defineError)({
+        code: 'STEP_UP_REQUIRED',
+        class: 'public',
+        http: 403,
+        message: 'Additional verification is required to continue.'
+    }),
+    MFA_REQUIRED: (0, define_1.defineError)({
+        code: 'MFA_REQUIRED',
+        class: 'public',
+        http: 403,
+        message: 'Multi-factor authentication is required to continue.'
+    }),
+    INVALID_TOKEN: (0, define_1.defineError)({
+        code: 'INVALID_TOKEN',
+        class: 'public',
+        http: 401,
+        message: 'This link or token is invalid or has expired.'
+    }),
+    // ===========================================================================
+    // Limits (public, dynamic)
+    // ===========================================================================
+    LIMIT_REACHED: (0, define_1.defineError)({
+        code: 'LIMIT_REACHED',
+        class: 'public',
+        http: 429,
+        message: 'You have reached a plan limit for this resource.',
+        positional: ['resource', 'limit']
+    }),
+    RATE_LIMITED: (0, define_1.defineError)({
+        code: 'RATE_LIMITED',
+        class: 'public',
+        http: 429,
+        message: 'Too many requests. Please slow down and try again shortly.'
+    }),
+    // ===========================================================================
+    // Client / transport (public) — synthesized client-side by the GraphQL client
+    // for network, timeout, and HTTP-level failures (no DB/server origin).
+    // ===========================================================================
+    NETWORK_ERROR: (0, define_1.defineError)({
+        code: 'NETWORK_ERROR',
+        class: 'public',
+        http: 0,
+        message: 'Network error. Please check your connection and try again.'
+    }),
+    TIMEOUT_ERROR: (0, define_1.defineError)({
+        code: 'TIMEOUT_ERROR',
+        class: 'public',
+        http: 408,
+        message: 'The request timed out. Please try again.'
+    }),
+    BAD_USER_INPUT: (0, define_1.defineError)({
+        code: 'BAD_USER_INPUT',
+        class: 'public',
+        http: 400,
+        message: 'The request was invalid. Please check your input and try again.'
+    }),
+    VALIDATION_FAILED: (0, define_1.defineError)({
+        code: 'VALIDATION_FAILED',
+        class: 'public',
+        http: 400,
+        message: 'Validation failed. Please check your input and try again.'
+    }),
+    UNKNOWN_ERROR: (0, define_1.defineError)({
+        code: 'UNKNOWN_ERROR',
+        class: 'internal',
+        http: 500,
+        message: 'An unexpected error occurred.'
+    }),
+    // ===========================================================================
+    // Native PostgreSQL constraint violations (public) — synthetic codes mapped
+    // from SQLSTATE by parse().
+    // ===========================================================================
+    UNIQUE_VIOLATION: (0, define_1.defineError)({
+        code: 'UNIQUE_VIOLATION',
+        class: 'public',
+        http: 409,
+        message: 'That value already exists.'
+    }),
+    FOREIGN_KEY_VIOLATION: (0, define_1.defineError)({
+        code: 'FOREIGN_KEY_VIOLATION',
+        class: 'public',
+        http: 409,
+        message: 'A related record is required or still referenced.'
+    }),
+    NOT_NULL_VIOLATION: (0, define_1.defineError)({
+        code: 'NOT_NULL_VIOLATION',
+        class: 'public',
+        http: 400,
+        message: 'A required value is missing.'
+    }),
+    CHECK_VIOLATION: (0, define_1.defineError)({
+        code: 'CHECK_VIOLATION',
+        class: 'public',
+        http: 400,
+        message: 'A value did not satisfy a constraint.'
+    }),
+    EXCLUSION_VIOLATION: (0, define_1.defineError)({
+        code: 'EXCLUSION_VIOLATION',
+        class: 'public',
+        http: 409,
+        message: 'A value conflicts with an existing record.'
+    }),
+    // ===========================================================================
+    // pgpm CLI / engine (mostly internal) — behavior preserved from the former
+    // pgpm/types error-factory so existing call sites are unchanged.
+    // ===========================================================================
+    NOT_FOUND: (0, define_1.defineError)({
+        code: 'NOT_FOUND',
+        class: 'public',
+        http: 404,
+        message: 'Not found.'
+    }),
+    MODULE_NOT_FOUND: (0, define_1.defineError)({
+        code: 'MODULE_NOT_FOUND',
+        class: 'internal',
+        http: 404,
+        message: 'Module "{{name}}" not found in modules list.'
+    }),
+    INTERNAL_FAILURE: (0, define_1.defineError)({
+        code: 'INTERNAL_FAILURE',
+        class: 'internal',
+        http: 500,
+        message: 'Something went wrong: {{details}}'
+    }),
+    CONTEXT_MISSING: (0, define_1.defineError)({
+        code: 'CONTEXT_MISSING',
+        class: 'internal',
+        http: 500,
+        message: 'Context is not initialized. Did you run setup()?'
+    }),
+    NOT_IN_WORKSPACE: (0, define_1.defineError)({
+        code: 'NOT_IN_WORKSPACE',
+        class: 'internal',
+        http: 400,
+        message: 'You must be in a PGPM workspace. Initialize with "pgpm init workspace".'
+    }),
+    NOT_IN_WORKSPACE_MODULE: (0, define_1.defineError)({
+        code: 'NOT_IN_WORKSPACE_MODULE',
+        class: 'internal',
+        http: 400,
+        message: 'Error: You must be inside one of the workspace packages.'
+    }),
+    DEPLOYMENT_FAILED: (0, define_1.defineError)({
+        code: 'DEPLOYMENT_FAILED',
+        class: 'internal',
+        http: 500,
+        message: '{{type}} failed for module: {{module}}'
+    }),
+    UNSUPPORTED_TYPE_HINT: (0, define_1.defineError)({
+        code: 'UNSUPPORTED_TYPE_HINT',
+        class: 'internal',
+        http: 400,
+        message: 'Unsupported type hint: {{typeHint}}'
+    }),
+    BAD_FILE_NAME: (0, define_1.defineError)({
+        code: 'BAD_FILE_NAME',
+        class: 'internal',
+        http: 400,
+        message: 'Invalid file name: {{name}}'
+    }),
+    UNKNOWN_COMMAND: (0, define_1.defineError)({
+        code: 'UNKNOWN_COMMAND',
+        class: 'internal',
+        http: 400,
+        message: 'Unknown command: {{cmd}}'
+    }),
+    CHANGE_NOT_FOUND: (0, define_1.defineError)({
+        code: 'CHANGE_NOT_FOUND',
+        class: 'internal',
+        http: 404,
+        message: ({ change, plan }) => `Change '${change}' not found in plan${plan ? ` file: ${plan}` : ''}`
+    }),
+    TAG_NOT_FOUND: (0, define_1.defineError)({
+        code: 'TAG_NOT_FOUND',
+        class: 'internal',
+        http: 404,
+        message: ({ tag, project }) => `Tag '${tag}' not found${project ? ` in project ${project}` : ' in plan'}`
+    }),
+    PATH_NOT_FOUND: (0, define_1.defineError)({
+        code: 'PATH_NOT_FOUND',
+        class: 'internal',
+        http: 404,
+        message: ({ path, type }) => `${type} path not found: ${path}`
+    }),
+    OPERATION_FAILED: (0, define_1.defineError)({
+        code: 'OPERATION_FAILED',
+        class: 'internal',
+        http: 500,
+        message: ({ operation, target, reason }) => `${operation} failed${target ? ` for ${target}` : ''}${reason ? `: ${reason}` : ''}`
+    }),
+    PLAN_PARSE_ERROR: (0, define_1.defineError)({
+        code: 'PLAN_PARSE_ERROR',
+        class: 'internal',
+        http: 400,
+        message: ({ planPath, errors }) => `Failed to parse plan file ${planPath}: ${errors}`
+    }),
+    CIRCULAR_DEPENDENCY: (0, define_1.defineError)({
+        code: 'CIRCULAR_DEPENDENCY',
+        class: 'internal',
+        http: 400,
+        message: ({ module, dependency }) => `Circular reference detected: ${module} → ${dependency}`
+    }),
+    INVALID_NAME: (0, define_1.defineError)({
+        code: 'INVALID_NAME',
+        class: 'internal',
+        http: 400,
+        message: ({ name, type, rules }) => `Invalid ${type} name: ${name}${rules ? `. ${rules}` : ''}`
+    }),
+    WORKSPACE_OPERATION_ERROR: (0, define_1.defineError)({
+        code: 'WORKSPACE_OPERATION_ERROR',
+        class: 'internal',
+        http: 400,
+        message: ({ operation }) => `Cannot perform non-recursive ${operation} on workspace. Use recursive=true or specify a target module.`
+    }),
+    FILE_NOT_FOUND: (0, define_1.defineError)({
+        code: 'FILE_NOT_FOUND',
+        class: 'internal',
+        http: 404,
+        message: ({ filePath, type }) => `${type ? `${type} file` : 'File'} not found: ${filePath}`
+    })
+};
+/**
+ * All known definitions, keyed by code: every constructive-db code (generated)
+ * merged with the curated entries, curated winning on conflict.
+ */
+const allDefinitions = {
+    ...registry_generated_1.generatedRegistry,
+    ...exports.registry
+};
+/** Look up a definition by code (from anywhere, not just typed keys). */
+function getDefinition(code) {
+    return allDefinitions[code];
+}
+/** Every registered code (curated + generated). */
+function allCodes() {
+    return Object.keys(allDefinitions);
+}

package/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Core types for the Constructive error system.
+ *
+ * A Constructive error is identified by a stable, machine-readable `code`
+ * (ALL_CAPS). Human-facing copy is kept separate (in i18n catalogs) so the
+ * same code can be localized. Every code is classified as `public` (safe to
+ * surface to end users) or `internal` (an invariant/developer error that must
+ * be masked in production).
+ */
+/** Values that can be interpolated into a message or carried as error context. */
+export type ContextValue = string | number | boolean | null | undefined;
+/** Structured, machine-readable context attached to an error. */
+export type ErrorContext = Record<string, ContextValue>;
+/** A context with no parameters (codes that take no dynamic values). */
+export type EmptyContext = Record<never, never>;
+/**
+ * Classification of a code.
+ * - `public`   — user-facing; safe to send to clients as-is.
+ * - `internal` — developer/invariant error; masked in production.
+ */
+export type ErrorClass = 'public' | 'internal';
+/**
+ * A single registry entry describing one error code. This is the source of
+ * truth; message copy, factories, and classification all derive from it.
+ */
+export interface ErrorDefinition<C extends ErrorContext = EmptyContext> {
+    /** Stable machine code, e.g. `ACCOUNT_EXISTS`. */
+    code: string;
+    /** Public (surface to users) vs internal (mask in prod). */
+    class: ErrorClass;
+    /** HTTP status hint for transports that want one. */
+    http: number;
+    /**
+     * Default message. Either an i18n template using `{{var}}` placeholders
+     * (preferred — localizable) or a function for messages with conditional
+     * logic that a flat template cannot express.
+     */
+    message: string | ((context: C) => string);
+    /** Documented context parameter names (for tooling / codegen). */
+    params?: readonly (keyof C & string)[];
+    /**
+     * For legacy dynamic DB throws of the form `CODE (arg0, arg1)`, maps the
+     * positional args to context keys so `parse()` can recover structure.
+     */
+    positional?: readonly (keyof C & string)[];
+}
+/** The canonical, normalized result of parsing an error from any source. */
+export interface ParsedError {
+    /** Constructive code if one could be determined, else `null`. */
+    code: string | null;
+    /** Structured context recovered from the error (may be empty). */
+    context: ErrorContext;
+    /** Classification (`internal` when the code is unknown — fail safe). */
+    class: ErrorClass;
+    /** `true` when `code` is present in the registry. */
+    known: boolean;
+    /** Best-effort raw message from the source error. */
+    rawMessage: string;
+    /** Original PostgreSQL SQLSTATE, when the source was a pg error. */
+    sqlState?: string;
+    /** The original error, for logging/debugging. */
+    originalError: unknown;
+}
+/** Extended PostgreSQL error fields (populated by pg-protocol on errors). */
+export interface PgErrorFields {
+    code?: string;
+    detail?: string;
+    hint?: string;
+    where?: string;
+    position?: string;
+    internalPosition?: string;
+    internalQuery?: string;
+    schema?: string;
+    table?: string;
+    column?: string;
+    dataType?: string;
+    constraint?: string;
+    file?: string;
+    line?: string;
+    routine?: string;
+}

package/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Core types for the Constructive error system.
+ *
+ * A Constructive error is identified by a stable, machine-readable `code`
+ * (ALL_CAPS). Human-facing copy is kept separate (in i18n catalogs) so the
+ * same code can be localized. Every code is classified as `public` (safe to
+ * surface to end users) or `internal` (an invariant/developer error that must
+ * be masked in production).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });