@c15t/backend 1.0.0 → 1.1.0-canary.0

package/src/pkgs/logger/logger-factory.ts

@@ -1,121 +0,0 @@
-import { formatMessage } from './console-formatter';
-import { levels, shouldPublishLog } from './log-levels';
-import { withLogSpan } from './telemetry';
-import type { LogEntry, LogLevel, Logger, LoggerOptions } from './types';
-
-/**
- * Creates a configured logger instance with methods for each log level.
- *
- * @param options - Configuration options for the logger or an existing logger instance
- * @returns An object with methods for each log level
- *
- * @example
- * ```ts
- * // Create a logger that only shows warnings and errors
- * const logger = createLogger({ level: 'warn', appName: 'c15t' });
- *
- * // These will be output
- * logger.error('This is an error');
- * logger.warn('This is a warning');
- *
- * // These will be suppressed
- * logger.info('This info won\'t be shown');
- * logger.debug('This debug message won\'t be shown');
- * ```
- *
- * @public
- */
-export const createLogger = (options?: LoggerOptions | Logger): Logger => {
-	// If options is already a Logger instance, return it
-	if (
-		options &&
-		typeof options === 'object' &&
-		levels.every((level) => typeof (options as Logger)[level] === 'function')
-	) {
-		return options as Logger;
-	}
-
-	// Otherwise, treat options as LoggerOptions
-	const loggerOptions = options as LoggerOptions;
-	const enabled = loggerOptions?.disabled !== true;
-	const logLevel = loggerOptions?.level ?? 'error';
-	const appName = loggerOptions?.appName ?? 'c15t';
-
-	/**
-	 * Internal function that handles the actual logging logic.
-	 *
-	 * @param level - The severity level of the log
-	 * @param message - The message to log
-	 * @param args - Additional data to include in the log
-	 *
-	 * @internal
-	 */
-	const logFunc = async (
-		level: LogLevel,
-		message: string,
-		args: unknown[] = []
-	): Promise<void> => {
-		if (!enabled || !shouldPublishLog(logLevel, level)) {
-			return;
-		}
-
-		await withLogSpan(level, message, args, async () => {
-			const formattedMessage = formatMessage(level, message, appName);
-
-			if (!loggerOptions || typeof loggerOptions.log !== 'function') {
-				if (level === 'error') {
-					// biome-ignore lint/suspicious/noConsole: Logger implementation
-					console.error(formattedMessage, ...args);
-				} else if (level === 'warn') {
-					// biome-ignore lint/suspicious/noConsole: Logger implementation
-					console.warn(formattedMessage, ...args);
-				} else if (level === 'info') {
-					// biome-ignore lint/suspicious/noConsole: Logger implementation
-					// biome-ignore lint/suspicious/noConsoleLog: Logger implementation
-					console.log(formattedMessage, ...args);
-				} else if (level === 'debug') {
-					// biome-ignore lint/suspicious/noConsole: Logger implementation
-					console.debug(formattedMessage, ...args);
-				} else if (level === 'success') {
-					// biome-ignore lint/suspicious/noConsole: Logger implementation
-					// biome-ignore lint/suspicious/noConsoleLog: Logger implementation
-					console.log(formattedMessage, ...args);
-				}
-				return;
-			}
-
-			loggerOptions.log(level === 'success' ? 'info' : level, message, ...args);
-		});
-	};
-
-	return Object.fromEntries(
-		levels.map((level) => [
-			level,
-			(...[message, ...args]: LogEntry) => {
-				// Return the promise but don't await it
-				return logFunc(level, message, args).catch((error) => {
-					// biome-ignore lint/suspicious/noConsole: <explanation>
-					console.error('Logger error:', error);
-				});
-			},
-		])
-	) as unknown as Logger;
-};
-
-/**
- * Default logger instance with standard configuration.
- *
- * @remarks
- * Ready-to-use logger with default settings (logs errors only).
- *
- * @example
- * ```ts
- * import { logger } from '@doubletie/logger';
- *
- * logger.error('Something went wrong');
- * logger.info('This won\'t be shown with default settings');
- * ```
- *
- * @public
- */
-export const logger = createLogger();

package/src/pkgs/logger/result-logging.ts

@@ -1,134 +0,0 @@
-import { SpanStatusCode } from '@opentelemetry/api';
-import type { Result, ResultAsync } from 'neverthrow';
-import { getTracer } from './telemetry';
-import type { LoggableError } from './types';
-
-/**
- * Logs any errors in a Result without changing the Result.
- *
- * @remarks
- * This utility function allows logging errors from a Result type without
- * affecting the Result's flow. It uses the mapErr function to extract
- * and log the error if present, then returns the original Result.
- *
- * @typeParam ValueType - The type of the successful value in the Result
- * @typeParam ErrorType - The type of the error in the Result, must extend LoggableError
- *
- * @param result - The Result that may contain an error
- * @param logger - Logger instance with an error method
- * @param message - Optional message prefix for the error
- * @returns The original Result unchanged
- *
- * @example
- * ```ts
- * import { logResult } from '@doubletie/logger';
- * import { createLogger } from '@doubletie/logger';
- * import { ok, err } from 'neverthrow';
- *
- * const logger = createLogger();
- * const result = err({ message: 'Failed operation', code: 'OP_FAILED' });
- *
- * // Log the error but continue processing the Result
- * const processedResult = logResult(result, logger);
- * ```
- *
- * @public
- */
-export const logResult = <ValueType, ErrorType extends LoggableError>(
-	result: Result<ValueType, ErrorType>,
-	logger: { error: (message: string, ...args: unknown[]) => void },
-	message = 'Error occurred:'
-): Result<ValueType, ErrorType> => {
-	const tracer = getTracer();
-	const span = tracer.startSpan('log_result');
-
-	return result.mapErr((error) => {
-		span.setAttributes({
-			'error.message': error.message,
-			'error.code': error.code,
-			'error.status': error.status,
-			'error.category': error.category,
-			'error.has_meta': !!error.meta,
-		});
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: error.message,
-		});
-
-		logger.error(`${message} ${error.message}`, {
-			code: error.code,
-			status: error.status,
-			meta: error.meta,
-			category: error.category,
-			stack: error.stack,
-		});
-
-		span.end();
-		return error;
-	});
-};
-
-/**
- * Logs any errors in a ResultAsync without changing the ResultAsync.
- *
- * @remarks
- * This utility function allows logging errors from a ResultAsync type without
- * affecting the ResultAsync's flow. It uses the mapErr function to extract
- * and log the error if present, then returns the original ResultAsync.
- *
- * @typeParam ValueType - The type of the successful value in the ResultAsync
- * @typeParam ErrorType - The type of the error in the ResultAsync, must extend LoggableError
- *
- * @param resultAsync - The ResultAsync that may contain an error
- * @param logger - Logger instance with an error method
- * @param message - Optional message prefix for the error
- * @returns The original ResultAsync unchanged
- *
- * @example
- * ```ts
- * import { logResultAsync } from '@doubletie/logger';
- * import { createLogger } from '@doubletie/logger';
- * import { okAsync, errAsync } from 'neverthrow';
- *
- * const logger = createLogger();
- * const resultAsync = errAsync({ message: 'Failed async operation', code: 'ASYNC_FAILED' });
- *
- * // Log the error but continue processing the ResultAsync
- * const processedResultAsync = logResultAsync(resultAsync, logger);
- * ```
- *
- * @public
- */
-export const logResultAsync = <ValueType, ErrorType extends LoggableError>(
-	resultAsync: ResultAsync<ValueType, ErrorType>,
-	logger: { error: (message: string, ...args: unknown[]) => void },
-	message = 'Error occurred:'
-): ResultAsync<ValueType, ErrorType> => {
-	const tracer = getTracer();
-	const span = tracer.startSpan('log_result_async');
-
-	return resultAsync.mapErr((error) => {
-		span.setAttributes({
-			'error.message': error.message,
-			'error.code': error.code,
-			'error.status': error.status,
-			'error.category': error.category,
-			'error.has_meta': !!error.meta,
-		});
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: error.message,
-		});
-
-		logger.error(`${message} ${error.message}`, {
-			code: error.code,
-			status: error.status,
-			meta: error.meta,
-			category: error.category,
-			stack: error.stack,
-		});
-
-		span.end();
-		return error;
-	});
-};

package/src/pkgs/logger/telemetry.ts

@@ -1,96 +0,0 @@
-import { SpanStatusCode, trace } from '@opentelemetry/api';
-import type { LogLevel, LoggerOptions } from './types';
-
-const LOGGER_TRACER_NAME = '@doubletie/logger';
-
-/**
- * Maps log levels to OpenTelemetry span status codes
- */
-const LOG_LEVEL_TO_SPAN_STATUS: Record<LogLevel, SpanStatusCode> = {
-	error: SpanStatusCode.ERROR,
-	warn: SpanStatusCode.OK,
-	info: SpanStatusCode.OK,
-	success: SpanStatusCode.OK,
-	debug: SpanStatusCode.OK,
-};
-
-/**
- * Gets or creates a tracer for the logger package
- */
-export const getTracer = (options?: LoggerOptions) => {
-	if (options?.telemetry?.tracer) {
-		return options.telemetry.tracer;
-	}
-	return trace.getTracer(LOGGER_TRACER_NAME);
-};
-
-/**
- * Creates a span for a log entry and sets appropriate attributes
- */
-export const createLogSpan = (
-	level: LogLevel,
-	message: string,
-	args: unknown[] = [],
-	options?: LoggerOptions
-) => {
-	if (options?.telemetry?.disabled) {
-		return null;
-	}
-
-	const tracer = getTracer(options);
-	const span = tracer.startSpan('log_entry', {
-		attributes: {
-			'log.level': level,
-			'log.message': message,
-			'log.has_args': args.length > 0,
-			...(options?.telemetry?.defaultAttributes || {}),
-		},
-	});
-
-	// Add any structured data as span attributes
-	if (args.length > 0 && typeof args[0] === 'object' && args[0] !== null) {
-		const data = args[0] as Record<string, unknown>;
-		for (const [key, value] of Object.entries(data)) {
-			if (value !== undefined && value !== null) {
-				span.setAttribute(`log.data.${key}`, String(value));
-			}
-		}
-	}
-
-	// Set span status based on log level
-	span.setStatus({
-		code: LOG_LEVEL_TO_SPAN_STATUS[level],
-		message: level === 'error' || level === 'warn' ? message : undefined,
-	});
-
-	return span;
-};
-
-/**
- * Wraps a logging operation in a span
- */
-export const withLogSpan = async <T>(
-	level: LogLevel,
-	message: string,
-	args: unknown[],
-	operation: () => T | Promise<T>,
-	options?: LoggerOptions
-): Promise<T> => {
-	const span = createLogSpan(level, message, args, options);
-	if (!span) {
-		return operation();
-	}
-
-	try {
-		const result = await operation();
-		return result;
-	} catch (error) {
-		span.setStatus({
-			code: SpanStatusCode.ERROR,
-			message: error instanceof Error ? error.message : String(error),
-		});
-		throw error;
-	} finally {
-		span.end();
-	}
-};

package/src/pkgs/logger/types.ts

@@ -1,138 +0,0 @@
-import type { Tracer } from '@opentelemetry/api';
-
-/**
- * Represents the available log severity levels.
- *
- * @remarks
- * These levels determine the priority and visibility of log messages.
- * The order from highest to lowest severity is:
- * error > warn > info > success > debug
- *
- * @public
- */
-export type LogLevel = 'info' | 'success' | 'warn' | 'error' | 'debug';
-
-/**
- * Configuration interface for logger instances.
- *
- * @remarks
- * Provides options to customize logger behavior including
- * disabling logs, setting log levels, and custom log handlers.
- *
- * @public
- */
-export interface LoggerOptions {
-	/**
-	 * Whether logging is disabled.
-	 *
-	 * @remarks
-	 * When true, no logs will be published regardless of log level.
-	 */
-	disabled?: boolean;
-
-	/**
-	 * The minimum log level to publish.
-	 *
-	 * @remarks
-	 * Only logs with this level or higher severity will be published.
-	 * Note that 'success' is treated as 'info' when using custom log handlers.
-	 */
-	level?: Exclude<LogLevel, 'success'>;
-
-	/**
-	 * Custom log handler function.
-	 *
-	 * @remarks
-	 * When provided, this function will be called instead of console methods.
-	 *
-	 * @param level - The severity level of the log message
-	 * @param message - The message to log
-	 * @param args - Additional data to include in the log
-	 */
-	log?: (level: LogLevel, message: string, ...args: unknown[]) => void;
-
-	/**
-	 * Custom application name to display in log messages.
-	 *
-	 * @remarks
-	 * When provided, this will override the default app name in the log format.
-	 *
-	 * @default '🪢 doubletie'
-	 */
-	appName?: string;
-
-	/**
-	 * OpenTelemetry configuration options
-	 */
-	telemetry?: {
-		/**
-		 * Custom tracer to use for OpenTelemetry integration
-		 */
-		tracer?: Tracer;
-
-		/**
-		 * Whether to disable OpenTelemetry tracing
-		 */
-		disabled?: boolean;
-
-		/**
-		 * Additional attributes to add to all spans
-		 */
-		defaultAttributes?: Record<string, string | number | boolean>;
-	};
-}
-
-/**
- * Type representing the parameters for log handlers.
- *
- * @remarks
- * This utility type extracts parameter types from the Logger.log function,
- * excluding the first parameter (log level).
- *
- * @internal
- */
-export type LogEntry = Parameters<NonNullable<LoggerOptions['log']>> extends [
-	LogLevel,
-	...infer Rest,
-]
-	? Rest
-	: never;
-
-/**
- * Type representing a logger instance with methods for each log level.
- *
- * @remarks
- * Each method corresponds to a log level and accepts a message and optional arguments.
- *
- * @public
- */
-export type Logger = Record<LogLevel, (...params: LogEntry) => void>;
-
-/**
- * Base error interface that must be implemented by errors used with the logger.
- *
- * @remarks
- * This interface defines the minimum properties an error object should have
- * to work properly with the logging utilities.
- *
- * @public
- */
-export interface LoggableError {
-	/** The error message */
-	message: string;
-
-	/** Optional error code */
-	code?: string | number;
-
-	/** Optional HTTP status code */
-	status?: number;
-
-	/** Optional additional error metadata */
-	meta?: Record<string, unknown>;
-
-	/** Optional error category */
-	category?: string;
-
-	/** Error stack trace */
-	stack?: string;
-}

package/src/pkgs/results/__tests__/retrieval-pipeline.test.ts

@@ -1,157 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { DoubleTieError } from '../core/error-class';
-import { ERROR_CODES } from '../core/error-codes';
-import { retrievalPipeline } from '../pipeline/retrieval-pipeline';
-
-describe('retrievalPipeline', () => {
-	// Setup test data
-	const mockUser = { id: '123', name: 'John Doe', email: 'john@example.com' };
-
-	// Mock fetcher and transformer functions
-	let fetcher: ReturnType<typeof vi.fn>;
-	let transformer: ReturnType<typeof vi.fn>;
-
-	beforeEach(() => {
-		fetcher = vi.fn();
-		transformer = vi.fn().mockImplementation((data) => ({
-			...data,
-			displayName: `${data.name} <${data.email}>`,
-		}));
-	});
-
-	it('should return a function that returns a ResultAsync', () => {
-		fetcher.mockResolvedValue(mockUser);
-
-		const retrieveUser = retrievalPipeline(fetcher, transformer);
-
-		expect(typeof retrieveUser).toBe('function');
-
-		const result = retrieveUser();
-		expect(result).toHaveProperty('then');
-		expect(result).toHaveProperty('map');
-		expect(result).toHaveProperty('mapErr');
-	});
-
-	it('should transform data successfully when fetcher resolves', async () => {
-		fetcher.mockResolvedValue(mockUser);
-
-		const retrieveUser = retrievalPipeline(fetcher, transformer);
-		const result = await retrieveUser();
-
-		expect(result.isOk()).toBe(true);
-		expect(result._unsafeUnwrap()).toEqual({
-			id: '123',
-			name: 'John Doe',
-			email: 'john@example.com',
-			displayName: 'John Doe <john@example.com>',
-		});
-
-		// Verify fetcher and transformer were called correctly
-		expect(fetcher).toHaveBeenCalledTimes(1);
-		expect(transformer).toHaveBeenCalledWith(mockUser);
-	});
-
-	it('should return a not found error when fetcher resolves with null', async () => {
-		fetcher.mockResolvedValue(null);
-
-		const retrieveUser = retrievalPipeline(fetcher, transformer);
-		const result = await retrieveUser();
-
-		expect(result.isErr()).toBe(true);
-		const error = result._unsafeUnwrapErr();
-
-		expect(error).toBeInstanceOf(DoubleTieError);
-		expect(error.code).toBe(ERROR_CODES.NOT_FOUND);
-		expect(error.statusCode).toBe(404);
-		expect(error.message).toBe('Resource not found');
-
-		// Verify fetcher was called but transformer wasn't
-		expect(fetcher).toHaveBeenCalledTimes(1);
-		expect(transformer).not.toHaveBeenCalled();
-	});
-
-	it('should return a not found error when fetcher resolves with undefined', async () => {
-		fetcher.mockResolvedValue(undefined);
-
-		const retrieveUser = retrievalPipeline(fetcher, transformer);
-		const result = await retrieveUser();
-
-		expect(result.isErr()).toBe(true);
-		const error = result._unsafeUnwrapErr();
-
-		expect(error).toBeInstanceOf(DoubleTieError);
-		expect(error.code).toBe(ERROR_CODES.NOT_FOUND);
-		expect(error.statusCode).toBe(404);
-	});
-
-	it('should return a not found error when fetcher rejects with not found message', async () => {
-		const notFoundError = new Error('Resource not found');
-		fetcher.mockRejectedValue(notFoundError);
-
-		const retrieveUser = retrievalPipeline(fetcher, transformer);
-		const result = await retrieveUser();
-
-		expect(result.isErr()).toBe(true);
-		const error = result._unsafeUnwrapErr();
-
-		expect(error).toBeInstanceOf(DoubleTieError);
-		expect(error.code).toBe(ERROR_CODES.NOT_FOUND);
-		expect(error.statusCode).toBe(404);
-		expect(error.cause).toBe(notFoundError);
-	});
-
-	it('should return a bad request error when fetcher rejects with other error', async () => {
-		const connectionError = new Error('Database connection failed');
-		fetcher.mockRejectedValue(connectionError);
-
-		const retrieveUser = retrievalPipeline(fetcher, transformer);
-		const result = await retrieveUser();
-
-		expect(result.isErr()).toBe(true);
-		const error = result._unsafeUnwrapErr();
-
-		expect(error).toBeInstanceOf(DoubleTieError);
-		expect(error.code).toBe(ERROR_CODES.BAD_REQUEST);
-		expect(error.statusCode).toBe(400);
-		expect(error.cause).toBe(connectionError);
-	});
-
-	it('should use a custom error code when provided', async () => {
-		const notFoundError = new Error('Record not found');
-		fetcher.mockRejectedValue(notFoundError);
-
-		const customErrorCode = 'CUSTOM_NOT_FOUND_ERROR';
-		const retrieveUser = retrievalPipeline(
-			fetcher,
-			transformer,
-			customErrorCode
-		);
-		const result = await retrieveUser();
-
-		expect(result.isErr()).toBe(true);
-		const error = result._unsafeUnwrapErr();
-
-		expect(error).toBeInstanceOf(DoubleTieError);
-		expect(error.code).toBe(customErrorCode);
-	});
-
-	it('should return a bad request error when transformer throws', async () => {
-		fetcher.mockResolvedValue(mockUser);
-
-		const transformerError = new Error('Transformation failed');
-		transformer.mockImplementation(() => {
-			throw transformerError;
-		});
-
-		const retrieveUser = retrievalPipeline(fetcher, transformer);
-		const result = await retrieveUser();
-
-		expect(result.isErr()).toBe(true);
-		const error = result._unsafeUnwrapErr();
-
-		expect(error).toBeInstanceOf(DoubleTieError);
-		expect(error.code).toBe(ERROR_CODES.BAD_REQUEST);
-		expect(error.statusCode).toBe(400);
-		expect(error.cause).toBe(transformerError);
-	});
-});