source/teaql-ts/examples/browser-sqlite/README.md

Browser SQLite/WASM order playground

This executable example uses a familiar commerce domain—platform, customer, order, item, payment, and shipment—to demonstrate TeaQL queries entirely in a dedicated browser worker. It includes deterministic, internally consistent demo data and thirteen runnable examples organized as basic, aggregate, filtered, and dynamic queries.

This page executes the TeaQL TypeScript runtime and SQLite/WASM directly in the browser. The model-driven Q and TraceChain contract is also implemented by the Java, Rust, Go, Python, .NET and Swift runtimes. The seven-language strip links to each runtime source and marks TypeScript as the current browser runtime; it does not imply that selecting another link swaps the page's execution engine.

OrderStatus is a seventh, constant model object rather than a string field. Its five fixed values are reconciled through RuntimeModule bootstrap, orders store the status object ID, and generated Q expressions select, filter, and facet through the status relation. Visible status projections select name and color—not code—and the queried color drives the metric cards and status badges. Embedded relation Q expressions are displayed on one line so they align with the horizontal element they populate.

The interface defaults to English and can be switched to Chinese without re-running the active query. Tabular results use a table by default and remain available as an expandable Result Tree instead of a raw JSON text block. Dynamic examples pass user-shaped filters through TeaQL's validated field metadata and do not use eval.

The first example is a complete order management center. Its status metrics, search (including product-name subqueries), item previews, and pagination are all driven by one generated Q.customerOrders() expression. Application code uses the generated domain request API; the lower-level SelectQuery is confined to src/generated. Every example shows the exact Q expression used by the page and the parameterized SQL statements that SQLite executed, including timing, row counts, and policy-safe bindings. The execution evidence table prints the captured time, identity, intent, tracePath, and parameterized SQL on one row per statement. Each trace is plain text with arrows between its original path steps; no JSON metadata or decorative visualization is added, and no application tracing code is required.

The order list labels its fourth column Line Items. Two seeded orders contain five internally consistent line items; the query still loads only three bounded previews and uses the separately queried item count to display 5 items.

The order-center Q expression is stable across free-text search, status-card selection, and pagination. Those interactions only replace searchParams, pageOffset, and pageSize; generated dynamic-search bindings compile order number, OrderStatus.code, and item product-name paths without changing the page query.

The final page section retains an unmodified OpenObserve capture of the same Order-query lineage rendered as a business TraceChain. It connects the page purpose and nested request comments to the eight SQL executions captured by the observability backend; the screenshot is evidence, not a client-side reconstruction.

The order-center projection intentionally contains only the four visible table columns: order number, order date, the OrderStatus object, and item preview. It does not load Platform or Customer. The Q chain follows the page vertically: dynamic filter, countAs('totalOrders'), status facet, four table projections, then bounded offset / limit list execution.

npm install
npm run dev

Memory storage is the deterministic default. Refreshing recreates the data. The optional OPFS mode persists within the current browser origin. Reset drops the browser-local schema, explicitly runs context.ensureSchema() again, and re-seeds the six mutable entities through governed, audited mutations; the five OrderStatus constants are restored by runtime bootstrap.

The same application-approved mutation policy is used by both storage profiles. A denied plan is rejected before SQL is posted to the worker.

The previous WorkItem example remains independently available at /work-items.html. The Vite development server emits the COOP/COEP headers required by the SQLite OPFS implementation. A production host must emit the same headers. This first profile intentionally excludes multi-tab database coordination and true row streaming.

Generated order TraceChain page

Open /orders.html to run the shared request-tree Order model in the same browser SQLite/WASM provider. The WorkItem page remains available at /work-items.html, while / presents the full order management center. order-model.xml defines the model; orders-lib/ is generated by the local Model-Aware Services producer, not handwritten Q or entity code. Model-aware Assist outputs are retained under assist/.

The order page uses generated audited mutation APIs to create four orders and five items per order. Generated bootstrap provisions the platform and three status constants. The example search matches three orders and loads the second one: KEEP-002, Paid, three item previews, and a full item count of five. Status facets retain counts and sums (1,100), (2,500), (0,null).

The textarea accepts runtime-validated search JSON, not executable JavaScript. The actual query is compiled application code using the generated Q API. The view reads selected fields through generated E expressions and displays data, page metadata and facets. Business TraceChain rendering uses only each actual statement's traceChain; tracePath is displayed separately. No SQL parsing, known-alias branches or UI-owned lineage is used.

Diagnostic logging is on by default. Disabling it suppresses the diagnostic sink, while the explicitly installed evidence store still supplies the eight actual statements for the view. Memory refresh resets the data; OPFS survives refresh. Reset re-runs context-owned schema/bootstrap and generated mutations.

npm run build
npm run smoke
npm run smoke:orders

The order smoke test runs real Chromium against the built deployment and checks memory/OPFS refresh/reset, both diagnostic modes, Q/E results, exact facet values, native operation comments, actual SQL count and unchanged generated-library hashes. The repository's scripts/verify-examples.sh runs both browser smoke tests.

For maintainers with the generator checkout, regenerate the library and Assist:

cd /path/to/teaql-code-gen
TEAQL_TEST_TYPESCRIPT_RUNTIME_PATH=/path/to/teaql-ts \
  mvn -q -pl generator -am \
  -Dtest=PolyglotRequestTreeSqliteTest#sharedOrderFixtureExportsBrowserLibraryAndAssist \
  -Dsurefire.failIfNoSpecifiedTests=false test

The generated library's local dependency points to this runtime repository. Do not manually repair orders-lib/; change the model or upstream templates and regenerate instead.