Serve Runtime Reference

Use serve(config) to turn query definitions into an exported runtime surface.

export const api = serve({
  queries: { activeUsers, weeklyRevenue },
  basePath: '/api/analytics',
});

serve(config)

serve() collects query definitions into one API object that can be executed locally, routed over HTTP, or mounted in frameworks.

Returned api

The exported api object is the main runtime surface.

It also exposes:

• queries
• basePath
• queryLogger
• _routeConfig

api.queries includes auto-generated semantic endpoints: a metric is keyed by its name, and a dataset is keyed as dataset:<name>. Those same keys are used by api.run(...), e.g. api.run('revenue') or api.run('dataset:orders').

api.route(path, endpoint, options?)

Registers an HTTP route for an existing query.

api.route('/active-users', api.queries.activeUsers, {
  method: 'POST',
});

api.run(name, options?)

Runs a query in-process through the exported API.

const rows = await api.run('activeUsers', {
  input: { limit: 25 },
});

Execution options support:

• input
• context
• request

api.execute(name, options?)

Alias for api.run(...).

api.client(name, options?)

Alias for in-process execution, useful when you want a client-like surface inside server code.

api.handler

Framework-compatible request handler surface used by adapters such as createFetchHandler.

import { createFetchHandler } from '@hypequery/serve';

const handler = createFetchHandler(api.handler);

api.start(options?)

Starts a dedicated server directly from the exported API.

const server = await api.start({ port: 4000 });

start() accepts options such as:

• port
• hostname
• signal
• quiet
• requestTimeout
• bodyLimit
• gracefulShutdownTimeout

api.use(middleware)

Pushes a global middleware onto the runtime.

api.useAuth(strategy)

Appends an auth strategy to the runtime.

api.describe()

Returns a runtime description object for docs/client tooling. describe().queries lists every endpoint, including semantic ones (keyed by metric name or dataset:<name>).

api.manifest()

Returns a serializable RouteManifest mapping every query/metric/dataset key to its HTTP method and full path. Pass it to @hypequery/react's createHooks/createAnalyticsHooks as manifest so the client can resolve routes. Every route's path differs from its map key (named queries live under queries/, datasets under datasets/<name>/query), so the hooks need it.

api.manifest() runs on the server. For browser code, write it to JSON with hypequery generate:manifest <api-file> and import the file.

const manifest = api.manifest();
// { weeklyRevenue: { method: 'GET', path: '/api/analytics/queries/weeklyRevenue' },
//   revenue: { method: 'POST', path: '/api/analytics/metrics/revenue' },
//   'dataset:orders': { method: 'POST', path: '/api/analytics/datasets/orders/query' }, ... }

api.queries

api.queries exposes the routed query definitions by name so they can be reused in api.route(...).

api.route('/weekly-revenue', api.queries.weeklyRevenue, {
  method: 'POST',
});

Delivery Modes

The same api can be used in three ways:

• api.run(...) for in-process execution
• api.handler for framework mounting
• api.start(...) for a dedicated server

See Also

• Query Definition Reference
• Core Concepts
• Type Helpers