· · ·
\n\n## 👀 Preview\n\n\n\n· · ·
\n\n## Features ✨\n\n- Works locally and in browsers\n- Zero dependencies, written in TypeScript\n- Configure programmatically or through environment variables\n- Tiny: **8 kB** packed\n- Logs can be sent to the console or a file\n- Both plain-text `line` and `json` (JSON Lines) formats supported\n- Color-coded `info`, `imp`, `warn`, and `err` levels in terminals\n\n· · ·
\n\n## 📦 Installation\n\n```bash\nnpm install jet-logger\n```\n\n> Requires Node.js 20.16+ or 22.3+. Jet-Logger is an ES module; CommonJS projects can `require()` it on Node.js 20.19+ and 22.12+.\n\n· · ·
\n\n## ⚡ Quick Start\n\n```ts\nimport logger from 'jet-logger';\n\nlogger.info('Server started on port', 3000);\nlogger.imp('Connected to the database');\nlogger.warn('Slow response:', { route: '/users', ms: 1200 });\nlogger.err('Payment failed:', 'card declined');\n```\n\nWith the default options, that prints (colors not shown):\n\n```text\n[14:03:21.045] INFO: hello jet-logger\n[14:03:21.046] IMPORTANT: hello jet-logger\n[14:03:21.046] WARNING: hello jet-logger\n[14:03:21.046] ERROR: hello jet-logger\n```\n\nThe default export is a ready-made logger configured from environment variables. To create your own, call `JetLogger()`:\n\n```ts\nimport { JetLogger } from 'jet-logger';\n\nconst fileLogger = JetLogger({\n mode: JetLogger.Modes.FILE,\n filepath: './logs/app.log',\n format: JetLogger.Formats.JSON,\n});\n\nfileLogger.info('Written to disk');\n```\n\n· · ·
\n\n## 📘 Log Methods\n\n| Method | Description |\n| --------------- | ----------------------------------------------------------------------------------- |\n| `info(...args)` | Log at `INFO` level |\n| `imp(...args)` | Log at `IMPORTANT` level |\n| `warn(...args)` | Log at `WARNING` level (stderr in console mode) |\n| `err(...args)` | Log at `ERROR` level (stderr in console mode) |\n| `out(...args)` | Print the arguments as their own line, without a label or timestamp |\n| `line()` | Print an empty line |\n| `catch(fn)` | Call `fn` and log its error message if it throws or returns a rejected promise |\n| `flush()` | Returns a promise that resolves once everything logged so far has been written |\n| `close()` | Flush, then release the log file. Later calls on this logger are ignored |\n\nArguments are joined with a space. Objects are printed in full (`util.inspect` in Node, JSON in the browser).\n\n· · ·
\n\n## ⚙️ Configuration\n\nEvery option can be passed to `JetLogger()` or set with an environment variable. Options passed in code take priority over environment variables, which take priority over the defaults.\n\n| Option | Environment variable | Values | Default |\n| ----------------------- | ------------------------------------- | ---------------------------------------------- | ---------------- |\n| `mode` | `JET_LOGGER_MODE` | `console`, `file`, `browser`, `custom`, `off` | `console` |\n| `format` | `JET_LOGGER_FORMAT` | `line`, `json` | `line` |\n| `filepath` | `JET_LOGGER_FILEPATH` | Path of the log file (file mode) | `jet-logger.log` |\n| `prependTimeToFilename` | `JET_LOGGER_PREPEND_TIME_TO_FILENAME` | `true`, `false` | `false` |\n| `showTime` | `JET_LOGGER_SHOW_TIME` | `true`, `false` | `true` |\n| `customTransport` | — | Your function (required when mode is `custom`) | — |\n\n- `JetLogger.Modes` and `JetLogger.Formats` hold the mode and format values.\n- Environment variables are read when a logger is created. The default logger is created the first time you use it, so variables set after importing (e.g. by a `.env` loader) still apply.\n- Environment values are case-insensitive (except `JET_LOGGER_FILEPATH`); unrecognized values are ignored.\n- Options set to `undefined` use the default. Invalid or unknown options throw an `InvalidOptionError`, which is exported.\n\n---\n\n### Output formats\n\n`line` uses local time. The console shows just the time of day; files also include the date:\n\n```text\n[14:03:21.045] WARNING: something happened <- console\n[2026-09-24 14:03:21.045] WARNING: something happened <- file\n```\n\nColors are used only when the output is a terminal. Set `NO_COLOR` to turn them off or `FORCE_COLOR` to force them on.\n\n`json` writes one object per line with an ISO timestamp in `time`. Text is joined into `msg`, objects go into `data` (an array if there are several), and the first `Error` adds its message to `msg` and its stack frames to `stack`:\n\n```ts\nlogger.warn('payment failed:', new Error('card declined'), { orderId: 42 });\n```\n\n```json\n{\"time\":\"2026-09-25T01:04:01.247Z\",\"level\":\"WARNING\",\"msg\":\"payment failed: card declined\",\"data\":{\"orderId\":42},\"stack\":[\"at charge (/app/pay.js:10:11)\"]}\n```\n\n`line` prints messages as-is, so text from users could add fake log lines or terminal escape codes. Use `json` for untrusted input; its values are escaped.\n\n---\n\n### File mode\n\n- Logs are appended to `filepath`. Missing directories are created automatically.\n- Loggers writing to the same file share it, so their lines stay in order.\n- Lines logged in the same tick are written together in one synchronous write at the end of the tick, or as soon as 64 KB are waiting, so memory use stays small even when logging in bursts.\n- Anything not yet written is flushed when the process exits, crashes, or receives `SIGINT` or `SIGTERM`. If your app handles those signals itself, jet-logger flushes and leaves exiting to your handler.\n- `await logger.flush()` makes sure everything is on disk; `await logger.close()` also closes the file.\n- `prependTimeToFilename` starts a new file each run: `logs/app.log` → `logs/20260925T010401Z_app.log`.\n- With the `json` format, the default file name becomes `jet-logger.jsonl`.\n- Files are created with your process's default permissions, which usually lets other users read them. Use a stricter `umask` or directory if your logs hold sensitive data.\n\n---\n\n### Browser\n\nIn browsers and web workers, `console` and `file` modes switch to `browser` mode automatically, which prints styled logs with `console.info`, `console.warn`, and `console.error`.\n\n· · ·
\n\n## 🚚 Custom Transports\n\nSet `mode` to `custom` to send every log to your own function, e.g. to forward it to Datadog, Splunk, or an HTTP collector:\n\n```ts\nimport { JetLogger, type CustomTransportFn } from 'jet-logger';\n\nconst sendToSplunk: CustomTransportFn = async ({ time, level, msg }) => {\n await splunkClient.emit({ time, level, msg });\n};\n\nconst remoteLogger = JetLogger({\n mode: JetLogger.Modes.CUSTOM,\n customTransport: sendToSplunk,\n});\n\nremoteLogger.imp('Sent to Splunk');\nawait remoteLogger.flush(); // e.g. before exiting: waits for pending sends\n```\n\nThe function can be async. If it throws or its promise rejects, the error is reported on stderr (`console.error` in browsers) instead of crashing your app.\n\nIt receives a `CustomTransportContext`:\n\n```ts\ninterface CustomTransportContext {\n time: string; // ISO 8601\n level: 'INFO' | 'IMPORTANT' | 'WARNING' | 'ERROR' | null; // null for out() and line()\n msg: string; // all arguments joined into one string\n}\n```\n\n· · ·
\n\n## License\n\n[MIT](./LICENSE) © seanpmaxwell\n","readmeFilename":"README.md"}