@veloxts/core 0.1.0 → 0.2.0

package/dist/context.d.ts

@@ -1,88 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,57 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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

@@ -1,298 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}