ArctonArcton
API Reference

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): ArctonLogger

Parameters

ParameterTypeDescription
optionsLoggerOptionsOptional. 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.method and the request URL's pathname (the query string is left out) before calling next().
  • With pretty: false (the default): once next() resolves, logs one JSON line with method, path, status (ctx.response.status, defaulting to 200), and durationMs — at error for a 5xx status, warn for 4xx, info otherwise.
  • With pretty: true: logs a → line as the request arrives, and a ← line once it's done (or an ERR line if nothing downstream caught a thrown error) — see Pretty mode.
  • If next() rejects — nothing downstream caught the error — logs one line at error (JSON) or an ERR line (pretty), with the error attached, then rethrows the same error unchanged. No completion line follows.
  • level gates 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.response itself — 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): Logger

Parameters

ParameterTypeDescription
optionsLoggerOptionsOptional. 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

FieldTypeDefaultDescription
levelLevelWithSilent'info'Minimum level to log. Anything below it is dropped before a record is even built.
prettybooleanfalseFormats for a human instead of newline-delimited JSON.
sink(line: string) => voidwrites to process.stdout where it exists, console.log otherwiseWhere each formatted line is written.
bindingsRecord<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}`)

On this page