Networked access

Code generation

Generate typed operation references and a registry digest from the same definitions that the server serves.

sirannon-codegen imports an operation registry and writes TypeScript references for its reads and writes. The generator needs the registry module, not a listening database server.

Keep registry definitions in a module without startup side effects, such as the complete operations.ts from registered operations. The server and generator can then import the same definitions.

Run the generator

The database package installs the executable. Execute it in a workspace that depends on @delali/sirannon-db.

pnpm exec sirannon-codegen --registry ./src/operations.ts --out ./src/generated/operations.ts
FlagRequirementBehaviour
--registryRequired.The generator imports this module.
--outRequired.The generator writes TypeScript here and creates missing parent directories.
--manifestOptional.The generator also writes its manifest as JSON.
--exportOptional.The generator reads this export in place of operations or the default export.
--shared-exportOptional.The generator reads this export in place of sharedOperations.
--packageOptional.The generated type import uses this package identifier.

Flags require values. Missing required flags, unknown flags, failed module imports, and missing requested exports stop generation with an error.

The execution environment must support the registry's source format. Node 24 can load erasable TypeScript, while syntax requiring a transform needs a loader. If the workspace already uses tsx, it can execute the CLI through that loader.

pnpm exec tsx node_modules/@delali/sirannon-db/dist/codegen/cli.mjs --registry ./src/operations.ts --out ./src/generated/operations.ts

What it emits

The published 0.4.0 generator produces this complete file from the owner-scoped registry in registered operations.

src/generated/operations.ts
import type { OperationRef } from '@delali/sirannon-db'
 
export const registryDigest = "8848da8cd5d9537501dbf824f7bdaf25a64c3fec419376367088c832787c529d"
 
export interface OrdersMyOrdersRow {
  id: unknown
  total: unknown
  status: unknown
}
 
export interface OrdersOrdersByStatusRow {
  id: unknown
  total: unknown
  status: unknown
}
 
export const orders = {
  reads: {
    myOrders: { name: "myOrders" } as OperationRef<Record<string, never>, OrdersMyOrdersRow>,
    ordersByStatus: { name: "ordersByStatus" } as OperationRef<{ status: unknown }, OrdersOrdersByStatusRow>,
  },
  writes: {
    placeOrder: { name: "placeOrder" } as OperationRef<{ total: unknown }, never>,
  },
}

Each database gets a constant with reads and writes. A read with declared columns gets a row interface. Without a column declaration, the generator can infer column identifiers only from an argument-free statement that it can inspect.

Generated argument and column values use unknown, because registry declarations describe identifiers without a runtime value schema. Narrow those values before using them in the application.

An operation whose arguments all come from identity accepts Record<string, never> from the caller. Pass an empty object for that call.

The generator escapes reserved TypeScript binding identifiers and rejects collisions when different definitions would produce the same declaration. Rename a conflicting database or operation before generating again.

A module containing only a sharedOperations export also works. Generate from the complete shared module in shared operations.

pnpm exec sirannon-codegen --registry ./src/shared-operations.ts --out ./src/generated/shared-operations.ts
src/generated/shared-operations.ts
import type { OperationRef } from '@delali/sirannon-db'
 
export const registryDigest = "e32a04e09391bbb508f4be0cecbfc12bb90196fdfb5cc4717e1e712a29d8a129"
 
export interface SharedOpenInvoicesRow {
  id: unknown
  total: unknown
}
 
export const sharedOperations = {
  reads: {
    openInvoices: { name: "openInvoices" } as OperationRef<Record<string, never>, SharedOpenInvoicesRow>,
  },
  writes: {
    raiseInvoice: { name: "raiseInvoice" } as OperationRef<{ total: unknown }, never>,
  },
}

Shared constants use sharedOperations, and their row interfaces use the Shared prefix.

Call through the generated file

With the registered-operations server listening, execute the complete src/client.ts file below using the same SIRANNON_TOKEN. Generate the references above before executing it.

src/client.ts
import { SirannonClient } from '@delali/sirannon-db/client'
import { orders } from './generated/operations.ts'
 
const token = process.env.SIRANNON_TOKEN
if (!token) throw new Error('Set SIRANNON_TOKEN to the application credential')
 
const client = new SirannonClient('http://127.0.0.1:9876', {
  transport: 'http',
  headers: { Authorization: `Bearer ${token}` },
})
 
try {
  const db = client.database('orders')
  console.log(await db.query(orders.reads.ordersByStatus, { status: 'pending' }))
  console.log(await db.query(orders.reads.myOrders, {}))
  await db.execute(orders.writes.placeOrder, { total: 4999 })
} finally {
  client.close()
}

Regeneration removes a renamed operation's earlier property, so TypeScript can report call sites using that property. Generated references provide compile-time argument identifiers; the server continues to enforce the runtime operation contract.

registryDigest describes the registry at generation time. An application can compare it with registry.digest from GET /capabilities when it needs to check its generated contract against a deployed server.

A remote live query obtains its subscription digest from the client's cached capability report. The generated OperationRef contains the operation identifier; it does not automatically attach the generated file's digest. Live queries explains the capability refresh after a mismatch.

Catch a stale generated file in CI

Regenerate during validation and compare the generated file with the checked-in version.

pnpm exec sirannon-codegen --registry ./src/operations.ts --out ./src/generated/operations.ts
git diff --exit-code src/generated/operations.ts

A changed file indicates that the generated contract differs from the registry. Include generation in the application's validation so that operation renames and argument changes reach its typed call sites before deployment.

The public code-generation entry also exports buildOperationManifest, renderOperationTypes, and selectColumns for tooling that needs the same manifest and source generation without the CLI.