LogLoom-js — file-first Node logger 🪵⚡️

A tiny, file-first logger for Node.js that focuses on reliable writes, simple log levels, and optional timestamps. It supports ESM + CommonJS, comes with TypeScript types, and offers both async and sync modes for different workloads. Package name on npm: logloom. (GitHub)

✨ Features

• Async & Sync loggers: choose between background queued writes (async) or immediate writes (sync). (GitHub)
• Simple levels: INFO, WARNING, ERROR, ALERT. (GitHub)
• Optional timestamps: enable/disable time column (default: enabled). Format DD-MM-YYYY HH:mm:ss. (GitHub)
• Stable line format: uuid | LEVEL | message | timestamp?. (GitHub)
• File-first by design: appends to <destination>/<filename>.<extension>; directories auto-created. (GitHub)
• ESM & CJS with exported types subpath (logloom/types). Node 18+. (GitHub)

📦 Install

npm install logloom

Requires Node.js 18+. Works in both ESM (import) and CommonJS (require). Types are bundled and also available via logloom/types. (GitHub)

🚀 Quick start (Async logger)

TypeScript

import { initLogLoom } from 'logloom';

const logger = await initLogLoom({
  file: {
    destination: './logs',
    filename: 'app',
    extension: 'log', // 'log' | 'txt' | 'csv'
  },
  time: { isTimestampEnable: true },
});

await logger.write('Server started', 'INFO');
await logger.write('Cache warmed', 'ALERT');

// Ensure all queued writes are flushed before process exit:
await logger.flush();

JavaScript (ESM)

import { initLogLoom } from 'logloom';

const logger = await initLogLoom({
  file: { destination: './logs', filename: 'app', extension: 'log' },
  time: { isTimestampEnable: true },
});

await logger.write('Server started', 'INFO');
await logger.flush();

JavaScript (CommonJS)

const { initLogLoom } = require('logloom');

(async () => {
  const logger = await initLogLoom({
    file: { destination: './logs', filename: 'app', extension: 'log' },
  });

  await logger.write('Server started');
  await logger.flush();
})();

What gets written? Each call appends a line like:

3a3a1d3e-3b20-4b86-8b39-0e7e9c8f5b73 | INFO | Server started | 10-09-2025 14:32:18

Format is uuid | LEVEL | message | timestamp?. Timestamps are included only when enabled. (GitHub)

🧵 Synchronous logger (no queue)

Use this when you need immediate writes (e.g., very short scripts, early-boot logs):

TypeScript

import { initLogLoomSync } from 'logloom';

const logger = initLogLoomSync({
  file: { destination: './logs', filename: 'setup', extension: 'txt' },
  time: { isTimestampEnable: false },
});

logger.write('Bootstrapping...', 'INFO');
logger.write('Done.');

JavaScript

const { initLogLoomSync } = require('logloom');

const logger = initLogLoomSync({
  file: { destination: './logs', filename: 'setup', extension: 'txt' },
  time: { isTimestampEnable: false },
});

logger.write('Bootstrapping...');

Sync mode appends directly using appendFileSync after ensuring the directory and file exist. (GitHub)

🧰 API

Factory functions

• await initLogLoom(options) -> AsyncLogger Creates an async logger that queues appends; call flush() to wait for completion. (GitHub)

• initLogLoomSync(options) -> SyncLogger Creates a synchronous logger that writes immediately. (GitHub)

Logger methods

• write(message: string, type?: RowType) => void | Promise<void> Appends a line: uuid | type | message | timestamp?. Default type is INFO. (Async flavor returns a resolved promise; sync returns void.) (GitHub)

• flush() => Promise<void> (async logger only) Resolves when all queued writes are on disk. (GitHub)

Options (TypeScript)

// from `logloom/types`
import type { logParams, fileParams, timeParams } from 'logloom/types';

• logParams

  interface logParams {
    time?: TimeOptions;
    file: fileOptions;
    row?: rowOptions; // (currently reserved)
  }

• timeParams

  interface timeParams {
    isTimestampEnable?: boolean; // default true
  }

• fileParams

  interface fileParams {
    destination: string;              // folder path
    filename: string;                 // file name (no extension)
    extension: 'log' | 'txt' | 'csv'; // file extension only
  }

• RowType

  type rowType = 'ERROR' | 'INFO' | 'WARNING' | 'ALERT';

Types are re-exported via the logloom/types subpath. (GitHub)

📝 Output & file behavior

• Line format: uuid | LEVEL | message | timestamp?. The timestamp column is omitted when time.isTimestampEnable === false. (GitHub)
• Timestamps: DD-MM-YYYY HH:mm:ss via an internal helper. (GitHub)
• Files: The logger creates <destination> recursively (if needed) and ensures <filename>.<extension> exists (no overwrite). Writes are appended with a trailing newline. (GitHub)
• Note on .csv: the extension is purely the file suffix; the content is the same pipe-delimited line format (not RFC-CSV). (GitHub)

🛡️ Reliability tips

• Async mode internally serializes appends with a promise queue; call logger.flush() before process exit to ensure everything is written. (GitHub)
• Prefer one logger instance per file in a single process. Multiple processes writing to the same file will interleave lines (as expected for append).
• Consider external tools for rotation or size limits (not provided by this package).

🔄 ESM / CJS / Types

The package exports both ESM and CJS entry points and ships .d.ts types:

• ESM: "module": "dist/index.mjs"
• CJS: "main": "dist/index.cjs"
• Types: "types": "dist/index.d.ts" and subpath export logloom/types
• Node engines: "node": ">=18"

See package.json for full details. (GitHub)

🧪 Example patterns

Disable timestamps

const logger = initLogLoomSync({
  file: { destination: './logs', filename: 'no-time', extension: 'log' },
  time: { isTimestampEnable: false },
});
logger.write('Timestamps are off');

Flush on shutdown (async)

const logger = await LogLoom({ file: { destination: './logs', filename: 'app', extension: 'log' } });

process.on('beforeExit', async () => {
  await logger.flush();
});

🤝 Contributing

PRs and issues are welcome in the GitHub repo.

📄 License

MIT. (GitHub)

Sources

Key implementation details were derived from the repository source:

• Package metadata, exports, engines, and name (logloom). (GitHub)
• Public exports (initLogLoom, initLogLoomSync). (GitHub)
• Async logger (queue, flush, write format). (GitHub)
• Sync logger (direct append). (GitHub)
• Line format & timestamp helper. (GitHub)
• Types & allowed log levels. (GitHub)

If you want, I can also drop this into your repo as README.md with badges and a quick “Why LogLoom?” section tailored to your project voice.