Skip to main content
Introducing packages.sweber.dev
Documentation menuAPI

API

Functions and types of @sweberdev/logarithm.

createAuditLog<Actions>(options)

OptionTypeMeaning
storeAuditStoreWhere events are stored
redactstring[]Field names stored as [redacted]. Default DEFAULT_REDACT
ignorestring[]Dot paths left out of computed diffs
defaultsAuditDefaultsTenant, actor, context and metadata for every event
now() => DateClock, for tests

Returns an AuditLog:

MethodReturns
record(input)Promise<AuditEvent>
recordMany(inputs)Promise<AuditEvent[]>, one write
query(query?)Promise<AuditPage>, newest first
count(query?)Promise<number>, the number of matching events
count({ ...query, groupBy })Promise<AuditGroupCount[]>, counts per day, action or actor
get(id)Promise<AuditEvent | null>
with(defaults)A scoped AuditLog

Invalid input throws AuditValidationError; invalid queries throw AuditQueryError.

Actions is an optional action catalog. Without it, any action name and any metadata are accepted, as before.

count(query)

Takes the same filters as query (tenantId, actorId, action, targetId, targetType, from, to, search), without limit and cursor. A log scoped with with({ tenantId }) counts only that tenant.

await audit.count({ tenantId: org.id, action: "member.*", from: "2026-10-01" }) // 42

await audit.count({ tenantId: org.id, groupBy: "day" })
// [{ key: "2026-10-01", count: 12 }, { key: "2026-10-02", count: 30 }]
groupBykeyOrder
"day"UTC day, YYYY-MM-DDOldest first; days without events are left out
"action"Action nameMost frequent first, then by name
"actor"Actor idMost frequent first, then by id

The built-in stores count in the database. A custom store without count still works: the log pages through query instead.

AuditQuery

FieldMeaning
tenantIdTenant, or null for events without one
actorIdExact actor id
actionExact action or prefix.*; an array means OR
targetId, targetTypeEvent has a target with this id or type
from, toTime range, from inclusive, to exclusive
searchCase-insensitive text in action, actor and targets
outcomesuccess, failure or denied; events from before 2.0 count as success
correlationIdEvents with this correlation id
limit1 to 500, default 50
cursornextCursor of the previous page

AuditEvent

interface AuditEvent {
  id: string                 // ULID
  occurredAt: string         // ISO 8601, UTC
  tenantId: string | null
  action: string
  actor: { id: string; type?: string; name?: string; email?: string }
  targets: { id: string; type: string; name?: string }[]
  changes: { field: string; before?: unknown; after?: unknown }[]
  context: { ip?: string; userAgent?: string; requestId?: string; location?: string }
  metadata: Record<string, unknown>
  outcome?: "success" | "failure" | "denied"   // always set since 2.0
  correlationId?: string
}

Helpers

FunctionMeaning
contextFromRequest(request, { trustProxy })IP, browser, request id and location from a Request or Headers
diff(before, after, options?)Field changes with redaction
describeAction(event, { locale, nouns })Short sentence such as updated project "Website"
memoryStore()In-memory store for tests and demos
ulid()Time-sortable id
redactChanges(changes, redact?), REDACTED, DEFAULT_REDACTBlank out sensitive fields in changes you built yourself; the marker is [redacted]
searchText(event)The text search matches against, for custom stores that index it
parseQueryParams(searchParams)Turns URL parameters into an AuditQuery, as createAuditHandler does
toCloudEvent(event, options?), fromCloudEvent(ce)CloudEvents 1.0 envelope and back, see Export formats
toOtelLogRecord(event), toOtlpLogs(events, options?)OpenTelemetry log record and the POST /v1/logs body
labelsFor(locale) (@sweberdev/logarithm-react)The built-in labels for a locale (en, de, fr, it), to extend them

Stability

The API is frozen from 0.8 and follows semantic versioning from 1.0: no breaking change without a new major version, deprecations announced one minor version ahead with @deprecated. Version 2.0 is the first major version; what it changed is listed in Migrating to 2.0. The 1.x line gets security and bug fixes for 12 months after the release of 2.0.0.

What the promise covers:

  • Everything on this page, the AuditStore interface and the types it uses, the parameters and responses of the HTTP endpoint, and the props of <AuditLog> and <ActivityFeed>.
  • The table layout, through the schema version: a change to it is a new SCHEMA_VERSION with a migration, never a silent edit.
  • The CSS custom properties on .lg-root (--lg-*) and the data-theme attribute.

What it does not cover: the lg-* class names inside the viewer (style through the custom properties, or tell us what is missing), text of error messages, and the exact wording of the built-in labels. Helpers that are not on this page were removed from the public exports in 0.8 (DEFAULT_LIMIT, MAX_LIMIT, encodeCursor, decodeCursor, toStoreQuery, toStoreFilter, sortGroups and, in the React package, relativeTime); they were deprecated since 0.6.

Subpaths

ImportExports
@sweberdev/logarithm/postgrespostgresStore, migratePostgres, postgresSchema, postgresSchemaVersion, postgresUpgradeSchema, ensurePartitions, listPartitions, detachPartitions
@sweberdev/logarithm/sqlitesqliteStore, migrateSqlite, sqliteSchema, sqliteSchemaVersion, sqliteUpgradeSchema
@sweberdev/logarithm/mysqlmysqlStore, migrateMysql, mysqlSchema, mysqlSchemaVersion, mysqlUpgradeSchema (MySQL 8+, MariaDB 10.6+)
@sweberdev/logarithm/testingstoreConformanceChecks, runStoreConformance, ConformanceError for your own stores