@variablesoftware/logface 🎛️🪵😎

🎛️🪵😎 A fun, lightweight, structured console-style logger with tag-based filtering for TypeScript projects.

---

✨ Features

• Drop-in replacements for console.* methods: debug, info, warn, error, log
• Scoped tagging via log.options({ tag })
• Filters logs using LOG or LOG_VERBOSE environment variables (supports wildcards)
• Runtime log level: log.level = 'warn' or log.setLogLevel('warn') to suppress lower levels (unless LOG/LOG_VERBOSE is set)
• Per-call configuration: timestamps, level formatting, and custom tags
• Wildcard filtering support (e.g. auth:*, metrics*)
• Global setup via log.setup({ ... })
• Designed for Node.js and edge runtimes
• Debug output is always gated: debug logs only appear if LOG/LOG_VERBOSE match, or if log.level is 'debug'andDEBUG=1 is set
• log.level = 'silent' or log.setLogLevel('silent') suppresses all output
• All log filtering logic falls back to LOG/LOG_VERBOSE if set, otherwise uses the runtime log level

---

🚀 Install

pnpm add @variablesoftware/logface

---

🔧 Quick Usage

import{log}from"@variablesoftware/logface";// Basic usagelog.debug("Boot sequence initiated");log.info("App started on port %d",3000);log.warn("Disk usage at %d%%",91);log.error("Database connection failed: %s",err.message);// Scoped/tagged logslog.options({tag: "auth"}).debug("User login event");log.options({tag: "metrics",timestamp: true}).info("Memory: %dMB",182);log.options({tag: "api",levelShort: false}).warn("Rate limit exceeded");// Global setuplog.setup({timestamp: true,levelShort: false});// Runtime log level (NEW)log.level="warn";// Only warn, error, and log will be emittedlog.setLogLevel("error");// Only error and log will be emittedlog.level="silent";// Suppress all output// Restore to defaultlog.level="debug";

---

📤 Output Format

[D][init] Booting...
[I][auth] Login successful
[L][metrics] 200 OK

Use log.setup() to enable timestamps or full level names.

---

🔍 Filtering

Use LOG or LOG_VERBOSE to filter logs by tag or level:

LOG=auth node app.js
LOG=metrics,debug,auth* node app.js
LOG="!foo;auth,debug" node app.js # Negation: suppress 'foo' unless also matches 'auth' or 'debug'

• Wildcards are supported (e.g. auth:*, metrics*).
• Negation is supported: Prefix a pattern with ! to suppress logs matching that pattern, unless also matched by a positive pattern. Example: LOG="!foo;auth,debug" suppresses logs with tag foo unless they also match auth or debug.
• If neither is set, you can control output at runtime:

log.level="warn";// Only warn, error, and loglog.level="silent";// Suppress all output

Debug logs are only shown if LOG/LOG_VERBOSE match, or if log.level is 'debug' andDEBUG=1 is set in the environment.

---

📚 Full Guide

For wildcard matching, structured output, test helpers, global setup, and advanced filtering:

➡️ See LOGGING.md for full logging level guidance

---

📄 License

MIT © Rob Friedman / Variable Software

---

Built with ❤️ by @variablesoftware
Thank you for downloading and using this project. Pull requests are warmly welcomed!

---

🌐 Inclusive & Accessible Design

• Naming, logging, error messages, and tests avoid cultural or ableist bias
• Avoids assumptions about input/output formats or encodings
• Faithfully reflects user data — no coercion or silent transformations
• Designed for clarity, predictability, and parity with underlying platforms (e.g., Cloudflare APIs)
• Works well in diverse, multilingual, and inclusive developer environments

---

Logface Configuration

Logface supports powerful customization via a config file. You can control emoji, color, and more for your log output.

Quick Start

1. Copy the example config:

   cp logface.example.config.js logface.config.js

2. Edit logface.config.js to your liking.

Example: Multiple Emoji Sets & Randomization

// logface.config.jsmodule.exports={emojiRandom: true,// Random emoji per log messageemojis: {debug: ["🐛","🔍","🦠"],info: ["ℹ️","💡","🧭"],log: ["📝","📄","🗒️"],warn: ["⚠️","🚧","🛑"],error: ["🔥","💥","💣"],},colorEnabled: true,// Enable/disable colorcolorLibrary: "chalk",// 'chalk', 'picocolors', 'colorette', or 'kleur'};

Disabling Emoji/Color in Tests

Logface disables emoji and color automatically during tests for stable output. You can also set these manually:

module.exports={emojiRandom: false,emojis: {debug: "",info: "",log: "",warn: "",error: ""},colorEnabled: false,};

Supported Config Options

• emojiRandom: true for random emoji per log, false for fixed.
• emojis: Object mapping log levels to emoji (array or string).
• colorEnabled: Enable/disable color output.
• colorLibrary: Choose color library: 'chalk', 'picocolors', 'colorette', 'kleur'.

.js vs .mjs

• Use .js for CommonJS or ESM (depends on your package.jsontype).
• Use .mjs for guaranteed ESM.

Example: ESM Config

// logface.config.mjsexportdefault{emojiRandom: true,emojis: {debug: ["🐛","🔍","🦠"],info: ["ℹ️","💡","🧭"],log: ["📝","📄","🗒️"],warn: ["⚠️","🚧","🛑"],error: ["🔥","💥","💣"],},colorEnabled: true,colorLibrary: "picocolors",};

Tips

• Add logface.config.js to your .gitignore to avoid committing user-specific config.
• See logface.example.config.js for a template.

---

For more, see LOGGING.md.