turbine-orm 0.34.0 → 0.35.0

package/dist/query/builder.d.ts

@@ -36,7 +36,12 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly warnOnUnlimited;
     private readonly utcTimestamps;
     private readonly preparedStatementsEnabled;
-    private readonly sqlCacheEnabled;
+    /**
+     * Whether the SQL template cache is active. Set once in the constructor.
+     * Mutable (not `readonly`) only so {@link withSqlCacheDisabled} can flip it
+     * off around a single synchronous compile (see {@link explain}).
+     */
+    private sqlCacheEnabled;
     private readonly dialect;
     /** Client-level default relation-loading strategy ('join' unless configured). */
     private readonly relationLoadStrategy;
@@ -290,6 +295,36 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private runFindUniqueBatched;
     buildFindUnique<W extends TypedWithClause<R> = {}>(args: FindUniqueArgs<T, R, W, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): DeferredQuery<T | null>;
     findMany<W extends TypedWithClause<R> = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, R, W, S, O>): Promise<QueryResult<T, R, W, S, O>[]>;
+    /**
+     * Return the engine's query plan for a {@link findMany}-shaped query as plain
+     * text lines: a diagnostic surface for inspecting how the database will run a
+     * query (index usage, join strategy, scan type).
+     *
+     * The compiled SELECT is prefixed with the dialect's explain syntax
+     * (Postgres `EXPLAIN`, SQLite `EXPLAIN QUERY PLAN`, MySQL `EXPLAIN
+     * FORMAT=TREE`) and run as a read. The findMany args are compiled with the
+     * SQL template cache disabled, so an explain never reads or writes the shared
+     * cache. Middleware is NOT applied: the returned rows are plan text, not
+     * entity rows. Each result row is flattened to one line by joining its column
+     * values with a single space (Postgres returns one `QUERY PLAN` text column,
+     * SQLite's `EXPLAIN QUERY PLAN` returns four, MySQL's tree format one).
+     *
+     * Only `findMany` shapes are supported (where / orderBy / with / limit /
+     * pagination). Engines whose plan cannot be requested in-band from a compiled
+     * query (SQL Server, whose SHOWPLAN is a session toggle) throw
+     * {@link UnsupportedFeatureError} (E017).
+     *
+     * The plan text itself is engine-owned and NOT covered by semver: its content
+     * and formatting can change with the underlying database version.
+     */
+    explain(args?: FindManyArgs<T, R>): Promise<string[]>;
+    /**
+     * Run `fn` with the SQL template cache forced off, restoring the prior state
+     * afterward. Used by {@link explain}, whose one-off prefixed statement must
+     * neither read nor write the shared cache. `fn` is synchronous, so no query
+     * interleaves between the toggle and its restore.
+     */
+    private withSqlCacheDisabled;
     /**
      * Emit a one-time `console.warn` when {@link findMany} is called without an
      * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.

package/dist/query/builder.js

@@ -141,6 +141,11 @@ export class QueryInterface {
     warnOnUnlimited;
     utcTimestamps;
     preparedStatementsEnabled;
+    /**
+     * Whether the SQL template cache is active. Set once in the constructor.
+     * Mutable (not `readonly`) only so {@link withSqlCacheDisabled} can flip it
+     * off around a single synchronous compile (see {@link explain}).
+     */
     sqlCacheEnabled;
     dialect;
     /** Client-level default relation-loading strategy ('join' unless configured). */
@@ -834,6 +839,61 @@ export class QueryInterface {
             return deferred.transform(result);
         });
     }
+    /**
+     * Return the engine's query plan for a {@link findMany}-shaped query as plain
+     * text lines: a diagnostic surface for inspecting how the database will run a
+     * query (index usage, join strategy, scan type).
+     *
+     * The compiled SELECT is prefixed with the dialect's explain syntax
+     * (Postgres `EXPLAIN`, SQLite `EXPLAIN QUERY PLAN`, MySQL `EXPLAIN
+     * FORMAT=TREE`) and run as a read. The findMany args are compiled with the
+     * SQL template cache disabled, so an explain never reads or writes the shared
+     * cache. Middleware is NOT applied: the returned rows are plan text, not
+     * entity rows. Each result row is flattened to one line by joining its column
+     * values with a single space (Postgres returns one `QUERY PLAN` text column,
+     * SQLite's `EXPLAIN QUERY PLAN` returns four, MySQL's tree format one).
+     *
+     * Only `findMany` shapes are supported (where / orderBy / with / limit /
+     * pagination). Engines whose plan cannot be requested in-band from a compiled
+     * query (SQL Server, whose SHOWPLAN is a session toggle) throw
+     * {@link UnsupportedFeatureError} (E017).
+     *
+     * The plan text itself is engine-owned and NOT covered by semver: its content
+     * and formatting can change with the underlying database version.
+     */
+    async explain(args) {
+        const explainSyntax = this.dialect.explainQuery;
+        if (!explainSyntax) {
+            throw new UnsupportedFeatureError('explain()', this.dialect.name, 'This engine cannot explain a compiled query in-band.');
+        }
+        // Compile the findMany SQL with the cache disabled: the prefixed EXPLAIN
+        // statement is a one-off diagnostic and must never read or write the shared
+        // query-template cache.
+        const deferred = this.withSqlCacheDisabled(() => this.buildFindMany(args));
+        const sql = `${explainSyntax.prefix} ${deferred.sql}`;
+        this.currentAction = 'explain';
+        // No preparedName: keep the diagnostic statement out of the prepared path.
+        const result = await this.queryWithTimeout(sql, deferred.params, args?.timeout);
+        return result.rows.map((row) => Object.values(row)
+            .map((value) => (typeof value === 'string' ? value : String(value)))
+            .join(' '));
+    }
+    /**
+     * Run `fn` with the SQL template cache forced off, restoring the prior state
+     * afterward. Used by {@link explain}, whose one-off prefixed statement must
+     * neither read nor write the shared cache. `fn` is synchronous, so no query
+     * interleaves between the toggle and its restore.
+     */
+    withSqlCacheDisabled(fn) {
+        const prev = this.sqlCacheEnabled;
+        this.sqlCacheEnabled = false;
+        try {
+            return fn();
+        }
+        finally {
+            this.sqlCacheEnabled = prev;
+        }
+    }
     /**
      * Emit a one-time `console.warn` when {@link findMany} is called without an
      * explicit `limit`/`take` and `warnOnUnlimited` has not been disabled.

package/dist/query/deferred.d.ts

@@ -111,8 +111,12 @@ export interface QueryInterfaceOptions {
      */
     utcTimestamps?: boolean;
     /**
-     * Client-level default relation-loading strategy for `with` clauses. Per-query
-     * `relationLoadStrategy` args override this; both default to `'join'`.
+     * Client-level default relation-loading strategy for `with` clauses; a
+     * per-query `relationLoadStrategy` arg overrides it. On SQL engines the default
+     * is `'join'` (one single-statement `json_agg` query). On PowDB the default is
+     * the batched loaders, and `'join'` opts INTO native server-side joins where
+     * eligible (ineligible relations fall back to the loaders per-relation and
+     * silently; see the PowDB docs).
      */
     relationLoadStrategy?: RelationLoadStrategy;
     /**

package/dist/query/types.d.ts

@@ -7,15 +7,19 @@ export type OrderDirection = 'asc' | 'desc';
 /**
  * How a query resolves its `with` relations.
  *
- *   - `'join'` (default) — one SQL statement with correlated
- *     `json_agg(json_build_object(...))` subqueries. One round-trip; an index
- *     seek per parent row when the child FK is indexed.
- *   - `'batched'` — run the base query, then ONE flat follow-up query per
+ *   - `'join'`: one SQL statement with correlated
+ *     `json_agg(json_build_object(...))` subqueries. One round-trip, an index
+ *     seek per parent row when the child FK is indexed. On PowDB, `'join'`
+ *     instead opts into native PowQL server-side joins where eligible.
+ *   - `'batched'`: run the base query, then ONE flat follow-up query per
  *     relation (`WHERE fk = ANY($1)`), stitching children client-side. D levels
  *     cost D extra round-trips, but each is a single key-set lookup and rows come
- *     back flat — a win when FK columns are unindexed or result sets are huge.
+ *     back flat (a win when FK columns are unindexed or result sets are huge).
  *
- * Precedence: per-query arg > client `relationLoadStrategy` config > `'join'`.
+ * Precedence: per-query arg > client `relationLoadStrategy` config > the engine
+ * default. On SQL engines the default is `'join'`; on PowDB the default is the
+ * batched loaders (an ineligible relation falls back to them per-relation and
+ * silently even when `'join'` is requested).
  */
 export type RelationLoadStrategy = 'join' | 'batched';
 /**

package/dist/sqlite.js

@@ -372,6 +372,9 @@ export const sqliteDialect = {
     supportsAdvisoryLock: false,
     // No FROM-clause LATERAL: the opt-in lateral pick plan is Postgres-only.
     supportsLateralJoin: false,
+    // SQLite explains a compiled query with `EXPLAIN QUERY PLAN` (four columns:
+    // id, parent, notused, detail), overriding the inherited Postgres `EXPLAIN`.
+    explainQuery: { prefix: 'EXPLAIN QUERY PLAN' },
     // json_group_array / json_object have no inline ORDER BY argument, so every
     // ordered to-many relation is forced through the inner-subquery rewrite.
     aggSupportsInlineOrderBy: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {
@@ -103,8 +103,8 @@
     "@size-limit/esbuild": "^12.1.0",
     "@size-limit/file": "^12.1.0",
     "@types/node": "^26.1.0",
-    "@zvndev/powdb-client": "^0.13.0",
-    "@zvndev/powdb-embedded": "^0.13.0",
+    "@zvndev/powdb-client": "^0.15.0",
+    "@zvndev/powdb-embedded": "^0.15.0",
     "c8": "^11.0.0",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",