Skip to main content

TypeScript Runtime Guide

For AI-assisted development, use the generated Assist contracts with the TeaQL Agent Kit Harness Engineering workflow.

See Latest Versions for the generator-selected runtime and separately published npm release. Generated list terminals return Promise<SmartList<Entity>>; the former untyped result envelope and separate entity-list terminal are no longer the public boundary.

TeaQL TypeScript supports two deliberately separate profiles:

  • Node SQL runtime for PostgreSQL, MySQL and SQLite;
  • browser-safe generated domain client for TeaQL Federal Protocol calls.

The root/browser profile does not load Node database drivers. SQL providers are explicit subpath imports so client bundles do not accidentally acquire server-only dependencies.

Start here​

Use this sequence for a TypeScript project:

  1. TypeScript Quick Start — prepare Node SQL generation, trusted context, first query and audited save while preserving the browser boundary.
  2. TypeScript First Verification — prove a real SQLite round trip, browser-safe bundling, governance and federation semantics.
  3. TypeScript Business Scenarios — use relations, aggregates, mutations and the TeaQL Federal Protocol.
  4. TypeScript Customization — add policy, validators, audit sinks, explicit provider exports and federal adapters.
  5. TypeScript Debugging and Observability — capture safe SQL evidence and verify Query, Facet, Mutation, telemetry, audit, and server-enforced tenant boundaries.

The runtime is published as @teaql/teaql. Use the generated package manifest for its pinned version and provider subpaths.

Connect an AI SDK agent to application data​

For a Vercel AI SDK application, read the database-tool integration guide. It covers typed capability definitions, server-owned context, approval versus authorization, safe results and a deterministic SQLite adapter demonstration. The adapter example and this runtime's generated Order examples have separate version and verification scopes; keep their published/workspace qualifications.

Evidence boundary​

Use Latest Versions for release discovery and Cross-language Conformance Status for the committed capability/evidence snapshot. The provider and federation results below are dated verification evidence, not a support-lifetime promise; consult the Verification Evidence archive for the distinction between current pointers and historical campaigns.

Generated execution​

Generated Requests receive a single UserContext. The context supplies trusted identity, policy and runtime resources; dynamic client JSON cannot replace them.

const orders = await Q.customerOrders()
.comment("Find orders awaiting review")
.purpose("Prepare the authorized review queue")
.executeForList(context);

Both comment and purpose must be non-empty before execution, in either order and without an adjacency requirement. Use Assist for the generated executable type. Mutations require auditAs(...) before save. The runtime emits both an immutable mutation audit event and an independently attributable, metadata-masked application event.

Verified providers​

DatabaseNode driver observed in acceptanceFeature status
PostgreSQLpg 8.23.0PASS
MySQLmysql2 3.23.3PASS
SQLitebetter-sqlite3 11.7.0PASS

TypeScript to Rust federation​

The generated TypeScript domain client was also verified through the real TeaQL Federal Protocol /query path into a Rust backend using PostgreSQL. Direct Rust and federated canonical results matched. Attempts to override tenant, merchant, user, permissions, request policy, purpose policy or trusted context were rejected by the server.

This is protocol federation, not a generic HTTP feature wrapper. Keep server-owned context assembly on the Rust side and treat the client purpose as requested intent rather than approved policy.

Learn through an Order​

Follow the Order tutorial to download a complete source package, install locked public npm dependencies with Node 22.23.4, and perform the first SQLite read and audited quantity/total edit. The package uses published @teaql/teaql 0.3.1 under its retained teaql-ts alias; no retained workspace or generator account is required for this fixed example. Use the Order API usage guide for result shapes and the native troubleshooting table for recovery. The coverage matrix tracks the remaining language packaging gaps. Later deletion/pagination/advanced Order runtime RELEASE PENDING and generator-deployment qualifications remain.