@c15t/backend 1.0.5 → 1.2.0-canary.0

package/src/pkgs/logger/README.md

@@ -1,213 +0,0 @@
-# DoubleTie Logger
-
-A lightweight, customizable logging utility for Node.js and TypeScript applications. It provides structured logging capabilities, Result pattern integration, and flexible configuration options.
-
-## Features
-
-- Configurable log levels (`info`, `success`, `warn`, `error`, `debug`)
-- Color-coded console output for better readability
-- Custom log handlers for integration with other logging systems
-- Integration with Result pattern for error handling
-- TypeScript support with comprehensive type definitions
-- Customizable application name in log messages
-
-## Installation
-
-```bash
-npm install @doubletie/logger
-```
-
-## Core Concepts
-
-The logger provides a simple interface for outputting logs at different severity levels. The main interface is:
-
-```typescript
-interface Logger {
-  info(message: string, data?: object): void;
-  success(message: string, data?: object): void;
-  warn(message: string, data?: object): void;
-  error(message: string, data?: object): void;
-  debug(message: string, data?: object): void;
-}
-```
-
-### Log Levels
-
-Log levels are ordered by severity:
-- `error` - Critical issues that require immediate attention
-- `warn` - Potential problems that should be investigated
-- `info` - General informational messages about system operation
-- `success` - Successful operations (treated as info level in custom handlers)
-- `debug` - Detailed information for debugging purposes
-
-## Usage
-
-### Creating a Logger
-
-```typescript
-import { createLogger } from '@doubletie/logger';
-
-// Create a logger with default settings (only logs errors)
-const logger = createLogger();
-
-// Create a logger that logs all message types
-const verboseLogger = createLogger({ level: 'debug' });
-
-// Create a logger with a custom application name
-const appLogger = createLogger({ appName: 'my-service' });
-```
-
-### Logging at Different Levels
-
-```typescript
-// Critical issues
-logger.error('Failed to connect to database', { retryCount: 3, timeout: 5000 });
-
-// Warnings about potential issues
-logger.warn('Configuration missing, using defaults', { config: 'cache.json' });
-
-// General information
-logger.info('Application started', { environment: 'production', version: '1.2.3' });
-
-// Success messages
-logger.success('User registered successfully', { userId: 'user123' });
-
-// Debug information
-logger.debug('Processing request', { requestId: 'req-123', payload: { name: 'Test' } });
-```
-
-### Integration with Result Types
-
-When working with Result types from libraries like [neverthrow](https://github.com/supermacro/neverthrow), you can use these utilities to log errors without disrupting the flow:
-
-```typescript
-import { logResult, logResultAsync } from '@doubletie/logger';
-import { createLogger } from '@doubletie/logger';
-import { ok, err, okAsync, errAsync } from 'neverthrow';
-
-const logger = createLogger();
-
-// Log errors from a Result without disrupting the Result flow
-function processData(input: string) {
-  const result = validate(input); // Returns Result<ValidData, Error>
-  
-  // Log any errors but continue with the Result
-  return logResult(result, logger, 'Validation error:');
-}
-
-// Log errors from a ResultAsync
-async function fetchData(url: string) {
-  const resultAsync = fetchAsync(url); // Returns ResultAsync<Response, Error>
-  
-  // Log any errors but continue with the ResultAsync
-  return logResultAsync(resultAsync, logger, 'Fetch error:');
-}
-```
-
-### Custom Log Handler
-
-```typescript
-import { createLogger } from '@doubletie/logger';
-
-// Create a logger with a custom log handler
-const logger = createLogger({
-  level: 'info',
-  log: (level, message, data) => {
-    // Send logs to a custom logging service
-    myLoggingService.send({
-      level,
-      message,
-      timestamp: new Date().toISOString(),
-      data: data || {},
-    });
-  },
-});
-
-logger.info('User logged in', { userId: 'user123' });
-```
-
-## API Reference
-
-### Core Functions
-
-#### `createLogger(options?: LoggerOptions | Logger): Logger`
-
-Creates a configured logger instance with methods for each log level.
-
-#### `isLogLevelEnabled(currentLogLevel: LogLevel, logLevel: LogLevel): boolean`
-
-Determines if a log message should be published based on configured log level.
-
-### Result Logging Functions
-
-#### `logResult<T, E extends LoggableError>(result: Result<T, E>, logger, message?): Result<T, E>`
-
-Logs any errors in a Result without changing the Result.
-
-#### `logResultAsync<T, E extends LoggableError>(resultAsync: ResultAsync<T, E>, logger, message?): ResultAsync<T, E>`
-
-Logs any errors in a ResultAsync without changing the ResultAsync.
-
-### Types
-
-#### `LogLevel`
-
-```typescript
-type LogLevel = 'info' | 'success' | 'warn' | 'error' | 'debug';
-```
-
-#### `Logger`
-
-```typescript
-type Logger = {
-  info(message: string, data?: object): void;
-  success(message: string, data?: object): void;
-  warn(message: string, data?: object): void;
-  error(message: string, data?: object): void;
-  debug(message: string, data?: object): void;
-};
-```
-
-#### `LoggerOptions`
-
-```typescript
-interface LoggerOptions {
-  disabled?: boolean;
-  level?: Exclude<LogLevel, 'success'>;
-  log?: (level: LogLevel, message: string, data?: object) => void;
-  appName?: string;
-}
-```
-
-#### `LoggableError`
-
-```typescript
-interface LoggableError {
-  message: string;
-  code?: string | number;
-  status?: number;
-  meta?: Record<string, unknown>;
-  category?: string;
-  stack?: string;
-}
-```
-
-## Best Practices
-
-1. **Use Structured Logging**
-   - Always include relevant data objects with your log messages
-   - This makes logs easier to search and analyze
-
-2. **Choose Appropriate Log Levels**
-   - Use `error` only for actual errors that require attention
-   - Use `warn` for potentially problematic situations
-   - Use `info` for normal operation events
-   - Use `debug` only for detailed troubleshooting information
-
-3. **Include Context**
-   - Add request IDs, user IDs, or transaction IDs to logs
-   - This helps correlate related log entries
-
-## License
-
-MIT 

package/src/pkgs/logger/__tests__/console-formatter.test.ts

@@ -1,67 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { colors, formatMessage, levelColors } from '../console-formatter';
-
-describe('console-formatter', () => {
-	describe('colors', () => {
-		it('should define ANSI color codes for text formatting', () => {
-			expect(colors.reset).toBe('\x1b[0m');
-			expect(colors.bright).toBe('\x1b[1m');
-			expect(colors.dim).toBe('\x1b[2m');
-
-			// Foreground colors
-			expect(colors.fg.red).toBe('\x1b[31m');
-			expect(colors.fg.green).toBe('\x1b[32m');
-			expect(colors.fg.yellow).toBe('\x1b[33m');
-			expect(colors.fg.blue).toBe('\x1b[34m');
-			expect(colors.fg.magenta).toBe('\x1b[35m');
-		});
-	});
-
-	describe('levelColors', () => {
-		it('should assign appropriate colors to each log level', () => {
-			expect(levelColors.info).toBe(colors.fg.blue);
-			expect(levelColors.success).toBe(colors.fg.green);
-			expect(levelColors.warn).toBe(colors.fg.yellow);
-			expect(levelColors.error).toBe(colors.fg.red);
-			expect(levelColors.debug).toBe(colors.fg.magenta);
-		});
-	});
-
-	describe('formatMessage', () => {
-		it('should format a message with timestamp, level, and app name', () => {
-			const formattedMessage = formatMessage('error', 'Test message');
-
-			// Verify the message contains the main components
-			expect(formattedMessage).toContain('ERROR');
-			expect(formattedMessage).toContain('[c15t]');
-			expect(formattedMessage).toContain('Test message');
-
-			// Verify formatting includes timestamp (ISO format)
-			// biome-ignore lint/performance/useTopLevelRegex: its okay its a test
-			expect(formattedMessage).toMatch(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
-		});
-
-		it('should use custom app name when provided', () => {
-			const formattedMessage = formatMessage(
-				'info',
-				'Custom app',
-				'custom-app'
-			);
-
-			expect(formattedMessage).toContain('[custom-app]');
-			expect(formattedMessage).toContain('INFO');
-			expect(formattedMessage).toContain('Custom app');
-		});
-
-		it('should use appropriate color for each log level', () => {
-			const errorMessage = formatMessage('error', 'Error message');
-			const warnMessage = formatMessage('warn', 'Warning message');
-			const infoMessage = formatMessage('info', 'Info message');
-
-			// Check that each message contains the color code for its level
-			expect(errorMessage).toContain(colors.fg.red);
-			expect(warnMessage).toContain(colors.fg.yellow);
-			expect(infoMessage).toContain(colors.fg.blue);
-		});
-	});
-});

package/src/pkgs/logger/__tests__/integration.test.ts

@@ -1,184 +0,0 @@
-import { err, errAsync } from 'neverthrow';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { createLogger } from '../logger-factory';
-import { logResult, logResultAsync } from '../result-logging';
-import type { LoggableError } from '../types';
-
-describe('logger integration', () => {
-	beforeEach(() => {
-		// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-		vi.spyOn(console, 'log').mockImplementation(() => {});
-		// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-		vi.spyOn(console, 'warn').mockImplementation(() => {});
-		// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-		vi.spyOn(console, 'error').mockImplementation(() => {});
-		// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-		vi.spyOn(console, 'debug').mockImplementation(() => {});
-	});
-
-	afterEach(() => {
-		vi.restoreAllMocks();
-	});
-
-	describe('full logger pipeline', () => {
-		it('should work with default logger and result logging together', () => {
-			// Create a default logger
-			const logger = createLogger();
-
-			// Create an error result
-			const testError: LoggableError = {
-				message: 'Integration test error',
-				code: 'INTEGRATION_TEST',
-			};
-			const errorResult = err(testError);
-
-			// Log the error using the result logging utility
-			logResult(errorResult, logger);
-
-			// Verify that console.error was called with a formatted message
-			expect(console.error).toHaveBeenCalledTimes(1);
-			const mockedConsoleError = vi.mocked(console.error);
-			expect(mockedConsoleError.mock.calls[0]?.[0]).toContain('ERROR');
-			expect(mockedConsoleError.mock.calls[0]?.[0]).toContain(
-				'Integration test error'
-			);
-			expect(mockedConsoleError.mock.calls[0]?.[1]).toEqual({
-				code: 'INTEGRATION_TEST',
-				status: undefined,
-				meta: undefined,
-				category: undefined,
-				stack: undefined,
-			});
-		});
-
-		it('should work with custom log level and error logging together', () => {
-			// Create a logger with custom configuration
-			const logger = createLogger({
-				level: 'info', // Change from 'debug' to 'info' to allow info, warn, and error logs
-			});
-
-			// Test standard logging
-			logger.info('Info message');
-			logger.debug('Debug message');
-			logger.warn('Warning message');
-
-			expect(console.log).toHaveBeenCalledTimes(1);
-			expect(console.debug).toHaveBeenCalledTimes(0); // Debug won't be logged with info level
-			expect(console.warn).toHaveBeenCalledTimes(1);
-
-			// Create an error for result logging
-			const testError: LoggableError = {
-				message: 'Integration error',
-			};
-
-			// Log using the result logging utility
-			logResult(err(testError), logger);
-
-			expect(console.error).toHaveBeenCalledTimes(1);
-		});
-
-		it('should work with custom log handler and result logging', () => {
-			// Create a mock log handler
-			const customLogHandler = vi.fn();
-
-			// Create a logger with the custom handler
-			const logger = createLogger({
-				level: 'info', // Change from 'debug' to 'info' to allow info, warn, and error logs
-				log: customLogHandler,
-				appName: 'c15t',
-			});
-
-			// Use direct logging
-			logger.info('Direct info');
-			logger.error('Direct error');
-
-			expect(customLogHandler).toHaveBeenCalledTimes(2);
-
-			// Use result logging
-			const testError: LoggableError = {
-				message: 'Result error',
-			};
-
-			logResult(err(testError), logger);
-
-			// Check that the custom handler was called again
-			expect(customLogHandler).toHaveBeenCalledTimes(3);
-			const mockedCustomLogHandler = vi.mocked(customLogHandler);
-			expect(mockedCustomLogHandler.mock.calls[2]?.[0]).toBe('error');
-			expect(mockedCustomLogHandler.mock.calls[2]?.[1]).toBe(
-				'Error occurred: Result error'
-			);
-		});
-
-		it('should support async result logging with the logger', async () => {
-			const logger = createLogger();
-
-			const testError: LoggableError = {
-				message: 'Async integration error',
-			};
-
-			const errorResultAsync = errAsync(testError);
-
-			await logResultAsync(errorResultAsync, logger).match(
-				// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-				() => {},
-				// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-				() => {}
-			);
-
-			expect(console.error).toHaveBeenCalledTimes(1);
-			const mockedConsoleError = vi.mocked(console.error);
-			expect(mockedConsoleError.mock.calls[0]?.[0]).toContain(
-				'Async integration error'
-			);
-		});
-
-		it('should use custom application name in logs', () => {
-			// Create a logger with a custom application name
-			const customAppName = 'c15t-api';
-			const logger = createLogger({
-				level: 'info',
-				appName: customAppName,
-			});
-
-			// Log messages at different levels
-			logger.info('Application started');
-			logger.warn('Configuration incomplete');
-			logger.error('Failed to connect to database');
-
-			// Verify logs contain the custom app name
-			const mockedConsoleLog = vi.mocked(console.log);
-			const mockedConsoleWarn = vi.mocked(console.warn);
-			const mockedConsoleError = vi.mocked(console.error);
-
-			expect(mockedConsoleLog.mock.calls[0]?.[0]).toContain(
-				`[${customAppName}]`
-			);
-			expect(mockedConsoleWarn.mock.calls[0]?.[0]).toContain(
-				`[${customAppName}]`
-			);
-			expect(mockedConsoleError.mock.calls[0]?.[0]).toContain(
-				`[${customAppName}]`
-			);
-
-			// Verify logs don't contain the default app name
-			expect(mockedConsoleLog.mock.calls[0]?.[0]).not.toContain(
-				'[🪢 doubletie]'
-			);
-
-			// Check that the custom app name works with result logging too
-			const testError: LoggableError = {
-				message: 'Integration error with custom app name',
-			};
-
-			logResult(err(testError), logger);
-
-			expect(mockedConsoleError.mock.calls[1]?.[0]).toContain(
-				`[${customAppName}]`
-			);
-			expect(mockedConsoleError.mock.calls[1]?.[0]).toContain(
-				'Integration error with custom app name'
-			);
-		});
-	});
-});

package/src/pkgs/logger/__tests__/log-levels.test.ts

@@ -1,77 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { levels, shouldPublishLog } from '../log-levels';
-import type { LogLevel } from '../types';
-
-describe('log-levels', () => {
-	describe('levels', () => {
-		it('should contain all expected log levels', () => {
-			expect(levels).toContain('error');
-			expect(levels).toContain('warn');
-			expect(levels).toContain('info');
-			expect(levels).toContain('success');
-			expect(levels).toContain('debug');
-		});
-
-		it('should be defined in correct order for log level comparison', () => {
-			// Lower index = more important (error should be first)
-			expect(levels.indexOf('error')).toBeLessThan(levels.indexOf('warn'));
-			expect(levels.indexOf('warn')).toBeLessThan(levels.indexOf('info'));
-			expect(levels.indexOf('info')).toBeLessThan(levels.indexOf('success'));
-			expect(levels.indexOf('success')).toBeLessThan(levels.indexOf('debug'));
-		});
-	});
-
-	describe('shouldPublishLog', () => {
-		// Define the expected behavior for our tests
-		it('should allow messages with level equal to or more important than the current level', () => {
-			// Test 'info' level
-			expect(shouldPublishLog('info', 'info')).toBe(true);
-
-			// Test 'warn' level
-			expect(shouldPublishLog('warn', 'warn')).toBe(true);
-			expect(shouldPublishLog('warn', 'error')).toBe(true);
-			expect(shouldPublishLog('warn', 'info')).toBe(false);
-
-			// Test 'error' level
-			expect(shouldPublishLog('error', 'error')).toBe(true);
-			expect(shouldPublishLog('error', 'warn')).toBe(false);
-			expect(shouldPublishLog('error', 'info')).toBe(false);
-
-			// Test 'debug' level (special case)
-			expect(shouldPublishLog('debug', 'debug')).toBe(true);
-			expect(shouldPublishLog('debug', 'error')).toBe(false);
-			expect(shouldPublishLog('debug', 'warn')).toBe(false);
-			expect(shouldPublishLog('debug', 'info')).toBe(false);
-			expect(shouldPublishLog('debug', 'success')).toBe(false);
-		});
-
-		it('should use array comparison for determining log level priority', () => {
-			const testFn = (
-				currentLevel: LogLevel,
-				messageLevel: LogLevel
-			): boolean => {
-				// Simulate the logic from shouldPublishLog
-				const currentLevelIndex = levels.indexOf(currentLevel);
-				const messageLevelIndex = levels.indexOf(messageLevel);
-
-				if (currentLevel === 'debug') {
-					return messageLevel === 'debug';
-				}
-
-				return messageLevelIndex <= currentLevelIndex;
-			};
-
-			// Test various combinations
-			expect(testFn('info', 'error')).toBe(true);
-			expect(testFn('warn', 'error')).toBe(true);
-			expect(testFn('error', 'error')).toBe(true);
-			expect(testFn('error', 'warn')).toBe(false);
-
-			// Compare with the actual function
-			expect(testFn('info', 'error')).toBe(shouldPublishLog('info', 'error'));
-			expect(testFn('warn', 'error')).toBe(shouldPublishLog('warn', 'error'));
-			expect(testFn('error', 'error')).toBe(shouldPublishLog('error', 'error'));
-			expect(testFn('error', 'warn')).toBe(shouldPublishLog('error', 'warn'));
-		});
-	});
-});

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

@@ -1,156 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { levels } from '../log-levels';
-import * as logLevels from '../log-levels';
-import { createLogger } from '../logger-factory';
-
-describe('logger-factory', () => {
-	// Mock console methods
-	beforeEach(() => {
-		// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-		vi.spyOn(console, 'log').mockImplementation(() => {});
-		// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-		vi.spyOn(console, 'warn').mockImplementation(() => {});
-		// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-		vi.spyOn(console, 'error').mockImplementation(() => {});
-		// biome-ignore lint/suspicious/noEmptyBlockStatements: its okay its a test
-		vi.spyOn(console, 'debug').mockImplementation(() => {});
-	});
-
-	afterEach(() => {
-		vi.restoreAllMocks();
-	});
-
-	describe('createLogger', () => {
-		it('should create a logger with all log level methods', () => {
-			const logger = createLogger();
-			for (const level of levels) {
-				expect(typeof logger[level]).toBe('function');
-			}
-		});
-
-		it('should respect disabled option', () => {
-			const logger = createLogger({ disabled: true });
-			logger.error('This should not be logged');
-			expect(console.error).not.toHaveBeenCalled();
-		});
-
-		it('should respect log level option', () => {
-			// Mock the shouldPublishLog function to return expected values for our test
-			vi.spyOn(logLevels, 'shouldPublishLog').mockImplementation(
-				(currentLevel, messageLevel) => {
-					if (currentLevel === 'warn') {
-						return messageLevel === 'warn' || messageLevel === 'error';
-					}
-					return false;
-				}
-			);
-
-			const logger = createLogger({ level: 'warn' });
-
-			logger.error('This should be logged'); // Should be logged
-			logger.warn('This should be logged'); // Should be logged
-			logger.info('This should not be logged'); // Should not be logged
-			logger.debug('This should not be logged'); // Should not be logged
-
-			// Verify calls
-			expect(console.error).toHaveBeenCalled();
-			expect(console.warn).toHaveBeenCalled();
-			expect(console.log).not.toHaveBeenCalled();
-			expect(console.debug).not.toHaveBeenCalled();
-
-			// Restore the original function
-			vi.mocked(logLevels.shouldPublishLog).mockRestore();
-		});
-
-		it('should use custom log handler when provided', () => {
-			const customLog = vi.fn();
-			const logger = createLogger({
-				log: customLog,
-				level: 'debug',
-			});
-
-			// Mock shouldPublishLog to always return true for this test
-			vi.spyOn(logLevels, 'shouldPublishLog').mockReturnValue(true);
-
-			logger.info('Info message');
-			logger.error('Error message');
-			logger.success('Success message');
-
-			expect(customLog).toHaveBeenCalledTimes(3);
-			expect(customLog).toHaveBeenCalledWith('info', 'Info message');
-			expect(customLog).toHaveBeenCalledWith('error', 'Error message');
-			// 'success' should be treated as 'info' when using custom log handler
-			expect(customLog).toHaveBeenCalledWith('info', 'Success message');
-
-			vi.mocked(logLevels.shouldPublishLog).mockRestore();
-		});
-
-		it('should format messages with timestamp and level', () => {
-			// Mock shouldPublishLog to return true for this test
-			vi.spyOn(logLevels, 'shouldPublishLog').mockReturnValue(true);
-
-			const logger = createLogger();
-			logger.error('Test message');
-
-			// Check that console.error was called with a formatted message
-			expect(console.error).toHaveBeenCalled();
-
-			// Extract the first argument from the first call
-			const mockedConsoleError = vi.mocked(console.error);
-			const firstCallArg = mockedConsoleError.mock.calls[0]?.[0];
-
-			// Check that the message contains the expected parts
-			expect(firstCallArg).toContain('ERROR');
-			expect(firstCallArg).toContain('[c15t]');
-			expect(firstCallArg).toContain('Test message');
-
-			// Check that timestamp matches ISO format
-			// biome-ignore lint/performance/useTopLevelRegex: its okay its a test
-			expect(firstCallArg).toMatch(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/);
-
-			vi.mocked(logLevels.shouldPublishLog).mockRestore();
-		});
-
-		it('should pass additional arguments to console methods', () => {
-			// Mock shouldPublishLog to return true for this test
-			vi.spyOn(logLevels, 'shouldPublishLog').mockReturnValue(true);
-
-			const logger = createLogger();
-			const meta = { userId: 'user123' };
-
-			logger.error('Error with meta', meta);
-
-			expect(console.error).toHaveBeenCalled();
-			const mockedConsoleError = vi.mocked(console.error);
-			expect(mockedConsoleError.mock.calls[0]?.[1]).toBe(meta);
-
-			vi.mocked(logLevels.shouldPublishLog).mockRestore();
-		});
-
-		it('should use custom app name when provided', () => {
-			// Mock shouldPublishLog to return true for this test
-			vi.spyOn(logLevels, 'shouldPublishLog').mockReturnValue(true);
-
-			// Create a logger with a custom app name
-			const customAppName = 'test-app';
-			const logger = createLogger({ appName: customAppName });
-
-			// Log a test message
-			logger.info('Test message with custom app name');
-
-			// Check that console.log was called with a formatted message
-			expect(console.log).toHaveBeenCalled();
-
-			// Extract the first argument from the first call
-			const mockedConsoleLog = vi.mocked(console.log);
-			const logMessage = mockedConsoleLog.mock.calls[0]?.[0];
-
-			// Verify the message contains the custom app name
-			expect(logMessage).toContain(`[${customAppName}]`);
-			// And doesn't contain the default app name
-			expect(logMessage).not.toContain('[🪢 doubletie]');
-
-			vi.mocked(logLevels.shouldPublishLog).mockRestore();
-		});
-	});
-});