@fimbul-works/logger 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FimbulWorks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# @fimbul-works/logger
+
+A lightweight, TypeScript-friendly wrapper around [Pino](https://getpino.io/) that provides flexible logging patterns with automatic argument handling.
+
+[![npm version](https://badge.fury.io/js/%40logger-works%2Flogger.svg)](https://www.npmjs.com/package/@logger-works/logger)
+[![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://github.com/microsoft/TypeScript)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@logger-works/logger)](https://bundlephobia.com/package/@logger-works/logger)
+
+**Note:** This is a wrapper around [Pino](https://getpino.io/). For advanced configuration and features, refer to the [Pino documentation](https://getpino.io/#/docs/api).
+
+## Quick Start
+
+```typescript
+import Logger from 'your-package-name';
+
+const logger = new Logger();
+
+logger.info('Hello, world!');
+logger.error('I AM ERROR');
+```
+
+## Installation
+
+```bash
+npm install @logger-works/logger
+```
+
+## Features
+
+- 🔄 Multiple argument patterns supported (console-style, Pino-style, printf-style)
+- 🎯 TypeScript support with full type definitions
+- 🧪 Automatic test environment detection (disables output in `NODE_ENV=test`)
+- 🚀 Zero-config defaults with STDOUT/STDERR separation
+- 📦 Access to underlying Pino instance for advanced usage
+
+## Usage Patterns
+
+The logger intelligently handles different argument patterns to accommodate various logging styles:
+
+### 1. Simple String Message
+
+```typescript
+logger.info('Server started on port 3000');
+// Output: {"level":30,"time":1234567890,"msg":"Server started on port 3000"}
+```
+
+### 2. Pino-Style (Object First)
+
+Standard Pino pattern with structured data first, message second:
+
+```typescript
+logger.info({ userId: 123, action: 'login' }, 'User logged in');
+// Output: {"level":30,"time":1234567890,"userId":123,"action":"login","msg":"User logged in"}
+```
+
+### 3. Console-Style (Message First, Object Second)
+
+Automatically swaps arguments to Pino format:
+
+```typescript
+logger.info('User logged in', { userId: 123, action: 'login' });
+// Output: {"level":30,"time":1234567890,"userId":123,"action":"login","msg":"User logged in"}
+```
+
+### 4. Printf-Style Formatting
+
+Uses Pino's built-in printf formatting when `%` is detected:
+
+```typescript
+logger.info('User %s logged in from %s', 'john', '192.168.1.1');
+// Output: {"level":30,"time":1234567890,"msg":"User john logged in from 192.168.1.1"}
+```
+
+### 5. Message with Multiple Arguments
+
+Wraps additional arguments in a structured `args` field:
+
+```typescript
+logger.info('Processing items', 'item1', 'item2', 'item3');
+// Output: {"level":30,"time":1234567890,"args":["item1","item2","item3"],"msg":"Processing items"}
+```
+
+### 6. Primitive Values
+
+Non-string primitives are wrapped in an `args` array:
+
+```typescript
+logger.info(42, true, null);
+// Output: {"level":30,"time":1234567890,"args":[42,true,null],"msg":"Log event"}
+```
+
+## API
+
+All methods support the argument patterns described above:
+
+- `logger.info(...args)` - Info level logs
+- `logger.error(...args)` - Error level logs
+- `logger.warn(...args)` - Warning level logs
+- `logger.debug(...args)` - Debug level logs
+- `logger.log(level, ...args)` - Log at specified level
+
+### Access Raw Pino Instance
+
+For advanced Pino features:
+
+```typescript
+const pinoInstance = logger.getRawLogger();
+pinoInstance.child({ requestId: '123' });
+```
+
+## Default Behavior
+
+### Output Destinations
+
+By default, the logger sends:
+- **Info, warn, debug** logs → STDOUT (file descriptor 1)
+- **Error** logs → STDERR (file descriptor 2)
+
+### Test Environment
+
+When `NODE_ENV=test`, all output is automatically disabled to keep test output clean.
+
+### Custom Targets
+
+Override default targets with your own configuration:
+
+```typescript
+const logger = new Logger({
+  transport: {
+    targets: [
+      {
+        target: 'pino-pretty',
+        options: { colorize: true }
+      }
+    ]
+  }
+});
+```
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file for details.
+
+---
+
+Built with ⚡ by [loggerWorks](https://github.com/logger-works)

package/biome.json

@@ -0,0 +1,15 @@
+{
+  "formatter": {
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120,
+    "lineEnding": "lf"
+  },
+  "linter": {
+    "rules": {
+      "suspicious": {
+        "noExplicitAny": "off"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@fimbul-works/logger",
+  "description": "Simple wrapper for Pino",
+  "version": "1.0.0",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "author": "FimbulWorks <contact@fimbul.works>",
+  "homepage": "https://github.com/fimbul-works/logger#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fimbul-works/logger.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fimbul-works/logger/issues"
+  },
+  "keywords": [
+    "pino",
+    "logger",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && pnpm build:esm && pnpm build:cjs",
+    "build:esm": "tsc -p tsconfig.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "format": "biome format --write",
+    "test": "NODE_ENV=test vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "pino": "^10.3.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/node": "^25.2.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from "vitest";
+import { Logger } from "./index";
+
+// Mock Pino
+vi.mock("pino", () => {
+  const info = vi.fn();
+  const error = vi.fn();
+  const warn = vi.fn();
+  const debug = vi.fn();
+  const logger = { info, error, warn, debug };
+  return {
+    default: vi.fn(() => logger),
+  };
+});
+
+describe("Logger", () => {
+  it("should log info messages", () => {
+    const logger = new Logger();
+    logger.info("Hello world");
+
+    const rawLogger = logger.getRawLogger();
+    expect(rawLogger.info).toHaveBeenCalledWith("Hello world");
+  });
+
+  it("should log error messages", () => {
+    const logger = new Logger();
+    const err = new Error("Test error");
+
+    logger.error("Something went wrong", err);
+
+    const rawLogger = logger.getRawLogger();
+    expect(rawLogger.error).toHaveBeenCalledWith(err, "Something went wrong");
+  });
+
+  describe("Smart Argument Handling", () => {
+    it("should swap args when calling (msg, obj)", () => {
+      const logger = new Logger();
+      const rawLogger = logger.getRawLogger();
+      const obj = { id: 123 };
+
+      logger.info("User login", obj);
+
+      // Expect swap: (obj, msg)
+      expect(rawLogger.info).toHaveBeenCalledWith(obj, "User login");
+    });
+
+    it("should wrap multiple args in payload object", () => {
+      const logger = new Logger();
+      const rawLogger = logger.getRawLogger();
+
+      logger.info("Values", 1, true, "extra");
+
+      // Expect wrap: ({ args: [1, true, "extra"] }, msg)
+      expect(rawLogger.info).toHaveBeenCalledWith({ args: [1, true, "extra"] }, "Values");
+    });
+
+    it("should respect printf style formatting", () => {
+      const logger = new Logger();
+      const rawLogger = logger.getRawLogger();
+
+      logger.info("User %s logged in", "Alice");
+
+      // Expect pass-through: (msg, ...args)
+      expect(rawLogger.info).toHaveBeenCalledWith("User %s logged in", "Alice");
+    });
+
+    it("should handle mixed printf and extra args (best effort)", () => {
+      const logger = new Logger();
+      const rawLogger = logger.getRawLogger();
+
+      // If user mixes printf with too many args, we just pass through and let Pino handle/ignore
+      logger.info("User %s", "Alice", "ExtraIgnored");
+
+      expect(rawLogger.info).toHaveBeenCalledWith("User %s", "Alice", "ExtraIgnored");
+    });
+
+    it("should pass through (obj, msg) as is", () => {
+      const logger = new Logger();
+      const rawLogger = logger.getRawLogger();
+      const obj = { id: 1 };
+
+      logger.info(obj, "Message");
+
+      expect(rawLogger.info).toHaveBeenCalledWith(obj, "Message");
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,170 @@
+import pino, { type Logger as Pino } from "pino";
+
+/**
+ * Log level.
+ */
+export type LogLevel = "info" | "error" | "warn" | "debug";
+
+/**
+ * Configuration options for the Logger.
+ */
+export interface LoggerOptions extends pino.LoggerOptions {
+  /**
+   * Optional name label (e.g., "http")
+   */
+  name?: string;
+
+  /**
+   * Optional log level (e.g., "info"), default: "info"
+   */
+  level?: string;
+
+  /**
+   * Optional targets, default: STDOUT & STDERR, disabled when NODE_ENV="test"
+   */
+  targets?: pino.TransportTargetOptions[];
+}
+
+/**
+ * A wrapper around Pino to provide a consistent logging interface.
+ */
+export class Logger {
+  /**
+   * pino instance.
+   *
+   * @private
+   * @type {Pino}
+   */
+  private logger: Pino;
+
+  /**
+   * Creates a new Logger instance.
+   *
+   * @param {LoggerOptions} options - Optional configuration options for the logger
+   */
+  constructor(options: pino.LoggerOptions = {}) {
+    this.logger = pino({
+      level: "info",
+      ...options,
+      transport: {
+        targets:
+          process.env.NODE_ENV !== "test"
+            ? [
+                {
+                  target: "pino/file",
+                  options: { destination: 1 }, // STDOUT
+                  level: options.level || "info",
+                },
+                {
+                  target: "pino/file",
+                  options: { destination: 2 }, // STDERR
+                  level: "error",
+                },
+              ]
+            : [],
+        ...options.transport,
+      },
+    });
+  }
+
+  /**
+   * Logs a message at the specified level.
+   *
+   * @param {LogLevel} level - The log level.
+   */
+  public log(level: LogLevel, ...args: any[]): void {
+    this.handleLog(level, args);
+  }
+
+  /**
+   * Logs a message at the `info` level.
+   */
+  public info(...args: any[]): void {
+    this.handleLog("info", args);
+  }
+
+  /**
+   * Logs a message at the `error` level.
+   */
+  public error(...args: any[]): void {
+    this.handleLog("error", args);
+  }
+
+  /**
+   * Logs a message at the `warn` level.
+   */
+  public warn(...args: any[]): void {
+    this.handleLog("warn", args);
+  }
+
+  /**
+   * Logs a message at the `debug` level.
+   */
+  public debug(...args: any[]): void {
+    this.handleLog("debug", args);
+  }
+
+  /**
+   * Returns the underlying Pino logger instance.
+   *
+   * @returns {Pino} The Pino logger instance.
+   */
+  public getRawLogger(): Pino {
+    return this.logger;
+  }
+
+  /**
+   * Handles logging by parsing arguments and calling the appropriate Pino method.
+   *
+   * @private
+   * @param {LogLevel} level
+   * @param {any[]} args
+   */
+  private handleLog(level: LogLevel, args: any[]): void {
+    if (args.length === 0) {
+      this.logger[level]("");
+      return;
+    }
+
+    const [first, ...rest] = args;
+
+    // Case 1: Object first -> Pass through (Standard Pino)
+    // logger.info({ id: 1 }, "msg")
+    if (typeof first === "object" && first !== null) {
+      this.logger[level](first, ...rest);
+      return;
+    }
+
+    // Case 2: String first
+    if (typeof first === "string") {
+      // Check for printf-style formatting
+      // Simple heuristic: if string contains %, treat as printf and pass through
+      if (first.includes("%") && rest.length > 0) {
+        this.logger[level](first, ...rest);
+        return;
+      }
+
+      // Check for (msg, obj) pattern -> Swap to (obj, msg) (Console style)
+      if (rest.length === 1 && typeof rest[0] === "object" && rest[0] !== null) {
+        this.logger[level](rest[0], first);
+        return;
+      }
+
+      // Check for (msg, ...vars) pattern -> Wrap in payload
+      if (rest.length > 0) {
+        this.logger[level]({ args: rest }, first);
+        return;
+      }
+
+      // Just a single string message
+      this.logger[level](first);
+      return;
+    }
+
+    // Case 3: Primitive first (non-string output) -> Wrap in payload
+    // logger.info(1, true)
+    this.logger[level]({ args }, "Log event");
+  }
+}
+
+export default Logger;

package/tsconfig.cjs.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "outDir": "dist/cjs",
+    "verbatimModuleSyntax": false
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "lib": ["ES2020"],
+    "moduleResolution": "Bundler",
+    "declaration": true,
+    "allowJs": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist/esm/"
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts", "node_modules"]
+}