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.

Release status: official npm package names, versions, exports, and the public TypeScript generator targets have not been announced. Do not guess them. Release notes must specify the Node runtime, browser client, provider subpaths, supported Node range, and generation targets before the installation block is filled.

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

After publication, install the exact official packages and generate with the target returned by the live catalog. Commit the resulting lock file.

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 ctx = new UserContext();
  // Register generated metadata and the SQLite Node provider.
  // Inject trusted identity, policy and audit resources here.
  return ctx;
}

Use exact constructors and export paths from the published package. Execution accepts only ctx; 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(ctx);

comment() may occur earlier and need not immediately precede purpose(). purpose() returns the executable type that exposes terminals.

6. Save with audit intent​

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

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

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.