@veloxts/core 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @veloxts/core
 
+## 0.8.1
+
+### Patch Changes
+
+- feat: add business logic primitives for B2B SaaS apps
+
 ## 0.8.0
 
 ### Minor Changes

package/dist/errors/domain-error.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Domain error base class for business logic errors
+ *
+ * Provides a typed, abstract error class that user-land code extends to define
+ * domain-specific error types with structured data payloads. Extends VeloxError
+ * so Fastify's error handler can serialize them automatically.
+ *
+ * @example
+ * ```typescript
+ * class InsufficientStock extends DomainError<{ sku: string; requested: number; available: number }> {
+ *   readonly code = 'INSUFFICIENT_STOCK' as const;
+ *   readonly status = 422;
+ *   readonly message = 'Not enough inventory';
+ * }
+ *
+ * throw new InsufficientStock({ sku: 'ABC-123', requested: 10, available: 3 });
+ * ```
+ *
+ * @module errors/domain-error
+ */
+import { VeloxError } from '../errors.js';
+/**
+ * Branded symbol for cross-package type guard checks.
+ * Uses `Symbol.for` so the same symbol is shared across package boundaries.
+ */
+declare const DOMAIN_ERROR_BRAND: unique symbol;
+/**
+ * JSON representation of a domain error for API responses.
+ */
+export interface DomainErrorJSON {
+    /** Error class name (e.g. "InsufficientStock") */
+    error: string;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code */
+    statusCode: number;
+    /** Machine-readable error code (e.g. "INSUFFICIENT_STOCK") */
+    code: string;
+    /** Structured error data payload */
+    data: Record<string, unknown>;
+}
+/**
+ * Abstract base class for domain-specific business logic errors.
+ *
+ * Subclasses declare `code`, `status`, and `message` as readonly class fields.
+ * The constructor accepts only the typed `data` payload.
+ *
+ * @template TData - Shape of the structured data payload
+ */
+export declare abstract class DomainError<TData extends Record<string, unknown>> extends VeloxError {
+    /**
+     * Machine-readable error code (e.g. "INSUFFICIENT_STOCK").
+     * Defined by each concrete subclass.
+     */
+    abstract readonly code: string;
+    /**
+     * HTTP status code for this domain error.
+     * Defined by each concrete subclass (e.g. 422, 403).
+     */
+    abstract readonly status: number;
+    /**
+     * Human-readable error message.
+     * Defined by each concrete subclass as a readonly class field.
+     */
+    abstract readonly message: string;
+    /**
+     * Structured data payload describing the error context.
+     */
+    readonly data: TData;
+    /**
+     * Brand marker for cross-package `isDomainError()` checks.
+     * @internal
+     */
+    readonly [DOMAIN_ERROR_BRAND]: true;
+    /**
+     * Creates a new DomainError instance.
+     *
+     * @param data - Typed data payload for the error
+     */
+    constructor(data: TData);
+    /**
+     * Converts domain error to JSON format for API responses.
+     * Includes `code` and `data` alongside the standard VeloxError fields.
+     */
+    toJSON(): DomainErrorJSON;
+}
+/**
+ * Type guard to check whether an unknown value is a DomainError.
+ *
+ * Uses a branded symbol (`Symbol.for('velox.domain-error')`) so the check
+ * works across package boundaries even when multiple copies of `@veloxts/core`
+ * are installed.
+ *
+ * @param value - Value to check
+ * @returns `true` if `value` is a DomainError instance
+ */
+export declare function isDomainError(value: unknown): value is DomainError<Record<string, unknown>>;
+export {};

package/dist/errors/domain-error.js

@@ -0,0 +1,101 @@
+/**
+ * Domain error base class for business logic errors
+ *
+ * Provides a typed, abstract error class that user-land code extends to define
+ * domain-specific error types with structured data payloads. Extends VeloxError
+ * so Fastify's error handler can serialize them automatically.
+ *
+ * @example
+ * ```typescript
+ * class InsufficientStock extends DomainError<{ sku: string; requested: number; available: number }> {
+ *   readonly code = 'INSUFFICIENT_STOCK' as const;
+ *   readonly status = 422;
+ *   readonly message = 'Not enough inventory';
+ * }
+ *
+ * throw new InsufficientStock({ sku: 'ABC-123', requested: 10, available: 3 });
+ * ```
+ *
+ * @module errors/domain-error
+ */
+import { VeloxError } from '../errors.js';
+/**
+ * Branded symbol for cross-package type guard checks.
+ * Uses `Symbol.for` so the same symbol is shared across package boundaries.
+ */
+const DOMAIN_ERROR_BRAND = Symbol.for('velox.domain-error');
+/**
+ * Abstract base class for domain-specific business logic errors.
+ *
+ * Subclasses declare `code`, `status`, and `message` as readonly class fields.
+ * The constructor accepts only the typed `data` payload.
+ *
+ * @template TData - Shape of the structured data payload
+ */
+export class DomainError extends VeloxError {
+    /**
+     * Structured data payload describing the error context.
+     */
+    data;
+    /**
+     * Brand marker for cross-package `isDomainError()` checks.
+     * @internal
+     */
+    [DOMAIN_ERROR_BRAND] = true;
+    /**
+     * Creates a new DomainError instance.
+     *
+     * @param data - Typed data payload for the error
+     */
+    constructor(data) {
+        // Pass placeholder values; subclass field initializers override them after super returns.
+        super('', 0);
+        this.data = data;
+        // Defer property synchronisation to a microtask-free post-init trick:
+        // We redefine `statusCode` as a getter so it always reflects the subclass's
+        // `status` field, which is set by the subclass's field initializers AFTER
+        // this constructor returns.
+        Object.defineProperty(this, 'statusCode', {
+            get() {
+                return this.status;
+            },
+            enumerable: true,
+            configurable: true,
+        });
+        // `name` should reflect the concrete subclass for stack traces and toJSON().
+        // Subclass field initializers haven't run yet, so we read from the constructor.
+        this.name = this.constructor.name;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Converts domain error to JSON format for API responses.
+     * Includes `code` and `data` alongside the standard VeloxError fields.
+     */
+    toJSON() {
+        return {
+            error: this.name,
+            message: this.message,
+            statusCode: this.statusCode,
+            code: this.code,
+            data: this.data,
+        };
+    }
+}
+/**
+ * Type guard to check whether an unknown value is a DomainError.
+ *
+ * Uses a branded symbol (`Symbol.for('velox.domain-error')`) so the check
+ * works across package boundaries even when multiple copies of `@veloxts/core`
+ * are installed.
+ *
+ * @param value - Value to check
+ * @returns `true` if `value` is a DomainError instance
+ */
+export function isDomainError(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    return value[DOMAIN_ERROR_BRAND] === true;
+}

package/dist/index.d.ts

@@ -21,6 +21,8 @@ export type { StartOptions } from './app.js';
 export { VeloxApp, velox, veloxApp } from './app.js';
 export type { BaseContext } from './context.js';
 export { createContext, isContext, setupContextHook, setupTestContext } from './context.js';
+export type { DomainErrorJSON } from './errors/domain-error.js';
+export { DomainError, isDomainError } from './errors/domain-error.js';
 export type { ConflictErrorResponse, ErrorCode, ErrorResponse, ForbiddenErrorResponse, GenericErrorResponse, InterpolationVars, NotFoundErrorResponse, ServiceUnavailableErrorResponse, TooManyRequestsErrorResponse, UnauthorizedErrorResponse, UnprocessableEntityErrorResponse, ValidationErrorResponse, VeloxCoreErrorCode, VeloxErrorCode, VeloxErrorCodeRegistry, } from './errors.js';
 export { assertNever, ConfigurationError, ConflictError, ForbiddenError, fail, isConfigurationError, isConflictError, isForbiddenError, isNotFoundError, isNotFoundErrorResponse, isServiceUnavailableError, isTooManyRequestsError, isUnauthorizedError, isUnprocessableEntityError, isValidationError, isValidationErrorResponse, isVeloxError, isVeloxFailure, logDeprecation, logWarning, NotFoundError, ServiceUnavailableError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, ValidationError, VeloxError, VeloxFailure, } from './errors.js';
 export type { ContextPluginConfig, InferPluginOptions, PluginMetadata, PluginOptions, VeloxPlugin, } from './plugin.js';

package/dist/index.js

@@ -21,6 +21,7 @@ const packageJson = require('../package.json');
 export const VELOX_VERSION = packageJson.version ?? '0.0.0-unknown';
 export { VeloxApp, velox, veloxApp } from './app.js';
 export { createContext, isContext, setupContextHook, setupTestContext } from './context.js';
+export { DomainError, isDomainError } from './errors/domain-error.js';
 export { assertNever, ConfigurationError, ConflictError, ForbiddenError, fail, isConfigurationError, isConflictError, isForbiddenError, isNotFoundError, isNotFoundErrorResponse, isServiceUnavailableError, isTooManyRequestsError, isUnauthorizedError, isUnprocessableEntityError, isValidationError, isValidationErrorResponse, isVeloxError, isVeloxFailure, logDeprecation, logWarning, NotFoundError, ServiceUnavailableError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, ValidationError, VeloxError, VeloxFailure, } from './errors.js';
 export { defineContextPlugin, definePlugin, isFastifyPlugin, isVeloxPlugin, validatePluginMetadata, } from './plugin.js';
 export { isValidHost, isValidPort } from './utils/config.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/core",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Fastify wrapper and plugin system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     }
   },
   "dependencies": {
-    "fastify": "5.7.4",
+    "fastify": "5.8.2",
     "fastify-plugin": "5.1.0",
     "picocolors": "1.1.1"
   },
@@ -43,10 +43,10 @@
   },
   "devDependencies": {
     "@fastify/static": "9.0.0",
-    "@types/node": "25.2.3",
-    "@vitest/coverage-v8": "4.0.18",
+    "@types/node": "25.5.0",
+    "@vitest/coverage-v8": "4.1.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.18"
+    "vitest": "4.1.0"
   },
   "keywords": [
     "velox",