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 (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.

``ts
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.

`ts
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.