Cube.js Client Core

@cubejs-client/core is the framework-agnostic JavaScript/TypeScript client for Cube, the open-source semantic layer. It handles everything needed to talk to a Cube API Gateway: building and validating query objects, sending them over HTTP or WebSockets via a pluggable transport layer, and turning the raw response into a ResultSet that’s easy to pivot into tables or chart-ready series.

Because it has zero UI dependencies, it’s the foundation every Cube integration builds on — the official React, Vue, and Angular bindings, as well as any custom dashboard or embedded-analytics surface, wrap this package rather than reimplement query execution, formatting, or streaming.

What You Get

• Typed query builder - Query, Filter, and TimeDimension types with compile-time member inference so invalid measures, dimensions, or filters are caught before a request is sent.
• Pluggable transport layer - HttpTransport ships by default, but the ITransport interface lets you swap in a WebSocket or custom subscription-based transport for real-time updates.
• ResultSet with chart/table pivots - chartPivot(), tablePivot(), and seriesNames() reshape raw Cube responses into series and rows most charting and table libraries can consume directly.
• d3-based value formatting - built-in numeric and time formatters (via d3-format/d3-time-format) for percentages, currency, and custom-numeric/custom-time formats defined in the Cube data model.
• Streaming response support - responseChunks() consumes streamed HTTP responses as an async iterable for progressively rendering large result sets.

Common Use Cases

• Building custom embedded-analytics dashboards - a SaaS product embeds Cube-powered charts in its own UI by querying @cubejs-client/core directly instead of building a framework-specific wrapper from scratch.
• Powering framework-specific Cube bindings - the official @cubejs-client/react, @cubejs-client/vue, and @cubejs-client/ngx packages all wrap this core package’s ResultSet and query API.
• Real-time dashboard updates via subscribe - dashboards use the subscribe: true load option with a WebSocket transport to get live-updating query results without polling.
• Server-side or Node.js Cube queries - background jobs and reporting scripts import the core client directly to fetch aggregated data on a schedule.

Under The Hood

Architecture The package centers on three cooperating layers: a typed query surface (types.ts, SqlQuery.ts) that models Cube’s query DSL with TypeScript member-inference so measures, dimensions, and time-dimensions are checked at compile time; a transport abstraction (HttpTransport.ts implementing the ITransport interface) that the top-level CubeApi class in index.ts delegates all network I/O to, so swapping in a WebSocket or custom subscription transport requires no change to query-building code; and a result-processing layer (ResultSet.ts, Meta.ts, utils.ts) that turns a raw LoadResponse into pivoted chart/table structures via ramda-based grouping and pipe compositions. CubeApi itself is a fairly dense single class that owns mutex-keyed request deduplication, AbortSignal-based cancellation, and dry-run/meta endpoints, so most day-to-day changes to query lifecycle behavior funnel through that one file.

Tech Stack Built in TypeScript targeting both browser and Node.js (isomorphic), the package compiles via tsc into CJS, ESM, and UMD bundles declared through a modern exports map, with a separate /format subpath export. Runtime dependencies are deliberately small: ramda for functional data transforms, dayjs for date handling, d3-format/d3-time-format for locale-aware numeric and time formatting, uuid for request IDs, and a url-search-params-polyfill plus core-js for older-runtime compatibility. Tests run on Vitest with built-in coverage reporting, and linting extends a shared linter config used across the monorepo’s other packages.

Code Quality Test coverage is extensive for a client library: numerous test files exercise ResultSet pivoting, compare-date-range and data-blending query types, granularity handling, drill-downs, SQL query generation, HTTP transport, and even dayjs timezone isolation, plus a dedicated ResultSet benchmark file. The monorepo runs a CI build workflow across the whole codebase, and this package’s own scripts wire lint/lint:fix through the shared linter and unit/bench through Vitest. Naming and typing are consistent — public types like Query, PivotConfig, and LoadResponse are centralized in types.ts and re-exported, and deprecated APIs are explicitly marked with @deprecated JSDoc rather than silently left in place.

API Design The public API favors a small number of high-leverage entry points — cubeApi() to construct a client, .load()/.subscribe() to run queries, and ResultSet.chartPivot()/.tablePivot() to reshape results — so most integrations touch only a handful of methods despite the client owning meta introspection, streaming, and cancellation internally. TypeScript’s member-inference types let a query’s measures and dimensions type-check the shape of returned rows without manual generics, which is a genuinely nice ergonomic touch for a client library. Documentation leans on inline JSDoc plus the external docs.cube.dev site rather than package-local guides, so newcomers are expected to pair the API with Cube’s hosted documentation rather than working from the README alone.