raffel 0.1.2

package/dist/errors/factories.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Error Factories
+ *
+ * Pre-built error helpers for common error scenarios.
+ * Each factory creates a RaffelError with both string code and numeric status.
+ */
+import { RaffelError } from '../core/router.js';
+/**
+ * Pre-built error factories for consistent error handling
+ *
+ * All factories create errors with both string code and numeric status.
+ *
+ * @example
+ * ```typescript
+ * throw Errors.notFound('User', userId)
+ * // Creates: { code: 'NOT_FOUND', status: 404, message: "User 'abc' not found" }
+ *
+ * throw Errors.validation('email', 'must be valid')
+ * // Creates: { code: 'VALIDATION_ERROR', status: 400, message: "email: must be valid" }
+ * ```
+ */
+export declare const Errors: {
+    /**
+     * Resource not found
+     * @param resource - Name of the resource (e.g., 'User', 'Order')
+     * @param id - Optional resource identifier
+     */
+    readonly notFound: (resource: string, id?: string | number) => RaffelError;
+    /**
+     * Validation error
+     * @param field - Field name that failed validation
+     * @param reason - Why validation failed
+     * @param value - Optional offending value
+     */
+    readonly validation: (field: string, reason: string, value?: unknown) => RaffelError;
+    /**
+     * Multiple validation errors
+     * @param errors - Array of field errors
+     */
+    readonly validationMultiple: (errors: Array<{
+        field: string;
+        reason: string;
+    }>) => RaffelError;
+    /**
+     * Authentication required
+     * @param reason - Optional reason
+     */
+    readonly unauthorized: (reason?: string) => RaffelError;
+    /**
+     * Permission denied
+     * @param reason - Why permission was denied
+     */
+    readonly forbidden: (reason?: string) => RaffelError;
+    /**
+     * Rate limit exceeded
+     * @param retryAfter - Optional seconds until retry is allowed
+     */
+    readonly rateLimit: (retryAfter?: number) => RaffelError;
+    /**
+     * Request timeout
+     * @param operation - What operation timed out
+     */
+    readonly timeout: (operation?: string) => RaffelError;
+    /**
+     * Internal server error
+     * @param message - Error message
+     * @param details - Optional additional details
+     */
+    readonly internal: (message?: string, details?: unknown) => RaffelError;
+    /**
+     * Bad request / invalid argument
+     * @param message - What was wrong with the request
+     */
+    readonly badRequest: (message: string) => RaffelError;
+    /**
+     * Resource already exists
+     * @param resource - Name of the resource
+     * @param identifier - What makes it duplicate
+     */
+    readonly alreadyExists: (resource: string, identifier?: string) => RaffelError;
+    /**
+     * Precondition failed
+     * @param condition - What condition was not met
+     */
+    readonly preconditionFailed: (condition: string) => RaffelError;
+    /**
+     * Resource exhausted (quota, disk space, etc.)
+     * @param resource - What resource is exhausted
+     */
+    readonly resourceExhausted: (resource: string) => RaffelError;
+    /**
+     * Operation cancelled
+     * @param operation - What was cancelled
+     */
+    readonly cancelled: (operation?: string) => RaffelError;
+    /**
+     * Feature not implemented
+     * @param feature - What feature is not implemented
+     */
+    readonly unimplemented: (feature?: string) => RaffelError;
+    /**
+     * Service unavailable
+     * @param service - What service is unavailable
+     */
+    readonly unavailable: (service?: string) => RaffelError;
+    /**
+     * Unprocessable entity - semantically invalid request
+     *
+     * Use for business logic validation (e.g., "can't delete user with active orders")
+     * vs validation() for schema/syntactic validation.
+     *
+     * @param reason - Why the entity cannot be processed
+     * @param details - Optional additional details
+     */
+    readonly unprocessable: (reason: string, details?: unknown) => RaffelError;
+    /**
+     * Bad gateway - upstream service returned invalid response
+     * @param upstream - Name of the upstream service
+     * @param details - Optional error details
+     */
+    readonly badGateway: (upstream?: string, details?: unknown) => RaffelError;
+    /**
+     * Gateway timeout - upstream service did not respond in time
+     * @param upstream - Name of the upstream service
+     * @param timeoutMs - Optional timeout value in milliseconds
+     */
+    readonly gatewayTimeout: (upstream?: string, timeoutMs?: number) => RaffelError;
+    /**
+     * Data loss / corruption detected
+     * @param message - What happened
+     */
+    readonly dataLoss: (message: string) => RaffelError;
+    /**
+     * Create a custom error
+     * @param code - Error code
+     * @param message - Error message
+     * @param details - Optional details
+     * @param status - Optional custom status code
+     */
+    readonly custom: (code: string, message: string, details?: unknown, status?: number) => RaffelError;
+};
+//# sourceMappingURL=factories.d.ts.map

package/dist/errors/factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../../src/errors/factories.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,MAAM;IACjB;;;;OAIG;kCACgB,MAAM,OAAO,MAAM,GAAG,MAAM,KAAG,WAAW;IAK7D;;;;;OAKG;iCACe,MAAM,UAAU,MAAM,UAAU,OAAO,KAAG,WAAW;IAQvE;;;OAGG;0CACwB,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,KAAG,WAAW;IAKjF;;;OAGG;qCACmB,MAAM,KAAG,WAAW;IAO1C;;;OAGG;kCACgB,MAAM,KAAG,WAAW;IAOvC;;;OAGG;sCACoB,MAAM,KAAG,WAAW;IAQ3C;;;OAGG;mCACiB,MAAM,KAAG,WAAW;IAKxC;;;;OAIG;kCACgB,MAAM,YAAY,OAAO,KAAG,WAAW;IAQ1D;;;OAGG;mCACiB,MAAM,KAAG,WAAW;IAIxC;;;;OAIG;uCACqB,MAAM,eAAe,MAAM,KAAG,WAAW;IAOjE;;;OAGG;6CAC2B,MAAM,KAAG,WAAW;IAIlD;;;OAGG;2CACyB,MAAM,KAAG,WAAW;IAIhD;;;OAGG;qCACmB,MAAM,KAAG,WAAW;IAK1C;;;OAGG;uCACqB,MAAM,KAAG,WAAW;IAK5C;;;OAGG;qCACmB,MAAM,KAAG,WAAW;IAK1C;;;;;;;;OAQG;qCACmB,MAAM,YAAY,OAAO,KAAG,WAAW;IAI7D;;;;OAIG;qCACmB,MAAM,YAAY,OAAO,KAAG,WAAW;IAO7D;;;;OAIG;yCACuB,MAAM,cAAc,MAAM,KAAG,WAAW;IAUlE;;;OAGG;iCACe,MAAM,KAAG,WAAW;IAItC;;;;;;OAMG;4BACU,MAAM,WAAW,MAAM,YAAY,OAAO,WAAW,MAAM,KAAG,WAAW;CAG9E,CAAA"}

package/dist/errors/factories.js

@@ -0,0 +1,201 @@
+/**
+ * Error Factories
+ *
+ * Pre-built error helpers for common error scenarios.
+ * Each factory creates a RaffelError with both string code and numeric status.
+ */
+import { RaffelError } from '../core/router.js';
+/**
+ * Pre-built error factories for consistent error handling
+ *
+ * All factories create errors with both string code and numeric status.
+ *
+ * @example
+ * ```typescript
+ * throw Errors.notFound('User', userId)
+ * // Creates: { code: 'NOT_FOUND', status: 404, message: "User 'abc' not found" }
+ *
+ * throw Errors.validation('email', 'must be valid')
+ * // Creates: { code: 'VALIDATION_ERROR', status: 400, message: "email: must be valid" }
+ * ```
+ */
+export const Errors = {
+    /**
+     * Resource not found
+     * @param resource - Name of the resource (e.g., 'User', 'Order')
+     * @param id - Optional resource identifier
+     */
+    notFound(resource, id) {
+        const message = id ? `${resource} '${id}' not found` : `${resource} not found`;
+        return new RaffelError('NOT_FOUND', message, { resource, id });
+    },
+    /**
+     * Validation error
+     * @param field - Field name that failed validation
+     * @param reason - Why validation failed
+     * @param value - Optional offending value
+     */
+    validation(field, reason, value) {
+        return new RaffelError('VALIDATION_ERROR', `${field}: ${reason}`, {
+            field,
+            reason,
+            value,
+        });
+    },
+    /**
+     * Multiple validation errors
+     * @param errors - Array of field errors
+     */
+    validationMultiple(errors) {
+        const message = errors.map((e) => `${e.field}: ${e.reason}`).join('; ');
+        return new RaffelError('VALIDATION_ERROR', message, { errors });
+    },
+    /**
+     * Authentication required
+     * @param reason - Optional reason
+     */
+    unauthorized(reason) {
+        return new RaffelError('UNAUTHENTICATED', reason || 'Authentication required');
+    },
+    /**
+     * Permission denied
+     * @param reason - Why permission was denied
+     */
+    forbidden(reason) {
+        return new RaffelError('PERMISSION_DENIED', reason || 'Access denied');
+    },
+    /**
+     * Rate limit exceeded
+     * @param retryAfter - Optional seconds until retry is allowed
+     */
+    rateLimit(retryAfter) {
+        return new RaffelError('RATE_LIMITED', 'Too many requests', retryAfter ? { retryAfter } : undefined);
+    },
+    /**
+     * Request timeout
+     * @param operation - What operation timed out
+     */
+    timeout(operation) {
+        const message = operation ? `Operation '${operation}' timed out` : 'Request timed out';
+        return new RaffelError('DEADLINE_EXCEEDED', message);
+    },
+    /**
+     * Internal server error
+     * @param message - Error message
+     * @param details - Optional additional details
+     */
+    internal(message, details) {
+        return new RaffelError('INTERNAL_ERROR', message || 'An internal error occurred', details);
+    },
+    /**
+     * Bad request / invalid argument
+     * @param message - What was wrong with the request
+     */
+    badRequest(message) {
+        return new RaffelError('INVALID_ARGUMENT', message);
+    },
+    /**
+     * Resource already exists
+     * @param resource - Name of the resource
+     * @param identifier - What makes it duplicate
+     */
+    alreadyExists(resource, identifier) {
+        const message = identifier
+            ? `${resource} with ${identifier} already exists`
+            : `${resource} already exists`;
+        return new RaffelError('ALREADY_EXISTS', message, { resource, identifier });
+    },
+    /**
+     * Precondition failed
+     * @param condition - What condition was not met
+     */
+    preconditionFailed(condition) {
+        return new RaffelError('FAILED_PRECONDITION', condition);
+    },
+    /**
+     * Resource exhausted (quota, disk space, etc.)
+     * @param resource - What resource is exhausted
+     */
+    resourceExhausted(resource) {
+        return new RaffelError('RESOURCE_EXHAUSTED', `${resource} exhausted`);
+    },
+    /**
+     * Operation cancelled
+     * @param operation - What was cancelled
+     */
+    cancelled(operation) {
+        const message = operation ? `Operation '${operation}' was cancelled` : 'Operation cancelled';
+        return new RaffelError('CANCELLED', message);
+    },
+    /**
+     * Feature not implemented
+     * @param feature - What feature is not implemented
+     */
+    unimplemented(feature) {
+        const message = feature ? `Feature '${feature}' is not implemented` : 'Not implemented';
+        return new RaffelError('UNIMPLEMENTED', message);
+    },
+    /**
+     * Service unavailable
+     * @param service - What service is unavailable
+     */
+    unavailable(service) {
+        const message = service ? `Service '${service}' is unavailable` : 'Service unavailable';
+        return new RaffelError('UNAVAILABLE', message);
+    },
+    /**
+     * Unprocessable entity - semantically invalid request
+     *
+     * Use for business logic validation (e.g., "can't delete user with active orders")
+     * vs validation() for schema/syntactic validation.
+     *
+     * @param reason - Why the entity cannot be processed
+     * @param details - Optional additional details
+     */
+    unprocessable(reason, details) {
+        return new RaffelError('UNPROCESSABLE_ENTITY', reason, details);
+    },
+    /**
+     * Bad gateway - upstream service returned invalid response
+     * @param upstream - Name of the upstream service
+     * @param details - Optional error details
+     */
+    badGateway(upstream, details) {
+        const message = upstream
+            ? `Invalid response from upstream service '${upstream}'`
+            : 'Invalid response from upstream service';
+        return new RaffelError('BAD_GATEWAY', message, details);
+    },
+    /**
+     * Gateway timeout - upstream service did not respond in time
+     * @param upstream - Name of the upstream service
+     * @param timeoutMs - Optional timeout value in milliseconds
+     */
+    gatewayTimeout(upstream, timeoutMs) {
+        let message = upstream
+            ? `Upstream service '${upstream}' timed out`
+            : 'Upstream service timed out';
+        if (timeoutMs) {
+            message += ` after ${timeoutMs}ms`;
+        }
+        return new RaffelError('GATEWAY_TIMEOUT', message, timeoutMs ? { timeoutMs } : undefined);
+    },
+    /**
+     * Data loss / corruption detected
+     * @param message - What happened
+     */
+    dataLoss(message) {
+        return new RaffelError('DATA_LOSS', message);
+    },
+    /**
+     * Create a custom error
+     * @param code - Error code
+     * @param message - Error message
+     * @param details - Optional details
+     * @param status - Optional custom status code
+     */
+    custom(code, message, details, status) {
+        return new RaffelError(code, message, details, status);
+    },
+};
+//# sourceMappingURL=factories.js.map

package/dist/errors/factories.js.map

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

package/dist/errors/factories.unit.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Error Factories Tests
+ *
+ * Tests for pre-built error helpers.
+ */
+export {};
+//# sourceMappingURL=factories.unit.test.d.ts.map

package/dist/errors/factories.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factories.unit.test.d.ts","sourceRoot":"","sources":["../../src/errors/factories.unit.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}