@veloxts/core 0.2.0 → 0.3.0

package/dist/context.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Context system for request-scoped state
+ * Supports TypeScript declaration merging for plugin extensions
+ * @module context
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+/**
+ * Base context interface available in all request handlers
+ *
+ * Plugins extend this via TypeScript declaration merging to add
+ * their own properties (e.g., database clients, user sessions, etc.)
+ *
+ * @example
+ * ```typescript
+ * // In a plugin file:
+ * declare module '@veloxts/core' {
+ *   interface BaseContext {
+ *     db: PrismaClient;
+ *     user?: User;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // In a route handler:
+ * server.get('/users', async (request) => {
+ *   const users = await request.context.db.user.findMany();
+ *   return users;
+ * });
+ * ```
+ */
+export interface BaseContext {
+    /**
+     * Fastify request object
+     * Provides access to request data (params, query, body, headers, etc.)
+     */
+    request: FastifyRequest;
+    /**
+     * Fastify reply object
+     * Provides access to response methods (send, status, header, etc.)
+     */
+    reply: FastifyReply;
+}
+/**
+ * Creates a context object for the current request
+ *
+ * This function is called automatically by the framework for each request
+ * via the `onRequest` hook. Users typically don't need to call this directly.
+ *
+ * @param request - Fastify request object
+ * @param reply - Fastify reply object
+ * @returns Context object with request and reply
+ *
+ * @internal
+ */
+export declare function createContext(request: FastifyRequest, reply: FastifyReply): BaseContext;
+/**
+ * Type guard to check if a value is a valid context object
+ *
+ * Uses the `in` operator for safe property access with proper null checks.
+ *
+ * @param value - Value to check
+ * @returns true if value is a valid BaseContext
+ *
+ * @example
+ * ```typescript
+ * if (isContext(someValue)) {
+ *   // TypeScript knows someValue has request and reply properties
+ *   console.log(someValue.request.url);
+ * }
+ * ```
+ */
+export declare function isContext(value: unknown): value is BaseContext;
+/**
+ * Augment Fastify's Request interface to include context
+ * This enables `request.context` in route handlers
+ */
+declare module 'fastify' {
+    interface FastifyRequest {
+        /**
+         * Request-scoped context object
+         * Contains request/reply and plugin-provided properties
+         */
+        context: BaseContext;
+    }
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,EAAE,cAAc,CAAC;IAExB;;;OAGG;IACH,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,GAAG,WAAW,CAKvF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAqB9D;AAED;;;GAGG;AACH,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB;;;WAGG;QACH,OAAO,EAAE,WAAW,CAAC;KACtB;CACF"}

package/dist/context.js

@@ -0,0 +1,57 @@
+/**
+ * Context system for request-scoped state
+ * Supports TypeScript declaration merging for plugin extensions
+ * @module context
+ */
+/**
+ * Creates a context object for the current request
+ *
+ * This function is called automatically by the framework for each request
+ * via the `onRequest` hook. Users typically don't need to call this directly.
+ *
+ * @param request - Fastify request object
+ * @param reply - Fastify reply object
+ * @returns Context object with request and reply
+ *
+ * @internal
+ */
+export function createContext(request, reply) {
+    return {
+        request,
+        reply,
+    };
+}
+/**
+ * Type guard to check if a value is a valid context object
+ *
+ * Uses the `in` operator for safe property access with proper null checks.
+ *
+ * @param value - Value to check
+ * @returns true if value is a valid BaseContext
+ *
+ * @example
+ * ```typescript
+ * if (isContext(someValue)) {
+ *   // TypeScript knows someValue has request and reply properties
+ *   console.log(someValue.request.url);
+ * }
+ * ```
+ */
+export function isContext(value) {
+    // Early return for non-objects
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    // Check properties exist using 'in' operator
+    if (!('request' in value) || !('reply' in value)) {
+        return false;
+    }
+    // After 'in' checks, safely access properties
+    const ctx = value;
+    // Verify request and reply are non-null objects
+    return (typeof ctx.request === 'object' &&
+        ctx.request !== null &&
+        typeof ctx.reply === 'object' &&
+        ctx.reply !== null);
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4CH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,OAAuB,EAAE,KAAmB;IACxE,OAAO;QACL,OAAO;QACP,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,+BAA+B;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,6CAA6C;IAC7C,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,8CAA8C;IAC9C,MAAM,GAAG,GAAG,KAA6C,CAAC;IAE1D,gDAAgD;IAChD,OAAO,CACL,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAC/B,GAAG,CAAC,OAAO,KAAK,IAAI;QACpB,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;QAC7B,GAAG,CAAC,KAAK,KAAK,IAAI,CACnB,CAAC;AACJ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Error handling foundation for VeloxTS framework
+ * Provides base error classes with HTTP status codes and discriminated unions
+ * @module errors
+ */
+/**
+ * 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';
+/**
+ * Registry for error codes - allows plugins to extend via declaration merging
+ *
+ * @example
+ * ```typescript
+ * // In your plugin
+ * declare module '@veloxts/core' {
+ *   interface VeloxErrorCodeRegistry {
+ *     myPlugin: 'MY_PLUGIN_ERROR' | 'ANOTHER_ERROR';
+ *   }
+ * }
+ * ```
+ */
+export interface VeloxErrorCodeRegistry {
+    core: VeloxCoreErrorCode;
+}
+/**
+ * Union of all registered error codes from all packages
+ */
+export type VeloxErrorCode = VeloxErrorCodeRegistry[keyof VeloxErrorCodeRegistry];
+/**
+ * Base error response fields common to all errors
+ */
+interface BaseErrorResponse {
+    /** Error class name */
+    error: string;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code */
+    statusCode: number;
+    /** Error code for programmatic handling */
+    code?: string;
+}
+/**
+ * Validation error response with field-specific errors
+ */
+export interface ValidationErrorResponse extends BaseErrorResponse {
+    error: 'ValidationError';
+    statusCode: 400;
+    code: 'VALIDATION_ERROR';
+    /** Field-specific validation errors */
+    fields?: Record<string, string>;
+}
+/**
+ * Not found error response with resource details
+ */
+export interface NotFoundErrorResponse extends BaseErrorResponse {
+    error: 'NotFoundError';
+    statusCode: 404;
+    code: 'NOT_FOUND';
+    /** Type of resource that was not found */
+    resource: string;
+    /** Optional identifier of the resource */
+    resourceId?: string;
+}
+/**
+ * Generic VeloxTS error response for all other errors
+ */
+export interface GenericErrorResponse extends BaseErrorResponse {
+    error: string;
+    statusCode: number;
+    code?: string;
+}
+/**
+ * Discriminated union of all error response types
+ * Enables type-safe error handling based on the 'error' field
+ *
+ * @example
+ * ```typescript
+ * function handleError(response: ErrorResponse) {
+ *   if (response.error === 'ValidationError') {
+ *     // TypeScript knows response.fields exists here
+ *     console.log(response.fields);
+ *   }
+ * }
+ * ```
+ */
+export type ErrorResponse = ValidationErrorResponse | NotFoundErrorResponse | GenericErrorResponse;
+/**
+ * Type guard for validation error responses
+ */
+export declare function isValidationErrorResponse(response: ErrorResponse): response is ValidationErrorResponse;
+/**
+ * Type guard for not found error responses
+ */
+export declare function isNotFoundErrorResponse(response: ErrorResponse): response is NotFoundErrorResponse;
+/**
+ * Base error class for all VeloxTS framework errors
+ *
+ * Extends the standard Error class with HTTP status code and optional error code.
+ * All framework errors should extend this class for consistent error handling.
+ *
+ * @template TCode - The error code type (defaults to VeloxErrorCode)
+ *
+ * @example
+ * ```typescript
+ * throw new VeloxError('Something went wrong', 500);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * throw new VeloxError('Database connection failed', 503, 'DB_CONNECTION_ERROR');
+ * ```
+ */
+export declare class VeloxError<TCode extends string = string> extends Error {
+    /**
+     * HTTP status code for the error
+     */
+    readonly statusCode: number;
+    /**
+     * Optional error code for programmatic error handling
+     */
+    readonly code?: TCode;
+    /**
+     * Creates a new VeloxError instance
+     *
+     * @param message - Human-readable error message
+     * @param statusCode - HTTP status code (default: 500)
+     * @param code - Optional error code for programmatic handling
+     */
+    constructor(message: string, statusCode?: number, code?: TCode);
+    /**
+     * Converts error to JSON format for API responses
+     *
+     * @returns Error response object
+     */
+    toJSON(): GenericErrorResponse;
+}
+/**
+ * Validation error for invalid user input
+ *
+ * Used when request data fails validation (e.g., missing required fields,
+ * invalid format, type mismatches, etc.)
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid email format', {
+ *   email: 'Must be a valid email address'
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Missing required fields', {
+ *   name: 'Name is required',
+ *   email: 'Email is required'
+ * });
+ * ```
+ */
+export declare class ValidationError extends VeloxError<'VALIDATION_ERROR'> {
+    /**
+     * Field-specific validation errors
+     * Maps field names to error messages
+     */
+    readonly fields?: Record<string, string>;
+    /**
+     * Creates a new ValidationError instance
+     *
+     * @param message - General validation error message
+     * @param fields - Optional object mapping field names to specific error messages
+     */
+    constructor(message: string, fields?: Record<string, string>);
+    /**
+     * Converts validation error to JSON format with field details
+     *
+     * @returns Validation error response with field-specific errors
+     */
+    toJSON(): ValidationErrorResponse;
+}
+/**
+ * Configuration error for framework setup issues
+ *
+ * Used when the framework is misconfigured or used incorrectly.
+ * These errors indicate developer mistakes rather than runtime issues.
+ *
+ * @example
+ * ```typescript
+ * throw new ConfigurationError('VeloxApp must be started before registering routes');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * throw new ConfigurationError('Missing required plugin: @veloxts/orm');
+ * ```
+ */
+export declare class ConfigurationError extends VeloxError<'CONFIGURATION_ERROR'> {
+    /**
+     * Creates a new ConfigurationError instance
+     *
+     * @param message - Human-readable error message explaining the configuration issue
+     */
+    constructor(message: string);
+}
+/**
+ * Not found error for missing resources
+ *
+ * Used when a requested resource (user, post, file, etc.) doesn't exist
+ *
+ * @example
+ * ```typescript
+ * throw new NotFoundError('User');
+ * // Message: "User not found"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * throw new NotFoundError('Post', '123');
+ * // Message: "Post with id 123 not found"
+ * ```
+ */
+export declare class NotFoundError extends VeloxError<'NOT_FOUND'> {
+    /**
+     * Type of resource that was not found
+     */
+    readonly resource: string;
+    /**
+     * Optional identifier of the resource that was not found
+     */
+    readonly resourceId?: string;
+    /**
+     * Creates a new NotFoundError instance
+     *
+     * @param resource - Type of resource (e.g., "User", "Post", "File")
+     * @param resourceId - Optional identifier of the specific resource
+     */
+    constructor(resource: string, resourceId?: string);
+    /**
+     * Converts not found error to JSON format with resource details
+     *
+     * @returns Not found error response with resource information
+     */
+    toJSON(): NotFoundErrorResponse;
+}
+/**
+ * Type guard to check if an error is a VeloxError
+ *
+ * @param error - Error to check
+ * @returns true if error is a VeloxError instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // ... some code
+ * } catch (error) {
+ *   if (isVeloxError(error)) {
+ *     console.log('Status code:', error.statusCode);
+ *   }
+ * }
+ * ```
+ */
+export declare function isVeloxError(error: unknown): error is VeloxError;
+/**
+ * Type guard to check if an error is a ValidationError
+ *
+ * @param error - Error to check
+ * @returns true if error is a ValidationError instance
+ */
+export declare function isValidationError(error: unknown): error is ValidationError;
+/**
+ * Type guard to check if an error is a NotFoundError
+ *
+ * @param error - Error to check
+ * @returns true if error is a NotFoundError instance
+ */
+export declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Type guard to check if an error is a ConfigurationError
+ *
+ * @param error - Error to check
+ * @returns true if error is a ConfigurationError instance
+ */
+export declare function isConfigurationError(error: unknown): error is ConfigurationError;
+/**
+ * Helper to ensure exhaustive handling of error types
+ * Throws at compile time if a case is not handled
+ *
+ * @example
+ * ```typescript
+ * function handleError(error: VeloxError): string {
+ *   if (isValidationError(error)) return 'validation';
+ *   if (isNotFoundError(error)) return 'not found';
+ *   return 'generic';
+ * }
+ * ```
+ */
+export declare function assertNever(value: never): never;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B,kBAAkB,GAClB,WAAW,GACX,qBAAqB,GACrB,2BAA2B,GAC3B,wBAAwB,GACxB,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,GACnB,yBAAyB,CAAC;AAE9B;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC,MAAM,sBAAsB,CAAC,CAAC;AAMlF;;GAEG;AACH,UAAU,iBAAiB;IACzB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,GAAG,CAAC;IAChB,IAAI,EAAE,kBAAkB,CAAC;IACzB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,KAAK,EAAE,eAAe,CAAC;IACvB,UAAU,EAAE,GAAG,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,uBAAuB,GAAG,qBAAqB,GAAG,oBAAoB,CAAC;AAEnG;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,aAAa,GACtB,QAAQ,IAAI,uBAAuB,CAErC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,aAAa,GACtB,QAAQ,IAAI,qBAAqB,CAEnC;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,UAAU,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,KAAK;IAClE;;OAEG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;OAEG;IACH,SAAgB,IAAI,CAAC,EAAE,KAAK,CAAC;IAE7B;;;;;;OAMG;gBACS,OAAO,EAAE,MAAM,EAAE,UAAU,GAAE,MAAY,EAAE,IAAI,CAAC,EAAE,KAAK;IAYnE;;;;OAIG;IACH,MAAM,IAAI,oBAAoB;CAQ/B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,eAAgB,SAAQ,UAAU,CAAC,kBAAkB,CAAC;IACjE;;;OAGG;IACH,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhD;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAU5D;;;;OAIG;IACM,MAAM,IAAI,uBAAuB;CAS3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,kBAAmB,SAAQ,UAAU,CAAC,qBAAqB,CAAC;IACvE;;;;OAIG;gBACS,OAAO,EAAE,MAAM;CAQ5B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,UAAU,CAAC,WAAW,CAAC;IACxD;;OAEG;IACH,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC;;OAEG;IACH,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpC;;;;;OAKG;gBACS,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;IAejD;;;;OAIG;IACM,MAAM,IAAI,qBAAqB;CAUzC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAEhF;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAE/C"}