@veloxts/core 0.7.5 → 0.7.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @veloxts/core
 
+## 0.7.7
+
+### Patch Changes
+
+- refactor(router): rename swaggerUIPlugin → swaggerPlugin, remove redundant exports
+
+## 0.7.6
+
+### Patch Changes
+
+- feat(router): custom access levels for the Resource API + advanced Architectural Patterns
+
 ## 0.7.5
 
 ### Patch Changes

package/dist/app.js

@@ -6,7 +6,7 @@
 import fastify from 'fastify';
 import fp from 'fastify-plugin';
 import { setupContextHook } from './context.js';
-import { isVeloxError, VeloxError } from './errors.js';
+import { ConflictError, isVeloxError, VeloxError } from './errors.js';
 import { isFastifyPlugin, isVeloxPlugin, validatePluginMetadata } from './plugin.js';
 import { requestLogger } from './plugins/request-logger.js';
 import { registerStatic } from './plugins/static.js';
@@ -136,13 +136,13 @@ export class VeloxApp {
                 if (error.name === 'PrismaClientKnownRequestError' &&
                     'code' in error &&
                     error.code === 'P2002') {
-                    const prismaError = error;
-                    const fields = prismaError.meta?.target?.join(', ') ?? 'field';
-                    return reply.status(409).send({
-                        error: 'ConflictError',
-                        message: `A record with this ${fields} already exists`,
-                        statusCode: 409,
-                    });
+                    const meta = 'meta' in error && typeof error.meta === 'object' && error.meta !== null
+                        ? error.meta
+                        : undefined;
+                    const target = Array.isArray(meta?.target) ? meta.target : [];
+                    const fieldNames = target.length > 0 ? target.join(', ') : 'field';
+                    const conflictError = new ConflictError(`A record with this ${fieldNames} already exists`, target.length > 0 ? target : undefined);
+                    return reply.status(conflictError.statusCode).send(conflictError.toJSON());
                 }
                 let statusCode = 500;
                 if (isVeloxError(error)) {

package/dist/errors/catalog.js

@@ -415,6 +415,43 @@ await app.register(databasePlugin({ client: prisma }));
         },
         docsUrl: 'https://veloxts.dev/errors/VELOX-4003',
     },
+    'VELOX-4004': {
+        code: 'VELOX-4004',
+        title: 'Unique Constraint Violation',
+        description: 'A database operation failed because it would create a duplicate record.',
+        statusCode: 409,
+        fix: {
+            suggestion: 'Check for existing records before creating, or use upsert.',
+            example: `// Use upsert to handle duplicates gracefully
+const user = await prisma.user.upsert({
+  where: { email: input.email },
+  create: input,
+  update: input,
+});
+
+// Or use the db() wrapper from @veloxts/orm
+import { db } from '@veloxts/orm';
+const user = await db(() => prisma.user.create({ data: input }));
+// Automatically throws ConflictError with field names`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-4004',
+    },
+    'VELOX-4005': {
+        code: 'VELOX-4005',
+        title: 'Foreign Key Constraint Violation',
+        description: 'A database operation failed because a related record does not exist.',
+        statusCode: 400,
+        fix: {
+            suggestion: 'Verify that all referenced records exist before creating or updating.',
+            example: `// Check related record exists first
+const post = await prisma.post.findUnique({ where: { id: input.postId } });
+if (!post) throw new NotFoundError('Post', input.postId);
+
+// Then create the comment
+const comment = await prisma.comment.create({ data: input });`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-4005',
+    },
     // ==========================================================================
     // VALIDATION ERRORS (5XXX)
     // ==========================================================================

package/dist/errors.d.ts

@@ -8,7 +8,7 @@ export { ERROR_CATALOG, ERROR_DOMAINS, type ErrorCatalogEntry, type ErrorCode, t
  * Known error codes in the VeloxTS framework core
  * Can be extended via declaration merging by plugins
  */
-export type VeloxCoreErrorCode = 'VALIDATION_ERROR' | 'NOT_FOUND' | 'CONFIGURATION_ERROR' | 'PLUGIN_REGISTRATION_ERROR' | 'SERVER_ALREADY_RUNNING' | 'SERVER_NOT_RUNNING' | 'SERVER_START_ERROR' | 'SERVER_STOP_ERROR' | 'INVALID_PLUGIN_METADATA';
+export type VeloxCoreErrorCode = 'VALIDATION_ERROR' | 'NOT_FOUND' | 'CONFLICT' | 'FORBIDDEN' | 'UNAUTHORIZED' | 'SERVICE_UNAVAILABLE' | 'RATE_LIMITED' | 'UNPROCESSABLE' | 'CONFIGURATION_ERROR' | 'PLUGIN_REGISTRATION_ERROR' | 'SERVER_ALREADY_RUNNING' | 'SERVER_NOT_RUNNING' | 'SERVER_START_ERROR' | 'SERVER_STOP_ERROR' | 'INVALID_PLUGIN_METADATA';
 /**
  * Registry for error codes - allows plugins to extend via declaration merging
  *
@@ -64,6 +64,56 @@ export interface NotFoundErrorResponse extends BaseErrorResponse {
     /** Optional identifier of the resource */
     resourceId?: string;
 }
+/**
+ * Conflict error response with field details
+ */
+export interface ConflictErrorResponse extends BaseErrorResponse {
+    error: 'ConflictError';
+    statusCode: 409;
+    code: 'CONFLICT';
+    fields?: string[];
+}
+/**
+ * Too many requests error response with retry timing
+ */
+export interface TooManyRequestsErrorResponse extends BaseErrorResponse {
+    error: 'TooManyRequestsError';
+    statusCode: 429;
+    code: 'RATE_LIMITED';
+    retryAfter?: number;
+}
+/**
+ * Forbidden error response
+ */
+export interface ForbiddenErrorResponse extends BaseErrorResponse {
+    error: 'ForbiddenError';
+    statusCode: 403;
+    code: 'FORBIDDEN';
+}
+/**
+ * Unauthorized error response
+ */
+export interface UnauthorizedErrorResponse extends BaseErrorResponse {
+    error: 'UnauthorizedError';
+    statusCode: 401;
+    code: 'UNAUTHORIZED';
+}
+/**
+ * Service unavailable error response
+ */
+export interface ServiceUnavailableErrorResponse extends BaseErrorResponse {
+    error: 'ServiceUnavailableError';
+    statusCode: 503;
+    code: 'SERVICE_UNAVAILABLE';
+}
+/**
+ * Unprocessable entity error response
+ */
+export interface UnprocessableEntityErrorResponse extends BaseErrorResponse {
+    error: 'UnprocessableEntityError';
+    statusCode: 422;
+    code: 'UNPROCESSABLE';
+}
 /**
  * Generic VeloxTS error response for all other errors
  */
@@ -86,7 +136,7 @@ export interface GenericErrorResponse extends BaseErrorResponse {
  * }
  * ```
  */
-export type ErrorResponse = ValidationErrorResponse | NotFoundErrorResponse | GenericErrorResponse;
+export type ErrorResponse = ValidationErrorResponse | NotFoundErrorResponse | ConflictErrorResponse | TooManyRequestsErrorResponse | ForbiddenErrorResponse | UnauthorizedErrorResponse | ServiceUnavailableErrorResponse | UnprocessableEntityErrorResponse | GenericErrorResponse;
 /**
  * Type guard for validation error responses
  */
@@ -272,6 +322,95 @@ export declare class NotFoundError extends VeloxError<'NOT_FOUND'> {
      */
     toJSON(): NotFoundErrorResponse;
 }
+/**
+ * Conflict error for duplicate resources
+ *
+ * Used when an operation would violate a uniqueness constraint
+ * (e.g., creating a user with an email that already exists)
+ *
+ * @example
+ * ```typescript
+ * throw new ConflictError('A user with this email already exists', ['email']);
+ * ```
+ */
+export declare class ConflictError extends VeloxError<'CONFLICT'> {
+    readonly fields?: string[];
+    constructor(message: string, fields?: string[]);
+    toJSON(): ConflictErrorResponse;
+}
+/**
+ * Forbidden error for insufficient permissions
+ *
+ * Used when an authenticated user lacks the required permissions
+ * for an operation (different from UnauthorizedError which means not authenticated)
+ *
+ * @example
+ * ```typescript
+ * throw new ForbiddenError('You do not have permission to delete this resource');
+ * ```
+ */
+export declare class ForbiddenError extends VeloxError<'FORBIDDEN'> {
+    constructor(message?: string);
+    toJSON(): ForbiddenErrorResponse;
+}
+/**
+ * Unauthorized error for missing or invalid authentication
+ *
+ * Used when a request lacks valid authentication credentials
+ *
+ * @example
+ * ```typescript
+ * throw new UnauthorizedError('Invalid or expired token');
+ * ```
+ */
+export declare class UnauthorizedError extends VeloxError<'UNAUTHORIZED'> {
+    constructor(message?: string);
+    toJSON(): UnauthorizedErrorResponse;
+}
+/**
+ * Service unavailable error for downstream failures
+ *
+ * Used when an external service or dependency is unreachable
+ *
+ * @example
+ * ```typescript
+ * throw new ServiceUnavailableError('Payment gateway is temporarily unavailable');
+ * ```
+ */
+export declare class ServiceUnavailableError extends VeloxError<'SERVICE_UNAVAILABLE'> {
+    constructor(message?: string);
+    toJSON(): ServiceUnavailableErrorResponse;
+}
+/**
+ * Too many requests error for rate limiting
+ *
+ * Used when a client exceeds the allowed request rate
+ *
+ * @example
+ * ```typescript
+ * throw new TooManyRequestsError('Rate limit exceeded', 60);
+ * ```
+ */
+export declare class TooManyRequestsError extends VeloxError<'RATE_LIMITED'> {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+    toJSON(): TooManyRequestsErrorResponse;
+}
+/**
+ * Unprocessable entity error for semantically invalid requests
+ *
+ * Used when the request is syntactically valid but semantically wrong
+ * (e.g., trying to publish a draft that has no content)
+ *
+ * @example
+ * ```typescript
+ * throw new UnprocessableEntityError('Cannot publish a post without content');
+ * ```
+ */
+export declare class UnprocessableEntityError extends VeloxError<'UNPROCESSABLE'> {
+    constructor(message: string);
+    toJSON(): UnprocessableEntityErrorResponse;
+}
 /**
  * Type guard to check if an error is a VeloxError
  *
@@ -311,6 +450,30 @@ export declare function isNotFoundError(error: unknown): error is NotFoundError;
  * @returns true if error is a ConfigurationError instance
  */
 export declare function isConfigurationError(error: unknown): error is ConfigurationError;
+/**
+ * Type guard to check if an error is a ConflictError
+ */
+export declare function isConflictError(error: unknown): error is ConflictError;
+/**
+ * Type guard to check if an error is a ForbiddenError
+ */
+export declare function isForbiddenError(error: unknown): error is ForbiddenError;
+/**
+ * Type guard to check if an error is an UnauthorizedError
+ */
+export declare function isUnauthorizedError(error: unknown): error is UnauthorizedError;
+/**
+ * Type guard to check if an error is a ServiceUnavailableError
+ */
+export declare function isServiceUnavailableError(error: unknown): error is ServiceUnavailableError;
+/**
+ * Type guard to check if an error is a TooManyRequestsError
+ */
+export declare function isTooManyRequestsError(error: unknown): error is TooManyRequestsError;
+/**
+ * Type guard to check if an error is an UnprocessableEntityError
+ */
+export declare function isUnprocessableEntityError(error: unknown): error is UnprocessableEntityError;
 /**
  * Helper to ensure exhaustive handling of error types
  * Throws at compile time if a case is not handled

package/dist/errors.js

@@ -271,6 +271,177 @@ export class NotFoundError extends VeloxError {
         };
     }
 }
+/**
+ * Conflict error for duplicate resources
+ *
+ * Used when an operation would violate a uniqueness constraint
+ * (e.g., creating a user with an email that already exists)
+ *
+ * @example
+ * ```typescript
+ * throw new ConflictError('A user with this email already exists', ['email']);
+ * ```
+ */
+export class ConflictError extends VeloxError {
+    fields;
+    constructor(message, fields) {
+        super(message, 409, 'CONFLICT');
+        this.name = 'ConflictError';
+        this.fields = fields;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ConflictError);
+        }
+    }
+    toJSON() {
+        return {
+            error: 'ConflictError',
+            message: this.message,
+            statusCode: 409,
+            code: 'CONFLICT',
+            fields: this.fields,
+        };
+    }
+}
+/**
+ * Forbidden error for insufficient permissions
+ *
+ * Used when an authenticated user lacks the required permissions
+ * for an operation (different from UnauthorizedError which means not authenticated)
+ *
+ * @example
+ * ```typescript
+ * throw new ForbiddenError('You do not have permission to delete this resource');
+ * ```
+ */
+export class ForbiddenError extends VeloxError {
+    constructor(message = 'Forbidden') {
+        super(message, 403, 'FORBIDDEN');
+        this.name = 'ForbiddenError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ForbiddenError);
+        }
+    }
+    toJSON() {
+        return {
+            error: 'ForbiddenError',
+            message: this.message,
+            statusCode: 403,
+            code: 'FORBIDDEN',
+        };
+    }
+}
+/**
+ * Unauthorized error for missing or invalid authentication
+ *
+ * Used when a request lacks valid authentication credentials
+ *
+ * @example
+ * ```typescript
+ * throw new UnauthorizedError('Invalid or expired token');
+ * ```
+ */
+export class UnauthorizedError extends VeloxError {
+    constructor(message = 'Unauthorized') {
+        super(message, 401, 'UNAUTHORIZED');
+        this.name = 'UnauthorizedError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, UnauthorizedError);
+        }
+    }
+    toJSON() {
+        return {
+            error: 'UnauthorizedError',
+            message: this.message,
+            statusCode: 401,
+            code: 'UNAUTHORIZED',
+        };
+    }
+}
+/**
+ * Service unavailable error for downstream failures
+ *
+ * Used when an external service or dependency is unreachable
+ *
+ * @example
+ * ```typescript
+ * throw new ServiceUnavailableError('Payment gateway is temporarily unavailable');
+ * ```
+ */
+export class ServiceUnavailableError extends VeloxError {
+    constructor(message = 'Service unavailable') {
+        super(message, 503, 'SERVICE_UNAVAILABLE');
+        this.name = 'ServiceUnavailableError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ServiceUnavailableError);
+        }
+    }
+    toJSON() {
+        return {
+            error: 'ServiceUnavailableError',
+            message: this.message,
+            statusCode: 503,
+            code: 'SERVICE_UNAVAILABLE',
+        };
+    }
+}
+/**
+ * Too many requests error for rate limiting
+ *
+ * Used when a client exceeds the allowed request rate
+ *
+ * @example
+ * ```typescript
+ * throw new TooManyRequestsError('Rate limit exceeded', 60);
+ * ```
+ */
+export class TooManyRequestsError extends VeloxError {
+    retryAfter;
+    constructor(message = 'Too many requests', retryAfter) {
+        super(message, 429, 'RATE_LIMITED');
+        this.name = 'TooManyRequestsError';
+        this.retryAfter = retryAfter;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TooManyRequestsError);
+        }
+    }
+    toJSON() {
+        return {
+            error: 'TooManyRequestsError',
+            message: this.message,
+            statusCode: 429,
+            code: 'RATE_LIMITED',
+            retryAfter: this.retryAfter,
+        };
+    }
+}
+/**
+ * Unprocessable entity error for semantically invalid requests
+ *
+ * Used when the request is syntactically valid but semantically wrong
+ * (e.g., trying to publish a draft that has no content)
+ *
+ * @example
+ * ```typescript
+ * throw new UnprocessableEntityError('Cannot publish a post without content');
+ * ```
+ */
+export class UnprocessableEntityError extends VeloxError {
+    constructor(message) {
+        super(message, 422, 'UNPROCESSABLE');
+        this.name = 'UnprocessableEntityError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, UnprocessableEntityError);
+        }
+    }
+    toJSON() {
+        return {
+            error: 'UnprocessableEntityError',
+            message: this.message,
+            statusCode: 422,
+            code: 'UNPROCESSABLE',
+        };
+    }
+}
 // ============================================================================
 // Type Guards
 // ============================================================================
@@ -321,6 +492,42 @@ export function isNotFoundError(error) {
 export function isConfigurationError(error) {
     return error instanceof ConfigurationError;
 }
+/**
+ * Type guard to check if an error is a ConflictError
+ */
+export function isConflictError(error) {
+    return error instanceof ConflictError;
+}
+/**
+ * Type guard to check if an error is a ForbiddenError
+ */
+export function isForbiddenError(error) {
+    return error instanceof ForbiddenError;
+}
+/**
+ * Type guard to check if an error is an UnauthorizedError
+ */
+export function isUnauthorizedError(error) {
+    return error instanceof UnauthorizedError;
+}
+/**
+ * Type guard to check if an error is a ServiceUnavailableError
+ */
+export function isServiceUnavailableError(error) {
+    return error instanceof ServiceUnavailableError;
+}
+/**
+ * Type guard to check if an error is a TooManyRequestsError
+ */
+export function isTooManyRequestsError(error) {
+    return error instanceof TooManyRequestsError;
+}
+/**
+ * Type guard to check if an error is an UnprocessableEntityError
+ */
+export function isUnprocessableEntityError(error) {
+    return error instanceof UnprocessableEntityError;
+}
 // ============================================================================
 // Utility Types
 // ============================================================================

package/dist/index.d.ts

@@ -21,16 +21,21 @@ 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 { ErrorCode, ErrorResponse, GenericErrorResponse, InterpolationVars, NotFoundErrorResponse, ValidationErrorResponse, VeloxCoreErrorCode, VeloxErrorCode, VeloxErrorCodeRegistry, } from './errors.js';
-export { assertNever, ConfigurationError, fail, isConfigurationError, isNotFoundError, isNotFoundErrorResponse, isValidationError, isValidationErrorResponse, isVeloxError, isVeloxFailure, logDeprecation, logWarning, NotFoundError, ValidationError, VeloxError, VeloxFailure, } from './errors.js';
-export type { InferPluginOptions, PluginMetadata, PluginOptions, VeloxPlugin } from './plugin.js';
-export { definePlugin, isFastifyPlugin, isVeloxPlugin, validatePluginMetadata } from './plugin.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';
+export { defineContextPlugin, definePlugin, isFastifyPlugin, isVeloxPlugin, validatePluginMetadata, } from './plugin.js';
 export type { AsyncHandler, JsonArray, JsonObject, JsonPrimitive, JsonValue, LifecycleHook, ShutdownHandler, SyncHandler, } from './types.js';
 export type { FrozenVeloxAppConfig, ValidHost, ValidPort, VeloxAppConfig, VeloxFastifyOptions, } from './utils/config.js';
 export { isValidHost, isValidPort } from './utils/config.js';
 export type { AuthContextExtension, CombineContexts, ContextExtension, CoreContext, DbContextExtension, defineContext, MergeContext, SessionContextExtension, } from './typed-context.js';
 export type { CacheControl, StaticOptions } from './plugins/static.js';
 export { registerStatic } from './plugins/static.js';
+export { rawBodyPlugin } from './plugins/raw-body.js';
 export { requestLogger } from './plugins/request-logger.js';
 export type { Logger, LogLevel } from './utils/logger.js';
 export { createLogger } from './utils/logger.js';
+export type { FireAndForgetOptions } from './utils/fire-and-forget.js';
+export { fireAndForget } from './utils/fire-and-forget.js';
+export type { RetryOptions } from './utils/retry.js';
+export { withRetry } from './utils/retry.js';

package/dist/index.js

@@ -21,12 +21,18 @@ 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 { assertNever, ConfigurationError, fail, isConfigurationError, isNotFoundError, isNotFoundErrorResponse, isValidationError, isValidationErrorResponse, isVeloxError, isVeloxFailure, logDeprecation, logWarning, NotFoundError, ValidationError, VeloxError, VeloxFailure, } from './errors.js';
-export { definePlugin, isFastifyPlugin, isVeloxPlugin, validatePluginMetadata } from './plugin.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';
 export { registerStatic } from './plugins/static.js';
 // ============================================================================
+// Raw Body (Webhook Support)
+// ============================================================================
+export { rawBodyPlugin } from './plugins/raw-body.js';
+// ============================================================================
 // Request Logging (Development)
 // ============================================================================
 export { requestLogger } from './plugins/request-logger.js';
 export { createLogger } from './utils/logger.js';
+export { fireAndForget } from './utils/fire-and-forget.js';
+export { withRetry } from './utils/retry.js';

package/dist/plugin.d.ts

@@ -172,6 +172,58 @@ export declare function isVeloxPlugin(value: unknown): value is VeloxPlugin;
  * ```
  */
 export declare function isFastifyPlugin<Options extends PluginOptions = PluginOptions>(value: unknown): value is FastifyPluginAsync<Options>;
+/**
+ * Configuration for a context-injecting plugin
+ *
+ * @template TService - The type of service to inject into the context
+ */
+export interface ContextPluginConfig<TService> {
+    /** Plugin name (e.g., '@myapp/analytics') */
+    name: string;
+    /** Plugin version (semver) */
+    version: string;
+    /** Context key used to access the service (e.g., 'analytics' for ctx.analytics) */
+    contextKey: string;
+    /** Factory function to create the service instance */
+    create: () => TService | Promise<TService>;
+    /** Optional cleanup function called on server shutdown */
+    close?: (service: TService) => void | Promise<void>;
+}
+/**
+ * Creates a plugin that injects a service into the request context
+ *
+ * Eliminates the runtime boilerplate of `Symbol.for()`, `decorateRequest()`,
+ * `addHook('onRequest')`, and `addHook('onClose')` that every
+ * context-injecting plugin must implement.
+ *
+ * **Note on types:** You still need `declare module` for TypeScript to
+ * know about the context property. This helper handles the runtime
+ * injection; declaration merging handles the types:
+ *
+ * ```typescript
+ * declare module '@veloxts/core' {
+ *   interface BaseContext {
+ *     analytics: Analytics;
+ *   }
+ * }
+ * ```
+ *
+ * @template TService - The type of service to inject
+ * @param config - Plugin configuration
+ * @returns A VeloxPlugin ready for registration
+ *
+ * @example
+ * ```typescript
+ * export const analyticsPlugin = defineContextPlugin({
+ *   name: '@myapp/analytics',
+ *   version: '1.0.0',
+ *   contextKey: 'analytics',
+ *   create: () => new Analytics(process.env.ANALYTICS_KEY!),
+ *   close: (a) => a.flush(),
+ * });
+ * ```
+ */
+export declare function defineContextPlugin<TService>(config: ContextPluginConfig<TService>): VeloxPlugin;
 /**
  * Infers the options type from a VeloxPlugin
  *

package/dist/plugin.js

@@ -135,3 +135,66 @@ export function isVeloxPlugin(value) {
 export function isFastifyPlugin(value) {
     return typeof value === 'function';
 }
+/**
+ * Creates a plugin that injects a service into the request context
+ *
+ * Eliminates the runtime boilerplate of `Symbol.for()`, `decorateRequest()`,
+ * `addHook('onRequest')`, and `addHook('onClose')` that every
+ * context-injecting plugin must implement.
+ *
+ * **Note on types:** You still need `declare module` for TypeScript to
+ * know about the context property. This helper handles the runtime
+ * injection; declaration merging handles the types:
+ *
+ * ```typescript
+ * declare module '@veloxts/core' {
+ *   interface BaseContext {
+ *     analytics: Analytics;
+ *   }
+ * }
+ * ```
+ *
+ * @template TService - The type of service to inject
+ * @param config - Plugin configuration
+ * @returns A VeloxPlugin ready for registration
+ *
+ * @example
+ * ```typescript
+ * export const analyticsPlugin = defineContextPlugin({
+ *   name: '@myapp/analytics',
+ *   version: '1.0.0',
+ *   contextKey: 'analytics',
+ *   create: () => new Analytics(process.env.ANALYTICS_KEY!),
+ *   close: (a) => a.flush(),
+ * });
+ * ```
+ */
+export function defineContextPlugin(config) {
+    const symbolKey = Symbol.for(`${config.name}:${config.contextKey}`);
+    const plugin = definePlugin({
+        name: config.name,
+        version: config.version,
+        async register(fastify) {
+            const service = await config.create();
+            // Store on Fastify instance via symbol for programmatic retrieval
+            // (e.g., getCacheFromInstance pattern in ecosystem packages)
+            Object.defineProperty(fastify, symbolKey, {
+                value: service,
+                writable: false,
+                enumerable: false,
+                configurable: false,
+            });
+            fastify.decorateRequest(config.contextKey, undefined);
+            fastify.addHook('onRequest', async (request) => {
+                request[config.contextKey] = service;
+            });
+            if (config.close) {
+                const closeFn = config.close;
+                fastify.addHook('onClose', async () => {
+                    await closeFn(service);
+                });
+            }
+        },
+    });
+    return plugin;
+}

package/dist/plugins/raw-body.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Raw Body Plugin
+ *
+ * Preserves the raw request body as a Buffer on the request object.
+ * Required for webhook signature verification (Stripe, GitHub, etc.)
+ * where the raw bytes must match the HMAC signature.
+ *
+ * Uses a `preParsing` hook to capture the raw bytes before Fastify's
+ * built-in JSON parser processes them, so normal JSON parsing is preserved
+ * for all routes.
+ *
+ * @module plugins/raw-body
+ */
+declare module 'fastify' {
+    interface FastifyRequest {
+        /** Raw request body as Buffer (available when rawBodyPlugin is registered) */
+        rawBody?: Buffer;
+    }
+}
+/**
+ * Fastify plugin that preserves the raw request body.
+ *
+ * After registration, `request.rawBody` contains the raw Buffer
+ * for all requests. Fastify's built-in JSON parser continues to
+ * work normally — this plugin does not replace it.
+ *
+ * @example
+ * ```typescript
+ * import { rawBodyPlugin } from '@veloxts/core';
+ *
+ * await app.register(rawBodyPlugin);
+ *
+ * // In a webhook handler:
+ * const isValid = verifySignature(request.rawBody, request.headers['stripe-signature']);
+ * ```
+ */
+export declare const rawBodyPlugin: import("../plugin.js").VeloxPlugin<import("fastify").FastifyPluginOptions>;

package/dist/plugins/raw-body.js

@@ -0,0 +1,48 @@
+/**
+ * Raw Body Plugin
+ *
+ * Preserves the raw request body as a Buffer on the request object.
+ * Required for webhook signature verification (Stripe, GitHub, etc.)
+ * where the raw bytes must match the HMAC signature.
+ *
+ * Uses a `preParsing` hook to capture the raw bytes before Fastify's
+ * built-in JSON parser processes them, so normal JSON parsing is preserved
+ * for all routes.
+ *
+ * @module plugins/raw-body
+ */
+import { Readable } from 'node:stream';
+import { definePlugin } from '../plugin.js';
+/**
+ * Fastify plugin that preserves the raw request body.
+ *
+ * After registration, `request.rawBody` contains the raw Buffer
+ * for all requests. Fastify's built-in JSON parser continues to
+ * work normally — this plugin does not replace it.
+ *
+ * @example
+ * ```typescript
+ * import { rawBodyPlugin } from '@veloxts/core';
+ *
+ * await app.register(rawBodyPlugin);
+ *
+ * // In a webhook handler:
+ * const isValid = verifySignature(request.rawBody, request.headers['stripe-signature']);
+ * ```
+ */
+export const rawBodyPlugin = definePlugin({
+    name: '@veloxts/raw-body',
+    version: '1.0.0',
+    async register(fastify) {
+        fastify.decorateRequest('rawBody', undefined);
+        fastify.addHook('preParsing', async (request, _reply, payload) => {
+            const chunks = [];
+            for await (const chunk of payload) {
+                chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+            }
+            const rawBody = Buffer.concat(chunks);
+            request.rawBody = rawBody;
+            return Readable.from(rawBody);
+        });
+    },
+});

package/dist/utils/fire-and-forget.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Fire-and-forget utility for non-blocking side effects
+ *
+ * @module utils/fire-and-forget
+ */
+export interface FireAndForgetOptions {
+    /** Label for error logging context */
+    label?: string;
+    /** Custom error handler (defaults to VeloxTS logger) */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Execute a promise without awaiting it, catching and logging any errors.
+ *
+ * Use this for non-critical side effects (analytics, notifications, audit logs)
+ * that shouldn't block the main response.
+ *
+ * @param promise - The promise to execute in the background
+ * @param options - Optional label and error handler
+ *
+ * @example
+ * ```typescript
+ * import { fireAndForget } from '@veloxts/core';
+ *
+ * // In a procedure handler
+ * fireAndForget(analytics.track('user.created', { userId }), {
+ *   label: 'analytics',
+ * });
+ *
+ * return user; // Returns immediately
+ * ```
+ */
+export declare function fireAndForget(promise: Promise<unknown>, options?: FireAndForgetOptions): void;

package/dist/utils/fire-and-forget.js

@@ -0,0 +1,40 @@
+/**
+ * Fire-and-forget utility for non-blocking side effects
+ *
+ * @module utils/fire-and-forget
+ */
+import { createLogger } from './logger.js';
+const log = createLogger('core');
+/**
+ * Execute a promise without awaiting it, catching and logging any errors.
+ *
+ * Use this for non-critical side effects (analytics, notifications, audit logs)
+ * that shouldn't block the main response.
+ *
+ * @param promise - The promise to execute in the background
+ * @param options - Optional label and error handler
+ *
+ * @example
+ * ```typescript
+ * import { fireAndForget } from '@veloxts/core';
+ *
+ * // In a procedure handler
+ * fireAndForget(analytics.track('user.created', { userId }), {
+ *   label: 'analytics',
+ * });
+ *
+ * return user; // Returns immediately
+ * ```
+ */
+export function fireAndForget(promise, options) {
+    const { label, onError } = options ?? {};
+    promise.catch((error) => {
+        if (onError) {
+            onError(error);
+        }
+        else {
+            const prefix = label ? `[${label}] ` : '';
+            log.error(`${prefix}Fire-and-forget error:`, error);
+        }
+    });
+}

package/dist/utils/retry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Retry utility with exponential backoff
+ *
+ * @module utils/retry
+ */
+export interface RetryOptions {
+    /** Maximum number of attempts (default: 3, minimum: 1) */
+    attempts?: number;
+    /** Base delay in milliseconds (default: 500) */
+    delayMs?: number;
+    /** Use exponential backoff (default: true) */
+    exponential?: boolean;
+    /** Only retry if this predicate returns true */
+    retryIf?: (error: unknown) => boolean;
+    /**
+     * Called after each failed attempt with the error and the 1-based
+     * attempt number that just failed. Called on every failure including
+     * the final one.
+     */
+    onRetry?: (error: unknown, attempt: number) => void;
+}
+/**
+ * Retry an async operation with configurable backoff.
+ *
+ * @param fn - The async function to retry
+ * @param options - Retry configuration
+ * @returns The result of the first successful invocation
+ * @throws The last error if all attempts are exhausted
+ *
+ * @example
+ * ```typescript
+ * import { withRetry } from '@veloxts/core';
+ *
+ * const result = await withRetry(() => fetch('https://api.example.com/data'), {
+ *   attempts: 3,
+ *   retryIf: (err) => err instanceof Error && err.message.includes('ECONNRESET'),
+ *   onRetry: (err, attempt) => console.log(`Attempt ${attempt} failed:`, err),
+ * });
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/utils/retry.js

@@ -0,0 +1,48 @@
+/**
+ * Retry utility with exponential backoff
+ *
+ * @module utils/retry
+ */
+/**
+ * Retry an async operation with configurable backoff.
+ *
+ * @param fn - The async function to retry
+ * @param options - Retry configuration
+ * @returns The result of the first successful invocation
+ * @throws The last error if all attempts are exhausted
+ *
+ * @example
+ * ```typescript
+ * import { withRetry } from '@veloxts/core';
+ *
+ * const result = await withRetry(() => fetch('https://api.example.com/data'), {
+ *   attempts: 3,
+ *   retryIf: (err) => err instanceof Error && err.message.includes('ECONNRESET'),
+ *   onRetry: (err, attempt) => console.log(`Attempt ${attempt} failed:`, err),
+ * });
+ * ```
+ */
+export async function withRetry(fn, options) {
+    const { attempts = 3, delayMs = 500, exponential = true, retryIf, onRetry } = options ?? {};
+    if (attempts < 1) {
+        throw new Error('withRetry: attempts must be at least 1');
+    }
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (retryIf && !retryIf(error)) {
+                throw error;
+            }
+            onRetry?.(error, attempt);
+            if (attempt < attempts) {
+                const delay = exponential ? delayMs * 2 ** (attempt - 1) : delayMs;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+    }
+    throw lastError;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/core",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Fastify wrapper and plugin system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",