Documentation menuAPI
API
Functions and types of @sweberdev/logarithm.
createAuditLog<Actions>(options)
| Option | Type | Meaning |
|---|---|---|
store | AuditStore | Where events are stored |
redact | string[] | Field names stored as [redacted]. Default DEFAULT_REDACT |
ignore | string[] | Dot paths left out of computed diffs |
defaults | AuditDefaults | Tenant, actor, context and metadata for every event |
now | () => Date | Clock, for tests |
Returns an AuditLog:
| Method | Returns |
|---|---|
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 }]
groupBy | key | Order |
|---|---|---|
"day" | UTC day, YYYY-MM-DD | Oldest first; days without events are left out |
"action" | Action name | Most frequent first, then by name |
"actor" | Actor id | Most 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
| Field | Meaning |
|---|---|
tenantId | Tenant, or null for events without one |
actorId | Exact actor id |
action | Exact action or prefix.*; an array means OR |
targetId, targetType | Event has a target with this id or type |
from, to | Time range, from inclusive, to exclusive |
search | Case-insensitive text in action, actor and targets |
outcome | success, failure or denied; events from before 2.0 count as success |
correlationId | Events with this correlation id |
limit | 1 to 500, default 50 |
cursor | nextCursor 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
| Function | Meaning |
|---|---|
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_REDACT | Blank 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
AuditStoreinterface 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_VERSIONwith a migration, never a silent edit. - The CSS custom properties on
.lg-root(--lg-*) and thedata-themeattribute.
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
| Import | Exports |
|---|---|
@sweberdev/logarithm/postgres | postgresStore, migratePostgres, postgresSchema, postgresSchemaVersion, postgresUpgradeSchema, ensurePartitions, listPartitions, detachPartitions |
@sweberdev/logarithm/sqlite | sqliteStore, migrateSqlite, sqliteSchema, sqliteSchemaVersion, sqliteUpgradeSchema |
@sweberdev/logarithm/mysql | mysqlStore, migrateMysql, mysqlSchema, mysqlSchemaVersion, mysqlUpgradeSchema (MySQL 8+, MariaDB 10.6+) |
@sweberdev/logarithm/testing | storeConformanceChecks, runStoreConformance, ConformanceError for your own stores |