@c15t/backend 1.8.0 → 2.0.0-rc.0

package/src/pkgs/results/index.ts

@@ -1,115 +0,0 @@
-/**
- * # DoubleTie Results Package
- *
- * A comprehensive outcome handling system for TypeScript applications that implements
- * the Result pattern for managing both successful results and errors in a type-safe way.
- *
- * ## Key Features
- *
- * - **Type-safe Result pattern**: Based on the neverthrow library for handling outcomes
- * - **Structured error handling**: Rich error objects with codes, categories, and metadata
- * - **Recovery utilities**: Tools for gracefully handling expected error conditions
- * - **Processing pipelines**: Standardized patterns for validation and data retrieval
- * - **Zero dependency** (except for neverthrow)
- * - **H3.js integration**: Full integration with H3.js error handling
- *
- * ## Example Usage
- *
- * ```typescript
- * import {
- *   DoubleTieError,
- *   ERROR_CODES,
- *   ok,
- *   fail,
- *   tryCatchAsync
- * } from '@doubletie/results';
- *
- * // Create a function that returns a Result
- * async function getUserById(id: string) {
- *   return tryCatchAsync(
- *     async () => {
- *       const response = await fetch(`/api/users/${id}`);
- *
- *       if (!response.ok) {
- *         if (response.status === 404) {
- *           throw new DoubleTieError('User not found', {
- *             code: ERROR_CODES.NOT_FOUND,
- *             status: 404
- *           });
- *         }
- *
- *         throw new DoubleTieError('Failed to fetch user', {
- *           code: ERROR_CODES.API_ERROR,
- *           status: response.status
- *         });
- *       }
- *
- *       return response.json();
- *     },
- *     ERROR_CODES.UNKNOWN_ERROR
- *   );
- * }
- *
- * // Use the Result pattern to handle both success and error cases
- * const result = await getUserById('123');
- *
- * result.match(
- *   (user) => {
- *     console.log(`Found user: ${user.name}`);
- *     renderUserProfile(user);
- *   },
- *   (error) => {
- *     if (error.code === ERROR_CODES.NOT_FOUND) {
- *       showNotFoundMessage();
- *     } else {
- *       showErrorMessage(error.message);
- *     }
- *   }
- * );
- * ```
- *
- * @packageDocumentation
- */
-
-// Re-export everything from neverthrow that we use
-export {
-	err,
-	errAsync,
-	fromPromise,
-	ok,
-	okAsync,
-	Result,
-	ResultAsync,
-} from 'neverthrow';
-
-// Export our error class
-export { DoubleTieError } from './core/error-class';
-// Export our error classes, codes, and categories
-export { ERROR_CATEGORIES, ERROR_CODES } from './core/error-codes';
-// Export telemetry options
-export {
-	createTelemetryOptions,
-	type TelemetryConfig,
-} from './create-telemetry-options';
-// Export recovery utilities
-export {
-	withFallbackForCategory,
-	withFallbackForCodes,
-} from './results/recovery-utils';
-// Export result handling utilities
-export {
-	fail,
-	failAsync,
-	promiseToResult,
-	tryCatch,
-	tryCatchAsync,
-} from './results/result-helpers';
-// Export our types
-export type {
-	DoubleTieErrorOptions,
-	ErrorCategory,
-	ErrorMessageType,
-	ErrorTransformer,
-	SDKResult,
-	SDKResultAsync,
-} from './types';

package/src/pkgs/results/orpc-error-handler.ts

@@ -1,137 +0,0 @@
-import { ORPCError } from '@orpc/server';
-import { DoubleTieError } from './core/error-class';
-import { ERROR_CODES } from './core/error-codes';
-
-/**
- * Creates an oRPC error handler middleware that properly handles DoubleTieError instances
- *
- * This utility ensures consistent error handling across your oRPC application and
- * properly converts DoubleTieError objects to oRPC-compatible error responses.
- *
- * @returns An oRPC request handler middleware for error handling
- *
- * @example
- * ```typescript
- * import { createORPCErrorHandler } from '@doubletie/results';
- * import { OpenAPIHandler } from '@orpc/server';
- *
- * const handler = new OpenAPIHandler(router);
- *
- * // Register the error handler middleware
- * handler.use(createORPCErrorHandler());
- *
- * // Your routes...
- * ```
- */
-export function createORPCErrorHandler() {
-	return (
-		_request: Request,
-		context: { logger?: { error: (message: string, data?: object) => void } }
-	) => {
-		// Add error handler to context
-		return {
-			context: {
-				_onError: (error: unknown) => {
-					context.logger?.error('Error in oRPC error handler', { error });
-
-					// Handle DoubleTieError instances
-					if (error instanceof DoubleTieError) {
-						context.logger?.error('Handling DoubleTieError', {
-							code: error.code,
-							message: error.message,
-						});
-
-						// Convert DoubleTieError to ORPCError
-						throw new ORPCError(error.code, {
-							message: error.message,
-							cause: error.cause instanceof Error ? error.cause : undefined,
-							data: error.meta,
-						});
-					}
-
-					// For other errors, create a new ORPCError
-					context.logger?.error('Handling generic error', { error });
-					throw new ORPCError(ERROR_CODES.INTERNAL_SERVER_ERROR, {
-						message: error instanceof Error ? error.message : String(error),
-						cause: error instanceof Error ? error : undefined,
-					});
-				},
-			},
-		};
-	};
-}
-
-/**
- * Wraps an oRPC handler with error handling for DoubleTieError
- *
- * @param handler - The handler function to wrap
- * @returns A wrapped handler that automatically handles DoubleTieError instances
- *
- * @example
- * ```typescript
- * import { withORPCErrorHandling } from '@doubletie/results';
- * import { os } from '@orpc/server';
- *
- * const getUserHandler = os.handler(async ({ input }) => {
- *   // Your handler code that might throw DoubleTieError
- *   throw new DoubleTieError('User not found', {
- *     code: ERROR_CODES.NOT_FOUND,
- *     status: 404
- *   });
- * });
- *
- * // Wrap the handler with error handling
- * const safeGetUserHandler = withORPCErrorHandling(getUserHandler);
- * ```
- */
-export function withORPCErrorHandling<TInput, TOutput>(
-	handler: (
-		input: TInput,
-		context: {
-			logger?: { error: (message: string, data?: object) => void };
-			_onError?: (error: unknown) => unknown;
-		}
-	) => Promise<TOutput> | TOutput
-) {
-	return async (
-		input: TInput,
-		context: {
-			logger?: { error: (message: string, data?: object) => void };
-			_onError?: (error: unknown) => unknown;
-		}
-	) => {
-		try {
-			return await handler(input, context);
-		} catch (error) {
-			context.logger?.error('Error caught in withORPCErrorHandling', {
-				error,
-			});
-
-			// Handle DoubleTieError instances
-			if (error instanceof DoubleTieError) {
-				context.logger?.error('Handling DoubleTieError in wrapper', {
-					code: error.code,
-					message: error.message,
-				});
-
-				// Convert DoubleTieError to ORPCError
-				throw new ORPCError(error.code, {
-					message: error.message,
-					cause: error.cause instanceof Error ? error.cause : undefined,
-					data: error.meta,
-				});
-			}
-
-			// Use the context error handler if available
-			if (context._onError && typeof context._onError === 'function') {
-				return context._onError(error);
-			}
-
-			// Create and throw a new ORPCError
-			throw new ORPCError(ERROR_CODES.INTERNAL_SERVER_ERROR, {
-				message: error instanceof Error ? error.message : String(error),
-				cause: error instanceof Error ? error : undefined,
-			});
-		}
-	};
-}

package/src/pkgs/results/results/recovery-utils.ts

@@ -1,181 +0,0 @@
-import { err, ok } from 'neverthrow';
-import { withSpan } from '../core/tracing';
-import type { ErrorCategory, ErrorMessageType, SDKResult } from '../types';
-
-/**
- * Recovers from specific error codes by handling the error and returning a default value.
- * If the error is one of the specified codes, returns the default value.
- * Otherwise, passes the error through.
- *
- * @template TValue - Type of the success value in the result
- * @param result - The result that may contain an error
- * @param errorCodes - Array of error codes to recover from
- * @param defaultValue - Value to return if the error code matches
- * @returns The original result if successful or if error code doesn't match,
- *          or a new successful result with the default value
- *
- * @remarks
- * This function implements the "fallback value" pattern for error recovery.
- * It's particularly useful for handling expected error conditions like "not found"
- * where you want to provide a default value instead of propagating the error.
- *
- * The function does not modify the original result if it is successful or
- * if the error doesn't match any of the specified codes.
- *
- * @see withFallbackForCategory for recovery based on error category
- *
- * @example
- * ```typescript
- * import { withFallbackForCodes, ERROR_CODES } from '@doubletie/results';
- *
- * // Recover from not found errors with a default user
- * const getUserById = async (userId: string) => {
- *   const result = await fetchUserFromDatabase(userId);
- *
- *   return withFallbackForCodes(
- *     result,
- *     [ERROR_CODES.NOT_FOUND, ERROR_CODES.RESOURCE_DELETED],
- *     {
- *       id: userId,
- *       name: 'Unknown User',
- *       isDefault: true,
- *       email: 'unknown@example.com'
- *     }
- *   );
- * };
- *
- * // Usage with pattern matching
- * const userResult = await getUserById('123');
- * userResult.match(
- *   user => {
- *     console.log(`User: ${user.name}`);
- *     if (user.isDefault) {
- *       console.log('Using default user');
- *     }
- *   },
- *   error => console.error(`Unexpected error: ${error.message}`)
- * );
- * ```
- */
-export const withFallbackForCodes = <TValue>(
-	result: SDKResult<TValue>,
-	errorCodes: ErrorMessageType[],
-	defaultValue: TValue
-): SDKResult<TValue> => {
-	withSpan('recovery_with_fallback_codes', async (span) => {
-		span.setAttributes({
-			'recovery.type': 'error_codes',
-			'recovery.codes': errorCodes.join(','),
-			'result.is_error': result.isErr(),
-		});
-	});
-
-	return result.orElse((error) => {
-		if (error.code && errorCodes.includes(error.code)) {
-			withSpan('recovery_with_fallback_codes', async (span) => {
-				span.setAttributes({
-					'recovery.matched': true,
-					'recovery.error_code': error.code,
-				});
-			});
-			return ok(defaultValue);
-		}
-
-		withSpan('recovery_with_fallback_codes', async (span) => {
-			span.setAttributes({
-				'recovery.matched': false,
-				'recovery.error_code': error.code,
-			});
-		});
-		return err(error);
-	});
-};
-
-/**
- * Recovers from errors in a specific category by handling the error and returning a default value.
- * If the error's category matches the specified category, returns the default value.
- * Otherwise, passes the error through.
- *
- * @template TValue - Type of the success value in the result
- * @param result - The result that may contain an error
- * @param category - Error category to recover from
- * @param defaultValue - Value to return if the error category matches
- * @returns The original result if successful or if error category doesn't match,
- *          or a new successful result with the default value
- *
- * @remarks
- * This function is similar to `withFallbackForCodes` but matches errors based on
- * their category rather than specific error codes. This is useful when you want to
- * handle all errors in a particular domain (e.g., network, database, validation)
- * in a consistent way.
- *
- * The function does not modify the original result if it is successful or
- * if the error's category doesn't match the specified category.
- *
- * @see withFallbackForCodes for recovery based on specific error codes
- * @see ERROR_CATEGORIES for predefined categories
- *
- * @example
- * ```typescript
- * import { withFallbackForCategory, ERROR_CATEGORIES } from '@doubletie/results';
- *
- * // Recover from all network-related errors with a cached value
- * const fetchData = async (url: string, cachedData: ApiResponse) => {
- *   const result = await makeApiRequest(url);
- *
- *   return withFallbackForCategory(
- *     result,
- *     ERROR_CATEGORIES.NETWORK,
- *     {
- *       ...cachedData,
- *       fromCache: true,
- *       lastUpdated: new Date(cachedData.timestamp)
- *     }
- *   );
- * };
- *
- * // Usage with pattern matching
- * const dataResult = await fetchData('/api/stats', cachedStats);
- * dataResult.match(
- *   data => {
- *     if (data.fromCache) {
- *       console.log(`Using cached data from ${data.lastUpdated}`);
- *     }
- *     renderDashboard(data);
- *   },
- *   error => console.error(`Error: ${error.message}`)
- * );
- * ```
- */
-export const withFallbackForCategory = <TValue>(
-	result: SDKResult<TValue>,
-	category: ErrorCategory,
-	defaultValue: TValue
-): SDKResult<TValue> => {
-	withSpan('recovery_with_fallback_category', async (span) => {
-		span.setAttributes({
-			'recovery.type': 'error_category',
-			'recovery.category': category,
-			'result.is_error': result.isErr(),
-		});
-	});
-
-	return result.orElse((error) => {
-		if (error.category === category) {
-			withSpan('recovery_with_fallback_category', async (span) => {
-				span.setAttributes({
-					'recovery.matched': true,
-					'recovery.error_category': error.category,
-				});
-			});
-			return ok(defaultValue);
-		}
-		withSpan('recovery_with_fallback_category', async (span) => {
-			span.setAttributes({
-				'recovery.matched': false,
-				'recovery.error_category': error.category,
-			});
-		});
-		return err(error);
-	});
-};