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 Customization — add policy, validators, audit sinks, explicit provider exports and federal adapters.
4. TypeScript Business Scenarios — use relations, aggregates, mutations and the TeaQL Federal Protocol.

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

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);

Purpose transitions the Request to its executable state. Mutations require auditAs(...) before save. The runtime emits both an immutable mutation audit event and an independently attributable, metadata-masked application event.

Verified providers

Database	Node driver observed in acceptance	Feature status
PostgreSQL	pg 8.23.0	PASS
MySQL	mysql2 3.23.3	PASS
SQLite	better-sqlite3 11.7.0	PASS

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.