@danceroutine/tango-orm 1.7.0 → 1.8.1

package/dist/query/ModelQuerySet.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Maintainer note: model-backed and specialized relation-backed querysets
+ * share the fluent API through `QuerySet.spawn(...)`. This concrete class
+ * owns the direct "compile the accumulated state and execute it" path, while
+ * subclasses preserve specialized execution behavior by returning their own
+ * queryset family from `spawn(...)`.
+ */
+import type { QuerySetState } from './domain/QuerySetState';
+import type { QueryExecutor } from './QuerySet';
+import { QuerySet } from './QuerySet';
+/**
+ * Concrete `QuerySet` implementation returned by `Model.objects.query()`.
+ *
+ * It executes the accumulated queryset state directly against the bound
+ * model executor.
+ */
+export declare class ModelQuerySet<TModel extends Record<string, unknown>, TBaseResult extends Record<string, unknown> = TModel, TSourceModel = unknown, THydrated extends Record<string, unknown> = Record<never, never>> extends QuerySet<TModel, TBaseResult, TSourceModel, THydrated> {
+    constructor(executor: QueryExecutor<TModel>, state?: QuerySetState<TModel, TSourceModel>);
+    protected spawn<TNextBaseResult extends Record<string, unknown> = TBaseResult, TNextHydrated extends Record<string, unknown> = THydrated>(state: QuerySetState<TModel, TSourceModel>): ModelQuerySet<TModel, TNextBaseResult, TSourceModel, TNextHydrated>;
+}

package/dist/query/QBuilder.d.ts

@@ -16,14 +16,14 @@ export declare class QBuilder {
     /**
      * Combine multiple filter fragments using logical `AND`.
      */
-    static and<T>(...nodes: Array<FilterInput<T> | QNode<T>>): QNode<T>;
+    static and<T, TSourceModel = unknown>(...nodes: Array<FilterInput<T, TSourceModel> | QNode<T, TSourceModel>>): QNode<T, TSourceModel>;
     /**
      * Combine multiple filter fragments using logical `OR`.
      */
-    static or<T>(...nodes: Array<FilterInput<T> | QNode<T>>): QNode<T>;
+    static or<T, TSourceModel = unknown>(...nodes: Array<FilterInput<T, TSourceModel> | QNode<T, TSourceModel>>): QNode<T, TSourceModel>;
     /**
      * Negate a filter fragment using logical `NOT`.
      */
-    static not<T>(node: FilterInput<T> | QNode<T>): QNode<T>;
+    static not<T, TSourceModel = unknown>(node: FilterInput<T, TSourceModel> | QNode<T, TSourceModel>): QNode<T, TSourceModel>;
     private static wrapNode;
 }

package/dist/query/QuerySet.d.ts

@@ -1,12 +1,13 @@
 import type { DBClient } from '../connection/clients/DBClient';
-import type { Dialect } from './domain/Dialect';
+import type { Adapter } from '../connection/adapters/Adapter';
 import type { QuerySetState } from './domain/QuerySetState';
 import type { TableMeta } from './domain/TableMeta';
 import type { QNode } from './domain/QNode';
+import { QueryResult } from './domain/QueryResult';
 import type { OrderToken } from './domain/OrderToken';
+import type { OrderSpec } from './domain/OrderSpec';
 import type { FilterInput } from './domain/FilterInput';
 import type { CompiledQuery } from './domain/CompiledQuery';
-import { QueryResult } from './domain/QueryResult';
 import type { GeneratedHydratedRelationMap, GeneratedPrefetchRelatedPathKeys, GeneratedSelectRelatedPathKeys, HydratedQueryResult, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, PrefetchRelatedRelations, RelationKeys, SelectRelatedRelations, SingleRelationHydrationCardinality } from './domain/RelationTyping';
 /**
  * Query execution seam consumed by `QuerySet`.
@@ -19,8 +20,20 @@ import type { GeneratedHydratedRelationMap, GeneratedPrefetchRelatedPathKeys, Ge
 export interface QueryExecutor<TModel> {
     meta: TableMeta;
     client: DBClient;
-    dialect: Dialect;
+    adapter: Adapter;
     run(compiled: CompiledQuery): Promise<TModel[]>;
+    /**
+     * Optional hook invoked by `QuerySet` after a record has been
+     * materialized so executors can attach related-manager accessors
+     * (such as the many-to-many related manager) onto the record.
+     *
+     * The optional `modelKey` argument lets the executor route the attach
+     * call to the correct model when the record belongs to a related
+     * model rather than the executor's own source model. Implementations
+     * must not overwrite existing properties on the record so prior
+     * hydration assignments survive the attach pass.
+     */
+    attachPersistedRecordAccessors?(record: Record<string, unknown>, modelKey?: string): void;
 }
 type QueryShapeFunction<TInput, TOutput> = (row: TInput) => TOutput;
 type QueryShapeParser<TInput, TOutput> = {
@@ -34,12 +47,6 @@ type ProjectedResult<TModel extends Record<string, unknown>, TKeys extends reado
  * Provides a fluent API for filtering, ordering, pagination, projection, and
  * nested relation hydration.
  *
- * Refinements such as `filter`, `orderBy`, `select`, and relation loaders build
- * query state only. SQL runs when you call an evaluation method (`fetch`,
- * `fetchOne`, `count`, `exists`, or `for await` over this queryset). After the
- * first row-returning evaluation, this queryset instance reuses its cached
- * materialized result on later `fetch()` or async-iteration calls.
- *
  * @template TModel - The full model row type used for query composition
  * @template TBaseResult - The selected base-row shape returned by execution methods
  * @template TSourceModel - The source Tango model used for typed relation metadata
@@ -56,31 +63,47 @@ type ProjectedResult<TModel extends Record<string, unknown>, TKeys extends reado
  *   .fetch();
  * ```
  */
-export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResult extends Record<string, unknown> = TModel, TSourceModel = unknown, THydrated extends Record<string, unknown> = Record<never, never>> implements AsyncIterable<HydratedQueryResult<TBaseResult, THydrated>> {
+export declare abstract class QuerySet<TModel extends Record<string, unknown>, TBaseResult extends Record<string, unknown> = TModel, TSourceModel = unknown, THydrated extends Record<string, unknown> = Record<never, never>> implements AsyncIterable<HydratedQueryResult<TBaseResult, THydrated>> {
     [Symbol.asyncIterator]: () => AsyncIterator<HydratedQueryResult<TBaseResult, THydrated>>;
-    private executor;
-    private state;
+    protected executor: QueryExecutor<TModel>;
+    protected state: QuerySetState<TModel, TSourceModel>;
     static readonly BRAND: "tango.orm.query_set";
     readonly __tangoBrand: typeof QuerySet.BRAND;
     private evaluationCache?;
-    constructor(executor: QueryExecutor<TModel>, state?: QuerySetState<TModel>);
+    constructor(executor: QueryExecutor<TModel>, state?: QuerySetState<TModel, TSourceModel>);
+    /**
+     * Create another queryset of the same runtime family with the supplied
+     * query state. Concrete subclasses implement this so fluent calls keep
+     * their subclass-specific execution behavior instead of falling back to
+     * the standard queryset implementation.
+     */
+    protected abstract spawn<TNextBaseResult extends Record<string, unknown> = TBaseResult, TNextHydrated extends Record<string, unknown> = THydrated>(state: QuerySetState<TModel, TSourceModel>): QuerySet<TModel, TNextBaseResult, TSourceModel, TNextHydrated>;
     /**
      * Narrow an unknown value to `QuerySet`.
      */
     static isQuerySet<TModel extends Record<string, unknown>, TResult extends Record<string, unknown> = TModel>(value: unknown): value is QuerySet<TModel, TResult>;
+    /**
+     * Translate user-facing order tokens like `'name'` or `'-createdAt'` into
+     * the internal `OrderSpec` array used by `QuerySetState`.
+     *
+     * Exposed as `protected` so subclasses can compose the same parse logic
+     * when they need to return their own concrete type from `orderBy` without
+     * reaching into a base-class instance's protected state.
+     */
+    protected static buildOrderSpecs<T extends Record<string, unknown>>(tokens: readonly OrderToken<T>[]): OrderSpec<T>[];
     private static invertOrderSpec;
     /**
      * Add a filter expression to the query.
      *
      * Multiple `filter()` calls are composed with `AND`.
      */
-    filter(q: FilterInput<TModel> | QNode<TModel>): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
+    filter(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
     /**
      * Add an exclusion expression to the query.
      *
      * Exclusions are translated to `NOT (...)` predicates.
      */
-    exclude(q: FilterInput<TModel> | QNode<TModel>): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
+    exclude(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
     /**
      * Apply ordering tokens such as `'name'` or `'-createdAt'`.
      */
@@ -136,9 +159,10 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
     /**
      * Async iterable surface for `for await (... of queryset)`.
      *
-     * Evaluates this queryset on first use by awaiting {@link QuerySet.fetch} without arguments, then
-     * yields each element from that {@link QueryResult}. Later async iterations over the same queryset
-     * instance reuse the cached materialized result instead of issuing another database round-trip.
+     * Evaluates this queryset on first use by awaiting `fetch()` without
+     * arguments, then yields each element from that materialized result.
+     * Later async iterations over the same queryset instance reuse the cached
+     * materialized result instead of issuing another database round-trip.
      */
     [Symbol.asyncIterator](): AsyncIterator<HydratedQueryResult<TBaseResult, THydrated>>;
     /**
@@ -157,9 +181,9 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
     last(): Promise<HydratedQueryResult<TBaseResult, THydrated> | null>;
     last<Out>(shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
     last<Out>(shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
-    get(q: FilterInput<TModel> | QNode<TModel>): Promise<HydratedQueryResult<TBaseResult, THydrated>>;
-    get<Out>(q: FilterInput<TModel> | QNode<TModel>, shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out>;
-    get<Out>(q: FilterInput<TModel> | QNode<TModel>, shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out>;
+    get(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>): Promise<HydratedQueryResult<TBaseResult, THydrated>>;
+    get<Out>(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>, shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out>;
+    get<Out>(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>, shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out>;
     /**
      * Execute a `COUNT(*)` query for the current filtered state.
      */
@@ -171,10 +195,14 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
     private shapeFetchedRow;
     private getOrCreateEvaluationCache;
     private evaluateRows;
+    private normalizeRowsForSchemaParsing;
     private normalizeHydratedRowsForParserShape;
     private hydrateRows;
+    private primeManyToManyOwnerCache;
+    private attachRootRecordAccessors;
     private hydrateJoinNodesForOwner;
     private hydratePrefetchNode;
+    private chunkValues;
     private groupOwnersByAccessor;
     private canonicalizeEntity;
     private normalizeTargetRow;

package/dist/query/compiler/QueryCompiler.d.ts

@@ -1,20 +1,26 @@
 import type { QuerySetState } from '../domain/QuerySetState';
 import type { TableMeta } from '../domain/TableMeta';
 import type { CompiledHydrationNode, CompiledPrefetchQuery, CompiledQuery } from '../domain/CompiledQuery';
-import type { Dialect } from '../domain/Dialect';
+import type { Adapter } from '../../connection/adapters/Adapter';
 /**
  * Compiles immutable `QuerySet` state into parameterized SQL and recursive
  * hydration execution artifacts.
  */
 export declare class QueryCompiler {
     private meta;
-    private dialect;
+    private adapter;
     static readonly BRAND: "tango.orm.query_compiler";
     readonly __tangoBrand: typeof QueryCompiler.BRAND;
-    constructor(meta: TableMeta, dialect?: Dialect);
+    private readonly placeholders;
+    constructor(meta: TableMeta, adapter: Adapter);
     static isQueryCompiler(value: unknown): value is QueryCompiler;
-    compile<T>(state: QuerySetState<T>): CompiledQuery;
+    compile<T, TSourceModel = unknown>(state: QuerySetState<T, TSourceModel>): CompiledQuery;
     compilePrefetch(node: CompiledHydrationNode, sourceValues: readonly (string | number)[]): CompiledPrefetchQuery;
+    compileManyToManyTargets(node: CompiledHydrationNode, targetIds: readonly (string | number)[]): {
+        sql: string;
+        params: readonly unknown[];
+    };
+    private compileManyToManyPrefetch;
     private compileHydrationNode;
     private validateHydrationRelation;
     private buildRootHiddenSelects;
@@ -26,6 +32,7 @@ export declare class QueryCompiler {
     private buildPrefetchBaseAlias;
     private buildHydrationColumnAlias;
     private buildPrefetchSourceAlias;
+    private buildFilterAlias;
     private sanitizeRelationPath;
     private assertInternalAliasDoesNotCollide;
     private compileQNode;
@@ -33,6 +40,8 @@ export declare class QueryCompiler {
     private compileAnd;
     private compileOr;
     private compileNot;
+    private compileRelationFilter;
+    private buildRelationFilterExists;
     private lookupToSQL;
     private normalizeParam;
     private collectStateFilterKeys;

package/dist/query/domain/CompiledQuery.d.ts

@@ -1,42 +1,209 @@
 import type { RelationHydrationLoadMode } from './RelationMeta';
 import type { RelationHydrationCardinality } from './RelationTyping';
+import { InternalPrefetchQueryKind } from './internal/InternalPrefetchQueryKind';
+/**
+ * Result of compiling a {@link QuerySet} into an executable SQL statement plus
+ * the hydration plan the executor needs to reshape flat rows into nested
+ * relation graphs.
+ */
 export interface CompiledQuery {
+    /**
+     * Parameterized SQL string ready for `client.query(...)`. Identifiers and
+     * relation names are pre-validated; values never appear inline.
+     */
     sql: string;
+    /**
+     * Parameter values bound to the SQL statement in the same order the
+     * placeholders appear.
+     */
     params: readonly unknown[];
+    /**
+     * Optional hydration plan produced when the query declared selected or
+     * prefetched relations. Absent for plain row reads that do no
+     * relation-shaping work.
+     */
     hydrationPlan?: CompiledHydrationPlanRoot;
 }
+/**
+ * Top-level hydration plan for a compiled query. Groups the join-time
+ * hydration nodes (emitted inline with the root query) with the prefetch
+ * hydration nodes (executed as follow-up queries after the root rows land).
+ */
 export interface CompiledHydrationPlanRoot {
+    /**
+     * The relation paths the caller originally requested via
+     * `selectRelated(...)` / `prefetchRelated(...)`. Retained for diagnostic
+     * messages and snapshot stability.
+     */
     requestedPaths: readonly string[];
+    /**
+     * Column aliases on the root query that exist solely to support hydration
+     * (for example, join-mirrored primary keys). The hydrator strips these
+     * before handing rows back to application code.
+     */
     hiddenRootAliases: readonly string[];
+    /**
+     * Hydration nodes whose rows arrive joined into the root query's result
+     * set. Each node describes how to fold those joined columns back into a
+     * nested relation attribute.
+     */
     joinNodes: readonly CompiledHydrationNode[];
+    /**
+     * Hydration nodes that require a follow-up prefetch query after the root
+     * rows land. Each node drives one or more `compilePrefetch(...)` calls.
+     */
     prefetchNodes: readonly CompiledHydrationNode[];
 }
+/**
+ * Recursive description of how to hydrate one relation edge and its
+ * descendants. The same node shape is used for join-loaded and
+ * prefetch-loaded relations; {@link loadMode} distinguishes them.
+ */
 export interface CompiledHydrationNode {
+    /** Stable identifier for this node in the plan. */
     nodeId: string;
+    /**
+     * Public relation name as declared in the schema, mirrored onto the
+     * hydrated record (for example, `author` or `tags`).
+     */
     relationName: string;
+    /**
+     * Dot-less path expression that reaches this node from the root, used in
+     * error messages and plan diagnostics.
+     */
     relationPath: string;
+    /** Model key of the owner side of this edge. */
     ownerModelKey: string;
+    /** Model key of the target side of this edge. */
     targetModelKey: string;
+    /** Join-inline vs follow-up prefetch load strategy. */
     loadMode: RelationHydrationLoadMode;
+    /** Whether this edge yields one target or many. */
     cardinality: RelationHydrationCardinality;
+    /**
+     * Owner-side column whose value scopes the hydration read. For
+     * foreign-key relations this is the local column; for many-to-many this
+     * is the owner primary key.
+     */
     sourceKey: string;
+    /**
+     * Column alias on the root SQL row that surfaces `sourceKey` to the
+     * hydrator after projection.
+     */
     ownerSourceAccessor: string;
+    /**
+     * Target-side column that matches `sourceKey` during resolution.
+     */
     targetKey: string;
+    /** Target table name for the related rows. */
     targetTable: string;
+    /** Primary-key column name on the target table. */
     targetPrimaryKey: string;
+    /** Join table name for many-to-many edges. */
+    throughTable?: string;
+    /**
+     * Join-table column storing the owner-side primary key for many-to-many
+     * edges.
+     */
+    throughSourceKey?: string;
+    /**
+     * Join-table column storing the target-side primary key for many-to-many
+     * edges.
+     */
+    throughTargetKey?: string;
+    /**
+     * SQL type of the owner-side join column, used to validate compiled
+     * placeholder values.
+     */
+    throughSourceColumnType?: string;
+    /**
+     * SQL type of the target-side join column, used to validate compiled
+     * placeholder values.
+     */
+    throughTargetColumnType?: string;
+    /**
+     * Column map for the target table keyed by column name. Used by the
+     * hydrator to materialize target rows and by the compiler to emit a
+     * stable projection.
+     */
     targetColumns: Record<string, string>;
+    /**
+     * Ordered trail of relation names that led to this node. Used to produce
+     * precise error messages when a hydration plan fails to compile.
+     */
     provenance: readonly string[];
+    /** Child nodes whose rows arrive joined with this node's rows. */
     joinChildren: readonly CompiledHydrationNode[];
+    /** Child nodes that require their own follow-up prefetch. */
     prefetchChildren: readonly CompiledHydrationNode[];
+    /** SQL join descriptor attached when this node is loaded inline. */
     join?: CompiledJoinHydrationDescriptor;
 }
+/**
+ * Join-specific details for a hydration node loaded inline with its parent
+ * query. Captures the alias the compiler emitted for the joined table and
+ * the column aliases under which each projected column appears in the result
+ * row.
+ */
 export interface CompiledJoinHydrationDescriptor {
+    /** SQL alias emitted for the joined table. */
     alias: string;
+    /**
+     * Aliases for each projected target column, keyed by column name.
+     * Ensures the hydrator can pull the column out of the flat SQL row.
+     */
     columns: Record<string, string>;
 }
-export interface CompiledPrefetchQuery {
+/**
+ * Discriminated union describing a prefetch query that must run after the
+ * root rows load. `direct` is a one-shot select against the target table;
+ * `manyToMany` is a two-phase plan that first reads join rows, then loads
+ * the target rows by primary key.
+ */
+export type CompiledPrefetchQuery = {
+    /** Marks a single-query prefetch against the target table. */
+    kind: typeof InternalPrefetchQueryKind.DIRECT;
+    /** Parameterized select statement to execute. */
     sql: string;
+    /** Parameter values bound to the statement. */
     params: readonly unknown[];
+    /**
+     * Target column whose value matches the owner-side `sourceKey`. The
+     * hydrator buckets the returned rows by this column.
+     */
     targetKey: string;
+    /** Column map for the target rows the hydrator will materialize. */
     targetColumns: Record<string, string>;
-}
+} | {
+    /**
+     * Marks a two-phase many-to-many prefetch: the join-row query runs
+     * first, then a follow-up target query resolves the actual rows by
+     * primary key.
+     */
+    kind: typeof InternalPrefetchQueryKind.MANY_TO_MANY;
+    /**
+     * SQL for the first phase: select owner/target id pairs from the
+     * join table.
+     */
+    throughSql: string;
+    /** Parameter values bound to the join-row statement. */
+    throughParams: readonly unknown[];
+    /**
+     * Alias the compiler assigned to the owner-side join column in the
+     * join-row result set. The hydrator uses it to group targets by
+     * owner.
+     */
+    ownerAlias: string;
+    /**
+     * Alias the compiler assigned to the target-side join column in
+     * the join-row result set. The hydrator uses it to assemble the
+     * target primary-key list for phase two.
+     */
+    targetAlias: string;
+    /** Target table name for the phase-two read. */
+    targetTable: string;
+    /** Primary-key column on the target table for the phase-two read. */
+    targetPrimaryKey: string;
+    /** Column map for the target rows the hydrator will materialize. */
+    targetColumns: Record<string, string>;
+};

package/dist/query/domain/FilterInput.d.ts

@@ -1,3 +1,3 @@
 import type { FilterKey } from './FilterKey';
 import type { FilterValue } from './FilterValue';
-export type FilterInput<T> = Partial<Record<FilterKey<T>, FilterValue>>;
+export type FilterInput<T, TSourceModel = unknown> = Partial<Record<FilterKey<T, TSourceModel>, FilterValue>>;

package/dist/query/domain/FilterKey.d.ts

@@ -1,2 +1,4 @@
-import type { LookupType } from '.';
-export type FilterKey<T> = keyof T | `${string & keyof T}__${LookupType}`;
+import type { LookupType } from './LookupType';
+type ScalarFilterKey<T> = Extract<keyof T, string> | `${Extract<keyof T, string>}__${LookupType}`;
+export type FilterKey<T, _TSourceModel = unknown> = ScalarFilterKey<T> | string;
+export {};

package/dist/query/domain/QNode.d.ts

@@ -1,9 +1,9 @@
 import type { FilterInput } from './FilterInput';
 import type { InternalQNodeType } from './internal/InternalQNodeType';
 export type QNodeType = (typeof InternalQNodeType)[keyof typeof InternalQNodeType];
-export interface QNode<T> {
+export interface QNode<T, TSourceModel = unknown> {
     kind: QNodeType;
-    where?: FilterInput<T>;
-    nodes?: QNode<T>[];
-    node?: QNode<T>;
+    where?: FilterInput<T, TSourceModel>;
+    nodes?: QNode<T, TSourceModel>[];
+    node?: QNode<T, TSourceModel>;
 }

package/dist/query/domain/QuerySetState.d.ts

@@ -1,8 +1,8 @@
 import type { OrderSpec } from './OrderSpec';
 import type { QNode } from './QNode';
-export interface QuerySetState<T> {
-    q?: QNode<T>;
-    excludes?: QNode<T>[];
+export interface QuerySetState<T, TSourceModel = unknown> {
+    q?: QNode<T, TSourceModel>;
+    excludes?: QNode<T, TSourceModel>[];
     order?: OrderSpec<T>[];
     limit?: number;
     offset?: number;

package/dist/query/domain/RelationMeta.d.ts

@@ -36,6 +36,15 @@ export interface RelationMeta {
     sourceKey: string;
     /** Target-side column matched against the source key. */
     targetKey: string;
+    /** Many-to-many through table name when applicable. */
+    throughTable?: string;
+    throughModelKey?: string;
+    /** Many-to-many through column that matches the owner source key. */
+    throughSourceKey?: string;
+    /** Many-to-many through column that matches the target primary key. */
+    throughTargetKey?: string;
+    throughSourceColumnType?: string;
+    throughTargetColumnType?: string;
     /** Primary key column for the target model. */
     targetPrimaryKey: string;
     /** Target model columns and their storage types. */

package/dist/query/domain/RelationTyping.d.ts

@@ -1,6 +1,7 @@
 import type { z } from 'zod';
 import type { Model, PersistedModelOutput } from '@danceroutine/tango-schema/domain';
 import type { DecoratedFieldKind, InternalDecoratedFieldKind, RelationDecoratedSchema } from '@danceroutine/tango-schema/model';
+import type { ManyToManyRelatedManager } from '../../manager/relations/ManyToManyRelatedManager';
 export declare const InternalRelationHydrationCardinality: {
     readonly SINGLE: "single";
     readonly MANY: "many";
@@ -37,22 +38,68 @@ type NextSeenModels<TSeen extends readonly string[], TTargetModel> = ModelKey<TT
 type CanTraverseGeneratedTarget<TTargetModel, TSeen extends readonly string[], TCycleBudget extends readonly unknown[]> = ModelKey<TTargetModel> extends TSeen[number] ? (TCycleBudget extends [] ? false : true) : true;
 type NextGeneratedCycleBudget<TTargetModel, TSeen extends readonly string[], TCycleBudget extends readonly unknown[]> = ModelKey<TTargetModel> extends TSeen[number] ? TailTuple<TCycleBudget> : TCycleBudget;
 type GeneratedCardinalityIncludesMany<TCardinality extends RelationHydrationCardinality> = TCardinality extends typeof InternalRelationHydrationCardinality.MANY ? true : false;
+/**
+ * Generated path keys accepted by `selectRelated(...)`.
+ *
+ * Walks the ambient relation registry one hop at a time. Each hop contributes:
+ *   (a) the bare relation key (e.g. `author`) as a valid path terminus, and
+ *   (b) a dunder-joined extension (`author__profile`, ...) that recurses into
+ *       the target model.
+ *
+ * Because `selectRelated` only composes single-valued hops, the mapped type
+ * filters relations whose `cardinality` is not `SINGLE`. The `TSeen` tuple
+ * tracks which model keys the recursion has visited so cyclic schemas
+ * (`manager -> manager`) are allowed a bounded number of revisits before
+ * typing falls back to `never`. `TCycleBudget` is that revisit budget; see
+ * `CanTraverseGeneratedTarget` / `NextGeneratedCycleBudget` for how it
+ * shrinks only when the next hop actually re-enters a seen model.
+ */
 export type GeneratedSelectRelatedPathKeys<TSourceModel, TSeen extends readonly string[] = [ModelKey<TSourceModel>], TCycleBudget extends readonly unknown[] = DefaultGeneratedCycleBudget> = {
     [TKey in GeneratedRelationKeys<TSourceModel>]: GeneratedRelations<TSourceModel>[TKey] extends {
         target: infer TTarget extends AnyModel;
         cardinality: typeof InternalRelationHydrationCardinality.SINGLE;
     } ? TKey | (CanTraverseGeneratedTarget<TTarget, TSeen, TCycleBudget> extends true ? `${TKey}__${GeneratedSelectRelatedPathKeys<TTarget, NextSeenModels<TSeen, TTarget>, NextGeneratedCycleBudget<TTarget, TSeen, TCycleBudget>>}` : never) : never;
 }[GeneratedRelationKeys<TSourceModel>];
+/**
+ * Generated path keys accepted by `prefetchRelated(...)`.
+ *
+ * Similar in shape to {@link GeneratedSelectRelatedPathKeys}, but relaxes two
+ * constraints because prefetch can cross and continue past collection edges:
+ *   1. Any hop whose cardinality is `MANY` is a valid terminus. The
+ *      `THasMany` flag threads through recursion so once a collection edge
+ *      has been crossed, every subsequent hop is also a valid terminus
+ *      (matches Django's `prefetch_related` semantics).
+ *   2. Single-valued hops are still accepted as terminators so paths like
+ *      `posts__author` survive the join.
+ *
+ * Cycle handling reuses the same `TSeen` / `TCycleBudget` machinery described
+ * in {@link GeneratedSelectRelatedPathKeys}: cyclic schemas are typed up to
+ * the bound, then fall back to weaker typing rather than failing.
+ */
 export type GeneratedPrefetchRelatedPathKeys<TSourceModel, THasMany extends boolean = false, TSeen extends readonly string[] = [ModelKey<TSourceModel>], TCycleBudget extends readonly unknown[] = DefaultGeneratedCycleBudget> = {
     [TKey in GeneratedRelationKeys<TSourceModel>]: GeneratedRelations<TSourceModel>[TKey] extends {
         target: infer TTarget extends AnyModel;
         cardinality: infer TCardinality extends RelationHydrationCardinality;
     } ? (THasMany extends true ? TKey : GeneratedCardinalityIncludesMany<TCardinality> extends true ? TKey : never) | (CanTraverseGeneratedTarget<TTarget, TSeen, TCycleBudget> extends true ? `${TKey}__${GeneratedPrefetchRelatedPathKeys<TTarget, THasMany extends true ? true : GeneratedCardinalityIncludesMany<TCardinality>, NextSeenModels<TSeen, TTarget>, NextGeneratedCycleBudget<TTarget, TSeen, TCycleBudget>>}` : never) : never;
 }[GeneratedRelationKeys<TSourceModel>];
+/**
+ * Generated relation-path filter keys accepted by `filter(...)`, `exclude(...)`,
+ * and `Q(...)`.
+ *
+ * This stays intentionally lighter than the eager-loading path typing:
+ * applications with generated relation registries get completion for the
+ * relation path prefix, while the terminal field and lookup suffix remain a
+ * string tail so the compiler does not explode on deep recursive field
+ * extraction.
+ */
+export type GeneratedRelationFilterKeys<TSourceModel> = `${GeneratedSelectRelatedPathKeys<TSourceModel>}__${string}` | `${GeneratedPrefetchRelatedPathKeys<TSourceModel>}__${string}`;
 type GeneratedHydratedTarget<TDescriptor, TPath extends string | never> = TDescriptor extends {
     target: infer TTarget extends AnyModel;
 } ? [TPath] extends [never] ? ModelRow<TTarget> : HydratedQueryResult<ModelRow<TTarget>, GeneratedHydratedRelationMap<TTarget, TPath>> : never;
 type GeneratedHydratedValue<TDescriptor, TPath extends string | never> = TDescriptor extends {
+    target: infer TTarget extends AnyModel;
+    kind: 'manyToMany';
+} ? ManyToManyRelatedManager<ModelRow<TTarget>> : TDescriptor extends {
     cardinality: infer TCardinality extends RelationHydrationCardinality;
 } ? TCardinality extends typeof InternalRelationHydrationCardinality.SINGLE ? GeneratedHydratedTarget<TDescriptor, TPath> | null : GeneratedHydratedTarget<TDescriptor, TPath>[] : never;
 type GeneratedHydrationForPath<TSourceModel, TPath extends string> = SplitPath<TPath> extends [infer THead extends string, ...infer TRest extends string[]] ? THead extends GeneratedRelationKeys<TSourceModel> ? {

package/dist/query/domain/TableMetaFactory.d.ts

@@ -1,23 +1,10 @@
 import type { Model as SchemaModel } from '@danceroutine/tango-schema/domain';
 import type { TableMeta } from './TableMeta';
-type ModelMetadataLike = Omit<SchemaModel['metadata'], 'key' | 'namespace' | 'fields'> & {
-    key?: string;
-    namespace?: string;
-    fields: Array<{
-        name: string;
-        type: string;
-        primaryKey?: boolean;
-    }>;
-};
-type TableMetaModel = {
-    metadata: ModelMetadataLike;
-};
 /**
  * Build registry-backed recursive table metadata for query planning and
  * hydration execution.
  */
 export declare class TableMetaFactory {
-    static create(model: TableMetaModel): TableMeta;
+    static create(model: SchemaModel): TableMeta;
     private static createWithCache;
 }
-export {};

package/dist/query/domain/index.d.ts

@@ -14,7 +14,7 @@ export type { QNode } from './QNode';
 export { QueryResult } from './QueryResult';
 export type { QuerySetState } from './QuerySetState';
 export type { RelationMeta } from './RelationMeta';
-export type { ForwardSingleRelations, GeneratedHydratedRelationMap, GeneratedPrefetchRelatedPathKeys, GeneratedSelectRelatedPathKeys, HydratedQueryResult, HydratedRelationMap, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, PrefetchRelatedRelations, RelationKeys, RelationHydrationCardinality, ReverseCollectionRelations, ReverseSingleRelations, SelectRelatedRelations, SingleRelationHydrationCardinality, } from './RelationTyping';
+export type { ForwardSingleRelations, GeneratedRelationFilterKeys, GeneratedHydratedRelationMap, GeneratedPrefetchRelatedPathKeys, GeneratedSelectRelatedPathKeys, HydratedQueryResult, HydratedRelationMap, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, PrefetchRelatedRelations, RelationKeys, RelationHydrationCardinality, ReverseCollectionRelations, ReverseSingleRelations, SelectRelatedRelations, SingleRelationHydrationCardinality, } from './RelationTyping';
 export { InternalRelationHydrationCardinality } from './RelationTyping';
 export type { TableMeta } from './TableMeta';
 export { TableMetaFactory } from './TableMetaFactory';

package/dist/query/domain/internal/InternalPrefetchQueryKind.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Discriminator strings for compiled prefetch hydration: how `QueryCompiler.compilePrefetch`
+ * batches related rows for hydration (`CompiledPrefetchQuery`).
+ */
+export declare const InternalPrefetchQueryKind: {
+    /**
+     * Single-query prefetch against the related table (`SELECT … FROM target WHERE fk IN (...)`).
+     * Used when each related row is reachable from one physical table via a foreign key or
+     * symmetric join path (belongsTo, hasMany, hasOne, reverse one-to-one).
+     */
+    readonly DIRECT: "direct";
+    /**
+     * Two-phase many-to-many prefetch: first query reads join (through) rows pairing owner ids to
+     * target ids (`throughSql`), then target rows load by primary key (`compileManyToManyTargets`).
+     * Distinct from relation metadata’s `manyToMany` relation *kind* on an endpoint—this marks the
+     * compiled prefetch *strategy*, not the schema edge type.
+     */
+    readonly MANY_TO_MANY: "manyToMany";
+};
+export type PrefetchQueryKind = (typeof InternalPrefetchQueryKind)[keyof typeof InternalPrefetchQueryKind];

package/dist/query/index.d.ts

@@ -8,6 +8,7 @@ export type * from './domain/index';
 export type { TableMeta } from './domain/index';
 export { QueryResult } from './domain/index';
 export { QuerySet } from './QuerySet';
+export { ModelQuerySet } from './ModelQuerySet';
 export type { QueryExecutor } from './QuerySet';
 export { QBuilder, QBuilder as Q } from './QBuilder';
 export { QueryCompiler } from './compiler/index';