---
title: API Reference
description: Complete API reference for Logixlysia
---

## Functions

### `logixlysia`

Main plugin function that adds logging capabilities to your Elysia application.

```ts
function logixlysia(options?: Options): Logixlysia
```

**Parameters:**

- `options` (optional): Configuration options for Logixlysia

**Returns:**

- `Logixlysia`: Elysia instance with logging capabilities

**Example:**

```ts
import logixlysia from 'logixlysia'

const app = new Elysia()
  .use(logixlysia({
    config: {
      showStartupMessage: true
    }
  }))
```

## Types

### `Logixlysia`

Elysia instance type with Logixlysia store.

```ts
import type { LogixlysiaSingleton } from 'logixlysia'

type Logixlysia = Elysia<'', LogixlysiaSingleton>
```

The plugin uses an explicit `LogixlysiaSingleton`: a closed `store` plus empty `decorator` / `derive` / `resolve` slots that avoid both `SingletonBase`’s wide `Record<string, unknown>` and `Record<string, never>` (the latter would intersect Elysia’s `Context` keys with `never`). That keeps `Context` and WebSocket `ws.data` precise after `.use(logixlysia())`.

### `Options`

Configuration options for Logixlysia.

```ts
type Options = {
  config?: {
    showStartupMessage?: boolean
    startupMessageFormat?: 'simple' | 'banner'
    useColors?: boolean
    ip?: boolean
    autoRedact?: boolean
    timestamp?: {
      translateTime?: string
    }
    customLogFormat?: string
    service?: string
    slowThreshold?: number
    verySlowThreshold?: number
    showContextTree?: boolean
    contextDepth?: number
    logQueryParams?: boolean
    transports?: Transport[]
    useTransportsOnly?: boolean
    disableInternalLogger?: boolean
    disableFileLogging?: boolean
    logFilePath?: string
    logRotation?: LogRotationConfig
    pino?: PinoLoggerOptions & { prettyPrint?: boolean | object }
  }
}
```

### `LogixlysiaStore`

Store type available in Elysia context.

```ts
type LogixlysiaStore = {
  logger: Logger
  pino: Pino
  beforeTime?: bigint
}
```

**Properties:**

- `logger`: Logger instance with helper methods
- `pino`: Direct Pino logger instance
- `beforeTime`: Request start time (bigint)

Keep `LogixlysiaStore` a closed object type (no index signature). That helps merged handler and WebSocket types stay accurate.

### `Logger`

Logger interface with logging methods.

```ts
type Logger = {
  pino: Pino
  log: (
    level: LogLevel,
    request: RequestInfo,
    data: Record<string, unknown>,
    store: StoreData
  ) => void
  handleHttpError: (
    request: RequestInfo,
    error: unknown,
    store: StoreData
  ) => void
  debug: (
    request: RequestInfo,
    message: string,
    context?: Record<string, unknown>
  ) => void
  info: (
    request: RequestInfo,
    message: string,
    context?: Record<string, unknown>
  ) => void
  warn: (
    request: RequestInfo,
    message: string,
    context?: Record<string, unknown>
  ) => void
  error: (
    request: RequestInfo,
    message: string,
    context?: Record<string, unknown>
  ) => void
}
```

### `LogLevel`

Log level type.

```ts
type LogLevel = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR'
```

### `Transport`

Custom transport interface.

```ts
type Transport = {
  log: (
    level: LogLevel,
    message: string,
    meta?: Record<string, unknown>
  ) => void | Promise<void>
}
```

### `LogRotationConfig`

Log rotation configuration.

```ts
type LogRotationConfig = {
  maxSize?: string | number
  maxFiles?: number | string
  interval?: string
  compress?: boolean
  compression?: 'gzip'
}
```

### `Pino`

Pino logger type.

```ts
type Pino = PinoLogger<never, boolean>
```

### `LogixlysiaContext`

Context type for request handlers.

```ts
type LogixlysiaContext = {
  request: Request
  store: LogixlysiaStore
}
```

## Classes

### `HttpError`

An HTTP error carrying the context that makes a failure actionable.

```ts
class HttpError extends Error {
  readonly code?: string
  readonly fix?: string
  readonly internal?: unknown
  readonly link?: string
  readonly status: number
  readonly why?: string

  constructor(status: number, message: string, init?: HttpErrorInit)

  toJSON(): HttpErrorPayload
}

interface HttpErrorInit {
  code?: string
  fix?: string
  internal?: unknown
  link?: string
  why?: string
}
```

**Properties:**

- `status` — HTTP status code
- `code` — stable machine-readable identifier the client can branch on, e.g. `PAYMENT_DECLINED`. Unlike `message`, it is safe to depend on: rewording the message does not break a caller
- `why` — why the request failed, in plain language
- `fix` — what the caller should do about it
- `link` — documentation URL for this failure
- `internal` — **log-only** diagnostics. Non-enumerable and excluded from `toJSON()`, so no serializer can put it in a response body

**Example:**

```ts
throw new HttpError(402, 'Card declined', {
  code: 'PAYMENT_DECLINED',
  why: 'The issuing bank rejected the charge.',
  fix: 'Try a different card, or contact your bank.',
  link: 'https://docs.example.com/errors/payment-declined',
  internal: { gatewayCode: 'do_not_honor', chargeId }
})
```

Response body:

```json
{
  "code": "PAYMENT_DECLINED",
  "fix": "Try a different card, or contact your bank.",
  "link": "https://docs.example.com/errors/payment-declined",
  "message": "Card declined",
  "status": 402,
  "why": "The issuing bank rejected the charge."
}
```

The log line carries the same fields **plus** `internal`, rendered in the context tree as `error.code`, `error.why`, `error.fix`, `error.link`, and `error.internal`.

An error with no client-facing fields keeps its previous behaviour exactly — `throw new HttpError(404, 'User not found')` still responds with the bare message, not JSON. Only an error carrying at least one of `code`, `why`, `fix`, or `link` responds as JSON.

## Usage Examples

### Accessing Logger in Route Handlers

```ts
app.get('/users/:id', ({ store, params, request }) => {
  const { logger, pino } = store
  
  // Use logger helper methods
  logger.info(request, 'User accessed', { userId: params.id })
  
  // Or use Pino directly
  pino.info({ userId: params.id }, 'User accessed')
  
  return { user: 'data' }
})
```

### Custom Logging

```ts
app.post('/users', ({ store, body, request }) => {
  const { logger } = store
  
  logger.debug(request, 'Creating user', { email: body.email })
  
  // ... create user logic
  
  logger.info(request, 'User created', { userId: newUser.id })
  
  return newUser
})
```