← Back to Home

API Reference

Complete reference for all better-logger APIs. Everything you need to use better-logger effectively.

Core API

Method	Signature	Description
better.log()	(msg: string, data?: unknown) => void	Drop-in replacement for console.log(). Creates implicit flow and auto-groups rapid calls.
better.log.info()	(msg: string, data?: unknown) => void	Info-level logging. Same as better.log() but explicitly tagged.
better.log.warn()	(msg: string, data?: unknown) => void	Warning logging. Auto-tags flow with [warn] severity tag.
better.log.error()	(msg: string, error?: unknown) => void	Error logging. Auto-tags flow with [error] and fails the flow.
better.flow()	(name: string, options?: BetterFlowOptions) => FlowHandle	Create explicit flow for structured logging.
better.setEnabled()	(enabled: boolean) => void	Globally enable/disable all logging.
better.isEnabled()	() => boolean	Check if logging is enabled.
better.subscribe()	(fn: FlowListener) => () => void	Register listener for flow completion events. Returns unsubscribe function.
better.toJSON()	(flow: FlowHandle) => string	Export flow as versioned JSON string.

Flow Methods

Methods available on FlowHandle returned by better.flow().

Steps

// Create a step with optional data
const step = flow.step('step-name', { key: 'value' })

// Mark step as successful
step.success()

// Mark step as failed
step.fail(new Error('something went wrong'))

// Async step with auto-complete
const result = await flow.run('async-step', async () => {
  return await someAsyncOperation()
})

Context

// Set shared context (merged with existing)
flow.setContext({ userId: 'abc', requestId: 'xyz' })

// Get current context copy
const ctx = flow.getContext() // { userId: 'abc', requestId: 'xyz' }

Child Flows

// Create nested child flow
const childFlow = flow.child('sub-process')
childFlow.setContext({ sharedKey: 'value' }) // Inherits parent context

childFlow.step('child-step').success()
childFlow.success()

Tags

// Add tags to flow
flow.tag('auth')
flow.tag('api')

// Or at creation time
const flow = better.flow('checkout', { tags: ['payment', 'ecommerce'] })

Completion

// Complete flow successfully
flow.success()

// Fail flow with error
flow.fail(new Error('something went wrong'))

BetterFlowOptions

Option	Type	Default	Description
enabled	boolean	true	Enable/disable this flow. If false, returns NOOP_FLOW.
tags	string[]	[]	Indexing labels for grouping/filtering.
maxSteps	number	undefined	Safety limit for step count. Excess steps return NOOP_STEP.
sample	number	1.0	Sampling rate (0.0 to 1.0). 0 = no flows, 1.0 = all flows.
initialContext	Record<string, unknown>	{}	Initial context to seed the flow with.

Configuration Methods

Method	Default	Description
better.setIdleTimeout(ms)	100	Auto-complete timeout for implicit flows (ms).
better.setFlowName(name)	'default'	Default flow name for implicit flows.
better.setDefaultTags(tags)	[]	Tags applied to all implicit flows.
better.log.flush()	—	Force complete current implicit flow.
better.log.activeFlow()	—	Get current implicit flow handle or null.

Transport Methods

Method	Signature	Description
better.log.toFile()	(path: string, opts?: { append?: boolean }) => void	Write logs to file (zero-dep).
better.log.toStream()	(stream: NodeJS.WriteStream) => void	Write logs to any writable stream.
better.log.toHttp()	(url: string, opts?: { method?: string; headers? }) => void	POST logs to HTTP endpoint.

Production Features

PII Redaction

// Redact specific fields from all log data
better.log.redact(['password', 'ssn', 'creditCard'])

// Clear redaction
better.log.redact([])

Async Logging

// Enable non-blocking buffered mode
better.log.async(true)

// Logs are buffered
better.log('msg1')
better.log('msg2')
better.log('msg3')

// Force flush
better.log.flush()

// Disable async mode (auto-flushes remaining)
better.log.async(false)

Silent Mode

// Global disable
better.setEnabled(false)

// Per-flow silent
const flow = better.flow('health-check', { enabled: false })