tim-logger

Tiny logger for Tim apps with shared event shape from tim-types.

Interface

The core event is LogEvent (from tim-types):

• message (string, required)
• level ('info' | 'warn' | 'error')
• source (string)
• verb (string)
• data (Json)
• timestamp (number)
• duration (number)
• machineId / sessionId (string)

Common functions (client + server):

• createClientLogger(config) / createServerLogger(config)
• initClientLogger(config) / initServerLogger(config)
• log(eventOrMessage, data?)
• info(message, data?)
• warn(message, data?)
• error(message, data?)
• interceptConsoleLogs(logger, options?)

Configs:

• source?: string (default source tag)
• transports?: ('console' | 'custom' | 'fs')[] (client: console/custom, server: console/custom/fs)
• addLog?: (event: LogEvent) => Promise<void> | void (required for custom)
• fsPath?: string (server only, for fs transport)

Client usage

Procedure:

1. Initialize a logger (or use the default logger).
2. Call log/info/warn/error.
3. Optional: use a custom transport via addLog.
4. Optional: intercept console.* and pipe through your logger.

import {
  createClientLogger,
  initClientLogger,
  log,
  info,
  warn,
  error,
  interceptConsoleLogs,
} from 'tim-logger';

// Option A: create a dedicated instance
const clientLogger = createClientLogger({
  source: 'web-ui',
  transports: ['console', 'custom'],
  addLog: async (event) => {
    // send to your API
    await fetch('/api/log', {
      method: 'POST',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(event),
    });
  },
});

await clientLogger.info('UI ready', { route: '/' });

// Option B: initialize the default singleton
initClientLogger({ source: 'web-ui' });
await info('Loaded', { route: '/' });
await warn('Slow render', { ms: 1200 });
await error('Failed to load widget', { id: 'w-12' });

// You can also pass a full LogEvent:
await log({ message: 'Clicked', verb: 'CLICK', data: { id: 'btn-1' } });

// Intercept console on the client (returns a restore function)
const restoreConsole = interceptConsoleLogs(clientLogger, {
  defaults: { source: 'web-ui' },
});
console.log('Hello from console');
restoreConsole();

Server usage

Procedure:

1. Create/initialize a server logger with desired transports.
2. Call log/info/warn/error.
3. Optional: use fs for file output or custom with addLog.
4. Optional: install crash handlers.
5. Optional: intercept console.* and pipe through your logger.

import {
  createServerLogger,
  initServerLogger,
  log,
  info,
  warn,
  error,
  clearLogs,
  registerCrashHandlers,
  interceptConsoleLogs,
} from 'tim-logger';

// Option A: create a dedicated instance
const serverLogger = createServerLogger({
  source: 'api',
  transports: ['console', 'fs'],
  fsPath: 'logs/server.log',
});

await serverLogger.info('Server started', { port: 3000 });

// Option B: initialize the default singleton
initServerLogger({ source: 'api', transports: ['console', 'fs'] });
await info('Listening', { port: 3000 });
await warn('High memory', { rssMb: 512 });
await error('Unhandled request', { path: '/bad' });

// Clear file logs (no-op if fs transport is off)
await clearLogs();

// Intercept console on the server (returns a restore function)
const restoreConsole = interceptConsoleLogs(serverLogger, {
  defaults: { source: 'api' },
});
console.warn('Deprecated path');
restoreConsole();

// Crash handlers (optional)
registerCrashHandlers({
  onCrash: (err) => {
    // send to Sentry or persist
  },
});

Notes

• log(eventOrMessage, data?) accepts either a LogEvent or a string message.
• custom transport requires addLog; if missing, it logs a one-time warning.
• Server fs transport writes readable text lines to the file.