turbine-orm 0.22.0 → 0.23.0

package/dist/powdb.js

@@ -201,18 +201,32 @@ function isDateColumn(col) {
  * Generate PowQL DDL (`type T { … }`) for every table in a schema. Used to
  * provision a PowDB database from a code-first `defineSchema`/`SchemaMetadata`
  * (PowDB has no migration runner yet). The primary key column is declared
- * `required unique`; non-nullable columns are `required`.
+ * `required unique`; non-nullable columns are `required`. A server-generated
+ * column ({@link ColumnMetadata.isGenerated}) that maps to PowQL `int` gets the
+ * `auto` modifier, so PowDB assigns a monotonic id on insert and Turbine stops
+ * synthesizing a client-side value for it.
  */
 export function powqlSchemaDDL(schema) {
     const stmts = [];
     for (const meta of Object.values(schema.tables)) {
         const pkSet = new Set(meta.primaryKey);
+        // PowDB's `unique` is single-column only — there is no composite-unique
+        // constraint (`add unique` takes one `.column`). So the per-field `unique`
+        // modifier is emitted only for a single-column PK; a composite PK (e.g. a
+        // m2m junction's `(source_id, target_id)`) marks its columns `required` but
+        // cannot enforce the tuple's uniqueness at the engine level.
+        const pkIsSingle = meta.primaryKey.length === 1;
         const fields = meta.columns.map((col) => {
             const mods = [];
             if (!col.nullable || pkSet.has(col.name))
                 mods.push('required');
-            if (pkSet.has(col.name))
+            if (pkSet.has(col.name) && pkIsSingle)
                 mods.push('unique');
+            // `auto` = server-generated monotonic int. PowDB requires it be `int` and
+            // rejects it alongside a `default`; non-int generated columns fall back to
+            // a plain typed column (Turbine assigns the value client-side instead).
+            if (col.isGenerated && powqlColumnType(col) === 'int')
+                mods.push('auto');
             return `  ${mods.join(' ')}${mods.length ? ' ' : ''}${col.name}: ${powqlColumnType(col)}`;
         });
         stmts.push(`type ${meta.name} {\n${fields.join(',\n')}\n}`);

package/dist/powql.d.ts

@@ -15,10 +15,20 @@
  *   - `create`/`createMany`/`update`/`delete` use PowDB 0.7.0's trailing
  *     `returning` keyword (`RETURNING *`, all columns) to surface affected rows
  *     in one round-trip. `upsert` is the lone exception — its statement does not
- *     accept `returning`, so it reselects the row by PK.
- *   - The PK is generated client-side (UUID) when the column has a default.
- *   - `with` (nested relations) degrades to **batched N+1 loaders** — D
- *     round-trips for depth D, not one query. manyToMany is Phase B.
+ *     accept `returning`, so it reselects the row by PK (a composite-PK upsert
+ *     reselects-or-writes inside one flat transaction).
+ *   - The PK is server-assigned when the column is `isGenerated` (PowDB's `auto`
+ *     int — read back via `returning`); otherwise a defaulted **string** PK is
+ *     generated client-side (UUID).
+ *   - `with` (nested relations) uses **batched N+1 loaders** — D round-trips for
+ *     depth D, not one query — including manyToMany (junction → targets).
+ *   - **Relation filters** (`some`/`none`/`every`, all cardinalities incl. m2m)
+ *     are resolved client-side to a literal `in (…)` list, never an IN-subquery:
+ *     PowDB's executor caches a subquery's result by plan shape and would return
+ *     a stale prior result for a later subquery of the same shape.
+ *   - **Nested writes** (relation ops in `create`/`update` data) run through the
+ *     shared nested-write engine as one flat top-level transaction (PowDB is
+ *     single-writer, no savepoints).
  *   - pgvector / JSON / array filters and cursor streaming throw
  *     {@link UnsupportedFeatureError} (E017) — they have no PowDB equivalent.
  *
@@ -87,11 +97,25 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     /** `lhs [not] in ($1, $2, …)` — empty list collapses to a constant. */
     private buildInList;
     /**
-     * Relation filter (`some`/`none`/`every`) via the verified IN-subquery form
-     * `Outer filter .localKey in (Target filter <e> { .targetKey })`. `exists`
-     * correlation is unreliable on PowDB, so it is never used.
+     * Pre-resolve every relation filter (`some`/`none`/`every`) in a where clause
+     * into a plain scalar `in`/`notIn` condition on the **local key**, by running
+     * the inner predicate as its own query and materializing the matching keys as
+     * a literal list. The compiled where is then relation-free and `buildWhere`
+     * emits only `in (<literal list>)`.
+     *
+     * Why not an IN-subquery (`.k in (Target filter <e> { .fk })`)? PowDB's
+     * executor caches a subquery's result by **plan shape, ignoring the literal**,
+     * so a second subquery of the same shape with a different value returns the
+     * first one's stale rows (reproduced live on the embedded engine; the
+     * single-statement literal `in (list)` form is always correct). Resolving
+     * client-side trades extra round-trips for correctness, and recurses — nested
+     * relation filters in the inner predicate resolve when the target query runs.
      */
-    private buildRelationFilter;
+    private resolveRelationFilters;
+    /** Resolve one hasMany/hasOne/belongsTo filter to `{ localField: { in|notIn: [...] } }`. */
+    private resolveRelationCondition;
+    /** Resolve a manyToMany filter through the junction to `{ sourceRefField: { in|notIn: [...] } }`. */
+    private resolveManyToManyCondition;
     /** Resolve the set of columns to project, honouring `select` / `omit`. */
     private projectedColumns;
     /** `{ .c1, .c2, … }` projection clause. */
@@ -114,9 +138,23 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     findFirstOrThrow(args?: FindManyArgs<T>): Promise<T>;
     /** Load each requested relation for `parents` and attach it onto each row. */
     private loadRelations;
+    /**
+     * manyToMany nested read — a three-hop batched loader (no `json_agg`/join
+     * pushdown): (1) read the junction rows for all parents in `sourceKey in (…)`
+     * chunks, (2) read the target rows for the collected `targetKey`s, (3) stitch
+     * each parent → its junction rows → its targets in memory. Mirrors the
+     * single-key N+1 loaders; the junction's source/target columns must be single
+     * (composite junction keys would need PowQL tuple-`in`, which it lacks).
+     */
+    private loadManyToMany;
     /** Split `data` into scalar assignments; reject relation (nested-write) keys. */
     private scalarData;
-    /** Fill in a client-generated UUID for a defaulted PK that wasn't supplied. */
+    /**
+     * Fill in a client-generated UUID for a defaulted **string** PK that wasn't
+     * supplied. A server-generated PK ({@link ColumnMetadata.isGenerated}, e.g. an
+     * `int` column with PowDB's `auto` modifier) is left untouched — PowDB assigns
+     * it and the trailing `returning` reads it back — as is any non-string PK.
+     */
     private applyPkDefault;
     create(args: CreateArgs<T>): Promise<T>;
     createMany(args: CreateManyArgs<T>): Promise<T[]>;
@@ -126,11 +164,25 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     }>;
     /** Compile `data` into PowQL update assignments, including atomic operators. */
     private buildUpdateAssignments;
+    private isTxScoped;
+    private nestedCreate;
+    private nestedUpdate;
+    /** Open a flat PowDB transaction on a pinned connection and run `fn` inside it. */
+    private runInImplicitTx;
+    /** Already inside a transaction: build a context whose table accessors reuse the pinned pool. */
+    private buildNestedCtx;
     delete(args: DeleteArgs<T>): Promise<T>;
     deleteMany(args: DeleteManyArgs<T>): Promise<{
         count: number;
     }>;
     upsert(args: UpsertArgs<T>): Promise<T>;
+    /**
+     * Composite-key upsert: PowQL's `upsert … on .col` only takes one conflict
+     * column, so reselect by the full composite PK and update-or-create inside one
+     * flat transaction (PowDB single-writer makes the read-then-write safe from
+     * concurrent writers; the transaction makes it atomic with the write).
+     */
+    private upsertComposite;
     count(args?: CountArgs<T>): Promise<number>;
     aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;