variablesoftware
@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
LOGorLOG_VERBOSEenvironment variables (supports wildcards) - Runtime log level:
log.level = 'warn'orlog.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_VERBOSEmatch, or iflog.levelis'debug'andDEBUG=1is set log.level = 'silent'orlog.setLogLevel('silent')suppresses all output- All log filtering logic falls back to
LOG/LOG_VERBOSEif set, otherwise uses the runtime log level
π Install
pnpm add @variablesoftware/logfaceπ§ Quick Usage
import { log } from "@variablesoftware/logface";
// Basic usage
log.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 logs
log.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 setup
log.setup({ timestamp: true, levelShort: false });
// Runtime log level (NEW)
log.level = "warn"; // Only warn, error, and log will be emitted
log.setLogLevel("error"); // Only error and log will be emitted
log.level = "silent"; // Suppress all output
// Restore to default
log.level = "debug";π€ Output Format
[D][init] Booting...
[I][auth] Login successful
[L][metrics] 200 OKUse 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 tagfoounless they also matchauthordebug. - If neither is set, you can control output at runtime:
log.level = "warn"; // Only warn, error, and log
log.level = "silent"; // Suppress all outputDebug logs are only shown if LOG/LOG_VERBOSE match, or if log.level is 'debug' and DEBUG=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
- Copy the example config:
cp logface.example.config.js logface.config.js - Edit
logface.config.jsto your liking.
Example: Multiple Emoji Sets & Randomization
// logface.config.js
module.exports = {
emojiRandom: true, // Random emoji per log message
emojis: {
debug: ["π", "π", "π¦ "],
info: ["βΉοΈ", "π‘", "π§"],
log: ["π", "π", "ποΈ"],
warn: ["β οΈ", "π§", "π"],
error: ["π₯", "π₯", "π£"],
},
colorEnabled: true, // Enable/disable color
colorLibrary: "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:truefor random emoji per log,falsefor 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
.jsfor CommonJS or ESM (depends on yourpackage.jsontype). - Use
.mjsfor guaranteed ESM.
Example: ESM Config
// logface.config.mjs
export default {
emojiRandom: true,
emojis: {
debug: ["π", "π", "π¦ "],
info: ["βΉοΈ", "π‘", "π§"],
log: ["π", "π", "ποΈ"],
warn: ["β οΈ", "π§", "π"],
error: ["π₯", "π₯", "π£"],
},
colorEnabled: true,
colorLibrary: "picocolors",
};Tips
- Add
logface.config.jsto your.gitignoreto avoid committing user-specific config. - See
logface.example.config.jsfor a template.
For more, see LOGGING.md.