axiom-js

@axiomhq/js is the official JavaScript/TypeScript SDK for Axiom, the observability platform for logs, traces, and metrics. It exposes a typed client for ingesting events, running APL and MPL queries, and managing datasets, monitors, dashboards, annotations, saved queries, and users through Axiom’s REST API.

The package ships two client variants: Axiom, which batches and background-flushes ingested events every second or 1,000 events, and AxiomWithoutBatching, which sends each ingest call immediately. Both support routing ingest/query traffic through Axiom’s edge deployments for lower latency, automatic gzip compression via the native CompressionStream API, and a pluggable fetch implementation for proxying through custom dispatchers.

What You Get

• Batched or unbatched event ingestion with automatic background flushing
• Typed APL and MPL query methods with tabular and legacy result formats
• Service clients for datasets, monitors, dashboards, annotations, saved queries, and users
• Edge deployment routing for low-latency ingest and query
• Automatic gzip compression of ingest payloads when supported by the runtime

Common Use Cases

• Shipping structured application logs from a Node.js or edge service directly to Axiom
• Running ad-hoc APL queries against ingested datasets from a script or dashboard backend
• Building custom internal tooling on top of Axiom’s datasets, monitors, and saved queries APIs
• Powering higher-level integrations like the @axiomhq/winston and @axiomhq/pino log transports

Under The Hood

Architecture BaseClient extends an abstract HTTPClient (httpClient.ts), composing per-resource “service” namespaces (annotations, dashboards, datasets, monitors, savedQueries, users) each instantiated with the same ClientOptions and holding their own HTTPClient-derived instance; two concrete client subclasses (AxiomWithoutBatching, Axiom) layer ingest behavior on top of that shared base, with Axiom adding a Batch (batch.ts) per dataset+options key that queues events and flushes on a timer or size threshold via ingestRaw, using a serialized activeFlush promise chain to preserve ordering across overlapping flushes. URL construction (resolveIngestUrl/resolveAplQueryUrl/resolveMplQueryUrl in httpClient.ts) centralizes edge-vs-cloud endpoint resolution so ingestion and querying can be redirected to regional edge deployments independently of the main API’s base URL. HTTP transport is isolated in FetchClient (fetchClient.ts), which wraps fetch-retry, converts non-2xx responses into a typed AxiomRequestError, and reads rate-limit headers via limit.ts. This is a clean layered design (transport to typed client to composed services) with configuration flowing through a plain ClientOptions object rather than a DI container; because every service and both client classes depend directly on FetchClient for request execution, a breaking change there would ripple through all seven exported service namespaces.

Tech Stack TypeScript (roughly 98% of the codebase) targeting Node.js 20 or higher, published as dual ESM/CJS builds (separate rollup configs producing dist/esm and dist/cjs), with a single runtime dependency, fetch-retry, wrapping the native fetch API. The package lives in a pnpm/Turborepo monorepo alongside sibling packages (winston, pino, react, tanstack-start, nextjs, logging), sharing a base tsconfig and an internal ESLint config. Testing runs on vitest with @vitest/coverage-v8, and GitHub Actions CI builds, typechecks, lints, and tests across Node 20.x, 22.x, and 24.x on every push and pull request.

Code Quality Unit tests cover annotations, batching, browser behavior, the base client, per-service clients, dashboards, datasets, the fetch client, URL resolution, monitors, and saved/query users (thirteen test files total) using vitest with fake timers to assert precise batching and flush-timing behavior. Error handling is explicit and typed rather than swallowed: failed HTTP responses are converted into a custom AxiomRequestError carrying structured method/endpoint/status fields, and ingest failures are routed through a configurable onError callback instead of throwing unhandled. Naming is consistent camelCase with extensive JSDoc on nearly every public method and interface, and overloaded query()/aplQuery() signatures give precise return types keyed on the requested result format. CI enforces typecheck, lint, and test on every change.

API Design The public API favors a single class-based entry point (Axiom or AxiomWithoutBatching) that exposes ingest and query methods alongside nested service namespaces such as axiom.datasets and axiom.monitors, so most workflows need only one import. Getting started requires minimal boilerplate — constructing the client with a token and calling ingest() once — and the batching client’s separate ingest()/flush() methods cleanly split fire-and-forget writes from an explicit “wait for delivery” step, which is more deliberate than typical fire-and-forget logging SDKs. Edge routing is opt-in through a few named options (edge, edgeUrl, edgeDeployment) rather than a separate client construction path, and appendAxiomClient lets downstream packages like the Winston and Pino transports tag the X-Axiom-Client header without re-authenticating. Nearly every exported method carries JSDoc with runnable @example blocks, which is a genuine strength relative to typical SDK documentation.