Logger
The logger() and createLogger() factories, the Logger interface, and their options, from @arcton/logger.
Overview
Log one line per request, with no runtime dependency at all:
import { Arcton } from '@arcton/core'
import { logger } from '@arcton/logger'
const app = Arcton()
app.use(logger())
app.get('/', () => ({ hello: 'world' }))
app.listen()@arcton/logger is app.use()-only. See
Logging for the usage-first guide.
logger()
Purpose — builds a request-logging middleware.
Signature
function logger(options?: LoggerOptions): ArctonLoggerParameters
| Parameter | Type | Description |
|---|---|---|
options | LoggerOptions | Optional. See below for fields and defaults. |
Return type — an ArctonLogger: a Middleware with a .logger property attached, meant to be passed to app.use().
Behavior
- Reads
ctx.request.methodand the request URL'spathname(the query string is left out) before callingnext(). - With
pretty: false(the default): oncenext()resolves, logs one JSON line withmethod,path,status(ctx.response.status, defaulting to200), anddurationMs— aterrorfor a5xxstatus,warnfor4xx,infootherwise. - With
pretty: true: logs a→line as the request arrives, and a←line once it's done (or anERRline if nothing downstream caught a thrown error) — see Pretty mode. - If
next()rejects — nothing downstream caught the error — logs one line aterror(JSON) or anERRline (pretty), with the error attached, then rethrows the same error unchanged. No completion line follows. levelgates both formats identically:'silent'prints nothing, and a level above what a given line would log at drops just that line.- Never short-circuits and never touches
ctx.responseitself — a route behaves exactly as it would with no logger registered.
Errors — none.
Example
import { Arcton } from '@arcton/core'
import { logger } from '@arcton/logger'
const app = Arcton()
app.use(logger({ level: 'debug', pretty: true }))
app.get('/users/:id', ctx => ({ id: ctx.params.id }))
app.get('/boom', () => {
throw new Error('kaboom')
})
app.listen()createLogger()
Purpose — builds a standalone Logger, independent of any request. logger() above builds one of these internally for its request-logging middleware, but it's just as usable for a background job or at startup.
Signature
function createLogger(options?: LoggerOptions): LoggerParameters
| Parameter | Type | Description |
|---|---|---|
options | LoggerOptions | Optional. See below for fields and defaults. |
Return type — a Logger.
Errors — none.
Example
import { createLogger } from '@arcton/logger'
const log = createLogger({ level: 'debug' })
log.info('server starting', { pid: process.pid })
const dbLog = log.child({ component: 'database' })
dbLog.info('query executed', { table: 'users' })Logger
Purpose — the interface every logging method (trace through fatal) and child() share, returned by both createLogger() and as .logger on an ArctonLogger.
Signature
interface Logger {
trace(msg: string, data?: Record<string, unknown>): void
debug(msg: string, data?: Record<string, unknown>): void
info(msg: string, data?: Record<string, unknown>): void
warn(msg: string, data?: Record<string, unknown>): void
error(msg: string, data?: Record<string, unknown>): void
fatal(msg: string, data?: Record<string, unknown>): void
child(bindings: Record<string, unknown>): Logger
}Parameters
Prop
Type
Behavior: a call below the configured level returns immediately — no record is built, no Date/serialization cost is paid. data on a given call overrides a bindings field of the same name for that one record only. A value under err (or any key) that's an Error serializes to { name, message, stack }, since JSON.stringify alone reduces a plain Error to {}. child(bindings) returns a new Logger with bindings merged into its own — recursively, so a grandchild carries everything its ancestors bound — without mutating the logger it was called on.
Example
import { createLogger } from '@arcton/logger'
const log = createLogger()
log.warn('cache miss', { key: 'user:42' })
const requestLog = log.child({ requestId: 'req_1' })
requestLog.info('handled') // includes requestId: 'req_1'LoggerOptions
Purpose — the options object accepted by both logger() and createLogger().
Signature
import type { LevelWithSilent } from '@arcton/logger'
interface LoggerOptions {
level?: LevelWithSilent
pretty?: boolean
sink?: (line: string) => void
bindings?: Record<string, unknown>
}Fields
| Field | Type | Default | Description |
|---|---|---|---|
level | LevelWithSilent | 'info' | Minimum level to log. Anything below it is dropped before a record is even built. |
pretty | boolean | false | Formats for a human instead of newline-delimited JSON. |
sink | (line: string) => void | writes to process.stdout where it exists, console.log otherwise | Where each formatted line is written. |
bindings | Record<string, unknown> | {} | Fields merged into every record — what child() adds to, not a replacement for it. |
Behavior: the default sink is resolved once, when @arcton/logger loads — process.stdout.write on Node/Bun, console.log anywhere process doesn't exist (a Worker). Pass your own to redirect output — to a file, a test capture, another service — without changing anything else.
LogLevel and LevelWithSilent
Purpose — the level names a Logger accepts, and the wider set LoggerOptions.level accepts.
Signature
type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
type LevelWithSilent = LogLevel | 'silent'Behavior: ranked in the order listed, trace lowest — a call is written when its own level's rank is at or above the configured minimum's. 'silent' outranks every real level, so nothing at all passes it.
ArctonLogger
Purpose — what logger() returns.
Signature
type ArctonLogger = Middleware & {
readonly logger: Logger
}Behavior — a plain Middleware function, so app.use(logger()) works exactly like app.use(cors()). .logger is the same Logger instance the middleware logs through, for logging anything outside the request/response cycle:
import { Arcton } from '@arcton/core'
import { logger } from '@arcton/logger'
const app = Arcton()
const log = logger()
app.use(log)
app.get('/', () => 'ok')
const server = app.listen({ port: 0 })
log.logger.info(`listening on ${server.url}`)