@resq-sw/logger 0.1.0

package/README.md

@@ -0,0 +1,185 @@
+# @resq-sw/logger
+
+> Structured logging with log levels, decorators, and singleton management for Node.js and Bun.
+
+## Installation
+
+```bash
+bun add @resq-sw/logger
+```
+
+Zero runtime dependencies.
+
+## Quick Start
+
+```ts
+import { Logger, LogLevel } from "@resq-sw/logger";
+
+const log = Logger.getLogger("[MyService]");
+
+log.info("Server started", { port: 3000 });
+log.warn("Disk usage high", { percent: 92 });
+log.error("Connection failed", new Error("timeout"), { host: "db" });
+log.debug("Cache hit", { key: "user:123" });
+```
+
+Output format: `YYYY-MM-DD HH:mm:ss.SSS LEVEL [context] message {data}`
+
+## API Reference
+
+### Logger Class
+
+#### `Logger.getLogger(context, options?): Logger`
+
+Returns a singleton Logger instance for the given context. Subsequent calls with the same context return the same instance.
+
+#### `new Logger(context, options?)`
+
+Creates a new Logger instance.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `minLevel` | `LogLevel` | env-based | Minimum log level |
+| `includeTimestamp` | `boolean` | -- | Include timestamps |
+| `colorize` | `boolean` | -- | Colorize output |
+| `logToFile` | `boolean` | -- | Write to file (server-side) |
+| `filePath` | `string` | -- | Log file path |
+
+**Level resolution priority**: `options.minLevel` > `LOG_LEVEL` env > `BUN_LOG_LEVEL` env > `LogLevel.ERROR` (production) / `LogLevel.ALL` (development).
+
+#### `Logger.setGlobalLogLevel(level: LogLevel): void`
+
+Sets the minimum log level for all existing logger instances.
+
+### Log Levels
+
+```ts
+enum LogLevel {
+  NONE  = 0,  // No logging
+  ERROR = 1,  // Errors only
+  WARN  = 2,  // Errors + warnings
+  INFO  = 3,  // + informational
+  DEBUG = 4,  // + debug messages
+  TRACE = 5,  // + trace messages
+  ALL   = 6,  // Everything
+}
+```
+
+### Logging Methods
+
+All methods accept an optional `data` parameter (`Record<string, unknown>`).
+
+| Method | Min Level | Console Method | Description |
+|--------|-----------|----------------|-------------|
+| `info(message, data?)` | `INFO` | `console.info` | Informational messages |
+| `error(message, error?, data?)` | `ERROR` | `console.error` | Errors (auto-serializes Error objects) |
+| `warn(message, data?)` | `WARN` | `console.warn` | Warnings |
+| `debug(message, data?)` | `DEBUG` | `console.debug` | Debug messages |
+| `trace(message, data?)` | `TRACE` | `console.debug` | Trace messages (most verbose) |
+| `action(message, data?)` | `INFO` | `console.info` | Server actions / user interactions |
+| `success(message, data?)` | `INFO` | `console.info` | Success confirmations |
+
+### Grouping
+
+```ts
+log.group("Request Processing");
+log.info("Step 1");
+log.info("Step 2");
+log.groupEnd();
+```
+
+### Timing
+
+#### `logger.time<T>(label, fn): Promise<T>`
+
+Measures and logs execution time of a sync or async function.
+
+```ts
+const result = await log.time("DB query", async () => {
+  return await db.query("SELECT * FROM users");
+});
+// Logs: "DB query completed" { duration: "12.34ms" }
+```
+
+On error, logs the failure with duration and rethrows.
+
+## Decorators
+
+### `@Log(options?)`
+
+Logs method entry and exit with optional argument and return value logging.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `logArgs` | `boolean` | `true` | Log method arguments |
+| `logResult` | `boolean` | `false` | Log return value |
+| `message` | `string` | method name | Custom message prefix |
+| `level` | `LogLevelString` | `"debug"` | Log level to use |
+
+```ts
+class UserService {
+  @Log({ logArgs: true, logResult: true, level: "info" })
+  async getUser(id: string) { return { id, name: "John" }; }
+}
+```
+
+### `@LogTiming(options?)`
+
+Logs method execution time. Works with both sync and async methods.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `label` | `string` | `ClassName.methodName` | Custom timing label |
+| `threshold` | `number` | `0` | Only log if duration exceeds this (ms) |
+| `level` | `LogLevelString` | `"info"` | Log level to use |
+
+```ts
+class DataService {
+  @LogTiming({ threshold: 100 })
+  async fetchData() { /* only logged if > 100ms */ }
+}
+```
+
+### `@LogError(options?)`
+
+Wraps method in try/catch, logs errors with stack traces.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `rethrow` | `boolean` | `true` | Rethrow after logging |
+| `message` | `string` | `"<method> error"` | Custom error prefix |
+| `includeStack` | `boolean` | `true` | Include stack trace in log |
+
+```ts
+class Api {
+  @LogError({ rethrow: false, message: "API call failed" })
+  async callApi() { throw new Error("Network error"); }
+  // Error is logged but swallowed; method returns undefined
+}
+```
+
+### `@LogClass(options?)`
+
+Class decorator that applies logging to all methods on the prototype.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `exclude` | `string[]` | `[]` | Method names to skip |
+| `logCalls` | `boolean` | `true` | Log method entry/exit |
+| `timing` | `boolean` | `false` | Log execution times |
+
+```ts
+@LogClass({ exclude: ["internalHelper"], timing: true })
+class MyService {
+  publicMethod() { /* logged with timing */ }
+  internalHelper() { /* not logged */ }
+}
+```
+
+## Types
+
+Exported types: `LogData`, `LoggerOptions`, `LogLevel`, `LogLevelString`, `ColorKey`, `LogEntry`, `LogTransport`, `LogMethodOptions`, `LogTimingOptions`, `LogErrorOptions`, `LogClassOptions`.
+
+## License
+
+Apache-2.0

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+import { ColorKey, LogData, LogLevel, Logger, LoggerOptions, logger } from "./logger.js";
+import { LogClassOptions, LogEntry, LogErrorOptions, LogLevelString, LogMethodOptions, LogTimingOptions, LogTransport } from "./logger.types.js";
+import { Log, LogClass, LogError, LogTiming } from "./logger.decorators.js";
+export { ColorKey, Log, LogClass, type LogClassOptions, LogData, type LogEntry, LogError, type LogErrorOptions, LogLevel, type LogLevelString, type LogMethodOptions, LogTiming, type LogTimingOptions, type LogTransport, Logger, LoggerOptions, logger };

package/lib/index.js

@@ -0,0 +1,3 @@
+import { LogLevel, Logger, logger } from "./logger.js";
+import { Log, LogClass, LogError, LogTiming } from "./logger.decorators.js";
+export { Log, LogClass, LogError, LogLevel, LogTiming, Logger, logger };

package/lib/logger.d.ts

@@ -0,0 +1,210 @@
+//#region src/logger.d.ts
+/**
+ * Copyright (c) 2026 ResQ
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @fileoverview A comprehensive logging utility for both client and server environments.
+ * Provides structured logging with support for different log levels, colorization,
+ * and contextual information.
+ *
+ * This logger uses native console methods with structured formatting — no external
+ * dependencies are required. Log output follows the pattern:
+ *   TIMESTAMP LEVEL [CONTEXT] message { data }
+ */
+/**
+ * Enum representing different logging levels with their priority values.
+ * Higher values indicate more verbose logging.
+ * @enum {number}
+ */
+declare enum LogLevel {
+  /** No logging */
+  NONE = 0,
+  /** Only error messages */
+  ERROR = 1,
+  /** Errors and warnings */
+  WARN = 2,
+  /** Errors, warnings, and informational messages */
+  INFO = 3,
+  /** Errors, warnings, info, and debug messages */
+  DEBUG = 4,
+  /** Errors, warnings, info, debug, and trace messages */
+  TRACE = 5,
+  /** All possible log messages */
+  ALL = 6
+}
+/**
+ * Available color keys for log formatting
+ * @typedef {'reset' | 'red' | 'yellow' | 'blue' | 'green' | 'gray' | 'bold' | 'magenta' | 'cyan' | 'white'} ColorKey
+ */
+type ColorKey = 'reset' | 'red' | 'yellow' | 'blue' | 'green' | 'gray' | 'bold' | 'magenta' | 'cyan' | 'white';
+/**
+ * Interface for structured data that can be attached to log messages
+ * @interface
+ */
+interface LogData {
+  /**
+   * Any key-value pairs to include in the log
+   */
+  [key: string]: unknown;
+}
+/**
+ * Configuration options for the Logger
+ * @interface
+ */
+interface LoggerOptions {
+  /**
+   * The minimum level of messages to log
+   */
+  minLevel?: LogLevel;
+  /**
+   * Whether to include timestamps in log messages
+   */
+  includeTimestamp?: boolean;
+  /**
+   * Whether to colorize log output
+   */
+  colorize?: boolean;
+  /**
+   * Whether to write logs to a file (server-side only)
+   */
+  logToFile?: boolean;
+  /**
+   * Path to the log file if logToFile is enabled
+   */
+  filePath?: string;
+}
+/**
+ * A versatile logging utility that works in both browser and Node.js environments.
+ * Supports multiple log levels, colorized output, and structured data logging.
+ */
+declare class Logger {
+  /** The context/category name for this logger instance */
+  private readonly context;
+  /** The minimum log level that will be output */
+  private minLevel;
+  /**
+   * Parse log level from string or return default
+   */
+  private static parseLevel;
+  /** Registry of logger instances to implement the singleton pattern */
+  private static readonly instances;
+  /**
+   * Create a new Logger instance or return an existing one for the given context
+   * @param {string} context - The context name for this logger (e.g., component or service name)
+   * @param {LoggerOptions} [options={}] - Optional logger configuration
+   */
+  constructor(context: string, options?: LoggerOptions);
+  /**
+   * Get a logger instance for the given context.
+   * If a logger with this context already exists, returns the existing instance.
+   *
+   * @param {string} context - The context name
+   * @param {LoggerOptions} [options] - Optional logger configuration
+   * @returns {Logger} A logger instance for the specified context
+   */
+  static getLogger(context: string, options?: LoggerOptions): Logger;
+  /**
+   * Set global minimum log level for all logger instances
+   *
+   * @param {LogLevel} level - The minimum level to log across all loggers
+   */
+  static setGlobalLogLevel(level: LogLevel): void;
+  /**
+   * Format a timestamp for log output
+   */
+  private formatTimestamp;
+  /**
+   * Format structured log data into a readable suffix string.
+   * Returns empty string if data is null/empty.
+   */
+  private formatData;
+  /**
+   * Emit a log entry using the appropriate console method
+   */
+  private emit;
+  /**
+   * Log an informational message
+   *
+   * @param {string} message - The message to log
+   * @param {LogData} [data] - Optional data to include
+   */
+  info(message: string, data?: LogData): void;
+  /**
+   * Log an error message
+   *
+   * @param {string} message - The error message
+   * @param {Error|unknown} [error] - Optional Error object or unknown error
+   * @param {LogData} [data] - Optional additional data
+   */
+  error(message: string, error?: unknown, data?: LogData): void;
+  /**
+   * Log a warning message
+   *
+   * @param {string} message - The warning message
+   * @param {LogData} [data] - Optional data to include
+   */
+  warn(message: string, data?: LogData): void;
+  /**
+   * Log a debug message
+   *
+   * @param {string} message - The debug message
+   * @param {LogData} [data] - Optional data to include
+   */
+  debug(message: string, data?: LogData): void;
+  /**
+   * Log a trace message (most verbose level)
+   *
+   * @param {string} message - The trace message
+   * @param {LogData} [data] - Optional data to include
+   */
+  trace(message: string, data?: LogData): void;
+  /**
+   * Log an action message (for server actions or important user interactions)
+   *
+   * @param {string} message - The action message
+   * @param {LogData} [data] - Optional data to include
+   */
+  action(message: string, data?: LogData): void;
+  /**
+   * Log a success message
+   *
+   * @param {string} message - The success message
+   * @param {LogData} [data] - Optional data to include
+   */
+  success(message: string, data?: LogData): void;
+  /**
+   * Group related log messages (console.group wrapper)
+   *
+   * @param {string} label - The group label
+   */
+  group(label: string): void;
+  /**
+   * End a log group (console.groupEnd wrapper)
+   */
+  groupEnd(): void;
+  /**
+   * Log execution time of a function
+   *
+   * @template T - The return type of the function being timed
+   * @param {string} label - Description of the operation being timed
+   * @param {() => Promise<T> | T} fn - Function to execute and time
+   * @returns {Promise<T>} The result of the function execution
+   */
+  time<T>(label: string, fn: () => Promise<T> | T): Promise<T>;
+}
+declare const logger: Logger;
+//#endregion
+export { ColorKey, LogData, LogLevel, Logger, LoggerOptions, logger };
+//# sourceMappingURL=logger.d.ts.map

package/lib/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","names":[],"sources":["../src/logger.ts"],"mappings":";;AA+BA;;;;;;;;;;;;;AAqBA;;;;;AAgBA;;;;;AAWA;;;;;AAAA,aAhDY,QAAA;EAyDV;EAvDA,IAAA;EAiEA;EA/DA,KAAA;EAoEQ;EAlER,IAAA;EAyEW;EAvEX,IAAA;EAuEiB;EArEjB,KAAA;EA2HmD;EAzHnD,KAAA;EAyIuC;EAvIvC,GAAA;AAAA;;;;;KAOU,QAAA;;;;;UAgBK,OAAA;EAgRgD;;;EAAA,CA5Q9D,GAAA;AAAA;;;;;UAOc,aAAA;EAqFD;;;EAjFd,QAAA,GAAW,QAAA;EAiFwD;;;EA5EnE,gBAAA;EAqGQ;;;EAhGR,QAAA;EA6IK;;;EAxIL,SAAA;EAoJM;;;EA/IN,QAAA;AAAA;;;;;cAOW,MAAA;EAsKmB;EAAA,iBApKb,OAAA;EA+KjB;EAAA,QA5KQ,QAAA;EA4KsB;;;EAAA,eAvKf,UAAA;EAkLgB;EAAA,wBAlKP,SAAA;EA6KxB;;;;;cAtKY,OAAA,UAAiB,OAAA,GAAS,aAAA;EAwLtC;;;;;;;;EAAA,OAnKc,SAAA,CAAU,OAAA,UAAiB,OAAA,GAAU,aAAA,GAAgB,MAAA;EAgLH;;;AAmBlE;;EAnBkE,OAhKlD,iBAAA,CAAkB,KAAA,EAAO,QAAA;EAmLtB;;;EAAA,QA1KT,eAAA;;;;;UAgBA,UAAA;;;;UAYA,IAAA;;;;;;;EAiBR,IAAA,CAAK,OAAA,UAAiB,IAAA,GAAO,OAAA;;;;;;;;EAY7B,KAAA,CAAM,OAAA,UAAiB,KAAA,YAAiB,IAAA,GAAO,OAAA;;;;;;;EAmB/C,IAAA,CAAK,OAAA,UAAiB,IAAA,GAAO,OAAA;;;;;;;EAW7B,KAAA,CAAM,OAAA,UAAiB,IAAA,GAAO,OAAA;;;;;;;EAW9B,KAAA,CAAM,OAAA,UAAiB,IAAA,GAAO,OAAA;;;;;;;EAW9B,MAAA,CAAO,OAAA,UAAiB,IAAA,GAAO,OAAA;;;;;;;EAW/B,OAAA,CAAQ,OAAA,UAAiB,IAAA,GAAO,OAAA;;;;;;EAUhC,KAAA,CAAM,KAAA;;;;EAQN,QAAA,CAAA;;;;;;;;;EAaM,IAAA,GAAA,CAAQ,KAAA,UAAe,EAAA,QAAU,OAAA,CAAQ,CAAA,IAAK,CAAA,GAAI,OAAA,CAAQ,CAAA;AAAA;AAAA,cAmBrD,MAAA,EAAM,MAAA"}

package/lib/logger.decorators.d.ts

@@ -0,0 +1,77 @@
+import { LogClassOptions, LogErrorOptions, LogMethodOptions, LogTimingOptions } from "./logger.types.js";
+
+//#region src/logger.decorators.d.ts
+/**
+ * Decorator that logs method entry and exit.
+ * Can optionally log arguments and return values.
+ *
+ * @param {LogMethodOptions} [options={}] - Configuration options
+ * @returns {MethodDecorator} The decorator function
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   @Log({ logArgs: true, logResult: true })
+ *   async getUser(id: string) {
+ *     return { id, name: 'John' };
+ *   }
+ * }
+ * ```
+ */
+declare function Log(options?: LogMethodOptions): MethodDecorator;
+/**
+ * Decorator that logs method execution time.
+ * Useful for performance monitoring.
+ *
+ * @param {LogTimingOptions} [options={}] - Configuration options
+ * @returns {MethodDecorator} The decorator function
+ *
+ * @example
+ * ```typescript
+ * class DataService {
+ *   @LogTiming({ threshold: 100 }) // Only log if execution > 100ms
+ *   async fetchData() {
+ *     // ... slow operation
+ *   }
+ * }
+ * ```
+ */
+declare function LogTiming(options?: LogTimingOptions): MethodDecorator;
+/**
+ * Decorator that wraps method in try/catch and logs errors.
+ * Can optionally suppress the error or rethrow it.
+ *
+ * @param {LogErrorOptions} [options={}] - Configuration options
+ * @returns {MethodDecorator} The decorator function
+ *
+ * @example
+ * ```typescript
+ * class ApiService {
+ *   @LogError({ rethrow: false, message: 'API call failed' })
+ *   async callApi() {
+ *     throw new Error('Network error');
+ *   }
+ * }
+ * ```
+ */
+declare function LogError(options?: LogErrorOptions): MethodDecorator;
+/**
+ * Class decorator that applies logging to all methods of a class.
+ * Can be configured to exclude specific methods.
+ *
+ * @param {LogClassOptions} [options={}] - Configuration options
+ * @returns {ClassDecorator} The decorator function
+ *
+ * @example
+ * ```typescript
+ * @LogClass({ exclude: ['privateMethod'], timing: true })
+ * class MyService {
+ *   publicMethod() { ... }
+ *   privateMethod() { ... } // Won't be logged
+ * }
+ * ```
+ */
+declare function LogClass(options?: LogClassOptions): <T extends new (...args: unknown[]) => object>(target: T) => T;
+//#endregion
+export { Log, LogClass, LogError, LogTiming };
+//# sourceMappingURL=logger.decorators.d.ts.map

package/lib/logger.decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.decorators.d.ts","names":[],"sources":["../src/logger.decorators.ts"],"mappings":";;;;;;;;AAqLA;;;;;;;;;AAgEA;;;iBAvMgB,GAAA,CAAI,OAAA,GAAS,gBAAA,GAAwB,eAAA;;;;;;;;;;;;;;;;;;iBA2ErC,SAAA,CAAU,OAAA,GAAS,gBAAA,GAAwB,eAAA;;;;;;;;;;;;;;;;;;iBA4D3C,QAAA,CAAS,OAAA,GAAS,eAAA,GAAuB,eAAA;;;;;;;;;;;;;;;;;iBAgEzC,QAAA,CACd,OAAA,GAAS,eAAA,sBACW,IAAA,wBAA4B,MAAA,EAAQ,CAAA,KAAM,CAAA"}

package/lib/logger.decorators.js

@@ -0,0 +1,208 @@
+import { Logger } from "./logger.js";
+//#region src/logger.decorators.ts
+/**
+* Copyright 2026 ResQ
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+/**
+* @fileoverview TypeScript decorators for logging method calls, timing, and errors.
+* These decorators integrate with the Logger class to provide declarative logging.
+*/
+/**
+* Decorator that logs method entry and exit.
+* Can optionally log arguments and return values.
+*
+* @param {LogMethodOptions} [options={}] - Configuration options
+* @returns {MethodDecorator} The decorator function
+*
+* @example
+* ```typescript
+* class UserService {
+*   @Log({ logArgs: true, logResult: true })
+*   async getUser(id: string) {
+*     return { id, name: 'John' };
+*   }
+* }
+* ```
+*/
+function Log(options = {}) {
+	const { logArgs = true, logResult = false, message, level = "debug" } = options;
+	return (target, propertyKey, descriptor) => {
+		const originalMethod = descriptor.value;
+		const methodName = String(propertyKey);
+		const className = target.constructor.name;
+		descriptor.value = function(...args) {
+			const logger = Logger.getLogger(`[${className}]`);
+			const prefix = message || `${methodName}`;
+			if (logArgs && args.length > 0) logger[level](`${prefix} called`, { arguments: args });
+			else logger[level](`${prefix} called`);
+			const result = originalMethod.apply(this, args);
+			if (result instanceof Promise) return result.then((value) => {
+				if (logResult) logger[level](`${prefix} returned`, { result: value });
+				else logger[level](`${prefix} completed`);
+				return value;
+			}, (error) => {
+				logger.error(`${prefix} failed`, error);
+				throw error;
+			});
+			if (logResult) logger[level](`${prefix} returned`, { result });
+			else logger[level](`${prefix} completed`);
+			return result;
+		};
+		return descriptor;
+	};
+}
+/**
+* Decorator that logs method execution time.
+* Useful for performance monitoring.
+*
+* @param {LogTimingOptions} [options={}] - Configuration options
+* @returns {MethodDecorator} The decorator function
+*
+* @example
+* ```typescript
+* class DataService {
+*   @LogTiming({ threshold: 100 }) // Only log if execution > 100ms
+*   async fetchData() {
+*     // ... slow operation
+*   }
+* }
+* ```
+*/
+function LogTiming(options = {}) {
+	const { label, threshold = 0, level = "info" } = options;
+	return (target, propertyKey, descriptor) => {
+		const originalMethod = descriptor.value;
+		const methodName = String(propertyKey);
+		const className = target.constructor.name;
+		descriptor.value = function(...args) {
+			const logger = Logger.getLogger(`[${className}]`);
+			const timerLabel = label || `${className}.${methodName}`;
+			const startTime = performance.now();
+			const result = originalMethod.apply(this, args);
+			if (result instanceof Promise) return result.finally(() => {
+				const duration = performance.now() - startTime;
+				if (duration >= threshold) logger[level](`${timerLabel} completed in ${duration.toFixed(2)}ms`);
+			});
+			const duration = performance.now() - startTime;
+			if (duration >= threshold) logger[level](`${timerLabel} completed in ${duration.toFixed(2)}ms`);
+			return result;
+		};
+		return descriptor;
+	};
+}
+/**
+* Decorator that wraps method in try/catch and logs errors.
+* Can optionally suppress the error or rethrow it.
+*
+* @param {LogErrorOptions} [options={}] - Configuration options
+* @returns {MethodDecorator} The decorator function
+*
+* @example
+* ```typescript
+* class ApiService {
+*   @LogError({ rethrow: false, message: 'API call failed' })
+*   async callApi() {
+*     throw new Error('Network error');
+*   }
+* }
+* ```
+*/
+function LogError(options = {}) {
+	const { rethrow = true, message, includeStack = true } = options;
+	return (target, propertyKey, descriptor) => {
+		const originalMethod = descriptor.value;
+		const methodName = String(propertyKey);
+		const className = target.constructor.name;
+		descriptor.value = function(...args) {
+			const logger = Logger.getLogger(`[${className}]`);
+			const errorPrefix = message || `${methodName} error`;
+			try {
+				const result = originalMethod.apply(this, args);
+				if (result instanceof Promise) return result.catch((error) => {
+					const errorData = { method: methodName };
+					if (error instanceof Error && includeStack) errorData["stack"] = error.stack;
+					logger.error(errorPrefix, error, errorData);
+					if (rethrow) throw error;
+				});
+				return result;
+			} catch (error) {
+				const errorData = { method: methodName };
+				if (error instanceof Error && includeStack) errorData["stack"] = error.stack;
+				logger.error(errorPrefix, error, errorData);
+				if (rethrow) throw error;
+				return;
+			}
+		};
+		return descriptor;
+	};
+}
+/**
+* Class decorator that applies logging to all methods of a class.
+* Can be configured to exclude specific methods.
+*
+* @param {LogClassOptions} [options={}] - Configuration options
+* @returns {ClassDecorator} The decorator function
+*
+* @example
+* ```typescript
+* @LogClass({ exclude: ['privateMethod'], timing: true })
+* class MyService {
+*   publicMethod() { ... }
+*   privateMethod() { ... } // Won't be logged
+* }
+* ```
+*/
+function LogClass(options = {}) {
+	const { exclude = [], logCalls = true, timing = false } = options;
+	return (target) => {
+		const className = target.name;
+		const prototype = target.prototype;
+		if (prototype) {
+			const methodNames = Object.getOwnPropertyNames(prototype).filter((name) => name !== "constructor" && typeof prototype[name] === "function" && !exclude.includes(name));
+			for (const methodName of methodNames) {
+				const descriptor = Object.getOwnPropertyDescriptor(prototype, methodName);
+				if (!descriptor) continue;
+				const originalMethod = descriptor.value;
+				descriptor.value = function(...args) {
+					const logger = Logger.getLogger(`[${className}]`);
+					const startTime = timing ? performance.now() : 0;
+					if (logCalls) logger.debug(`${methodName} called`, { arguments: args });
+					const result = originalMethod.apply(this, args);
+					if (result instanceof Promise) return result.then((value) => {
+						if (timing) {
+							const duration = performance.now() - startTime;
+							logger.debug(`${methodName} completed in ${duration.toFixed(2)}ms`);
+						} else if (logCalls) logger.debug(`${methodName} completed`);
+						return value;
+					}, (error) => {
+						logger.error(`${methodName} failed`, error);
+						throw error;
+					});
+					if (timing) {
+						const duration = performance.now() - startTime;
+						logger.debug(`${methodName} completed in ${duration.toFixed(2)}ms`);
+					} else if (logCalls) logger.debug(`${methodName} completed`);
+					return result;
+				};
+				Object.defineProperty(prototype, methodName, descriptor);
+			}
+		}
+		return target;
+	};
+}
+//#endregion
+export { Log, LogClass, LogError, LogTiming };
+
+//# sourceMappingURL=logger.decorators.js.map

package/lib/logger.decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.decorators.js","names":[],"sources":["../src/logger.decorators.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview TypeScript decorators for logging method calls, timing, and errors.\n * These decorators integrate with the Logger class to provide declarative logging.\n */\n\nimport { Logger } from './logger.js';\nimport type {\n  LogClassOptions,\n  LogErrorOptions,\n  LogMethodOptions,\n  LogTimingOptions,\n} from './logger.types.js';\n\n/**\n * Decorator that logs method entry and exit.\n * Can optionally log arguments and return values.\n *\n * @param {LogMethodOptions} [options={}] - Configuration options\n * @returns {MethodDecorator} The decorator function\n *\n * @example\n * ```typescript\n * class UserService {\n *   @Log({ logArgs: true, logResult: true })\n *   async getUser(id: string) {\n *     return { id, name: 'John' };\n *   }\n * }\n * ```\n */\nexport function Log(options: LogMethodOptions = {}): MethodDecorator {\n  const { logArgs = true, logResult = false, message, level = 'debug' } = options;\n\n  return (\n    target: object,\n    propertyKey: string | symbol,\n    descriptor: PropertyDescriptor,\n  ): PropertyDescriptor => {\n    const originalMethod = descriptor.value;\n    const methodName = String(propertyKey);\n    const className = target.constructor.name;\n\n    descriptor.value = function (...args: unknown[]) {\n      const logger = Logger.getLogger(`[${className}]`);\n      const prefix = message || `${methodName}`;\n\n      // Log method entry\n      if (logArgs && args.length > 0) {\n        logger[level](`${prefix} called`, { arguments: args });\n      } else {\n        logger[level](`${prefix} called`);\n      }\n\n      // Execute the original method\n      const result = originalMethod.apply(this, args);\n\n      // Handle async methods\n      if (result instanceof Promise) {\n        return result.then(\n          (value: unknown) => {\n            if (logResult) {\n              logger[level](`${prefix} returned`, { result: value });\n            } else {\n              logger[level](`${prefix} completed`);\n            }\n            return value;\n          },\n          (error: unknown) => {\n            logger.error(`${prefix} failed`, error);\n            throw error;\n          },\n        );\n      }\n\n      // Log sync method result\n      if (logResult) {\n        logger[level](`${prefix} returned`, { result });\n      } else {\n        logger[level](`${prefix} completed`);\n      }\n\n      return result;\n    };\n\n    return descriptor;\n  };\n}\n\n/**\n * Decorator that logs method execution time.\n * Useful for performance monitoring.\n *\n * @param {LogTimingOptions} [options={}] - Configuration options\n * @returns {MethodDecorator} The decorator function\n *\n * @example\n * ```typescript\n * class DataService {\n *   @LogTiming({ threshold: 100 }) // Only log if execution > 100ms\n *   async fetchData() {\n *     // ... slow operation\n *   }\n * }\n * ```\n */\nexport function LogTiming(options: LogTimingOptions = {}): MethodDecorator {\n  const { label, threshold = 0, level = 'info' } = options;\n\n  return (\n    target: object,\n    propertyKey: string | symbol,\n    descriptor: PropertyDescriptor,\n  ): PropertyDescriptor => {\n    const originalMethod = descriptor.value;\n    const methodName = String(propertyKey);\n    const className = target.constructor.name;\n\n    descriptor.value = function (...args: unknown[]) {\n      const logger = Logger.getLogger(`[${className}]`);\n      const timerLabel = label || `${className}.${methodName}`;\n      const startTime = performance.now();\n\n      // Execute the original method\n      const result = originalMethod.apply(this, args);\n\n      // Handle async methods\n      if (result instanceof Promise) {\n        return result.finally(() => {\n          const duration = performance.now() - startTime;\n          if (duration >= threshold) {\n            logger[level](`${timerLabel} completed in ${duration.toFixed(2)}ms`);\n          }\n        });\n      }\n\n      // Log sync method timing\n      const duration = performance.now() - startTime;\n      if (duration >= threshold) {\n        logger[level](`${timerLabel} completed in ${duration.toFixed(2)}ms`);\n      }\n\n      return result;\n    };\n\n    return descriptor;\n  };\n}\n\n/**\n * Decorator that wraps method in try/catch and logs errors.\n * Can optionally suppress the error or rethrow it.\n *\n * @param {LogErrorOptions} [options={}] - Configuration options\n * @returns {MethodDecorator} The decorator function\n *\n * @example\n * ```typescript\n * class ApiService {\n *   @LogError({ rethrow: false, message: 'API call failed' })\n *   async callApi() {\n *     throw new Error('Network error');\n *   }\n * }\n * ```\n */\nexport function LogError(options: LogErrorOptions = {}): MethodDecorator {\n  const { rethrow = true, message, includeStack = true } = options;\n\n  return (\n    target: object,\n    propertyKey: string | symbol,\n    descriptor: PropertyDescriptor,\n  ): PropertyDescriptor => {\n    const originalMethod = descriptor.value;\n    const methodName = String(propertyKey);\n    const className = target.constructor.name;\n\n    descriptor.value = function (...args: unknown[]) {\n      const logger = Logger.getLogger(`[${className}]`);\n      const errorPrefix = message || `${methodName} error`;\n\n      try {\n        const result = originalMethod.apply(this, args);\n\n        // Handle async methods\n        if (result instanceof Promise) {\n          return result.catch((error: unknown) => {\n            const errorData: Record<string, unknown> = { method: methodName };\n            if (error instanceof Error && includeStack) {\n              errorData['stack'] = error.stack;\n            }\n            logger.error(errorPrefix, error, errorData);\n            if (rethrow) throw error;\n            return undefined;\n          });\n        }\n\n        return result;\n      } catch (error) {\n        const errorData: Record<string, unknown> = { method: methodName };\n        if (error instanceof Error && includeStack) {\n          errorData['stack'] = error.stack;\n        }\n        logger.error(errorPrefix, error, errorData);\n        if (rethrow) throw error;\n        return undefined;\n      }\n    };\n\n    return descriptor;\n  };\n}\n\n/**\n * Class decorator that applies logging to all methods of a class.\n * Can be configured to exclude specific methods.\n *\n * @param {LogClassOptions} [options={}] - Configuration options\n * @returns {ClassDecorator} The decorator function\n *\n * @example\n * ```typescript\n * @LogClass({ exclude: ['privateMethod'], timing: true })\n * class MyService {\n *   publicMethod() { ... }\n *   privateMethod() { ... } // Won't be logged\n * }\n * ```\n */\nexport function LogClass(\n  options: LogClassOptions = {},\n): <T extends new (...args: unknown[]) => object>(target: T) => T {\n  const { exclude = [], logCalls = true, timing = false } = options;\n\n  return <T extends new (...args: unknown[]) => object>(target: T): T => {\n    const className = target.name;\n    const prototype = target.prototype;\n\n    // Only apply decorators if prototype exists\n    if (prototype) {\n      // Get all method names from the prototype\n      const methodNames = Object.getOwnPropertyNames(prototype).filter(\n        (name) =>\n          name !== 'constructor' &&\n          typeof prototype[name] === 'function' &&\n          !exclude.includes(name),\n      );\n\n      // Apply decorators to each method\n      for (const methodName of methodNames) {\n        const descriptor = Object.getOwnPropertyDescriptor(prototype, methodName);\n        if (!descriptor) continue;\n\n        const originalMethod = descriptor.value;\n\n        descriptor.value = function (...args: unknown[]) {\n          const logger = Logger.getLogger(`[${className}]`);\n          const startTime = timing ? performance.now() : 0;\n\n          if (logCalls) {\n            logger.debug(`${methodName} called`, { arguments: args });\n          }\n\n          const result = originalMethod.apply(this, args);\n\n          if (result instanceof Promise) {\n            return result.then(\n              (value: unknown) => {\n                if (timing) {\n                  const duration = performance.now() - startTime;\n                  logger.debug(`${methodName} completed in ${duration.toFixed(2)}ms`);\n                } else if (logCalls) {\n                  logger.debug(`${methodName} completed`);\n                }\n                return value;\n              },\n              (error: unknown) => {\n                logger.error(`${methodName} failed`, error);\n                throw error;\n              },\n            );\n          }\n\n          if (timing) {\n            const duration = performance.now() - startTime;\n            logger.debug(`${methodName} completed in ${duration.toFixed(2)}ms`);\n          } else if (logCalls) {\n            logger.debug(`${methodName} completed`);\n          }\n\n          return result;\n        };\n\n        Object.defineProperty(prototype, methodName, descriptor);\n      }\n    }\n\n    return target;\n  };\n}\n"],"mappings":"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"}

package/lib/logger.js

@@ -0,0 +1,268 @@
+//#region src/logger.ts
+/**
+* Copyright (c) 2026 ResQ
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+/**
+* @fileoverview A comprehensive logging utility for both client and server environments.
+* Provides structured logging with support for different log levels, colorization,
+* and contextual information.
+*
+* This logger uses native console methods with structured formatting — no external
+* dependencies are required. Log output follows the pattern:
+*   TIMESTAMP LEVEL [CONTEXT] message { data }
+*/
+/**
+* Enum representing different logging levels with their priority values.
+* Higher values indicate more verbose logging.
+* @enum {number}
+*/
+let LogLevel = /* @__PURE__ */ function(LogLevel) {
+	/** No logging */
+	LogLevel[LogLevel["NONE"] = 0] = "NONE";
+	/** Only error messages */
+	LogLevel[LogLevel["ERROR"] = 1] = "ERROR";
+	/** Errors and warnings */
+	LogLevel[LogLevel["WARN"] = 2] = "WARN";
+	/** Errors, warnings, and informational messages */
+	LogLevel[LogLevel["INFO"] = 3] = "INFO";
+	/** Errors, warnings, info, and debug messages */
+	LogLevel[LogLevel["DEBUG"] = 4] = "DEBUG";
+	/** Errors, warnings, info, debug, and trace messages */
+	LogLevel[LogLevel["TRACE"] = 5] = "TRACE";
+	/** All possible log messages */
+	LogLevel[LogLevel["ALL"] = 6] = "ALL";
+	return LogLevel;
+}({});
+/**
+* A versatile logging utility that works in both browser and Node.js environments.
+* Supports multiple log levels, colorized output, and structured data logging.
+*/
+var Logger = class Logger {
+	/** The context/category name for this logger instance */
+	context;
+	/** The minimum log level that will be output */
+	minLevel;
+	/**
+	* Parse log level from string or return default
+	*/
+	static parseLevel(level) {
+		if (!level) return void 0;
+		switch (level.toUpperCase()) {
+			case "NONE": return LogLevel.NONE;
+			case "ERROR": return LogLevel.ERROR;
+			case "WARN": return LogLevel.WARN;
+			case "INFO": return LogLevel.INFO;
+			case "DEBUG": return LogLevel.DEBUG;
+			case "TRACE": return LogLevel.TRACE;
+			case "ALL": return LogLevel.ALL;
+			default: return;
+		}
+	}
+	/** Registry of logger instances to implement the singleton pattern */
+	static instances = /* @__PURE__ */ new Map();
+	/**
+	* Create a new Logger instance or return an existing one for the given context
+	* @param {string} context - The context name for this logger (e.g., component or service name)
+	* @param {LoggerOptions} [options={}] - Optional logger configuration
+	*/
+	constructor(context, options = {}) {
+		this.context = context;
+		const env = typeof process !== "undefined" ? process.env : {};
+		const envLevel = Logger.parseLevel(env["LOG_LEVEL"] || env["BUN_LOG_LEVEL"]);
+		this.minLevel = options.minLevel ?? envLevel ?? (env["NODE_ENV"] === "production" ? LogLevel.ERROR : LogLevel.ALL);
+	}
+	/**
+	* Get a logger instance for the given context.
+	* If a logger with this context already exists, returns the existing instance.
+	*
+	* @param {string} context - The context name
+	* @param {LoggerOptions} [options] - Optional logger configuration
+	* @returns {Logger} A logger instance for the specified context
+	*/
+	static getLogger(context, options) {
+		let instance = Logger.instances.get(context);
+		if (!instance) {
+			instance = new Logger(context, options);
+			Logger.instances.set(context, instance);
+		}
+		return instance;
+	}
+	/**
+	* Set global minimum log level for all logger instances
+	*
+	* @param {LogLevel} level - The minimum level to log across all loggers
+	*/
+	static setGlobalLogLevel(level) {
+		Logger.instances.forEach((logger) => {
+			logger.minLevel = level;
+		});
+	}
+	/**
+	* Format a timestamp for log output
+	*/
+	formatTimestamp() {
+		const now = /* @__PURE__ */ new Date();
+		return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")} ${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}:${String(now.getSeconds()).padStart(2, "0")}.${String(now.getMilliseconds()).padStart(3, "0")}`;
+	}
+	/**
+	* Format structured log data into a readable suffix string.
+	* Returns empty string if data is null/empty.
+	*/
+	formatData(data) {
+		if (!data || Object.keys(data).length === 0) return "";
+		try {
+			return ` ${JSON.stringify(data)}`;
+		} catch {
+			return " [unserializable data]";
+		}
+	}
+	/**
+	* Emit a log entry using the appropriate console method
+	*/
+	emit(consoleFn, level, message, data) {
+		const ts = this.formatTimestamp();
+		const suffix = this.formatData(data);
+		consoleFn(`${ts} ${level} [${this.context}] ${message}${suffix}`);
+	}
+	/**
+	* Log an informational message
+	*
+	* @param {string} message - The message to log
+	* @param {LogData} [data] - Optional data to include
+	*/
+	info(message, data) {
+		if (this.minLevel < LogLevel.INFO) return;
+		this.emit(console.info, "INFO", message, data);
+	}
+	/**
+	* Log an error message
+	*
+	* @param {string} message - The error message
+	* @param {Error|unknown} [error] - Optional Error object or unknown error
+	* @param {LogData} [data] - Optional additional data
+	*/
+	error(message, error, data) {
+		if (this.minLevel < LogLevel.ERROR) return;
+		let errorObj = error;
+		if (error instanceof Error) {
+			const errorMessage = error.message || ("cause" in error && error.cause instanceof Error ? error.cause.message : "");
+			errorObj = {
+				name: error.name,
+				message: errorMessage,
+				stack: error.stack
+			};
+		}
+		this.emit(console.error, "ERROR", message, {
+			...data,
+			error: errorObj
+		});
+	}
+	/**
+	* Log a warning message
+	*
+	* @param {string} message - The warning message
+	* @param {LogData} [data] - Optional data to include
+	*/
+	warn(message, data) {
+		if (this.minLevel < LogLevel.WARN) return;
+		this.emit(console.warn, "WARN", message, data);
+	}
+	/**
+	* Log a debug message
+	*
+	* @param {string} message - The debug message
+	* @param {LogData} [data] - Optional data to include
+	*/
+	debug(message, data) {
+		if (this.minLevel < LogLevel.DEBUG) return;
+		this.emit(console.debug, "DEBUG", message, data);
+	}
+	/**
+	* Log a trace message (most verbose level)
+	*
+	* @param {string} message - The trace message
+	* @param {LogData} [data] - Optional data to include
+	*/
+	trace(message, data) {
+		if (this.minLevel < LogLevel.TRACE) return;
+		this.emit(console.debug, "TRACE", message, data);
+	}
+	/**
+	* Log an action message (for server actions or important user interactions)
+	*
+	* @param {string} message - The action message
+	* @param {LogData} [data] - Optional data to include
+	*/
+	action(message, data) {
+		if (this.minLevel < LogLevel.INFO) return;
+		this.emit(console.info, "ACTION", message, data);
+	}
+	/**
+	* Log a success message
+	*
+	* @param {string} message - The success message
+	* @param {LogData} [data] - Optional data to include
+	*/
+	success(message, data) {
+		if (this.minLevel < LogLevel.INFO) return;
+		this.emit(console.info, "SUCCESS", message, data);
+	}
+	/**
+	* Group related log messages (console.group wrapper)
+	*
+	* @param {string} label - The group label
+	*/
+	group(label) {
+		if (this.minLevel < LogLevel.INFO) return;
+		console.group(label);
+	}
+	/**
+	* End a log group (console.groupEnd wrapper)
+	*/
+	groupEnd() {
+		if (this.minLevel < LogLevel.INFO) return;
+		console.groupEnd();
+	}
+	/**
+	* Log execution time of a function
+	*
+	* @template T - The return type of the function being timed
+	* @param {string} label - Description of the operation being timed
+	* @param {() => Promise<T> | T} fn - Function to execute and time
+	* @returns {Promise<T>} The result of the function execution
+	*/
+	async time(label, fn) {
+		if (this.minLevel < LogLevel.DEBUG) return fn();
+		const startTime = performance.now();
+		try {
+			const result = await fn();
+			const duration = (performance.now() - startTime).toFixed(2);
+			this.info(`${label} completed`, { duration: `${duration}ms` });
+			return result;
+		} catch (error) {
+			const duration = (performance.now() - startTime).toFixed(2);
+			this.error(`${label} failed`, error, { duration: `${duration}ms` });
+			throw error;
+		}
+	}
+};
+const logger = new Logger("[LOGGER]", {
+	includeTimestamp: true,
+	colorize: true
+});
+//#endregion
+export { LogLevel, Logger, logger };
+
+//# sourceMappingURL=logger.js.map

package/lib/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","names":[],"sources":["../src/logger.ts"],"sourcesContent":["/**\n * Copyright (c) 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * @fileoverview A comprehensive logging utility for both client and server environments.\n * Provides structured logging with support for different log levels, colorization,\n * and contextual information.\n *\n * This logger uses native console methods with structured formatting — no external\n * dependencies are required. Log output follows the pattern:\n *   TIMESTAMP LEVEL [CONTEXT] message { data }\n */\n\n/**\n * Enum representing different logging levels with their priority values.\n * Higher values indicate more verbose logging.\n * @enum {number}\n */\nexport enum LogLevel {\n  /** No logging */\n  NONE = 0,\n  /** Only error messages */\n  ERROR = 1,\n  /** Errors and warnings */\n  WARN = 2,\n  /** Errors, warnings, and informational messages */\n  INFO = 3,\n  /** Errors, warnings, info, and debug messages */\n  DEBUG = 4,\n  /** Errors, warnings, info, debug, and trace messages */\n  TRACE = 5,\n  /** All possible log messages */\n  ALL = 6,\n}\n\n/**\n * Available color keys for log formatting\n * @typedef {'reset' | 'red' | 'yellow' | 'blue' | 'green' | 'gray' | 'bold' | 'magenta' | 'cyan' | 'white'} ColorKey\n */\nexport type ColorKey =\n  | 'reset'\n  | 'red'\n  | 'yellow'\n  | 'blue'\n  | 'green'\n  | 'gray'\n  | 'bold'\n  | 'magenta'\n  | 'cyan'\n  | 'white';\n\n/**\n * Interface for structured data that can be attached to log messages\n * @interface\n */\nexport interface LogData {\n  /**\n   * Any key-value pairs to include in the log\n   */\n  [key: string]: unknown;\n}\n\n/**\n * Configuration options for the Logger\n * @interface\n */\nexport interface LoggerOptions {\n  /**\n   * The minimum level of messages to log\n   */\n  minLevel?: LogLevel;\n\n  /**\n   * Whether to include timestamps in log messages\n   */\n  includeTimestamp?: boolean;\n\n  /**\n   * Whether to colorize log output\n   */\n  colorize?: boolean;\n\n  /**\n   * Whether to write logs to a file (server-side only)\n   */\n  logToFile?: boolean;\n\n  /**\n   * Path to the log file if logToFile is enabled\n   */\n  filePath?: string;\n}\n\n/**\n * A versatile logging utility that works in both browser and Node.js environments.\n * Supports multiple log levels, colorized output, and structured data logging.\n */\nexport class Logger {\n  /** The context/category name for this logger instance */\n  private readonly context: string;\n\n  /** The minimum log level that will be output */\n  private minLevel: LogLevel;\n\n  /**\n   * Parse log level from string or return default\n   */\n  private static parseLevel(level?: string): LogLevel | undefined {\n    if (!level) return undefined;\n    const upper = level.toUpperCase();\n    switch (upper) {\n      case 'NONE': return LogLevel.NONE;\n      case 'ERROR': return LogLevel.ERROR;\n      case 'WARN': return LogLevel.WARN;\n      case 'INFO': return LogLevel.INFO;\n      case 'DEBUG': return LogLevel.DEBUG;\n      case 'TRACE': return LogLevel.TRACE;\n      case 'ALL': return LogLevel.ALL;\n      default: return undefined;\n    }\n  }\n\n  /** Registry of logger instances to implement the singleton pattern */\n  private static readonly instances: Map<string, Logger> = new Map();\n\n  /**\n   * Create a new Logger instance or return an existing one for the given context\n   * @param {string} context - The context name for this logger (e.g., component or service name)\n   * @param {LoggerOptions} [options={}] - Optional logger configuration\n   */\n  constructor(context: string, options: LoggerOptions = {}) {\n    this.context = context;\n\n    // Priority: options.minLevel > LOG_LEVEL env > BUN_LOG_LEVEL env > Default\n    const env = typeof process !== 'undefined' ? process.env : {};\n    const envLevel = Logger.parseLevel(env['LOG_LEVEL'] || env['BUN_LOG_LEVEL']);\n\n    this.minLevel =\n      options.minLevel ??\n      envLevel ??\n      (env['NODE_ENV'] === 'production' ? LogLevel.ERROR : LogLevel.ALL);\n  }\n\n  /**\n   * Get a logger instance for the given context.\n   * If a logger with this context already exists, returns the existing instance.\n   *\n   * @param {string} context - The context name\n   * @param {LoggerOptions} [options] - Optional logger configuration\n   * @returns {Logger} A logger instance for the specified context\n   */\n  public static getLogger(context: string, options?: LoggerOptions): Logger {\n    let instance = Logger.instances.get(context);\n\n    if (!instance) {\n      instance = new Logger(context, options);\n      Logger.instances.set(context, instance);\n    }\n\n    return instance;\n  }\n\n  /**\n   * Set global minimum log level for all logger instances\n   *\n   * @param {LogLevel} level - The minimum level to log across all loggers\n   */\n  public static setGlobalLogLevel(level: LogLevel): void {\n    Logger.instances.forEach((logger) => {\n      logger.minLevel = level;\n    });\n  }\n\n  /**\n   * Format a timestamp for log output\n   */\n  private formatTimestamp(): string {\n    const now = new Date();\n    const y = now.getFullYear();\n    const mo = String(now.getMonth() + 1).padStart(2, '0');\n    const d = String(now.getDate()).padStart(2, '0');\n    const h = String(now.getHours()).padStart(2, '0');\n    const mi = String(now.getMinutes()).padStart(2, '0');\n    const s = String(now.getSeconds()).padStart(2, '0');\n    const ms = String(now.getMilliseconds()).padStart(3, '0');\n    return `${y}-${mo}-${d} ${h}:${mi}:${s}.${ms}`;\n  }\n\n  /**\n   * Format structured log data into a readable suffix string.\n   * Returns empty string if data is null/empty.\n   */\n  private formatData(data?: Record<string, unknown>): string {\n    if (!data || Object.keys(data).length === 0) return '';\n    try {\n      return ` ${JSON.stringify(data)}`;\n    } catch {\n      return ' [unserializable data]';\n    }\n  }\n\n  /**\n   * Emit a log entry using the appropriate console method\n   */\n  private emit(\n    consoleFn: (...args: unknown[]) => void,\n    level: string,\n    message: string,\n    data?: Record<string, unknown>,\n  ): void {\n    const ts = this.formatTimestamp();\n    const suffix = this.formatData(data);\n    consoleFn(`${ts} ${level} [${this.context}] ${message}${suffix}`);\n  }\n\n  /**\n   * Log an informational message\n   *\n   * @param {string} message - The message to log\n   * @param {LogData} [data] - Optional data to include\n   */\n  info(message: string, data?: LogData): void {\n    if (this.minLevel < LogLevel.INFO) return;\n    this.emit(console.info, 'INFO', message, data);\n  }\n\n  /**\n   * Log an error message\n   *\n   * @param {string} message - The error message\n   * @param {Error|unknown} [error] - Optional Error object or unknown error\n   * @param {LogData} [data] - Optional additional data\n   */\n  error(message: string, error?: unknown, data?: LogData): void {\n    if (this.minLevel < LogLevel.ERROR) return;\n\n    let errorObj: unknown = error;\n    if (error instanceof Error) {\n      const errorMessage =\n        error.message || ('cause' in error && error.cause instanceof Error ? error.cause.message : '');\n      errorObj = { name: error.name, message: errorMessage, stack: error.stack };\n    }\n\n    this.emit(console.error, 'ERROR', message, { ...data, error: errorObj });\n  }\n\n  /**\n   * Log a warning message\n   *\n   * @param {string} message - The warning message\n   * @param {LogData} [data] - Optional data to include\n   */\n  warn(message: string, data?: LogData): void {\n    if (this.minLevel < LogLevel.WARN) return;\n    this.emit(console.warn, 'WARN', message, data);\n  }\n\n  /**\n   * Log a debug message\n   *\n   * @param {string} message - The debug message\n   * @param {LogData} [data] - Optional data to include\n   */\n  debug(message: string, data?: LogData): void {\n    if (this.minLevel < LogLevel.DEBUG) return;\n    this.emit(console.debug, 'DEBUG', message, data);\n  }\n\n  /**\n   * Log a trace message (most verbose level)\n   *\n   * @param {string} message - The trace message\n   * @param {LogData} [data] - Optional data to include\n   */\n  trace(message: string, data?: LogData): void {\n    if (this.minLevel < LogLevel.TRACE) return;\n    this.emit(console.debug, 'TRACE', message, data);\n  }\n\n  /**\n   * Log an action message (for server actions or important user interactions)\n   *\n   * @param {string} message - The action message\n   * @param {LogData} [data] - Optional data to include\n   */\n  action(message: string, data?: LogData): void {\n    if (this.minLevel < LogLevel.INFO) return;\n    this.emit(console.info, 'ACTION', message, data);\n  }\n\n  /**\n   * Log a success message\n   *\n   * @param {string} message - The success message\n   * @param {LogData} [data] - Optional data to include\n   */\n  success(message: string, data?: LogData): void {\n    if (this.minLevel < LogLevel.INFO) return;\n    this.emit(console.info, 'SUCCESS', message, data);\n  }\n\n  /**\n   * Group related log messages (console.group wrapper)\n   *\n   * @param {string} label - The group label\n   */\n  group(label: string): void {\n    if (this.minLevel < LogLevel.INFO) return;\n    console.group(label);\n  }\n\n  /**\n   * End a log group (console.groupEnd wrapper)\n   */\n  groupEnd(): void {\n    if (this.minLevel < LogLevel.INFO) return;\n    console.groupEnd();\n  }\n\n  /**\n   * Log execution time of a function\n   *\n   * @template T - The return type of the function being timed\n   * @param {string} label - Description of the operation being timed\n   * @param {() => Promise<T> | T} fn - Function to execute and time\n   * @returns {Promise<T>} The result of the function execution\n   */\n  async time<T>(label: string, fn: () => Promise<T> | T): Promise<T> {\n    if (this.minLevel < LogLevel.DEBUG) return fn();\n\n    const startTime = performance.now();\n    try {\n      const result = await fn();\n      const endTime = performance.now();\n      const duration = (endTime - startTime).toFixed(2);\n      this.info(`${label} completed`, { duration: `${duration}ms` });\n      return result;\n    } catch (error) {\n      const endTime = performance.now();\n      const duration = (endTime - startTime).toFixed(2);\n      this.error(`${label} failed`, error, { duration: `${duration}ms` });\n      throw error;\n    }\n  }\n}\n\nexport const logger = new Logger('[LOGGER]', {\n  includeTimestamp: true,\n  colorize: true,\n});\n"],"mappings":"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"}

package/lib/logger.types.d.ts

@@ -0,0 +1,144 @@
+import { LogLevel } from "./logger.js";
+
+//#region src/logger.types.d.ts
+/**
+ * Copyright 2026 ResQ
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Interface for structured data that can be attached to log messages
+ * @interface
+ */
+interface LogData {
+  /**
+   * Any key-value pairs to include in the log
+   */
+  [key: string]: unknown;
+}
+/**
+ * Configuration options for the Logger
+ * @interface
+ */
+interface LoggerOptions {
+  /**
+   * The minimum level of messages to log
+   */
+  minLevel?: LogLevel;
+  /**
+   * Whether to include timestamps in log messages
+   */
+  includeTimestamp?: boolean;
+  /**
+   * Whether to colorize log output
+   */
+  colorize?: boolean;
+  /**
+   * Whether to write logs to a file (server-side only)
+   */
+  logToFile?: boolean;
+  /**
+   * Path to the log file if logToFile is enabled
+   */
+  filePath?: string;
+}
+/**
+ * Available color keys for log formatting
+ * @typedef ColorKey
+ */
+type ColorKey = 'reset' | 'red' | 'yellow' | 'blue' | 'green' | 'gray' | 'bold' | 'magenta' | 'cyan' | 'white';
+/**
+ * Log level strings for type safety
+ */
+type LogLevelString = 'error' | 'warn' | 'info' | 'debug' | 'trace' | 'action' | 'success';
+/**
+ * Structured log entry for transport/storage
+ * @interface
+ */
+interface LogEntry {
+  /** ISO timestamp of the log */
+  timestamp: string;
+  /** Log level */
+  level: LogLevelString;
+  /** Logger context/category */
+  context: string;
+  /** Log message */
+  message: string;
+  /** Optional structured data */
+  data?: LogData;
+  /** Environment (client/server) */
+  environment: 'client' | 'server';
+}
+/**
+ * Interface for custom log transports
+ * @interface
+ */
+interface LogTransport {
+  /** Transport name for identification */
+  name: string;
+  /** Method to write a log entry */
+  write(entry: LogEntry): void | Promise<void>;
+}
+/**
+ * Options for the @Log decorator
+ * @interface
+ */
+interface LogMethodOptions {
+  /** Whether to log method arguments (default: true) */
+  logArgs?: boolean;
+  /** Whether to log return value (default: false) */
+  logResult?: boolean;
+  /** Custom message prefix */
+  message?: string;
+  /** Log level to use (default: 'debug') */
+  level?: LogLevelString;
+}
+/**
+ * Options for the @LogTiming decorator
+ * @interface
+ */
+interface LogTimingOptions {
+  /** Custom label for timing logs */
+  label?: string;
+  /** Threshold in ms - only log if execution exceeds this (default: 0) */
+  threshold?: number;
+  /** Log level to use (default: 'info') */
+  level?: LogLevelString;
+}
+/**
+ * Options for the @LogError decorator
+ * @interface
+ */
+interface LogErrorOptions {
+  /** Whether to rethrow the error after logging (default: true) */
+  rethrow?: boolean;
+  /** Custom error message prefix */
+  message?: string;
+  /** Whether to log the stack trace (default: true) */
+  includeStack?: boolean;
+}
+/**
+ * Options for the @LogClass decorator
+ * @interface
+ */
+interface LogClassOptions {
+  /** Methods to exclude from logging */
+  exclude?: string[];
+  /** Whether to log all method calls (default: true) */
+  logCalls?: boolean;
+  /** Whether to time all method calls (default: false) */
+  timing?: boolean;
+}
+//#endregion
+export { ColorKey, LogClassOptions, LogData, LogEntry, LogErrorOptions, LogLevelString, LogMethodOptions, LogTimingOptions, LogTransport, LoggerOptions };
+//# sourceMappingURL=logger.types.d.ts.map

package/lib/logger.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.types.d.ts","names":[],"sources":["../src/logger.types.ts"],"mappings":";;;;;;AAoBA;;;;;AAWA;;;;;;;;;;;UAXiB,OAAA;EAsCL;;;EAAA,CAlCT,GAAA;AAAA;AAiDH;;;;AAAA,UA1CiB,aAAA;EAgDA;;;EA5Cf,QAAA,GAJ4B,QAAA;EAkD5B;;;EA1CA,gBAAA;EAgDA;;;EA5CA,QAAA;EAgDW;;AAOb;EAnDE,SAAA;;;;EAIA,QAAA;AAAA;;;;;KAOU,QAAA;;;;KAeA,cAAA;;;;;UAMK,QAAA;EAsCO;EApCtB,SAAA;EA2C+B;EAzC/B,KAAA,EAAO,cAAA;EA+Ce;EA7CtB,OAAA;EA2CA;EAzCA,OAAA;EA2CQ;EAzCR,IAAA,GAAO,OAAA;EAyCe;EAvCtB,WAAA;AAAA;;;;;UAOe,YAAA;EA6CH;EA3CZ,IAAA;EAkDe;EAhDf,KAAA,CAAM,KAAA,EAAO,QAAA,UAAkB,OAAA;AAAA;;;;;UAOhB,gBAAA;EA+CT;EA7CN,OAAA;;EAEA,SAAA;;EAEA,OAAA;;EAEA,KAAA,GAAQ,cAAA;AAAA;;;;;UAOO,gBAAA;;EAEf,KAAA;;EAEA,SAAA;;EAEA,KAAA,GAAQ,cAAA;AAAA;;;;;UAOO,eAAA;;EAEf,OAAA;;EAEA,OAAA;;EAEA,YAAA;AAAA;;;;;UAOe,eAAA;;EAEf,OAAA;;EAEA,QAAA;;EAEA,MAAA;AAAA"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@resq-sw/logger",
+  "version": "0.1.0",
+  "description": "Structured logging with log levels for Node.js and Bun",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "default": "./lib/index.js"
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": ["lib", "README.md"],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "tsdown": "^0.21.7",
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/resq-software/npm.git",
+    "directory": "packages/logger"
+  },
+  "keywords": ["logger", "logging", "structured-logging"],
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}