Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

L6 - Query Engine

Admit operations, compile portable queries, and execute provider statements

The query engine lives in src/query-engine/. Its public input is an operation on a registered model; its output is a parsed result or a typed failure. The compiler and its intermediate objects are private implementation details.

Admission and execution

A client operation returns a lazy PendingOperation. Awaiting it runs the operation lifecycle once; subsequent Promise consumers share that execution. Extension call parts patch or refuse its arguments before validation. The schema registry then admits the operation against the registered model graph. around parts surround execution, and a unit part declared { rewrites: true } rewrites each logical statement. Observation (unit parts) has separate operation and statement boundaries.

The current implementation is under raptor3/:

  • commands/index.ts admits an operation and runs it: on the client’s own driver, or inside the transaction an owner lends it.
  • shared/sql-operation-context.ts binds the schema, the driver and the call for one execution.
  • shared/query.ts prepares reads, filters, projections and aggregates, and decodes provider rows into the public scalar and relation domains; shared/sql-queries.ts lowers what was prepared to SQL.
  • write/ runs writes, nested relation work included: the verbs say what a write means, the store holds what the call believes of its rows, and the transports send its statements one unit at a time.

Those paths describe the installed implementation. They are not package entry points, supported extension hooks, or APIs applications should import.

SQL belongs to adapters

The engine decides which rows and relationships an operation addresses. The adapter owns the SQL spelling: identifier qualification, JSON aggregation, comparisons, storage conversions, returning clauses, and provider differences. Both layers compose parameterized Sql fragments. The engine does not recover semantic facts by parsing generated SQL.

A relation’s topology is resolved once by schema validation. Query and write consumers use that same resolved index. They do not scan for inverse relations or independently decide which side owns a foreign key.

Atomicity is a driver capability

An interactive transaction keeps an operation on one reserved session. A native batch can atomically execute a prepared statement group, but cannot generally branch in JavaScript on an earlier result. A driver offering neither facility cannot make several statements atomic merely because the caller issued one nested ORM operation.

The compiler refuses a shape when its required guarantees cannot be preserved. For example, relation-bearing skipDuplicates requires a supported savepoint or native strategy; unsupported combinations fail before writing rather than silently dropping the option. See transactions and the driver matrix for the concrete guarantees.

Prepared array transactions admit their members before dispatch. They preserve member order and statement attribution. Callback transactions execute against the callback’s bound client. A failed savepoint or transaction poisons further work on that scope until its owning cleanup boundary completes.

Result and storage boundaries

Input validation establishes the logical scalar domain. Provider parsers and the compiled row parser establish the returned domain. Invalid provider data raises an error; a missing or malformed value is not replaced with a plausible zero, empty object, or empty list.

Typed operations never inspect physical storage. A schema VibORM pushed or migrated is correct by construction; a foreign SQLite decimal column or noncanonical temporal text is found by viborm check --db, not per statement. Raw SQL stays physical and does not receive model-aware decoding.

Inspection and verification

PendingOperation.buildStatement() is an inspection facility for supported read shapes; it is not a general prepared-query API. Use the official instrumentation extension to inspect executed statement events under its disclosure settings.

pnpm test:layer:query-engine runs the layer’s fast checks. pnpm test:core runs the complete core selection in sequential bounded shards. Extended, provider, and coverage selections are documented in tests/README.md and owned by the CI manifests. A local compiler test does not establish a hosted provider contract.

Was this page helpful?