@danceroutine/tango-orm 1.2.0 → 1.4.0

package/dist/manager/internal/RuntimeBoundClient.d.ts

@@ -1,7 +1,8 @@
 import type { DBClient } from '../../connection/index';
 import type { TangoRuntime } from '../../runtime/index';
 /**
- * DB client proxy that resolves the real Tango runtime client lazily.
+ * DB client proxy that resolves either the active transaction lease or the
+ * runtime autocommit path lazily.
  */
 export declare class RuntimeBoundClient implements DBClient {
     private readonly runtime;
@@ -12,5 +13,8 @@ export declare class RuntimeBoundClient implements DBClient {
     begin(): Promise<void>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
+    createSavepoint(_name: string): Promise<void>;
+    releaseSavepoint(_name: string): Promise<void>;
+    rollbackToSavepoint(_name: string): Promise<void>;
     close(): Promise<void>;
 }

package/dist/{manager-CKUy1CIt.js → manager-C6oJ2tAF.js}

@@ -1,5 +1,5 @@
 import { __export } from "./chunk-DLY2FNSh.js";
-import { ModelManager, registerModelObjects } from "./registerModelObjects-vsX6GzCN.js";
+import { ModelManager, registerModelObjects } from "./registerModelObjects-Bva_f-Qh.js";
 
 //#region src/manager/index.ts
 var manager_exports = {};
@@ -10,4 +10,4 @@ __export(manager_exports, {
 
 //#endregion
 export { manager_exports };
-//# sourceMappingURL=manager-CKUy1CIt.js.map
+//# sourceMappingURL=manager-C6oJ2tAF.js.map

package/dist/{manager-CKUy1CIt.js.map → manager-C6oJ2tAF.js.map}

@@ -1 +1 @@
-{"version":3,"file":"manager-CKUy1CIt.js","names":[],"sources":["../src/manager/index.ts"],"sourcesContent":["/**\n * Domain boundary barrel: centralizes manager-first ORM APIs.\n */\nexport type { ManagerLike } from './ManagerLike';\nexport { ModelManager } from './ModelManager';\nexport { registerModelObjects } from './registerModelObjects';\n"],"mappings":""}
+{"version":3,"file":"manager-C6oJ2tAF.js","names":[],"sources":["../src/manager/index.ts"],"sourcesContent":["/**\n * Domain boundary barrel: centralizes manager-first ORM APIs.\n */\nexport type { ManagerLike } from './ManagerLike';\nexport { ModelManager } from './ModelManager';\nexport { registerModelObjects } from './registerModelObjects';\n"],"mappings":""}

package/dist/query/QuerySet.d.ts

@@ -6,22 +6,21 @@ import type { QNode } from './domain/QNode';
 import type { QueryResult } from './domain/QueryResult';
 import type { OrderToken } from './domain/OrderToken';
 import type { FilterInput } from './domain/FilterInput';
+import type { CompiledQuery } from './domain/CompiledQuery';
+import type { HydratedQueryResult, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, PrefetchRelatedRelations, RelationKeys, SelectRelatedRelations, SingleRelationHydrationCardinality } from './domain/RelationTyping';
 /**
  * Query execution seam consumed by `QuerySet`.
  *
  * Application code usually reaches this through `Model.objects` or testing
  * fixtures rather than implementing it directly.
  *
- * @template T - The model type
+ * @template TModel - The model row type returned by the database client
  */
-export interface QueryExecutor<T> {
+export interface QueryExecutor<TModel> {
     meta: TableMeta;
     client: DBClient;
     dialect: Dialect;
-    run(compiled: {
-        sql: string;
-        params: readonly unknown[];
-    }): Promise<T[]>;
+    run(compiled: CompiledQuery): Promise<TModel[]>;
 }
 type QueryShapeFunction<TInput, TOutput> = (row: TInput) => TOutput;
 type QueryShapeParser<TInput, TOutput> = {
@@ -32,10 +31,13 @@ type QueryShapeOutput<TInput, TShape> = TShape extends QueryShapeFunction<TInput
 type ProjectedResult<TModel extends Record<string, unknown>, TKeys extends readonly (keyof TModel)[]> = number extends TKeys['length'] ? TModel : [TKeys[number]] extends [never] ? TModel : Pick<TModel, TKeys[number]>;
 /**
  * Django-inspired query builder for constructing and executing database queries.
- * Provides a fluent API for filtering, ordering, pagination, and eager loading.
+ * Provides a fluent API for filtering, ordering, pagination, projection, and
+ * one-level relation hydration.
  *
  * @template TModel - The full model row type used for query composition
- * @template TResult - The fetched row shape returned by execution methods
+ * @template TBaseResult - The selected base-row shape returned by execution methods
+ * @template TSourceModel - The source Tango model used for typed relation metadata
+ * @template THydrated - Relation properties accumulated by eager-loading calls
  *
  * @example
  * ```typescript
@@ -48,7 +50,7 @@ type ProjectedResult<TModel extends Record<string, unknown>, TKeys extends reado
  *   .fetch();
  * ```
  */
-export declare class QuerySet<TModel extends Record<string, unknown>, TResult extends Record<string, unknown> = TModel> {
+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>> {
     private executor;
     private state;
     static readonly BRAND: "tango.orm.query_set";
@@ -63,65 +65,71 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TResult ex
      *
      * Multiple `filter()` calls are composed with `AND`.
      */
-    filter(q: FilterInput<TModel> | QNode<TModel>): QuerySet<TModel, TResult>;
+    filter(q: FilterInput<TModel> | QNode<TModel>): 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, TResult>;
+    exclude(q: FilterInput<TModel> | QNode<TModel>): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
     /**
      * Apply ordering tokens such as `'name'` or `'-createdAt'`.
      */
-    orderBy(...tokens: OrderToken<TModel>[]): QuerySet<TModel, TResult>;
+    orderBy(...tokens: OrderToken<TModel>[]): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
     /**
      * Limit the maximum number of rows returned.
      */
-    limit(n: number): QuerySet<TModel, TResult>;
+    limit(n: number): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
     /**
      * Skip the first `n` rows.
      */
-    offset(n: number): QuerySet<TModel, TResult>;
+    offset(n: number): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
     /**
-     * Restrict selected columns and narrow the fetched row type when the
+     * Restrict selected fields and narrow the fetched row type when the
      * selected keys are known precisely at the call site.
      *
      * Empty selections reset back to the full model row, and repeated
      * `select(...)` calls replace the previous projection rather than
      * intersecting it.
      */
-    select<const TKeys extends readonly (keyof TModel)[]>(cols: TKeys): QuerySet<TModel, ProjectedResult<TModel, TKeys>>;
-    select(cols: readonly (keyof TModel)[]): QuerySet<TModel, TModel>;
+    select<const TKeys extends readonly (keyof TModel)[]>(fields: TKeys): QuerySet<TModel, ProjectedResult<TModel, TKeys>, TSourceModel, THydrated>;
+    select(fields: readonly (keyof TModel)[]): QuerySet<TModel, ProjectedResult<TModel, readonly (keyof TModel)[]>, TSourceModel, THydrated>;
     /**
-     * Request SQL joins for related data when supported by relation metadata.
+     * Hydrate single-valued relations through SQL joins.
+     *
+     * Forward `belongsTo` relations can be inferred from the source model's
+     * field-authored relation metadata. Reverse `hasOne` relations can be
+     * selected with a target model generic when the target model points back to
+     * the source model.
      */
-    selectRelated(...rels: string[]): QuerySet<TModel, TResult>;
+    selectRelated<TTargetModel = undefined, const TRelationName extends RelationKeys<SelectRelatedRelations<TSourceModel, NoInfer<TTargetModel>>> = RelationKeys<SelectRelatedRelations<TSourceModel, NoInfer<TTargetModel>>>>(...rels: readonly TRelationName[]): QuerySet<TModel, TBaseResult, TSourceModel, THydrated & MaybeHydratedRelationMap<TSourceModel, SelectRelatedRelations<TSourceModel, NoInfer<TTargetModel>>, TRelationName, SingleRelationHydrationCardinality>>;
     /**
-     * Register relation names for prefetch behavior.
+     * Hydrate collection relations with a follow-up query.
      *
-     * Prefetch orchestration is adapter-specific.
+     * Reverse `hasMany` relations can be prefetched with a target model generic
+     * when the target model points back to the source model.
      */
-    prefetchRelated(...rels: string[]): QuerySet<TModel, TResult>;
+    prefetchRelated<TTargetModel = undefined, const TRelationName extends RelationKeys<PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>> = RelationKeys<PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>>>(...rels: readonly TRelationName[]): QuerySet<TModel, TBaseResult, TSourceModel, THydrated & MaybeHydratedRelationMap<TSourceModel, PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>, TRelationName, ManyRelationHydrationCardinality>>;
     /**
      * Execute the query and optionally shape each row.
      *
      * When the queryset has been narrowed by `select(...)`, rows passed to the
      * shaping callback or parser use that narrowed fetched-row type.
      */
-    fetch(): Promise<QueryResult<TResult>>;
-    fetch<Out>(shape: QueryShapeFunction<TResult, Out>): Promise<QueryResult<Out>>;
-    fetch<Out>(shape: QueryShapeParser<TResult, Out>): Promise<QueryResult<Out>>;
-    fetch<TShape extends QueryShape<TResult> | undefined>(shape: TShape): Promise<QueryResult<TResult | QueryShapeOutput<TResult, NonNullable<TShape>>>>;
+    fetch(): Promise<QueryResult<HydratedQueryResult<TBaseResult, THydrated>>>;
+    fetch<Out>(shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<QueryResult<Out>>;
+    fetch<Out>(shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<QueryResult<Out>>;
+    fetch<TShape extends QueryShape<HydratedQueryResult<TBaseResult, THydrated>> | undefined>(shape: TShape): Promise<QueryResult<HydratedQueryResult<TBaseResult, THydrated> | QueryShapeOutput<HydratedQueryResult<TBaseResult, THydrated>, NonNullable<TShape>>>>;
     /**
      * Execute the query and return the first row, or `null`.
      *
      * As with `fetch(...)`, parser and function overloads receive the current
      * fetched-row type after any `select(...)` projection narrowing.
      */
-    fetchOne(): Promise<TResult | null>;
-    fetchOne<Out>(shape: QueryShapeFunction<TResult, Out>): Promise<Out | null>;
-    fetchOne<Out>(shape: QueryShapeParser<TResult, Out>): Promise<Out | null>;
-    fetchOne<TShape extends QueryShape<TResult> | undefined>(shape: TShape): Promise<TResult | QueryShapeOutput<TResult, NonNullable<TShape>> | null>;
+    fetchOne(): Promise<HydratedQueryResult<TBaseResult, THydrated> | null>;
+    fetchOne<Out>(shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+    fetchOne<Out>(shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+    fetchOne<TShape extends QueryShape<HydratedQueryResult<TBaseResult, THydrated>> | undefined>(shape: TShape): Promise<HydratedQueryResult<TBaseResult, THydrated> | QueryShapeOutput<HydratedQueryResult<TBaseResult, THydrated>, NonNullable<TShape>> | null>;
     /**
      * Execute a `COUNT(*)` query for the current filtered state.
      */
@@ -131,6 +139,13 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TResult ex
      */
     exists(): Promise<boolean>;
     private normalizeRowsForSchemaParsing;
+    private validateHydrationState;
+    private hydrateRows;
+    private hydrateSelectedRows;
+    private hydratePrefetchedRows;
+    private fetchPrefetchGroup;
+    private normalizeTargetRow;
+    private normalizeTargetValue;
     private isBooleanColumnType;
     private normalizeSqliteBoolean;
     private normalizeBooleanColumns;

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

@@ -1,6 +1,6 @@
 import type { QuerySetState } from '../domain/QuerySetState';
 import type { TableMeta } from '../domain/TableMeta';
-import type { CompiledQuery } from '../domain/CompiledQuery';
+import type { CompiledPrefetchHydration, CompiledPrefetchQuery, CompiledQuery } from '../domain/CompiledQuery';
 import type { Dialect } from '../domain/Dialect';
 /**
  * Compiles immutable `QuerySet` state into parameterized SQL.
@@ -25,6 +25,16 @@ export declare class QueryCompiler {
      * Compile a query state tree into a SQL statement and bound parameters.
      */
     compile<T>(state: QuerySetState<T>): CompiledQuery;
+    /**
+     * Compile the follow-up query used by `prefetchRelated(...)`.
+     *
+     * The base query cannot bind source values until after it has returned rows,
+     * but SQL rendering and validation still belong to the compiler.
+     */
+    compilePrefetch(prefetch: CompiledPrefetchHydration, sourceValues: readonly (string | number)[]): CompiledPrefetchQuery;
+    private buildHydrationColumnAlias;
+    private buildPrefetchSourceAlias;
+    private assertInternalAliasDoesNotCollide;
     private compileQNode;
     private compileAtom;
     private compileAnd;

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

@@ -1,4 +1,25 @@
 export interface CompiledQuery {
     sql: string;
     params: readonly unknown[];
+    hydrations?: readonly CompiledRelationHydration[];
+    prefetches?: readonly CompiledPrefetchHydration[];
+}
+export interface CompiledRelationHydration {
+    relationName: string;
+    alias: string;
+    columns: Record<string, string>;
+}
+export interface CompiledPrefetchHydration {
+    relationName: string;
+    sourceKey: string;
+    sourceKeyAlias?: string;
+    table: string;
+    targetKey: string;
+    targetColumns: Record<string, string>;
+}
+export interface CompiledPrefetchQuery {
+    sql: string;
+    params: readonly unknown[];
+    targetKey: string;
+    targetColumns: Record<string, string>;
 }

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

@@ -3,8 +3,8 @@ export type RelationKind = (typeof InternalRelationKind)[keyof typeof InternalRe
 export interface RelationMeta {
     kind: RelationKind;
     table: string;
-    targetPk: string;
-    localKey?: string;
-    foreignKey?: string;
+    sourceKey: string;
+    targetKey: string;
+    targetColumns: Record<string, string>;
     alias: string;
 }

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

@@ -0,0 +1,74 @@
+import type { z } from 'zod';
+import type { Model, PersistedModelOutput } from '@danceroutine/tango-schema/domain';
+import type { DecoratedFieldKind, InternalDecoratedFieldKind, RelationDecoratedSchema } from '@danceroutine/tango-schema/model';
+export declare const InternalRelationHydrationCardinality: {
+    readonly SINGLE: "single";
+    readonly MANY: "many";
+};
+export type RelationHydrationCardinality = (typeof InternalRelationHydrationCardinality)[keyof typeof InternalRelationHydrationCardinality];
+export type SingleRelationHydrationCardinality = typeof InternalRelationHydrationCardinality.SINGLE;
+export type ManyRelationHydrationCardinality = typeof InternalRelationHydrationCardinality.MANY;
+export type HydratedQueryResult<TBase extends Record<string, unknown>, THydrated extends Record<string, unknown>> = [
+    keyof THydrated
+] extends [never] ? TBase : Omit<TBase, keyof THydrated> & THydrated;
+type AnyModel = Model<z.ZodObject<z.ZodRawShape>, string>;
+type ModelSchema<TModel> = TModel extends Model<infer TSchema extends z.ZodObject<z.ZodRawShape>, string> ? TSchema : never;
+type ModelShape<TModel> = ModelSchema<TModel> extends z.ZodObject<infer TShape> ? TShape : never;
+type ModelRow<TModel> = TModel extends Model<infer TSchema extends z.ZodObject<z.ZodRawShape>, string> ? PersistedModelOutput<TSchema> : never;
+type IsLiteralString<TValue> = TValue extends string ? (string extends TValue ? false : true) : false;
+type HasStrictModelKey<TModel> = TModel extends Model<z.ZodObject<z.ZodRawShape>, infer TKey> ? IsLiteralString<TKey> : false;
+export type HasStrictRelationTyping<TSourceModel> = HasStrictModelKey<TSourceModel>;
+type ModelKeysMatch<TCandidate, TExpected> = TCandidate extends Model<z.ZodObject<z.ZodRawShape>, infer TCandidateKey> ? TExpected extends Model<z.ZodObject<z.ZodRawShape>, infer TExpectedKey> ? IsLiteralString<TCandidateKey> extends true ? IsLiteralString<TExpectedKey> extends true ? [
+    TCandidateKey
+] extends [TExpectedKey] ? true : false : false : false : false : false;
+type FieldNamingHint<TKey extends string> = TKey extends `${infer TBase}Id` ? TBase : TKey extends `${infer TBase}_id` ? TBase : TKey;
+type RelationName<TKey extends string, TName> = TName extends string ? TName : FieldNamingHint<TKey>;
+type RelatedName<TName> = TName extends string ? TName : never;
+type RelationTarget<TField> = TField extends RelationDecoratedSchema<z.ZodTypeAny, DecoratedFieldKind, infer TTarget, string | undefined, string | undefined> ? TTarget : never;
+type RelationConfiguredName<TField> = TField extends RelationDecoratedSchema<z.ZodTypeAny, DecoratedFieldKind, AnyModel, infer TName, string | undefined> ? TName : undefined;
+type RelationConfiguredRelatedName<TField> = TField extends RelationDecoratedSchema<z.ZodTypeAny, DecoratedFieldKind, AnyModel, string | undefined, infer TRelatedName> ? TRelatedName : undefined;
+type RelationKindOf<TField> = TField extends RelationDecoratedSchema<z.ZodTypeAny, infer TKind, AnyModel, string | undefined, string | undefined> ? TKind : never;
+export type ForwardSingleRelations<TSourceModel> = HasStrictModelKey<TSourceModel> extends true ? {
+    [TKey in keyof ModelShape<TSourceModel> as TKey extends string ? [
+        RelationKindOf<ModelShape<TSourceModel>[TKey]>
+    ] extends [never] ? never : RelationKindOf<ModelShape<TSourceModel>[TKey]> extends typeof InternalDecoratedFieldKind.FOREIGN_KEY | typeof InternalDecoratedFieldKind.ONE_TO_ONE ? RelationTarget<ModelShape<TSourceModel>[TKey]> extends AnyModel ? RelationName<TKey, RelationConfiguredName<ModelShape<TSourceModel>[TKey]>> : never : never : never]: {
+        kind: typeof InternalDecoratedFieldKind.FOREIGN_KEY;
+        target: RelationTarget<ModelShape<TSourceModel>[TKey]>;
+    };
+} : Record<string, {
+    kind: typeof InternalDecoratedFieldKind.FOREIGN_KEY;
+    target: AnyModel;
+}>;
+export type ReverseSingleRelations<TSourceModel, TTargetModel> = HasStrictModelKey<TSourceModel> extends true ? HasStrictModelKey<TTargetModel> extends true ? {
+    [TKey in keyof ModelShape<TTargetModel> as [RelationKindOf<ModelShape<TTargetModel>[TKey]>] extends [
+        never
+    ] ? never : RelationKindOf<ModelShape<TTargetModel>[TKey]> extends typeof InternalDecoratedFieldKind.ONE_TO_ONE ? ModelKeysMatch<RelationTarget<ModelShape<TTargetModel>[TKey]>, TSourceModel> extends true ? RelatedName<RelationConfiguredRelatedName<ModelShape<TTargetModel>[TKey]>> : never : never]: {
+        kind: typeof InternalDecoratedFieldKind.ONE_TO_ONE;
+        target: TTargetModel;
+    };
+} : {} : Record<string, {
+    kind: typeof InternalDecoratedFieldKind.ONE_TO_ONE;
+    target: AnyModel;
+}>;
+export type ReverseCollectionRelations<TSourceModel, TTargetModel> = HasStrictModelKey<TSourceModel> extends true ? HasStrictModelKey<TTargetModel> extends true ? {
+    [TKey in keyof ModelShape<TTargetModel> as [RelationKindOf<ModelShape<TTargetModel>[TKey]>] extends [
+        never
+    ] ? never : RelationKindOf<ModelShape<TTargetModel>[TKey]> extends typeof InternalDecoratedFieldKind.FOREIGN_KEY ? ModelKeysMatch<RelationTarget<ModelShape<TTargetModel>[TKey]>, TSourceModel> extends true ? RelatedName<RelationConfiguredRelatedName<ModelShape<TTargetModel>[TKey]>> : never : never]: {
+        kind: typeof InternalDecoratedFieldKind.FOREIGN_KEY;
+        target: TTargetModel;
+    };
+} : {} : Record<string, {
+    kind: typeof InternalDecoratedFieldKind.FOREIGN_KEY;
+    target: AnyModel;
+}>;
+export type SelectRelatedRelations<TSourceModel, TTargetModel> = [TTargetModel] extends [undefined] ? ForwardSingleRelations<TSourceModel> : // Target generic supplied: include reverse hasOne relations discovered on that target model.
+ForwardSingleRelations<TSourceModel> & ReverseSingleRelations<TSourceModel, TTargetModel>;
+export type PrefetchRelatedRelations<TSourceModel, TTargetModel> = ReverseCollectionRelations<TSourceModel, TTargetModel>;
+export type RelationKeys<TRelations> = Extract<keyof TRelations, string>;
+export type HydratedRelationMap<TRelations, TKeys extends string, TCardinality extends RelationHydrationCardinality> = {
+    [TKey in TKeys]: TKey extends keyof TRelations ? TRelations[TKey] extends {
+        target: infer TTarget;
+    } ? TCardinality extends typeof InternalRelationHydrationCardinality.SINGLE ? ModelRow<TTarget> | null : ModelRow<TTarget>[] : never : never;
+};
+export type MaybeHydratedRelationMap<TSourceModel, TRelations, TKeys extends string, TCardinality extends RelationHydrationCardinality> = HasStrictModelKey<TSourceModel> extends true ? HydratedRelationMap<TRelations, TKeys, TCardinality> : Record<never, never>;
+export {};

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

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

package/dist/query/index.js

@@ -1,3 +1,3 @@
-import { QBuilder, QueryCompiler, QuerySet, compiler_exports, domain_exports } from "../query-BKt2nKIt.js";
+import { QBuilder, QueryCompiler, QuerySet, compiler_exports, domain_exports } from "../query-CWZ1cfjo.js";
 
 export { QBuilder as Q, QBuilder, QueryCompiler, QuerySet, compiler_exports as compiler, domain_exports as domain };