@zero-server/errors 0.9.0 → 0.9.2

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Tony Wiedman
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Tony Wiedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 > HttpError + 25+ typed framework and ORM errors.
 
-Every typed error class shipped by the SDK: HTTP status errors, framework errors (configuration / middleware / routing / timeout), ORM errors (database / connection / migration / transaction / query / adapter / cache), and the Phase 4 errors (tenancy / audit / plugin / procedure). Plus the `createError` factory and `isHttpError` guard.
+Every typed error class shipped by the SDK: HTTP status errors, framework errors (configuration / middleware / routing / timeout), ORM errors (database / connection / migration / transaction / query / adapter / cache), and the Phase 4 errors (tenancy / audit / plugin / procedure). Plus the `createError` factory, `isHttpError` guard, and the lightweight `debug` logger.
 
 ## Install
 
@@ -30,7 +30,7 @@ This package narrows `@zero-server/sdk` to **34** exports. See the [scope page](
 
 - [Scope page](https://github.com/tonywied17/zero-server/blob/main/docs/scopes/errors.md)
 - [Full API reference](https://github.com/tonywied17/zero-server/blob/main/API.md)
-- [Live docs](https://z-server.com)
+- [Live docs](https://z-server.dev)
 
 ## License
 

package/index.js

@@ -1,40 +1,40 @@
 // AUTO-GENERATED by .tools/generate-package-stubs.js — edit .tools/scope-manifest.js and re-run `npm run packages:generate`.
 'use strict';
-const sdk = require("@zero-server/sdk");
-
+const errors = require('./lib/errors');
+const debug  = require('./lib/debug');
 module.exports = {
-    HttpError: sdk.HttpError,
-    BadRequestError: sdk.BadRequestError,
-    UnauthorizedError: sdk.UnauthorizedError,
-    ForbiddenError: sdk.ForbiddenError,
-    NotFoundError: sdk.NotFoundError,
-    MethodNotAllowedError: sdk.MethodNotAllowedError,
-    ConflictError: sdk.ConflictError,
-    GoneError: sdk.GoneError,
-    PayloadTooLargeError: sdk.PayloadTooLargeError,
-    UnprocessableEntityError: sdk.UnprocessableEntityError,
-    ValidationError: sdk.ValidationError,
-    TooManyRequestsError: sdk.TooManyRequestsError,
-    InternalError: sdk.InternalError,
-    NotImplementedError: sdk.NotImplementedError,
-    BadGatewayError: sdk.BadGatewayError,
-    ServiceUnavailableError: sdk.ServiceUnavailableError,
-    DatabaseError: sdk.DatabaseError,
-    ConfigurationError: sdk.ConfigurationError,
-    MiddlewareError: sdk.MiddlewareError,
-    RoutingError: sdk.RoutingError,
-    TimeoutError: sdk.TimeoutError,
-    ConnectionError: sdk.ConnectionError,
-    MigrationError: sdk.MigrationError,
-    TransactionError: sdk.TransactionError,
-    QueryError: sdk.QueryError,
-    AdapterError: sdk.AdapterError,
-    CacheError: sdk.CacheError,
-    TenancyError: sdk.TenancyError,
-    AuditError: sdk.AuditError,
-    PluginError: sdk.PluginError,
-    ProcedureError: sdk.ProcedureError,
-    createError: sdk.createError,
-    isHttpError: sdk.isHttpError,
-    debug: sdk.debug,
+    HttpError:                  errors.HttpError,
+    BadRequestError:            errors.BadRequestError,
+    UnauthorizedError:          errors.UnauthorizedError,
+    ForbiddenError:             errors.ForbiddenError,
+    NotFoundError:              errors.NotFoundError,
+    MethodNotAllowedError:      errors.MethodNotAllowedError,
+    ConflictError:              errors.ConflictError,
+    GoneError:                  errors.GoneError,
+    PayloadTooLargeError:       errors.PayloadTooLargeError,
+    UnprocessableEntityError:   errors.UnprocessableEntityError,
+    ValidationError:            errors.ValidationError,
+    TooManyRequestsError:       errors.TooManyRequestsError,
+    InternalError:              errors.InternalError,
+    NotImplementedError:        errors.NotImplementedError,
+    BadGatewayError:            errors.BadGatewayError,
+    ServiceUnavailableError:    errors.ServiceUnavailableError,
+    DatabaseError:              errors.DatabaseError,
+    ConfigurationError:         errors.ConfigurationError,
+    MiddlewareError:            errors.MiddlewareError,
+    RoutingError:               errors.RoutingError,
+    TimeoutError:               errors.TimeoutError,
+    ConnectionError:            errors.ConnectionError,
+    MigrationError:             errors.MigrationError,
+    TransactionError:           errors.TransactionError,
+    QueryError:                 errors.QueryError,
+    AdapterError:               errors.AdapterError,
+    CacheError:                 errors.CacheError,
+    TenancyError:               errors.TenancyError,
+    AuditError:                 errors.AuditError,
+    PluginError:                errors.PluginError,
+    ProcedureError:             errors.ProcedureError,
+    createError:                errors.createError,
+    isHttpError:                errors.isHttpError,
+    debug,
 };

package/lib/debug.js

@@ -0,0 +1,372 @@
+/**
+ * @module debug
+ * @description Lightweight namespaced debug logger with levels, colors, and timestamps.
+ *              Enable via DEBUG env variable: DEBUG=app:*,router (supports glob patterns).
+ *              Each namespace gets a unique color for easy visual scanning.
+ *
+ * Levels: trace (0), debug (1), info (2), warn (3), error (4), fatal (5), silent (6).
+ * Set level via DEBUG_LEVEL env var or programmatically.
+ *
+ * @example
+ *   const debug = require('@zero-server/sdk').debug;
+ *   const log = debug('app:routes');
+ *
+ *   log.info('server started on port %d', 3000);
+ *   log.warn('deprecation notice');
+ *   log.error('failed to connect', err);
+ *   log('shorthand for debug level');
+ *
+ *   // Set minimum level — anything below is silenced
+ *   debug.level('warn');   // only warn, error, fatal
+ *   debug.level('silent'); // suppress all output
+ *   debug.level('trace');  // show everything
+ *   debug.level(0);        // same as 'trace'
+ */
+
+const LEVELS = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, fatal: 5, silent: 6 };
+const LEVEL_NAMES = ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL'];
+const LEVEL_COLORS = ['\x1b[2m', '\x1b[36m', '\x1b[32m', '\x1b[33m', '\x1b[31m', '\x1b[35;1m'];
+
+// Namespace colors (rotate through these)
+const NS_COLORS = [
+    '\x1b[36m', '\x1b[33m', '\x1b[32m', '\x1b[35m', '\x1b[34m',
+    '\x1b[36;1m', '\x1b[33;1m', '\x1b[32;1m', '\x1b[35;1m', '\x1b[34;1m',
+];
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+
+let _colorIdx = 0;
+const _nsColorMap = new Map();
+
+/**
+ * Global state
+ */
+let _globalLevel = LEVELS[process.env.DEBUG_LEVEL] !== undefined
+    ? LEVELS[process.env.DEBUG_LEVEL]
+    : LEVELS.debug;
+
+let _enabledPatterns = null;
+let _output = process.stdout;
+let _outputCustom = false;
+let _useColors = process.stdout.isTTY || false;
+let _timestamps = true;
+let _jsonMode = false;
+
+/**
+ * Parse DEBUG env var into patterns.
+ * @private
+ */
+function _parsePatterns()
+{
+    const raw = process.env.DEBUG;
+    if (!raw) return null;
+    return raw.split(/[\s,]+/).filter(Boolean).map(p =>
+    {
+        const neg = p.startsWith('-');
+        const pat = neg ? p.slice(1) : p;
+        // Convert glob to regex: * => .*, ? => .
+        const re = new RegExp('^' + pat.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+        return { neg, re };
+    });
+}
+
+_enabledPatterns = _parsePatterns();
+
+/**
+ * Check if a namespace is enabled.
+ * @private
+ * @param {string} ns - Debug namespace.
+ * @returns {boolean} True if the namespace matches the DEBUG patterns.
+ */
+function _isEnabled(ns)
+{
+    if (!_enabledPatterns) return true; // No DEBUG set — enable all
+    let enabled = false;
+    for (const { neg, re } of _enabledPatterns)
+    {
+        if (re.test(ns)) enabled = !neg;
+    }
+    return enabled;
+}
+
+/**
+ * Get a color for a namespace.
+ * @private
+ */
+function _nsColor(ns)
+{
+    if (!_nsColorMap.has(ns))
+    {
+        _nsColorMap.set(ns, NS_COLORS[_colorIdx % NS_COLORS.length]);
+        _colorIdx++;
+    }
+    return _nsColorMap.get(ns);
+}
+
+/**
+ * Format a timestamp.
+ * @private
+ */
+function _ts()
+{
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${String(d.getMilliseconds()).padStart(3, '0')}`;
+}
+
+/**
+ * Format arguments (like console.log — supports %s, %d, %j, %o).
+ * @private
+ */
+function _format(args)
+{
+    if (args.length === 0) return '';
+    if (typeof args[0] === 'string' && args.length > 1)
+    {
+        let i = 1;
+        const str = args[0].replace(/%([sdjo%])/g, (_, f) =>
+        {
+            if (f === '%') return '%';
+            if (i >= args.length) return `%${f}`;
+            const v = args[i++];
+            if (f === 's') return String(v);
+            if (f === 'd') return Number(v);
+            if (f === 'j' || f === 'o')
+            {
+                try { return JSON.stringify(v); }
+                catch { return String(v); }
+            }
+            return String(v);
+        });
+        const rest = args.slice(i).map(a =>
+            typeof a === 'object' ? JSON.stringify(a) : String(a)
+        );
+        return rest.length > 0 ? str + ' ' + rest.join(' ') : str;
+    }
+    return args.map(a =>
+    {
+        if (a instanceof Error) return a.stack || a.message;
+        if (typeof a === 'object')
+        {
+            try { return JSON.stringify(a); }
+            catch { return String(a); }
+        }
+        return String(a);
+    }).join(' ');
+}
+
+/**
+ * Write a log entry.
+ * @private
+ */
+function _write(ns, level, args)
+{
+    const msg = _format(args);
+    const out = (_outputCustom || level < LEVELS.warn) ? _output : process.stderr;
+
+    if (_jsonMode)
+    {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: LEVEL_NAMES[level],
+            namespace: ns,
+            message: msg,
+        };
+        // If last arg is an Error, attach stack
+        const last = args[args.length - 1];
+        if (last instanceof Error)
+        {
+            entry.error = { message: last.message, stack: last.stack, code: last.code };
+        }
+        out.write(JSON.stringify(entry) + '\n');
+        return;
+    }
+
+    // Pretty text output
+    const parts = [];
+    if (_timestamps)
+    {
+        parts.push(_useColors ? `${DIM}${_ts()}${RESET}` : _ts());
+    }
+    // Level
+    const lvlName = LEVEL_NAMES[level];
+    if (_useColors)
+    {
+        parts.push(`${LEVEL_COLORS[level]}${lvlName.padEnd(5)}${RESET}`);
+    }
+    else
+    {
+        parts.push(lvlName.padEnd(5));
+    }
+    // Namespace
+    if (_useColors)
+    {
+        parts.push(`${_nsColor(ns)}${ns}${RESET}`);
+    }
+    else
+    {
+        parts.push(ns);
+    }
+    parts.push(msg);
+
+    out.write(parts.join(' ') + '\n');
+}
+
+/**
+ * Create a namespaced debug logger.
+ *
+ * @param {string} namespace - Logger namespace (e.g. 'app:routes', 'db:queries').
+ * @returns {Function & { trace, debug, info, warn, error, fatal, enabled }} Logger function.
+ */
+function debug(namespace)
+{
+    const enabled = _isEnabled(namespace);
+
+    // Default call = debug level
+    const logger = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.debug) return;
+        _write(namespace, LEVELS.debug, args);
+    };
+
+    logger.trace = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.trace) return;
+        _write(namespace, LEVELS.trace, args);
+    };
+
+    logger.debug = logger;
+
+    logger.info = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.info) return;
+        _write(namespace, LEVELS.info, args);
+    };
+
+    logger.warn = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.warn) return;
+        _write(namespace, LEVELS.warn, args);
+    };
+
+    logger.error = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.error) return;
+        _write(namespace, LEVELS.error, args);
+    };
+
+    logger.fatal = (...args) =>
+    {
+        if (!enabled || _globalLevel > LEVELS.fatal) return;
+        _write(namespace, LEVELS.fatal, args);
+    };
+
+    /** Whether this namespace is active. */
+    logger.enabled = enabled;
+
+    /** The namespace string */
+    logger.namespace = namespace;
+
+    return logger;
+}
+
+// --- Configuration API -------------------------------------------
+
+/**
+ * Set the minimum log level globally.
+ * Messages below this level are silenced.
+ *
+ * @param {string|number} level - Level name or number.
+ *   `'trace'` (0) — all output
+ *   `'debug'` (1) — debug and above
+ *   `'info'` (2) — info and above
+ *   `'warn'` (3) — warn and above
+ *   `'error'` (4) — error and fatal only
+ *   `'fatal'` (5) — fatal only
+ *   `'silent'` (6) — nothing
+ */
+debug.level = function(level)
+{
+    if (typeof level === 'string') _globalLevel = LEVELS[level.toLowerCase()] ?? LEVELS.debug;
+    else _globalLevel = level;
+};
+
+/**
+ * Enable/disable namespaces programmatically (same syntax as DEBUG env var).
+ * @param {string} patterns - Comma-separated patterns. Use '-ns' to exclude.
+ */
+debug.enable = function(patterns)
+{
+    process.env.DEBUG = patterns;
+    _enabledPatterns = _parsePatterns();
+};
+
+/**
+ * Disable all debug output.
+ */
+debug.disable = function()
+{
+    process.env.DEBUG = '';
+    _enabledPatterns = [{ neg: false, re: /^$/ }]; // match nothing
+};
+
+/**
+ * Enable structured JSON output.
+ * @param {boolean} [on=true] - Enable flag.
+ */
+debug.json = function(on = true)
+{
+    _jsonMode = on;
+};
+
+/**
+ * Enable/disable timestamps.
+ * @param {boolean} [on=true] - Enable flag.
+ */
+debug.timestamps = function(on = true)
+{
+    _timestamps = on;
+};
+
+/**
+ * Enable/disable colors.
+ * @param {boolean} [on=true] - Enable flag.
+ */
+debug.colors = function(on = true)
+{
+    _useColors = on;
+};
+
+/**
+ * Set custom output stream.
+ * @param {object} stream - Writable stream with write() method.
+ */
+debug.output = function(stream)
+{
+    _output = stream;
+    _outputCustom = true;
+};
+
+/**
+ * Reset all settings to defaults.
+ */
+debug.reset = function()
+{
+    _globalLevel = LEVELS[process.env.DEBUG_LEVEL] !== undefined
+        ? LEVELS[process.env.DEBUG_LEVEL]
+        : LEVELS.debug;
+    _enabledPatterns = _parsePatterns();
+    _output = process.stdout;
+    _outputCustom = false;
+    _useColors = process.stdout.isTTY || false;
+    _timestamps = true;
+    _jsonMode = false;
+    _colorIdx = 0;
+    _nsColorMap.clear();
+};
+
+/** Expose level constants. */
+debug.LEVELS = LEVELS;
+
+module.exports = debug;

package/lib/errors.js

@@ -0,0 +1,683 @@
+/**
+ * @module errors
+ * @description HTTP error classes with status codes, error codes, and structured details.
+ *              Every error extends HttpError which carries a statusCode, code, and optional details.
+ *
+ * @example
+ *   const { NotFoundError, ValidationError, createError } = require('@zero-server/sdk');
+ *
+ *   // Throw a named error class
+ *   throw new NotFoundError('User not found');
+ *
+ *   // Attach a machine-readable code + details
+ *   throw new NotFoundError('Invoice missing', {
+ *       code: 'INVOICE_NOT_FOUND',
+ *       details: { invoiceId: 'INV-42' },
+ *   });
+ *
+ *   // Field-level validation errors
+ *   throw new ValidationError('Invalid input', {
+ *       email: 'required',
+ *       age:   'must be >= 18',
+ *   });
+ *
+ *   // Factory — create by status code
+ *   throw createError(503, 'Try again later');
+ */
+
+// --- Status Text Map ---------------------------------------------
+
+const STATUS_TEXT = {
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    402: 'Payment Required',
+    403: 'Forbidden',
+    404: 'Not Found',
+    405: 'Method Not Allowed',
+    406: 'Not Acceptable',
+    408: 'Request Timeout',
+    409: 'Conflict',
+    410: 'Gone',
+    413: 'Payload Too Large',
+    415: 'Unsupported Media Type',
+    418: "I'm a Teapot",
+    422: 'Unprocessable Entity',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    501: 'Not Implemented',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+    504: 'Gateway Timeout',
+};
+
+// --- Base HttpError ----------------------------------------------
+
+/**
+ * Base HTTP error class.  All framework error classes extend this.
+ */
+class HttpError extends Error
+{
+    /**
+     * @constructor
+     * @param {number} statusCode - HTTP status code.
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code (e.g. 'VALIDATION_FAILED').
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(statusCode, message, opts = {})
+    {
+        super(message || STATUS_TEXT[statusCode] || 'Error');
+        this.name = this.constructor.name;
+        this.statusCode = statusCode;
+        this.code = opts.code || this._defaultCode();
+        if (opts.details !== undefined) this.details = opts.details;
+        Error.captureStackTrace(this, this.constructor);
+    }
+
+    /** @private */
+    _defaultCode()
+    {
+        return (STATUS_TEXT[this.statusCode] || 'ERROR')
+            .toUpperCase()
+            .replace(/[^A-Z0-9]+/g, '_')
+            .replace(/(^_|_$)/g, '');
+    }
+
+    /**
+     * Serialize for JSON responses.
+     * @returns {{ error: string, code: string, statusCode: number, details?: * }}
+     */
+    toJSON()
+    {
+        const obj = { error: this.message, code: this.code, statusCode: this.statusCode };
+        if (this.details !== undefined) obj.details = this.details;
+        return obj;
+    }
+}
+
+// --- Specific Error Classes --------------------------------------
+
+class BadRequestError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(400, message, opts); }
+}
+
+class UnauthorizedError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(401, message, opts); }
+}
+
+class ForbiddenError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(403, message, opts); }
+}
+
+class NotFoundError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(404, message, opts); }
+}
+
+class MethodNotAllowedError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(405, message, opts); }
+}
+
+class ConflictError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(409, message, opts); }
+}
+
+class GoneError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(410, message, opts); }
+}
+
+class PayloadTooLargeError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(413, message, opts); }
+}
+
+class UnprocessableEntityError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(422, message, opts); }
+}
+
+/**
+ * Validation error with field-level details.
+ */
+class ValidationError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string}         [message]  - Summary message.
+     * @param {object|Array}   [errors]   - Field errors, e.g. { email: 'required', age: 'must be >= 18' }.
+     * @param {object}         [opts] - Additional error options.
+     * @param {string}         [opts.code] - Machine-readable error code.
+     */
+    constructor(message, errors, opts = {})
+    {
+        super(422, message || 'Validation Failed', { code: 'VALIDATION_FAILED', ...opts, details: errors });
+        this.errors = errors || {};
+    }
+}
+
+class TooManyRequestsError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(429, message, opts); }
+}
+
+class InternalError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(500, message, opts); }
+}
+
+class NotImplementedError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(501, message, opts); }
+}
+
+class BadGatewayError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(502, message, opts); }
+}
+
+class ServiceUnavailableError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Human-readable message.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.code]    - Machine-readable error code.
+     * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+     */
+    constructor(message, opts) { super(503, message, opts); }
+}
+
+// --- Framework Error Classes -------------------------------------
+
+/**
+ * Database / ORM error — wraps adapter-level failures.
+ */
+class DatabaseError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]  - Description of the DB failure.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.query]   - The query or operation that failed.
+     * @param {string}  [opts.adapter] - Adapter name (sqlite, mysql, etc.).
+     */
+    constructor(message, opts = {})
+    {
+        super(500, message || 'Database Error', { code: 'DATABASE_ERROR', ...opts });
+        if (opts.query) this.query = opts.query;
+        if (opts.adapter) this.adapter = opts.adapter;
+    }
+}
+
+/**
+ * Configuration error — thrown when app/adapter configuration is invalid.
+ */
+class ConfigurationError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message] - What misconfiguration was detected.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.setting] - The setting key that's invalid.
+     */
+    constructor(message, opts = {})
+    {
+        super(500, message || 'Configuration Error', { code: 'CONFIGURATION_ERROR', ...opts });
+        if (opts.setting) this.setting = opts.setting;
+    }
+}
+
+/**
+ * Middleware error — a middleware function failed unexpectedly.
+ */
+class MiddlewareError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]     - Description.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.middleware] - Middleware name.
+     */
+    constructor(message, opts = {})
+    {
+        super(500, message || 'Middleware Error', { code: 'MIDDLEWARE_ERROR', ...opts });
+        if (opts.middleware) this.middleware = opts.middleware;
+    }
+}
+
+/**
+ * Routing error — thrown when route resolution fails.
+ */
+class RoutingError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message] - Description.
+     * @param {object} [opts] - Additional error options.
+     * @param {string} [opts.path]   - The route path.
+     * @param {string} [opts.method] - The HTTP method.
+     */
+    constructor(message, opts = {})
+    {
+        super(500, message || 'Routing Error', { code: 'ROUTING_ERROR', ...opts });
+        if (opts.path) this.path = opts.path;
+        if (opts.method) this.method = opts.method;
+    }
+}
+
+/**
+ * Timeout error — operation exceeded allowed time.
+ */
+class TimeoutError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string} [message]  - Description.
+     * @param {object} [opts] - Additional error options.
+     * @param {number} [opts.timeout] - The timeout limit in ms.
+     */
+    constructor(message, opts = {})
+    {
+        super(408, message || 'Request Timeout', { code: 'TIMEOUT', ...opts });
+        if (opts.timeout) this.timeout = opts.timeout;
+    }
+}
+
+// --- ORM-Specific Error Classes ----------------------------------
+
+/**
+ * Connection error — database connection failures with retry context.
+ */
+class ConnectionError extends DatabaseError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]     - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.adapter]    - Adapter name.
+     * @param {number}  [opts.attempt]    - Retry attempt number.
+     * @param {number}  [opts.maxRetries] - Maximum retries configured.
+     * @param {string}  [opts.host]       - Target host.
+     * @param {number}  [opts.port]       - Target port.
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'Connection Failed', { code: 'CONNECTION_ERROR', ...opts });
+        if (opts.attempt !== undefined) this.attempt = opts.attempt;
+        if (opts.maxRetries !== undefined) this.maxRetries = opts.maxRetries;
+        if (opts.host) this.host = opts.host;
+        if (opts.port) this.port = opts.port;
+    }
+}
+
+/**
+ * Migration error — migration execution failures.
+ */
+class MigrationError extends DatabaseError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]         - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.migration]  - Migration name that failed.
+     * @param {string}  [opts.direction]  - 'up' or 'down'.
+     * @param {number}  [opts.batch]      - Batch number.
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'Migration Failed', { code: 'MIGRATION_ERROR', ...opts });
+        if (opts.migration) this.migration = opts.migration;
+        if (opts.direction) this.direction = opts.direction;
+        if (opts.batch !== undefined) this.batch = opts.batch;
+    }
+}
+
+/**
+ * Transaction error — transaction commit/rollback failures.
+ */
+class TransactionError extends DatabaseError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]       - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.phase]    - 'begin', 'commit', or 'rollback'.
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'Transaction Failed', { code: 'TRANSACTION_ERROR', ...opts });
+        if (opts.phase) this.phase = opts.phase;
+    }
+}
+
+/**
+ * Query error — query execution failures with SQL context.
+ */
+class QueryError extends DatabaseError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]      - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.sql]     - The SQL that failed (if applicable).
+     * @param {Array}   [opts.params]  - Query parameters.
+     * @param {string}  [opts.table]   - Target table.
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'Query Failed', { code: 'QUERY_ERROR', ...opts });
+        if (opts.sql) this.sql = opts.sql;
+        if (opts.params) this.params = opts.params;
+        if (opts.table) this.table = opts.table;
+    }
+}
+
+/**
+ * Adapter error — adapter-level issues (driver not found, unsupported operation).
+ */
+class AdapterError extends DatabaseError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]        - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.adapter]   - Adapter name.
+     * @param {string}  [opts.operation] - The operation that failed.
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'Adapter Error', { code: 'ADAPTER_ERROR', ...opts });
+        if (opts.operation) this.operation = opts.operation;
+    }
+}
+
+/**
+ * Cache error — caching layer failures.
+ */
+class CacheError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]        - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.operation] - Cache operation that failed.
+     * @param {string}  [opts.key]       - Cache key involved.
+     */
+    constructor(message, opts = {})
+    {
+        super(500, message || 'Cache Error', { code: 'CACHE_ERROR', ...opts });
+        if (opts.operation) this.operation = opts.operation;
+        if (opts.key) this.key = opts.key;
+    }
+}
+
+// --- Phase 4 Error Classes ---------------------------------------
+
+/**
+ * Tenancy error — multi-tenancy operation failures.
+ */
+class TenancyError extends DatabaseError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]       - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.tenant]   - Tenant identifier.
+     * @param {string}  [opts.strategy] - Tenancy strategy (row, schema).
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'Tenancy Error', { code: 'TENANCY_ERROR', ...opts });
+        if (opts.tenant) this.tenant = opts.tenant;
+        if (opts.strategy) this.strategy = opts.strategy;
+    }
+}
+
+/**
+ * Audit error — audit logging failures.
+ */
+class AuditError extends DatabaseError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]       - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.action]   - Audit action that failed.
+     * @param {string}  [opts.table]    - Target table.
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'Audit Error', { code: 'AUDIT_ERROR', ...opts });
+        if (opts.action) this.action = opts.action;
+        if (opts.table) this.table = opts.table;
+    }
+}
+
+/**
+ * Plugin error — plugin registration or lifecycle failures.
+ */
+class PluginError extends HttpError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]       - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.plugin]   - Plugin name.
+     * @param {string}  [opts.phase]    - Lifecycle phase (install, boot, uninstall).
+     */
+    constructor(message, opts = {})
+    {
+        super(500, message || 'Plugin Error', { code: 'PLUGIN_ERROR', ...opts });
+        if (opts.plugin) this.plugin = opts.plugin;
+        if (opts.phase) this.phase = opts.phase;
+    }
+}
+
+/**
+ * Procedure error — stored procedure/function failures.
+ */
+class ProcedureError extends DatabaseError
+{
+    /**
+     * @constructor
+     * @param {string}  [message]         - Description.
+     * @param {object}  [opts] - Additional error options.
+     * @param {string}  [opts.procedure]  - Procedure or function name.
+     * @param {string}  [opts.operation]  - Operation (create, drop, execute).
+     */
+    constructor(message, opts = {})
+    {
+        super(message || 'Procedure Error', { code: 'PROCEDURE_ERROR', ...opts });
+        if (opts.procedure) this.procedure = opts.procedure;
+        if (opts.operation) this.operation = opts.operation;
+    }
+}
+
+// --- Factory -----------------------------------------------------
+
+/**
+ * Create an HttpError by status code.
+ *
+ * @param {number} statusCode - HTTP status code.
+ * @param {string} [message] - Human-readable error message.
+ * @param {object} [opts] - Additional error options.
+ * @param {string} [opts.code]    - Machine-readable error code.
+ * @param {*}      [opts.details] - Extra data (field errors, debug info, etc.).
+ * @returns {HttpError} Matching HttpError subclass instance.
+ *
+ * @example
+ *   throw createError(404, 'User not found');
+ *   throw createError(422, 'Invalid input', { details: { email: 'required' } });
+ */
+function createError(statusCode, message, opts)
+{
+    const map = {
+        400: BadRequestError,
+        401: UnauthorizedError,
+        403: ForbiddenError,
+        404: NotFoundError,
+        405: MethodNotAllowedError,
+        408: TimeoutError,
+        409: ConflictError,
+        410: GoneError,
+        413: PayloadTooLargeError,
+        422: UnprocessableEntityError,
+        429: TooManyRequestsError,
+        500: InternalError,
+        501: NotImplementedError,
+        502: BadGatewayError,
+        503: ServiceUnavailableError,
+    };
+
+    const Cls = map[statusCode];
+    if (Cls) return new Cls(message, opts);
+    return new HttpError(statusCode, message, opts);
+}
+
+/**
+ * Check if a value is an HttpError (or duck-typed equivalent).
+ * @param {*} err - Error object.
+ * @returns {boolean} True if the value is an HttpError.
+ */
+function isHttpError(err)
+{
+    if (!err || !(err instanceof Error)) return false;
+    return err instanceof HttpError || typeof err.statusCode === 'number';
+}
+
+module.exports = {
+    HttpError,
+    BadRequestError,
+    UnauthorizedError,
+    ForbiddenError,
+    NotFoundError,
+    MethodNotAllowedError,
+    ConflictError,
+    GoneError,
+    PayloadTooLargeError,
+    UnprocessableEntityError,
+    ValidationError,
+    TooManyRequestsError,
+    InternalError,
+    NotImplementedError,
+    BadGatewayError,
+    ServiceUnavailableError,
+    // Framework-specific errors
+    DatabaseError,
+    ConfigurationError,
+    MiddlewareError,
+    RoutingError,
+    TimeoutError,
+    // ORM-specific errors
+    ConnectionError,
+    MigrationError,
+    TransactionError,
+    QueryError,
+    AdapterError,
+    CacheError,
+    // Phase 4 errors
+    TenancyError,
+    AuditError,
+    PluginError,
+    ProcedureError,
+    createError,
+    isHttpError,
+};

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zero-server/errors",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "HttpError + 25+ typed framework and ORM errors.",
   "keywords": [
     "zero-server",
-    "zero-http",
+    "zero-server",
     "errors"
   ],
   "author": "Anthony Wiedman",
@@ -20,6 +20,7 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "lib",
     "index.js",
     "index.d.ts",
     "README.md",
@@ -42,7 +43,12 @@
     "access": "public"
   },
   "sideEffects": false,
-  "dependencies": {
-    "@zero-server/sdk": "0.9.0"
+  "peerDependencies": {
+    "@zero-server/sdk": ">=0.9.2"
+  },
+  "peerDependenciesMeta": {
+    "@zero-server/sdk": {
+      "optional": true
+    }
   }
 }