@santana-org/logger 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @santa-org/logger
+
+A lightweight, configurable logger for Node.js and modern JavaScript environments.
+
+## Features
+
+- Log levels: `debug`, `info`, `success`, `warn`, `error`
+- Configurable minimum level
+- Optional timestamps
+- Optional label / namespace
+- Colorized output (auto-detected TTY)
+- Custom formatter support
+- ESM-first, CJS-compatible
+- Zero dependencies
+
+## Installation
+
+```sh
+npm install @santa-org/logger
+# or
+pnpm add @santa-org/logger
+```
+
+## Usage
+
+```ts
+import { createLogger } from "@santa-org/logger"
+
+const logger = createLogger({
+  level: "info",
+  label: "app",
+  timestamps: true,
+})
+
+logger.info("Server started")
+logger.warn("Low memory")
+logger.error("Unhandled exception", { code: 500 })
+```
+
+### Child logger
+
+```ts
+const dbLogger = logger.child("db")
+dbLogger.debug("Query executed")
+```
+
+### Custom formatter
+
+```ts
+import { createLogger, type LogEntry } from "@santa-org/logger"
+
+const logger = createLogger({
+  formatter: (entry: LogEntry, _colors: boolean) =>
+    `[${entry.level.toUpperCase()}] ${entry.message}`,
+})
+```
+
+## API
+
+### `createLogger(options?)`
+
+| Option      | Type        | Default       | Description                                |
+|-------------|-------------|---------------|--------------------------------------------|
+| `level`     | `LogLevel`  | `"debug"`     | Minimum log level                          |
+| `label`     | `string`    | —             | Label/namespace prepended to each message  |
+| `timestamps`| `boolean`   | `false`       | Include ISO timestamps                     |
+| `colors`    | `boolean`   | auto (TTY)    | Colorize output                            |
+| `formatter` | `Formatter` | built-in      | Custom formatter function                  |
+| `writer`    | `Writer`    | stdout/stderr | Custom output writer                       |
+
+### Log Levels
+
+`debug` < `info` < `success` < `warn` < `error`
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,118 @@
+'use strict';
+
+const ANSI_RESET = "\x1B[0m";
+const LEVEL_COLORS = {
+  debug: "\x1B[90m",
+  // gray
+  info: "\x1B[36m",
+  // cyan
+  success: "\x1B[32m",
+  // green
+  warn: "\x1B[33m",
+  // yellow
+  error: "\x1B[31m"
+  // red
+};
+const LEVEL_LABELS = {
+  debug: "DBG",
+  info: "INF",
+  success: "SUC",
+  warn: "WRN",
+  error: "ERR"
+};
+function colorize(text, color, enabled) {
+  return enabled ? `${color}${text}${ANSI_RESET}` : text;
+}
+const defaultFormatter = (entry, colors) => {
+  const parts = [];
+  if (entry.timestamp) {
+    const ts = entry.timestamp.toISOString();
+    parts.push(colorize(ts, "\x1B[2m", colors));
+  }
+  const levelColor = LEVEL_COLORS[entry.level];
+  const levelLabel = LEVEL_LABELS[entry.level];
+  parts.push(colorize(levelLabel, levelColor, colors));
+  if (entry.label) {
+    parts.push(colorize(`[${entry.label}]`, "\x1B[35m", colors));
+  }
+  parts.push(entry.message);
+  if (entry.args.length > 0) {
+    const extras = entry.args.map((a) => typeof a === "object" ? JSON.stringify(a, null, 2) : String(a)).join(" ");
+    parts.push(extras);
+  }
+  return parts.join(" ");
+};
+
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  success: 2,
+  warn: 3,
+  error: 4
+};
+function isLevelEnabled(current, minimum) {
+  return LOG_LEVELS[current] >= LOG_LEVELS[minimum];
+}
+
+function isTTY() {
+  return process.stdout.isTTY === true;
+}
+function defaultWriter() {
+  return {
+    out: (message) => process.stdout.write(`${message}
+`),
+    err: (message) => process.stderr.write(`${message}
+`)
+  };
+}
+function isErrorLevel(level) {
+  return level === "error" || level === "warn";
+}
+function createLogger(options = {}) {
+  const {
+    level: minLevel = "debug",
+    label,
+    timestamps = false,
+    colors = isTTY(),
+    formatter = defaultFormatter,
+    writer = defaultWriter()
+  } = options;
+  function log(level, message, ...args) {
+    if (!isLevelEnabled(level, minLevel)) {
+      return;
+    }
+    const entry = {
+      level,
+      message,
+      ...label !== void 0 ? { label } : {},
+      ...timestamps ? { timestamp: /* @__PURE__ */ new Date() } : {},
+      args
+    };
+    const formatted = formatter(entry, colors);
+    if (isErrorLevel(level)) {
+      writer.err(formatted);
+    } else {
+      writer.out(formatted);
+    }
+  }
+  return {
+    debug: (message, ...args) => log("debug", message, ...args),
+    info: (message, ...args) => log("info", message, ...args),
+    warn: (message, ...args) => log("warn", message, ...args),
+    error: (message, ...args) => log("error", message, ...args),
+    success: (message, ...args) => log("success", message, ...args),
+    child: (childLabel) => createLogger({
+      level: minLevel,
+      label: childLabel,
+      timestamps,
+      colors,
+      formatter,
+      writer
+    })
+  };
+}
+
+exports.LOG_LEVELS = LOG_LEVELS;
+exports.createLogger = createLogger;
+exports.defaultFormatter = defaultFormatter;
+exports.isLevelEnabled = isLevelEnabled;

package/dist/index.d.cts

@@ -0,0 +1,46 @@
+type LogLevel = "debug" | "info" | "warn" | "error" | "success";
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    label?: string;
+    timestamp?: Date;
+    args: unknown[];
+}
+interface LoggerOptions {
+    /** Minimum log level to output. Defaults to "debug". */
+    level?: LogLevel;
+    /** Optional label/namespace prepended to each message. */
+    label?: string;
+    /** Whether to include timestamps in output. Defaults to false. */
+    timestamps?: boolean;
+    /** Whether to colorize output. Defaults to true when a TTY is detected. */
+    colors?: boolean;
+    /** Custom formatter. Overrides the built-in formatter when provided. */
+    formatter?: Formatter;
+    /** Output writer. Defaults to process.stdout / process.stderr. */
+    writer?: Writer;
+}
+type Formatter = (entry: LogEntry, colors: boolean) => string;
+interface Writer {
+    out: (message: string) => void;
+    err: (message: string) => void;
+}
+interface Logger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    success: (message: string, ...args: unknown[]) => void;
+    /** Create a child logger with a specific label. */
+    child: (label: string) => Logger;
+}
+
+declare const defaultFormatter: Formatter;
+
+declare const LOG_LEVELS: Record<LogLevel, number>;
+declare function isLevelEnabled(current: LogLevel, minimum: LogLevel): boolean;
+
+declare function createLogger(options?: LoggerOptions): Logger;
+
+export { LOG_LEVELS, createLogger, defaultFormatter, isLevelEnabled };
+export type { Formatter, LogEntry, LogLevel, Logger, LoggerOptions, Writer };

package/dist/index.d.mts

@@ -0,0 +1,46 @@
+type LogLevel = "debug" | "info" | "warn" | "error" | "success";
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    label?: string;
+    timestamp?: Date;
+    args: unknown[];
+}
+interface LoggerOptions {
+    /** Minimum log level to output. Defaults to "debug". */
+    level?: LogLevel;
+    /** Optional label/namespace prepended to each message. */
+    label?: string;
+    /** Whether to include timestamps in output. Defaults to false. */
+    timestamps?: boolean;
+    /** Whether to colorize output. Defaults to true when a TTY is detected. */
+    colors?: boolean;
+    /** Custom formatter. Overrides the built-in formatter when provided. */
+    formatter?: Formatter;
+    /** Output writer. Defaults to process.stdout / process.stderr. */
+    writer?: Writer;
+}
+type Formatter = (entry: LogEntry, colors: boolean) => string;
+interface Writer {
+    out: (message: string) => void;
+    err: (message: string) => void;
+}
+interface Logger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    success: (message: string, ...args: unknown[]) => void;
+    /** Create a child logger with a specific label. */
+    child: (label: string) => Logger;
+}
+
+declare const defaultFormatter: Formatter;
+
+declare const LOG_LEVELS: Record<LogLevel, number>;
+declare function isLevelEnabled(current: LogLevel, minimum: LogLevel): boolean;
+
+declare function createLogger(options?: LoggerOptions): Logger;
+
+export { LOG_LEVELS, createLogger, defaultFormatter, isLevelEnabled };
+export type { Formatter, LogEntry, LogLevel, Logger, LoggerOptions, Writer };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+type LogLevel = "debug" | "info" | "warn" | "error" | "success";
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    label?: string;
+    timestamp?: Date;
+    args: unknown[];
+}
+interface LoggerOptions {
+    /** Minimum log level to output. Defaults to "debug". */
+    level?: LogLevel;
+    /** Optional label/namespace prepended to each message. */
+    label?: string;
+    /** Whether to include timestamps in output. Defaults to false. */
+    timestamps?: boolean;
+    /** Whether to colorize output. Defaults to true when a TTY is detected. */
+    colors?: boolean;
+    /** Custom formatter. Overrides the built-in formatter when provided. */
+    formatter?: Formatter;
+    /** Output writer. Defaults to process.stdout / process.stderr. */
+    writer?: Writer;
+}
+type Formatter = (entry: LogEntry, colors: boolean) => string;
+interface Writer {
+    out: (message: string) => void;
+    err: (message: string) => void;
+}
+interface Logger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+    success: (message: string, ...args: unknown[]) => void;
+    /** Create a child logger with a specific label. */
+    child: (label: string) => Logger;
+}
+
+declare const defaultFormatter: Formatter;
+
+declare const LOG_LEVELS: Record<LogLevel, number>;
+declare function isLevelEnabled(current: LogLevel, minimum: LogLevel): boolean;
+
+declare function createLogger(options?: LoggerOptions): Logger;
+
+export { LOG_LEVELS, createLogger, defaultFormatter, isLevelEnabled };
+export type { Formatter, LogEntry, LogLevel, Logger, LoggerOptions, Writer };

package/dist/index.mjs

@@ -0,0 +1,113 @@
+const ANSI_RESET = "\x1B[0m";
+const LEVEL_COLORS = {
+  debug: "\x1B[90m",
+  // gray
+  info: "\x1B[36m",
+  // cyan
+  success: "\x1B[32m",
+  // green
+  warn: "\x1B[33m",
+  // yellow
+  error: "\x1B[31m"
+  // red
+};
+const LEVEL_LABELS = {
+  debug: "DBG",
+  info: "INF",
+  success: "SUC",
+  warn: "WRN",
+  error: "ERR"
+};
+function colorize(text, color, enabled) {
+  return enabled ? `${color}${text}${ANSI_RESET}` : text;
+}
+const defaultFormatter = (entry, colors) => {
+  const parts = [];
+  if (entry.timestamp) {
+    const ts = entry.timestamp.toISOString();
+    parts.push(colorize(ts, "\x1B[2m", colors));
+  }
+  const levelColor = LEVEL_COLORS[entry.level];
+  const levelLabel = LEVEL_LABELS[entry.level];
+  parts.push(colorize(levelLabel, levelColor, colors));
+  if (entry.label) {
+    parts.push(colorize(`[${entry.label}]`, "\x1B[35m", colors));
+  }
+  parts.push(entry.message);
+  if (entry.args.length > 0) {
+    const extras = entry.args.map((a) => typeof a === "object" ? JSON.stringify(a, null, 2) : String(a)).join(" ");
+    parts.push(extras);
+  }
+  return parts.join(" ");
+};
+
+const LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  success: 2,
+  warn: 3,
+  error: 4
+};
+function isLevelEnabled(current, minimum) {
+  return LOG_LEVELS[current] >= LOG_LEVELS[minimum];
+}
+
+function isTTY() {
+  return process.stdout.isTTY === true;
+}
+function defaultWriter() {
+  return {
+    out: (message) => process.stdout.write(`${message}
+`),
+    err: (message) => process.stderr.write(`${message}
+`)
+  };
+}
+function isErrorLevel(level) {
+  return level === "error" || level === "warn";
+}
+function createLogger(options = {}) {
+  const {
+    level: minLevel = "debug",
+    label,
+    timestamps = false,
+    colors = isTTY(),
+    formatter = defaultFormatter,
+    writer = defaultWriter()
+  } = options;
+  function log(level, message, ...args) {
+    if (!isLevelEnabled(level, minLevel)) {
+      return;
+    }
+    const entry = {
+      level,
+      message,
+      ...label !== void 0 ? { label } : {},
+      ...timestamps ? { timestamp: /* @__PURE__ */ new Date() } : {},
+      args
+    };
+    const formatted = formatter(entry, colors);
+    if (isErrorLevel(level)) {
+      writer.err(formatted);
+    } else {
+      writer.out(formatted);
+    }
+  }
+  return {
+    debug: (message, ...args) => log("debug", message, ...args),
+    info: (message, ...args) => log("info", message, ...args),
+    warn: (message, ...args) => log("warn", message, ...args),
+    error: (message, ...args) => log("error", message, ...args),
+    success: (message, ...args) => log("success", message, ...args),
+    child: (childLabel) => createLogger({
+      level: minLevel,
+      label: childLabel,
+      timestamps,
+      colors,
+      formatter,
+      writer
+    })
+  };
+}
+
+export { LOG_LEVELS, createLogger, defaultFormatter, isLevelEnabled };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@santana-org/logger",
+  "version": "0.1.0",
+  "description": "A lightweight, configurable logger for Node.js and modern JavaScript environments",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/santana-org/uxie.git",
+    "directory": "packages/logger"
+  },
+  "keywords": [
+    "logger",
+    "logging",
+    "typescript",
+    "esm",
+    "colorized",
+    "santa-org"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "publint": "^0.3.4",
+    "typescript": "^5.8.2",
+    "unbuild": "^3.3.1",
+    "vitest": "^3.0.8"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=25"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "packcheck": "publint"
+  }
+}