Skip to main content

TypeScript Quick Start

TeaQL TypeScript has two profiles: a Node SQL runtime and a browser-safe generated federal client. This Quick Start uses Node and SQLite. Do not import Node database drivers through the browser profile.

Current runtime: @teaql/teaql@0.1.9, published on npm. The package exposes the browser-safe root plus explicit Node SQL provider subpaths.

1. Prepare the workspace​

teaql-typescript-quick-start/
├── model/main.xml
├── generated/domain/
├── src/main.ts
└── test/first-query.test.ts

Use Node 22 for the currently verified toolchain:

node --version
npm --version
cargo teaql services
cargo teaql evaluate --input model/main.xml

Install the runtime and generate with the exact target returned by the live catalog:

npm install @teaql/teaql@0.1.9
cargo teaql services

Commit the resulting lock file. Current generated Node workspaces use typescript-node-lib-core; query the catalog rather than hard-coding it in automation.

2. Create the model​

<?xml version="1.0" encoding="UTF-8"?>
<root name="order-review" org="example" data_service="sqlite" version="1.0.0">
  <customer_order
      order_number="WEB-10001"
      _module_key="root" />
</root>

Evaluate first and read Markdown diagnostics. Generate into generated/domain; do not hand-edit emitted TypeScript or compiled JavaScript.

3. Inspect and build​

find generated/domain -maxdepth 3 -type f | sort
sed -n '1,240p' generated/domain/package.json
rg 'purpose\(|executeForList|auditAs\(|save\(' generated/domain/src
npm ci
npm run build
npm test

The package manifest and exports map define the valid runtime/browser/provider entry points. Read generated Q and Request code for plurals and predicates; never append s/es, and preserve whoAre/whose for humans versus whichAre/with for non-human entities.

4. Build trusted context​

The Node data service, tenant, authenticated actor, permissions, policy and audit sinks are injected during context creation:

async function createRequestContext(
  infra: Infrastructure,
  trusted: AuthenticatedRequest,
): Promise<UserContext> {
  const context = new UserContext();
  // Register generated metadata and the SQLite Node provider.
  // Inject trusted identity, policy and audit resources here.
  return context;
}

Use exact constructors and export paths from the published package. Execution accepts only context; providers are not terminal arguments.

5. Execute the first query​

const orders = await Q.customerOrders()
  .comment("Find web orders")
  .withOrderNumberContaining("WEB-")
  .orderByIdAscending()
  .limit(20)
  .purpose("Display the authorized order list")
  .executeForList(context);

comment() may occur earlier and need not immediately precede purpose(). purpose() returns the executable type that exposes terminals. The result is SmartList<CustomerOrder>, so normal array operations remain available while totals, aggregations, summaries, facets, and loaded state have a stable home.

6. Save with audit intent​

const order = Q.customerOrders()
  .comment("Create the first verified order")
  .purpose("Persist an authorized order")
  .newEntity(context);

order.updateOrderNumber("WEB-10002");
order = await order.auditAs("Create the first verified order").save(context);

Inspect generated entities before using update names. Missing audit, intent, or context must fail closed.

7. Keep the browser profile separate​

A browser application imports only the generated federal client profile. It serializes TeaQL protocol requests to a trusted backend; it never receives SQL credentials or constructs server UserContext. Qualify federation separately from Node SQL.

Continue with TypeScript First Verification and TypeScript Customization.