Query Definition Reference

Object-style query({ ... }) is the recommended API. Builder-style chaining remains supported for backwards compatibility and is documented below where relevant.

Use initServe() to create the current query/runtime API:

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

const { procedure, query, queries, serve, define } = initServe({
  context: () => ({ db }),
  basePath: '/api/analytics',
});

`initServe(options)`

initServe() binds shared runtime configuration once and returns helpers for defining queries and exporting an API.

Prop

Type

Returned Initializer

initServe() returns:

procedure - builder-style query procedure factory
query - object-style query factory plus builder helpers
queries(definitions) - identity helper for typed query maps
serve(config) - bound serve factory with shared context/config
define(config) - alias of serve(config)

`query({ ... })`

query({ ... }) turns one builder chain into an executable, reusable definition.

const activeUsers = query({
  description: 'Most recent active users',
  requiredRoles: ['admin', 'editor'],
  input: z.object({
    limit: z.number().min(1).max(100).default(10),
  }),
  output: z.array(z.object({
    id: z.string(),
    email: z.string(),
  })),
  query: ({ ctx, input }) =>
    ctx.db
      .table('users')
      .select(['id', 'email'])
      .where('status', 'eq', 'active')
      .limit(input.limit)
      .execute(),
});

Query Options

Prop

Type

Returned Query Object

A query definition can be executed locally before you ever add HTTP:

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

The returned query object is designed to be:

executable locally via execute(...)
reusable inside serve(...)
inferable for client types

Auth and tenant metadata become active when the query is used through the serve runtime, for example via serve({ queries }), api.run(...), api.execute(...), or routed HTTP handlers. Standalone query.execute(...) does not run the auth/tenant pipeline.

It exposes:

query - the resolver
run - resolver alias
execute(options?) - local execution
inputSchema / outputSchema - normalized schema metadata
metadata such as method, name, description, summary, tags, auth, requiresAuth, requiredRoles, requiredScopes, tenant, cacheTtlMs, custom

Builder-style Query Procedures

The same query export also supports chained builder-style metadata through procedure methods:

const legacyStyle = query
  .input(z.object({ limit: z.number() }))
  .output(z.array(z.object({ id: z.string() })))
  .describe('Users')
  .query(({ ctx, input }) => {
    return ctx.db.table('users').limit(input.limit).execute();
  });

Available chain helpers include:

input(...)
output(...)
describe(...)
name(...)
summary(...)
tag(...) / tags(...)
method(...)
cache(...)
auth(...)
requireAuth()
requireRole(...)
requireScope(...)
public()
tenant(...)
tenantOptional(...)
require()
custom(...)
use(...)

These are still part of the actual exported API, even though the default docs path prefers object-style query({ ... }).

Query Definition