turbine-orm 0.81.0 → 0.90.0

package/dist/cjs/powql.d.ts

@@ -36,7 +36,8 @@
  */
 import type { PowdbPool } from './powdb.js';
 import type { MiddlewareFn, QueryInterfaceOptions } from './query/index.js';
-import type { AggregateArgs, AggregateResult, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FindManyArgs, FindUniqueArgs, GroupByArgs, UpdateArgs, UpdateManyArgs, UpsertArgs } from './query/types.js';
+import type { TableClient } from './query/table-client.js';
+import type { AggregateArgs, AggregateResultOf, CountArgs, CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindUniqueArgs, GroupByArgs, GroupByResult, OptionalInput, QueryResult, TypedWithClause, UpdateArgs, UpdateManyArgs, UpsertArgs } from './query/types.js';
 import { type SchemaMetadata } from './schema.js';
 /**
  * Max values one `in` / `notIn` on a PowDB-native `datetime` column may carry.
@@ -50,12 +51,28 @@ import { type SchemaMetadata } from './schema.js';
  * a loader can never build a chain the engine will reject.
  */
 export declare const MAX_POWQL_DATETIME_TERMS = 32;
+/**
+ * Max distinct keys one client-side relation filter may resolve to.
+ *
+ * A relation filter becomes a literal `in (…)` list on the local key, and the
+ * engine evaluates that list per row, so the cost grows with rows times keys
+ * (measured on the 0.20 addon over 100k rows: about 0.3 s per 1,000 keys).
+ * Past this bound the filter is refused with a typed error naming the bound,
+ * instead of building a statement whose cost has no ceiling.
+ */
+export declare const MAX_RELATION_FILTER_KEYS = 10000;
+/** The relations type argument of an untyped accessor: none known. */
+type NoRelations = {};
 /**
  * The PowQL query interface. Constructed by `turbinePowDB` via the
- * `queryInterfaceFactory` seam and cast to `QueryInterface<object>` so
- * `TurbineClient.table()` can return it transparently.
+ * `queryInterfaceFactory` seam. `implements TableClient` makes a method the SQL
+ * accessor has and this class lacks, or one whose signature differs, a build
+ * error. Where a method's result is narrowed by `select` / `omit` / `with`, a
+ * public overload signature carries the SQL accessor's typing and the
+ * implementation below it is typed on the plain row; both return the same
+ * projected, relation-loaded rows at run time.
  */
-export declare class PowqlInterface<T extends object = Record<string, unknown>> {
+export declare class PowqlInterface<T extends object = Record<string, unknown>> implements TableClient<T> {
     private readonly pool;
     private readonly table;
     private readonly schema;
@@ -65,7 +82,10 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
     private readonly onQuery?;
-    private warnedUnlimited;
+    /** Where this interface's log lines go: the client's logger, else the console. */
+    private readonly logger;
+    /** The logger for advice lines, or `undefined` when `diagnostics` turns advice off. */
+    private readonly advice;
     constructor(pool: PowdbPool, table: string, schema: SchemaMetadata, middlewares?: MiddlewareFn[], options?: QueryInterfaceOptions);
     /**
      * Resolve a camelCase field name (or raw snake) to its column metadata.
@@ -139,6 +159,12 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * and coercion stays unambiguous. Non-finite floats are still rejected.
      */
     private writeRef;
+    /**
+     * A PowQL `int` column declared as an integer type (not a Date, which is
+     * stored as int micros, and not a column whose declared type is something
+     * else).
+     */
+    private isIntegerCol;
     private isFloatCol;
     /**
      * The bound pool's {@link PowdbCapabilities}. Falls back to the trusted-caller
@@ -215,15 +241,6 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * which is the divergence class the projection resolver already cost.
      */
     private withDeclaredRelationNames;
-    /**
-     * Caller args in canonical form: declared relation spellings, and `take` /
-     * `skip` folded into `limit` / `offset`.
-     *
-     * Same composition as `QueryInterface.normalizeArgs` and here for the same
-     * reason the method above is here: nothing about a parallel implementation
-     * makes a core rule arrive on its own, and an engine that reads `take` but
-     * not `skip` pages differently from one that reads both.
-     */
     /**
      * Fill in the deterministic per-relation ordering `stableRelationOrder` asks
      * for, through the shared transform the SQL engines use.
@@ -233,8 +250,48 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * option whose entire purpose is that they do not. Same resolution as
      * QueryInterface: a per-query flag wins, else the client-level default.
      */
+    /** `take` / `skip` inside every `with` level folded into `limit` / `offset` (shared rule). */
+    private withRelationPagination;
     private withStableRelationOrder;
+    /**
+     * Caller args in canonical form: `undefined` pruned (query/normalize-args.ts),
+     * declared relation spellings, stable relation order, and `take` / `skip`
+     * folded into `limit` / `offset` at the top level and inside `with`. Same composition as
+     * `QueryInterface.normalizeArgs`, run at the top of every public operation,
+     * so the two engines agree about what each argument means.
+     *
+     * `refuseEmptiedWhere` names the single-row read (`findFirst`,
+     * `findFirstOrThrow`) that refuses a `where` whose every key was `undefined`.
+     */
     private normalizeArgs;
+    /**
+     * The per-query `timeout` and `relationLoadStrategy`, checked with the SQL
+     * engines' rule and message: a timeout is a positive number of ms up to
+     * {@link MAX_TIMEOUT_MS} (or 0 for none), a strategy one of the SQL engines' values.
+     */
+    private assertQueryOptions;
+    /**
+     * Whether `cursor` carries a value, after the SQL engines' cursor checks: a
+     * cursor that names no row (`null`, `{}`) is E003, and each value is a row's
+     * value under the shared rule (`cursorFieldValue`). Unknown fields are E003.
+     */
+    private cursorCarriesValues;
+    /**
+     * The SQL engines' cursor placement rule (query/builder.ts `planCursor`),
+     * so a cursor they refuse is the same E003 here and only a cursor they would
+     * serve reaches PowDB's E017. The page order is `orderBy` plus the
+     * tiebreaker; the cursor must carry a value for every column of it, or name
+     * one row by a unique key (the shared findUnique rule).
+     */
+    private assertCursorPlaceable;
+    /**
+     * A paginated `findMany` (`limit` / `offset`) whose `orderBy` can tie gets
+     * a tiebreaker appended in the last term's direction (the primary key, else
+     * the first unique key on NOT NULL columns), as on the SQL engines, so a page
+     * boundary cannot fall between tied rows in a different order on each page.
+     * Returns `args` itself when the order is already total or nothing pages.
+     */
+    private completePageOrder;
     /**
      * `jsonEncoding` selects between PostgreSQL's `json_build_object` and
      * `json_build_array` row encodings for relation subqueries. PowQL emits no
@@ -243,7 +300,13 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * Refused for the same reason `forceCustomPlan` is.
      */
     private assertNoJsonEncoding;
+    /** `optimisticLock` is an `update` option; the shared refusal and message from query/writes.ts. */
+    private assertNoOptimisticLock;
     private assertNoForceCustomPlan;
+    /** `lock` (a row-locking read): PowDB has no row locks. */
+    private assertNoRowLock;
+    /** `_percentile`: PowQL has no percentile aggregate. */
+    private assertNoPercentile;
     /** See query/compound-unique.ts: one rule and one message across engines. */
     private assertIdentifiesOneRow;
     /**
@@ -273,6 +336,11 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * an already-RESOLVED where (relation filters pre-resolved to literal in-lists
      * by {@link resolveRelationFilters}): the relation-key branch below still
      * throws, so an unresolved relation filter can never leak into a join.
+     *
+     * `NOT` here is PowQL's two-valued complement. A caller's where reaches this
+     * only through {@link sqlTrueWhere} (inside {@link resolveRelationFilters},
+     * and in {@link applyGlobalFilter}), which leaves `NOT` only where the two
+     * readings agree.
      */
     private buildWhere;
     /**
@@ -306,6 +374,40 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * read through `introspectPowdbDatabase`, or hand-written metadata.
      */
     private assertDatetimePredicateSupported;
+    /**
+     * Refuse a value comparison on a `numeric` / `decimal` column. PowDB stores
+     * those as `str` (it has no decimal type, and `float` would lose digits), so
+     * every comparison, ordering and aggregate the engine could run on them is a
+     * TEXT comparison: `'7.50' > '7.5'`, `'10' < '9'`, and `'7.5' = '7.50'` is
+     * false; arithmetic on a `str` yields NULL. Null checks, reads and plain
+     * writes are unaffected.
+     */
+    private assertDecimalComparable;
+    /** The labels of `col`'s enum type, or `undefined` when it is not an enum column. */
+    private enumLabels;
+    /**
+     * E003 unless `value` is one of the enum column's labels. PostgreSQL refuses
+     * any other value (22P02, which Turbine reports as E003) whether it is
+     * written or compared, and the label set is exact: case and spelling count.
+     * The value itself is not echoed, only its kind.
+     */
+    private assertEnumLabel;
+    /**
+     * Refuse an ORDERING of an enum column (orderBy, `_min` / `_max`). PostgreSQL
+     * orders an enum by the position of its labels in the type's declaration;
+     * PowDB stores the label text and would order it alphabetically, a different
+     * answer with no error. Range filters (`gt` / `gte` / `lt` / `lte`) do not come
+     * here: they compile to the exact set of labels on that side of the operand.
+     */
+    private assertEnumOrderable;
+    /**
+     * An aggregate over an enum column: `_min` / `_max` order it (see
+     * {@link assertEnumOrderable}); `_sum` / `_avg` have no meaning on a label,
+     * which PostgreSQL refuses as E003 (42883, no such function).
+     */
+    private assertEnumAggregate;
+    /** The E003 for an operand that is not a comparable value for its column. */
+    private operandError;
     /** Build a single `field: value | operator` condition. */
     private buildFieldCondition;
     /**
@@ -348,14 +450,47 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private buildJsonPathCondition;
     /** Bind a value, lowercasing for case-insensitive comparisons. */
     private bind;
-    /** Bind a LIKE pattern (already escaped), lowercasing for insensitive mode. */
-    private bindLike;
+    /**
+     * A bound filter operand. An integral number compared with a float column is
+     * cast to float in the statement: the typed wire carries an integral number as
+     * an int, and the engine compares int with float by type tag inside `not`,
+     * `or` and `in` (on 0.20 `not (.rating = 4)` matches the 4.0 row and
+     * `.rating in (4, 5)` matches nothing).
+     */
+    private filterOperand;
+    /**
+     * `contains` / `startsWith` / `endsWith` against `expr` (a column or a JSON
+     * path), matching `value` literally.
+     *
+     * PowQL's `like` has NO escape character: `%` and `_` in the pattern are
+     * always wildcards and `\` is an ordinary character. So a prefix or suffix
+     * test never goes through `like`: it compares the leading or trailing
+     * `length($v)` characters with `substring`, which is exact for every value
+     * on every engine version (and sidesteps the pre-0.27 matcher, which missed
+     * text containing a literal `%`). `contains` has no such form, since PowQL
+     * has no position function, so a value carrying `%` or `_` is refused rather
+     * than sent as a pattern that means something else.
+     */
+    private buildStringMatch;
     /**
      * `lhs [not] in ($1, $2, …)`, empty list collapses to a constant.
      *
      * A PowDB-native `datetime` column takes the expanded form instead (see
      * {@link buildDatetimeInList}): its `in` list is still broken upstream at 0.20.
      */
+    /**
+     * The enum-specific shapes of one operator on an enum column, or `undefined`
+     * for an operator compiled the ordinary way (equality, `in` / `notIn`, `not`,
+     * whose labels {@link param} checks).
+     *
+     * `gt` / `gte` / `lt` / `lte` compile to `in` over the labels on that side of
+     * the operand in DECLARATION order, which is what PostgreSQL compares; the
+     * text comparison PowDB would run is alphabetical, a different answer. A null
+     * operand matches no row, as `col > NULL` does. Case-insensitive matching and
+     * `contains` / `startsWith` / `endsWith` are E003: PostgreSQL has no `lower`
+     * or `LIKE` on an enum (42883).
+     */
+    private enumRangeCondition;
     private buildInList;
     /**
      * `in` / `not in` on a PowDB-native `datetime` column, expanded into the
@@ -405,31 +540,115 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      */
     private keyChunkSize;
     /**
-     * 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>)`.
+     * Pre-resolve every relation filter in a where clause into a plain scalar
+     * 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
+     * client-side trades extra round-trips for correctness, and recurses: nested
      * relation filters in the inner predicate resolve when the target query runs.
+     *
+     * `skip` is the query's `skipGlobalFilters`, forwarded to every target query
+     * so the target's global filter bounds the related rows exactly as the SQL
+     * engines' EXISTS does, and an opt-out reaches the targets as it does there.
      */
     private resolveRelationFilters;
-    /** Resolve one hasMany/hasOne/belongsTo filter to `{ localField: { in|notIn: [...] } }`. */
+    /**
+     * {@link resolveRelationFilters} over a where already in {@link sqlTrueWhere}'s
+     * form (`AND` / `OR` arrays, `NOT` objects).
+     */
+    private resolveRelationFiltersIn;
+    /**
+     * Resolve one relation filter to a relation-free condition on the local key,
+     * with the SQL engines' meaning for every branch:
+     *
+     *   some / is      EXISTS a related row matching the inner where
+     *   none / isNot   NOT EXISTS such a row (true for a NULL local key)
+     *   every          NOT EXISTS a related row for which the inner where is FALSE
+     *   is: null       NOT EXISTS any related row
+     *   isNot: null    EXISTS a related row
+     *
+     * A bare object on a to-one relation is an implicit `is` (the shared
+     * {@link normalizeRelationFilter} rule). Branches combine with AND. A shape
+     * that names no branch, or names something else, is refused: compiling it to
+     * nothing would match every row, and a mutation carrying it would write them.
+     * Returns `null` when every branch key is `undefined` (an absent filter).
+     */
     private resolveRelationCondition;
-    /** Resolve a manyToMany filter through the junction to `{ sourceRefField: { in|notIn: [...] } }`. */
-    private resolveManyToManyCondition;
+    /** A fresh interface over a relation's target table, for an internal fetch. */
+    private relationTargetQi;
+    /**
+     * `EXISTS` (or `NOT EXISTS`, when `exists` is false) a related row matching
+     * `inner`, as a condition on this table's local key.
+     *
+     * The NOT EXISTS form keeps a NULL local key: such a row has no related row,
+     * so it qualifies. PowQL's `not in` alone would drop it.
+     */
+    private relationMatch;
+    /**
+     * hasMany / hasOne / belongsTo: the local field, and the distinct correlation
+     * keys of the target rows matching `inner` (inside the target's global filter).
+     * hasMany/hasOne: local = our referenceKey, collected = the child's foreignKey.
+     * belongsTo:      local = our foreignKey,   collected = the target's referenceKey.
+     */
+    private directRelationKeys;
+    /**
+     * The distinct non-null values of `field` over this table's rows matching
+     * `where` (inside this table's global filter, honouring `skip`), refused
+     * past {@link MAX_RELATION_FILTER_KEYS}.
+     */
+    private collectRelationKeys;
+    /** Dedupe correlation keys by value (a Date or bigint by its value, not identity) and enforce the cap. */
+    private distinctKeys;
+    /** manyToMany: the source key field, and the source keys linked (through the junction) to targets matching `inner`. */
+    private manyToManySourceKeys;
+    /**
+     * Rows where `where` is TRUE under SQL three-valued logic. PowQL's own
+     * evaluation already excludes a NULL from every comparison, so this differs
+     * from `where` only under `NOT`, where PowQL takes the plain complement and
+     * SQL keeps a NULL comparison unknown.
+     *
+     * Combinators are read by the shared {@link combinatorBranches} rule, so a
+     * shape the SQL engines refuse is refused here (E003), and the output uses
+     * one spelling: `AND` / `OR` arrays and `NOT` objects. `OR: []` stays as
+     * written and compiles to no row.
+     */
+    private sqlTrueWhere;
+    /**
+     * Rows where `where` is FALSE under SQL three-valued logic, the complement
+     * PowQL's two-valued `not` cannot express: a comparison against a NULL
+     * column is unknown, which is neither TRUE nor FALSE, so the row belongs to
+     * neither set. Relation filters (EXISTS) are two-valued and negate plainly.
+     *
+     * A sub-where that compiles to no condition is TRUE, so it is FALSE for no
+     * row and contributes nothing; `OR: []` is FALSE for every row.
+     */
+    private sqlFalseWhere;
+    /**
+     * Whether a where compiles to no condition, as {@link buildWhere} and the
+     * SQL where walk both read it: only absent keys, and `AND` / `NOT` whose
+     * branches all compile to nothing (`AND: []`, `NOT: [{}]`). Any `OR` is a
+     * condition: `OR: []` matches no row, and an `OR` with a branch that has no
+     * condition is constant TRUE (`OR: [{}]`), which `NOT` negates. So is any
+     * column or relation key.
+     */
+    private compilesToNothing;
+    /** A where clause that matches every row (the primary key is null or not null). */
+    private trueWhere;
+    /** A where clause that matches no row (an empty `in` on the primary key). */
+    private falseWhere;
     /**
      * Resolve the set of columns to project, honouring `select` / `omit` and the
      * query-level `includePii` opt-in. PII-tagged (`defineSchema` `pii: true`)
      * columns are EXCLUDED from a default (or omit-only) projection unless
-     * `includePii` is true; an explicit `select` naming a PII column IS the opt-in
-     * and returns it regardless. Untagged tables project exactly as before.
+     * `includePii: UNSAFE` is passed, and a `select` naming one without it is
+     * refused (E003), as on the SQL engines. Untagged tables project exactly as
+     * before.
      */
     /**
      * Resolve one projection field name, or throw. PowQL already refused an
@@ -472,6 +691,14 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * every consumer of the key (relation stitching, reselect) has finished with
      * it. A no-op, and free, when nothing was forced.
      */
+    /**
+     * The columns of this table that the post-fetch relation loaders read off
+     * each parent row for `withClause`: a belongsTo's foreign key, a hasMany /
+     * hasOne / manyToMany's reference key, and the same for every relation a
+     * `_count` names. An unknown name contributes nothing; the loader raises its
+     * E005.
+     */
+    private loaderParentKeyColumns;
     private stripForcedPk;
     /**
      * The snake_case names of this table's PII-tagged columns. Empty for a table
@@ -582,7 +809,7 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * coerces its string cells correctly. Defaults to the pool capability for the
      * rare caller with no per-result flag (hand-built test pools). */
     private shape;
-    findMany(args?: FindManyArgs<T>): Promise<T[]>;
+    findMany<W extends TypedWithClause = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, NoRelations, W, S, O>): Promise<QueryResult<T, NoRelations, W, S, O>[]>;
     /**
      * Compile the findMany select into PowQL (no execution), pushing values into
      * `params`. Returns the query plus the RESOLVED where (relation filters
@@ -613,10 +840,10 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * too, so both engines agree.
      */
     explain(args?: FindManyArgs<T>): Promise<string[]>;
-    findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
-    findFirst(args?: FindManyArgs<T>): Promise<T | null>;
-    findUniqueOrThrow(args: FindUniqueArgs<T>): Promise<T>;
-    findFirstOrThrow(args?: FindManyArgs<T>): Promise<T>;
+    findUnique<W extends TypedWithClause = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, NoRelations, W, S, O>): Promise<QueryResult<T, NoRelations, W, S, O> | null>;
+    findFirst<W extends TypedWithClause = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, NoRelations, W, S, O>): Promise<QueryResult<T, NoRelations, W, S, O> | null>;
+    findUniqueOrThrow<W extends TypedWithClause = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: FindUniqueArgs<T, NoRelations, W, S, O>): Promise<QueryResult<T, NoRelations, W, S, O>>;
+    findFirstOrThrow<W extends TypedWithClause = {}, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args?: FindManyArgs<T, NoRelations, W, S, O>): Promise<QueryResult<T, NoRelations, W, S, O>>;
     /**
      * Load each requested relation for `parents` and attach it onto each row.
      *
@@ -629,6 +856,32 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * either way (the join reuses the same stitch / shape helpers).
      */
     private loadRelations;
+    /**
+     * Refuse a `_count` anywhere below the top-level `with`, as the SQL engines
+     * do (E005, their message). Checked over the whole tree before anything runs,
+     * because a loader re-enters the child table's public findMany, where a
+     * nested `_count` would otherwise read as top level and be counted.
+     */
+    private assertCountTopLevelOnly;
+    /**
+     * The reserved `with: { _count: ... }` key: one count per selected to-many
+     * relation, attached as `_count: { rel: n }` (0 for a parent with no rows),
+     * which is the SQL engines' output. The relations are selected by the shared
+     * `resolveCountRelations`, so `true` counts every to-many relation and the
+     * refusals match. Each count honours the counted table's global filter the
+     * way the SQL engines' correlated `COUNT(*)` does: hasMany counts the
+     * surviving child rows, manyToMany counts junction rows whose TARGET
+     * survives. One grouped query per relation per key chunk.
+     */
+    private loadRelationCounts;
+    /** Child rows per parent key for a hasMany `_count`, through the child's own groupBy. */
+    private countHasMany;
+    /**
+     * Junction rows per parent key for a manyToMany `_count`. When the target
+     * table has a global filter in force, only junction rows whose target row
+     * survives it are counted, as the SQL engines' `EXISTS` on the target does.
+     */
+    private countManyToMany;
     /**
      * manyToMany nested read, a three-hop batched loader (no `json_agg`/join
      * pushdown): (1) read the junction rows for all parents in `sourceKey in (…)`
@@ -707,6 +960,8 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * to literal in-lists before the base query ran); the relation where is resolved
      * on the target the same way before qualifying, so a nested relation filter in
      * the relation `where` never reaches the join unresolved. Params bind in order.
+     * Each side carries its own table's global filter under the query's `skip`,
+     * so the join returns exactly the rows the loaders would.
      */
     private joinFilter;
     /** Group join rows by their (normalized) `__tpk`, stripping it and shaping each child. */
@@ -762,6 +1017,10 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * Aliases share the parent statement's counter, so arbitrarily deep and
      * self-referential trees stay collision-free (the same discipline as the SQL
      * engine's json_agg subqueries).
+     *
+     * The target's global filter is ANDed into the block's filter at every level,
+     * under the query's `skip`, exactly as the SQL engines AND it into each
+     * relation subquery: a block that omitted it handed back another tenant's rows.
      */
     private buildNestedBlock;
     /**
@@ -807,7 +1066,8 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * link path would regress a hot path for no gain. Requires: single-column
      * belongsTo; no relation `with` / `where` / `distinct` / `orderBy` /
      * `limit` / `offset` (a scalar path has no per-hop filter/order and cannot
-     * reproduce those, such inputs stay on the loader for exact parity); a link
+     * reproduce those, such inputs stay on the loader for exact parity); no
+     * global filter on the target, for the same reason; a link
      * name and all projected columns that are bare identifiers (a quoted segment in
      * a dotted link path is outside the verified spelling, fall back); and a
      * DECLARED link that verifiably matches (`findMatchingLink`).
@@ -841,13 +1101,28 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * it and the trailing `returning` reads it back, as is any non-string PK.
      */
     private applyPkDefault;
+    /**
+     * Fill every omitted column that declares a default, since PowDB has no
+     * column defaults of its own (its only generated value is `auto`, which is
+     * left to the engine). Without this an omitted defaulted column was written
+     * as NULL, silently, or failed NOT NULL where every SQL engine applied the
+     * default.
+     *
+     * "Omitted" means absent or `undefined` under BOTH spellings, exactly the
+     * columns a SQL insert leaves to the database; an explicit `null` stays
+     * `null`. The value comes from the column's declared default expression,
+     * evaluated per row (`now()` is the insert time). An expression this cannot
+     * evaluate faithfully, or metadata that does not carry the expression, is
+     * refused rather than guessed.
+     */
+    private applyColumnDefaults;
     /**
      * The table name as a PowQL type reference, backtick-quoted when it is a
      * reserved word (e.g. a table named `order`). Used in every emitted
      * statement; plain `this.table` stays in error messages.
      */
     private get qt();
-    create(args: CreateArgs<T>): Promise<T>;
+    create<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateArgs<T, NoRelations, S, O>): Promise<FieldResult<T, S, O>>;
     /**
      * Refuse a `createMany` whose rows do not all name the SAME fields.
      *
@@ -869,13 +1144,28 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * byte-identical PowQL.
      */
     private assertUniformCreateManyRows;
-    createMany(args: CreateManyArgs<T>): Promise<T[]>;
-    update(args: UpdateArgs<T>): Promise<T>;
+    createMany<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: CreateManyArgs<T, OptionalInput<T>, S, O>): Promise<FieldResult<T, S, O>[]>;
+    update<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpdateArgs<T, NoRelations, S, O>): Promise<FieldResult<T, S, O>>;
     updateMany(args: UpdateManyArgs<T>): Promise<{
         count: number;
     }>;
     /** Compile `data` into PowQL update assignments, including atomic operators. */
     private buildUpdateAssignments;
+    /**
+     * The atomic operator an update value names, or `null` for a plain value.
+     * The SQL engines' `setOperatorOf` rule: a plain object with EXACTLY one key
+     * from {@link UPDATE_OPERATOR_KEYS}, and on a json column only `set`, since
+     * an object there IS the document (`{ increment: 1 }` is the document
+     * `{"increment":1}`, and `{ set: doc }` writes a document shaped like
+     * `{ set: ... }`).
+     */
+    private setOperatorOf;
+    /**
+     * A one-key plain object that is not an update operator, written to a
+     * non-json column, is a misspelled operator (`{ incremnt: 1 }`): refused with
+     * the SQL engines' message rather than stored as text.
+     */
+    private assertBindableSetValue;
     private isTxScoped;
     private nestedCreate;
     private nestedUpdate;
@@ -883,11 +1173,11 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private runInImplicitTx;
     /** Already inside a transaction: build a context whose table accessors reuse the pinned pool. */
     private buildNestedCtx;
-    delete(args: DeleteArgs<T>): Promise<T>;
+    delete<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: DeleteArgs<T, NoRelations, S, O>): Promise<FieldResult<T, S, O>>;
     deleteMany(args: DeleteManyArgs<T>): Promise<{
         count: number;
     }>;
-    upsert(args: UpsertArgs<T>): Promise<T>;
+    upsert<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpsertArgs<T, NoRelations, S, O>): Promise<FieldResult<T, S, O>>;
     /**
      * `upsert` as Prisma defines it, for every shape the native `upsert … on`
      * statement cannot express: find the row `where` names, update it if it
@@ -950,8 +1240,8 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * probe-only discipline `nestedProjections` follows.
      */
     private get groupsAggregatesInOneStatement();
-    aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
-    groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
+    aggregate<A extends AggregateArgs<T>>(args: A): Promise<AggregateResultOf<T, A>>;
+    groupBy<A extends GroupByArgs<T>>(args: A): Promise<GroupByResult<T, A>[]>;
     /** Validate a JSON-path target (group key / aggregate target): non-empty array of keys/indexes. */
     private assertJsonPath;
     /**
@@ -979,19 +1269,33 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     private buildGroupOrder;
     /** Resolve a groupBy order direction, refusing `nulls: 'first'` (E017); `nulls: 'last'` is a no-op. */
     private groupOrderDir;
-    findManyStream(): AsyncGenerator<T>;
-    findManyStreamBatches(): AsyncGenerator<T[]>;
+    findManyStream(): AsyncGenerator<never, void, undefined>;
+    findManyStreamBatches(): AsyncGenerator<never, void, undefined>;
+    private deferredUnsupported;
+    buildFindMany(_args?: unknown): never;
+    buildFindFirst(_args?: unknown): never;
+    buildFindFirstOrThrow(_args?: unknown): never;
+    buildFindUnique(_args?: unknown): never;
+    buildFindUniqueOrThrow(_args?: unknown): never;
+    buildCount(_args?: unknown): never;
+    buildAggregate(_args?: unknown): never;
+    buildGroupBy(_args?: unknown): never;
+    buildCreate(_args?: unknown): never;
+    buildCreateMany(_args?: unknown): never;
+    buildUpdate(_args?: unknown): never;
+    buildUpdateMany(_args?: unknown): never;
+    buildDelete(_args?: unknown): never;
+    buildDeleteMany(_args?: unknown): never;
+    buildUpsert(_args?: unknown): never;
+    /** SQL template cache counters. PowDB keeps no statement cache, so every counter is zero. */
+    cacheStats(): {
+        hits: number;
+        misses: number;
+        hitRate: number;
+        size: number;
+    };
     /** Reselect a single row by its single-column primary key value. */
     private reselectByPk;
-    /**
-     * Empty-where guard, blocks accidental whole-table writes. Mirrors the SQL
-     * path's `assertMutationHasPredicate` (query/builder.ts): it gates on the
-     * *compiled* PowQL filter fragment, NOT the shape of the `where` object. A
-     * `where` whose conditions all evaporate during compilation, `{}`,
-     * `{ id: undefined }`, `{ OR: [] }`, `{ AND: [] }`, `{ NOT: {} }`,
-     * `{ OR: [{ f: undefined }] }`, compiles to the empty string and is refused,
-     * because emitting a filter-less write would hit every row.
-     */
     /**
      * AND this table's configured global filter (soft-delete / multi-tenancy)
      * onto an ALREADY-COMPILED user filter, pushing its params after the user's.
@@ -1012,5 +1316,44 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * column references the same way they qualify the user's.
      */
     private applyGlobalFilter;
+    /**
+     * Tables whose global filter is being resolved by an operation above this
+     * interface. A relation filter inside a global filter runs its own query on
+     * the related table, which applies THAT table's filter, so two filters that
+     * reach each other through relations would resolve forever; each table's
+     * filter applies once per chain instead.
+     */
+    private get globalFilterStack();
+    /** Whether this table's global filter constrains an operation under `skip`. */
+    private hasGlobalFilter;
+    /**
+     * This table's global filter for one operation, ready for
+     * {@link applyGlobalFilter}: read under SQL three-valued logic, with every
+     * relation filter in it (`posts: { some: ... }`, `user: { is: ... }`)
+     * resolved to a literal key list by the same client-side resolution a
+     * caller's `where` gets. The related table's own global filter bounds those
+     * lookups, as on the SQL engines, and `skip` reaches them too.
+     */
+    private globalFilterWhere;
+    /** Whether `where` holds a relation filter at any combinator depth. */
+    private namesRelation;
+    /**
+     * Empty-where guard, blocks accidental whole-table writes. Mirrors the SQL
+     * path's `assertMutationHasPredicate` (query/where.ts): it gates on the
+     * *compiled* PowQL filter fragment, NOT the shape of the `where` object, so a
+     * `where` whose conditions all evaporate during compilation (`{}`,
+     * `{ id: undefined }`, `{ AND: [] }`, `{ NOT: {} }`) is refused. A where that
+     * compiles but is TRUE for every row (`NOT: { OR: [] }`, `id: { notIn: [] }`)
+     * writes every row just the same, so `userWhere`, the caller's where before
+     * relation filters were resolved, is folded by the SQL engines' rule
+     * (`foldWhereFor`) and refused too.
+     *
+     * The fold also reads the schema's NOT NULL columns, as the SQL guard does:
+     * `{ name: { not: null } }` or `NOT: { name: null }` on a NOT NULL column is
+     * TRUE for every row (PowDB's `required` holds the same guarantee). It does
+     * NOT trust foreign keys: PowDB declares none, so an orphan row is possible
+     * and a belongsTo `is: {}` stays a condition.
+     */
     private assertCompiledWhere;
 }
+export {};