@danceroutine/tango-orm 1.5.0 → 1.7.0

package/dist/index.d.ts

@@ -14,9 +14,9 @@ export type { Adapter, AdapterConfig, DBClient } from './connection/index';
 export { PostgresAdapter, SqliteAdapter } from './connection/index';
 export { ModelManager } from './manager/index';
 export type { ManagerLike } from './manager/index';
-export { Q, QBuilder, QueryCompiler, QuerySet } from './query/index';
+export { Q, QBuilder, QueryCompiler, QueryResult, QuerySet } from './query/index';
 export type { QueryExecutor } from './query/index';
-export type { CompiledQuery, Dialect, Direction, FilterInput, FilterKey, FilterValue, LookupType, OrderSpec, OrderToken, QNode, QueryResult, QuerySetState, RelationMeta, TableMeta, WhereClause, } from './query/domain/index';
+export type { CompiledQuery, Dialect, Direction, FilterInput, FilterKey, FilterValue, LookupType, OrderSpec, OrderToken, QNode, QuerySetState, RelationMeta, TableMeta, WhereClause, } from './query/domain/index';
 export { getTangoRuntime, initializeTangoRuntime, resetTangoRuntime, TangoRuntime } from './runtime/index';
 export { atomic, UnitOfWork } from './transaction/index';
 export type { AtomicTransaction, OnCommitOptions, SavepointOptions, SavepointResult } from './transaction/index';

package/dist/index.js

@@ -3,11 +3,11 @@ import { PostgresAdapter } from "./PostgresAdapter-CMiEpHya.js";
 import "./SqliteClient-CjOK9-ki.js";
 import { SqliteAdapter } from "./SqliteAdapter-CeqhyrPC.js";
 import { AdapterRegistry, connectDB, connection_exports, getDefaultAdapterRegistry } from "./connection-B_K2ZAf7.js";
-import { QBuilder, QueryCompiler, QuerySet, query_exports } from "./query-DYiJ5m_B.js";
+import { QBuilder, QueryCompiler, QueryResult, QuerySet, query_exports } from "./query-FZJoSCg4.js";
 import { TangoRuntime, getTangoRuntime, initializeTangoRuntime, resetTangoRuntime } from "./defaultRuntime-BPK9kWEW.js";
-import { ModelManager } from "./registerModelObjects-B1VzZ072.js";
+import { ModelManager } from "./registerModelObjects-C-1RbUHS.js";
 import { manager_exports } from "./manager-C6oJ2tAF.js";
 import { runtime_exports } from "./runtime-ByXbpVBS.js";
 import { UnitOfWork, atomic, transaction_exports } from "./transaction-Cs0Z9tbW.js";
 
-export { AdapterRegistry, ModelManager, PostgresAdapter, QBuilder as Q, QBuilder, QueryCompiler, QuerySet, SqliteAdapter, TangoRuntime, UnitOfWork, atomic, connectDB, connection_exports as connection, getDefaultAdapterRegistry, getTangoRuntime, initializeTangoRuntime, manager_exports as manager, query_exports as query, resetTangoRuntime, runtime_exports as runtime, transaction_exports as transaction };
+export { AdapterRegistry, ModelManager, PostgresAdapter, QBuilder as Q, QBuilder, QueryCompiler, QueryResult, QuerySet, SqliteAdapter, TangoRuntime, UnitOfWork, atomic, connectDB, connection_exports as connection, getDefaultAdapterRegistry, getTangoRuntime, initializeTangoRuntime, manager_exports as manager, query_exports as query, resetTangoRuntime, runtime_exports as runtime, transaction_exports as transaction };

package/dist/manager/ManagerLike.d.ts

@@ -1,3 +1,5 @@
+import type { QNode } from '../query/domain/QNode';
+import type { FilterInput } from '../query/domain/FilterInput';
 import type { QuerySet } from '../query/index';
 import type { TableMeta } from '../query/domain/index';
 /**
@@ -6,6 +8,23 @@ import type { TableMeta } from '../query/domain/index';
 export interface ManagerLike<TModelRow extends Record<string, unknown>, TSourceModel = unknown> {
     readonly meta: TableMeta;
     query(): QuerySet<TModelRow, TModelRow, TSourceModel>;
+    all(): QuerySet<TModelRow, TModelRow, TSourceModel>;
+    getOrCreate(args: {
+        where: FilterInput<TModelRow> | QNode<TModelRow>;
+        defaults?: Partial<TModelRow>;
+    }): Promise<{
+        record: TModelRow;
+        created: boolean;
+    }>;
+    updateOrCreate(args: {
+        where: FilterInput<TModelRow> | QNode<TModelRow>;
+        defaults?: Partial<TModelRow>;
+        update?: Partial<TModelRow>;
+    }): Promise<{
+        record: TModelRow;
+        created: boolean;
+        updated: boolean;
+    }>;
     findById(id: TModelRow[keyof TModelRow]): Promise<TModelRow | null>;
     getOrThrow(id: TModelRow[keyof TModelRow]): Promise<TModelRow>;
     create(input: Partial<TModelRow>): Promise<TModelRow>;

package/dist/manager/ModelManager.d.ts

@@ -1,6 +1,7 @@
+import type { QNode } from '../query/domain/QNode';
 import type { ModelWriteHooks } from '@danceroutine/tango-schema';
 import type { Model as SchemaModel } from '@danceroutine/tango-schema/domain';
-import type { TableMeta } from '../query/domain/index';
+import type { FilterInput, TableMeta } from '../query/domain/index';
 import type { QuerySet } from '../query/index';
 import type { TangoRuntime } from '../runtime/TangoRuntime';
 import type { ManagerLike } from './ManagerLike';
@@ -39,7 +40,29 @@ export declare class ModelManager<TModelRow extends Record<string, unknown>, TSo
      */
     static isModelManager<TModelRow extends Record<string, unknown>>(value: unknown): value is ModelManager<TModelRow>;
     private static createTableMeta;
+    private static mergeCreatePayloadFromWhere;
+    private static countNonPkValues;
+    private static collectPlainFieldsFromQNode;
+    private static omitLookupKeysFromAtom;
+    private static mergeCompatiblePartials;
     query(): QuerySet<TModelRow, TModelRow, TSourceModel>;
+    all(): QuerySet<TModelRow, TModelRow, TSourceModel>;
+    getOrCreate(args: {
+        where: FilterInput<TModelRow> | QNode<TModelRow>;
+        defaults?: Partial<TModelRow>;
+    }): Promise<{
+        record: TModelRow;
+        created: boolean;
+    }>;
+    updateOrCreate(args: {
+        where: FilterInput<TModelRow> | QNode<TModelRow>;
+        defaults?: Partial<TModelRow>;
+        update?: Partial<TModelRow>;
+    }): Promise<{
+        record: TModelRow;
+        created: boolean;
+        updated: boolean;
+    }>;
     findById(id: TModelRow[keyof TModelRow]): Promise<TModelRow | null>;
     getOrThrow(id: TModelRow[keyof TModelRow]): Promise<TModelRow>;
     create(input: Partial<TModelRow>): Promise<TModelRow>;

package/dist/manager/index.js

@@ -1,8 +1,8 @@
 import "../PostgresClient-BQJZfEOT.js";
 import "../SqliteClient-CjOK9-ki.js";
-import "../query-DYiJ5m_B.js";
+import "../query-FZJoSCg4.js";
 import "../defaultRuntime-BPK9kWEW.js";
-import { ModelManager, registerModelObjects } from "../registerModelObjects-B1VzZ072.js";
+import { ModelManager, registerModelObjects } from "../registerModelObjects-C-1RbUHS.js";
 import "../manager-C6oJ2tAF.js";
 
 export { ModelManager, registerModelObjects };

package/dist/manager-C6oJ2tAF.js

@@ -1,5 +1,5 @@
 import { __export } from "./chunk-DLY2FNSh.js";
-import { ModelManager, registerModelObjects } from "./registerModelObjects-B1VzZ072.js";
+import { ModelManager, registerModelObjects } from "./registerModelObjects-C-1RbUHS.js";
 
 //#region src/manager/index.ts
 var manager_exports = {};

package/dist/query/QuerySet.d.ts

@@ -3,10 +3,10 @@ import type { Dialect } from './domain/Dialect';
 import type { QuerySetState } from './domain/QuerySetState';
 import type { TableMeta } from './domain/TableMeta';
 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 { 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`.
@@ -34,6 +34,12 @@ 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
@@ -50,16 +56,19 @@ 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>> {
+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>> {
+    [Symbol.asyncIterator]: () => AsyncIterator<HydratedQueryResult<TBaseResult, THydrated>>;
     private executor;
     private state;
     static readonly BRAND: "tango.orm.query_set";
     readonly __tangoBrand: typeof QuerySet.BRAND;
+    private evaluationCache?;
     constructor(executor: QueryExecutor<TModel>, state?: QuerySetState<TModel>);
     /**
      * 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>;
+    private static invertOrderSpec;
     /**
      * Add a filter expression to the query.
      *
@@ -113,6 +122,7 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
      * app-local registry current.
      */
     prefetchRelated<TTargetModel = undefined, const TRelationName extends RelationKeys<PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>> | GeneratedPrefetchRelatedPathKeys<TSourceModel> = RelationKeys<PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>> | GeneratedPrefetchRelatedPathKeys<TSourceModel>>(...rels: readonly TRelationName[]): QuerySet<TModel, TBaseResult, TSourceModel, THydrated & MaybeHydratedRelationMap<TSourceModel, PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>, Extract<TRelationName, RelationKeys<PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>>>, ManyRelationHydrationCardinality> & GeneratedHydratedRelationMap<TSourceModel, Extract<TRelationName, GeneratedPrefetchRelatedPathKeys<TSourceModel>>>>;
+    all(): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
     /**
      * Execute the query and optionally shape each row.
      *
@@ -123,6 +133,14 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
     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>>>>;
+    /**
+     * 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.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<HydratedQueryResult<TBaseResult, THydrated>>;
     /**
      * Execute the query and return the first row, or `null`.
      *
@@ -133,6 +151,15 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
     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>;
+    first(): Promise<HydratedQueryResult<TBaseResult, THydrated> | null>;
+    first<Out>(shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+    first<Out>(shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+    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>;
     /**
      * Execute a `COUNT(*)` query for the current filtered state.
      */
@@ -141,7 +168,10 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
      * Return whether at least one row matches the current query state.
      */
     exists(): Promise<boolean>;
-    private normalizeRowsForSchemaParsing;
+    private shapeFetchedRow;
+    private getOrCreateEvaluationCache;
+    private evaluateRows;
+    private normalizeHydratedRowsForParserShape;
     private hydrateRows;
     private hydrateJoinNodesForOwner;
     private hydratePrefetchNode;

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

@@ -1,4 +1,35 @@
-export interface QueryResult<T> {
-    results: T[];
-    nextCursor?: string | null;
+/**
+ * Values materialized by {@link QuerySet.fetch}, iterable like an array plus `length`, `map`, `at`, and `toArray`.
+ *
+ * Prefer iteration or `items` over the deprecated `results` getter, which warns once per process when accessed.
+ */
+export declare class QueryResult<T> implements Iterable<T> {
+    /**
+     * Sync iteration over materialized rows.
+     */
+    [Symbol.iterator]: () => Iterator<T>;
+    static readonly BRAND: "tango.orm.query_result";
+    readonly __tangoBrand: typeof QueryResult.BRAND;
+    readonly items: readonly T[];
+    constructor(items: readonly T[]);
+    /**
+     * Runtime narrowing for values that may be a plain array or a `QueryResult` instance.
+     */
+    static isQueryResult<T>(value: unknown): value is QueryResult<T>;
+    /**
+     * Sync iteration over materialized rows.
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /** Number of materialized rows. */
+    get length(): number;
+    /** Same as `Array#map` on the materialized rows. */
+    map<U>(callbackfn: (value: T, index: number, array: readonly T[]) => U, thisArg?: unknown): U[];
+    /** Indexed read with support for negative indices, like `Array#at`. */
+    at(index: number): T | undefined;
+    /** Returns a shallow copy of the materialized rows as a plain array. */
+    toArray(): T[];
+    /**
+     * @deprecated Use iteration, `length`, `map`, or `toArray()` instead.
+     */
+    get results(): readonly T[];
 }

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

@@ -11,7 +11,7 @@ export type { LookupType } from './LookupType';
 export type { OrderSpec } from './OrderSpec';
 export type { OrderToken } from './OrderToken';
 export type { QNode } from './QNode';
-export type { QueryResult } from './QueryResult';
+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';

package/dist/query/index.d.ts

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

package/dist/query/index.js

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

package/dist/query/internal/isQNodeLike.d.ts

@@ -0,0 +1,3 @@
+import type { FilterInput } from '../domain/FilterInput';
+import type { QNode } from '../domain/QNode';
+export declare function isQNodeLike<T>(value: FilterInput<T> | QNode<T>): value is QNode<T>;

package/dist/{query-DYiJ5m_B.js → query-FZJoSCg4.js}

@@ -1,7 +1,16 @@
 import { __export } from "./chunk-DLY2FNSh.js";
-import { SqlSafetyEngine, isError } from "@danceroutine/tango-core";
+import { MultipleObjectsReturned, NotFoundError, SqlSafetyEngine, getLogger, isError } from "@danceroutine/tango-core";
 import { ModelRegistry } from "@danceroutine/tango-schema";
 
+//#region src/query/domain/internal/InternalQNodeType.ts
+const InternalQNodeType = {
+	ATOM: "atom",
+	AND: "and",
+	OR: "or",
+	NOT: "not"
+};
+
+//#endregion
 //#region src/query/domain/internal/InternalRelationKind.ts
 const InternalRelationKind = {
 	HAS_MANY: "hasMany",
@@ -83,15 +92,6 @@ const InternalDialect = {
 	SQLITE: "sqlite"
 };
 
-//#endregion
-//#region src/query/domain/internal/InternalQNodeType.ts
-const InternalQNodeType = {
-	ATOM: "atom",
-	AND: "and",
-	OR: "or",
-	NOT: "not"
-};
-
 //#endregion
 //#region src/query/domain/internal/InternalLookupType.ts
 const InternalLookupType = {
@@ -755,11 +755,62 @@ var QueryCompiler = class QueryCompiler {
 var compiler_exports = {};
 __export(compiler_exports, { QueryCompiler: () => QueryCompiler });
 
+//#endregion
+//#region src/query/domain/QueryResult.ts
+let didWarnDeprecatedResults = false;
+var QueryResult = class QueryResult {
+	static BRAND = "tango.orm.query_result";
+	__tangoBrand = QueryResult.BRAND;
+	items;
+	constructor(items) {
+		this.items = items;
+	}
+	/**
+	* Runtime narrowing for values that may be a plain array or a `QueryResult` instance.
+	*/
+	static isQueryResult(value) {
+		return typeof value === "object" && value !== null && value.__tangoBrand === QueryResult.BRAND;
+	}
+	/**
+	* Sync iteration over materialized rows.
+	*/
+	[Symbol.iterator]() {
+		return this.items[Symbol.iterator]();
+	}
+	/** Number of materialized rows. */
+	get length() {
+		return this.items.length;
+	}
+	/** Same as `Array#map` on the materialized rows. */
+	map(callbackfn, thisArg) {
+		return this.items.map(callbackfn, thisArg);
+	}
+	/** Indexed read with support for negative indices, like `Array#at`. */
+	at(index) {
+		return this.items.at(index);
+	}
+	/** Returns a shallow copy of the materialized rows as a plain array. */
+	toArray() {
+		return [...this.items];
+	}
+	/**
+	* @deprecated Use iteration, `length`, `map`, or `toArray()` instead.
+	*/
+	get results() {
+		if (!didWarnDeprecatedResults) {
+			didWarnDeprecatedResults = true;
+			getLogger("tango.orm.query_result").warn("`QueryResult.results` is deprecated. Use iteration, `length`, `map`, or `toArray()` instead.");
+		}
+		return this.items;
+	}
+};
+
 //#endregion
 //#region src/query/domain/index.ts
 var domain_exports = {};
 __export(domain_exports, {
 	InternalRelationHydrationCardinality: () => InternalRelationHydrationCardinality,
+	QueryResult: () => QueryResult,
 	TableMetaFactory: () => TableMetaFactory
 });
 
@@ -770,6 +821,19 @@ const InternalDirection = {
 	DESC: "desc"
 };
 
+//#endregion
+//#region src/query/internal/isQNodeLike.ts
+function isQNodeLike(value) {
+	if (typeof value !== "object" || value === null || "__tangoBrand" in value) return false;
+	switch (value.kind) {
+		case InternalQNodeType.ATOM: return "where" in value;
+		case InternalQNodeType.AND:
+		case InternalQNodeType.OR: return Array.isArray(value.nodes);
+		case InternalQNodeType.NOT: return "node" in value;
+		default: return false;
+	}
+}
+
 //#endregion
 //#region src/query/QBuilder.ts
 var QBuilder = class QBuilder {
@@ -809,7 +873,7 @@ var QBuilder = class QBuilder {
 		};
 	}
 	static wrapNode(input) {
-		if (input.kind) return input;
+		if (isQNodeLike(input)) return input;
 		return {
 			kind: InternalQNodeType.ATOM,
 			where: input
@@ -822,6 +886,7 @@ var QBuilder = class QBuilder {
 var QuerySet = class QuerySet {
 	static BRAND = "tango.orm.query_set";
 	__tangoBrand = QuerySet.BRAND;
+	evaluationCache;
 	constructor(executor, state = {}) {
 		this.executor = executor;
 		this.state = state;
@@ -832,13 +897,20 @@ var QuerySet = class QuerySet {
 	static isQuerySet(value) {
 		return typeof value === "object" && value !== null && value.__tangoBrand === QuerySet.BRAND;
 	}
+	static invertOrderSpec(order) {
+		if (!order?.length) return [];
+		return order.map((spec) => ({
+			by: spec.by,
+			dir: spec.dir === InternalDirection.ASC ? InternalDirection.DESC : InternalDirection.ASC
+		}));
+	}
 	/**
 	* Add a filter expression to the query.
 	*
 	* Multiple `filter()` calls are composed with `AND`.
 	*/
 	filter(q) {
-		const wrapped = q.kind ? q : {
+		const wrapped = isQNodeLike(q) ? q : {
 			kind: InternalQNodeType.ATOM,
 			where: q
 		};
@@ -854,7 +926,7 @@ var QuerySet = class QuerySet {
 	* Exclusions are translated to `NOT (...)` predicates.
 	*/
 	exclude(q) {
-		const wrapped = q.kind ? q : {
+		const wrapped = isQNodeLike(q) ? q : {
 			kind: InternalQNodeType.ATOM,
 			where: q
 		};
@@ -937,23 +1009,61 @@ var QuerySet = class QuerySet {
 			prefetchRelated: [...rels]
 		});
 	}
+	all() {
+		return new QuerySet(this.executor, { ...this.state });
+	}
 	async fetch(shape) {
-		const compiler = new QueryCompiler(this.executor.meta, this.executor.dialect);
-		const compiled = compiler.compile(this.state);
-		const rows = await this.executor.run(compiled);
-		const normalizedRows = this.normalizeRowsForSchemaParsing(rows, shape);
-		const hydratedRows = await this.hydrateRows(normalizedRows, compiled);
-		const projectedRows = hydratedRows;
-		const results = !shape ? projectedRows : typeof shape === "function" ? projectedRows.map(shape) : projectedRows.map((r) => shape.parse(r));
-		return {
-			results,
-			nextCursor: null
-		};
+		const baseResult = await this.getOrCreateEvaluationCache();
+		if (!shape) return baseResult;
+		const results = typeof shape === "function" ? baseResult.items.map(shape) : this.normalizeHydratedRowsForParserShape(baseResult.items).map((row) => shape.parse(row));
+		return new QueryResult(results);
+	}
+	/**
+	* 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.
+	*/
+	async *[Symbol.asyncIterator]() {
+		const result = await this.fetch();
+		for (const row of result) yield row;
 	}
 	async fetchOne(shape) {
 		const limited = this.limit(1);
 		const result = !shape ? await limited.fetch() : typeof shape === "function" ? await limited.fetch(shape) : await limited.fetch(shape);
-		return result.results[0] ?? null;
+		for (const row of result) return row;
+		return null;
+	}
+	async first(shape) {
+		return this.fetchOne(shape);
+	}
+	async last(shape) {
+		if (this.state.limit !== undefined || this.state.offset !== undefined) {
+			const page = await this.fetch();
+			const row = page.at(-1);
+			if (!row) return null;
+			return this.shapeFetchedRow(row, shape);
+		}
+		const invertedOrder = QuerySet.invertOrderSpec(this.state.order);
+		const effectiveOrder = invertedOrder.length > 0 ? invertedOrder : [{
+			by: this.executor.meta.pk,
+			dir: InternalDirection.DESC
+		}];
+		const qs = new QuerySet(this.executor, {
+			...this.state,
+			order: effectiveOrder
+		});
+		return qs.limit(1).fetchOne(shape);
+	}
+	async get(q, shape) {
+		const limited = this.filter(q).limit(2);
+		const page = await limited.fetch();
+		const rows = page.items;
+		const count = rows.length;
+		if (count === 0) throw new NotFoundError(`${this.executor.meta.table}: no matching record`);
+		if (count > 1) throw new MultipleObjectsReturned(`${this.executor.meta.table}: more than one matching record`);
+		return this.shapeFetchedRow(rows[0], shape);
 	}
 	/**
 	* Execute a `COUNT(*)` query for the current filtered state.
@@ -972,10 +1082,31 @@ var QuerySet = class QuerySet {
 		const count = await this.count();
 		return count > 0;
 	}
-	normalizeRowsForSchemaParsing(rows, shape) {
-		if (!shape || typeof shape === "function" || this.executor.dialect !== InternalDialect.SQLITE) return rows;
+	shapeFetchedRow(row, shape) {
+		if (!shape) return row;
+		if (typeof shape === "function") return shape(row);
+		const normalizedRow = this.normalizeHydratedRowsForParserShape([row])[0] ?? row;
+		return shape.parse(normalizedRow);
+	}
+	getOrCreateEvaluationCache() {
+		if (!this.evaluationCache) this.evaluationCache = this.evaluateRows().catch((error) => {
+			this.evaluationCache = undefined;
+			throw error;
+		});
+		return this.evaluationCache;
+	}
+	async evaluateRows() {
+		const compiler = new QueryCompiler(this.executor.meta, this.executor.dialect);
+		const compiled = compiler.compile(this.state);
+		const rows = await this.executor.run(compiled);
+		const hydratedRows = await this.hydrateRows(rows, compiled);
+		const projectedRows = hydratedRows;
+		return new QueryResult(projectedRows);
+	}
+	normalizeHydratedRowsForParserShape(rows) {
+		if (this.executor.dialect !== InternalDialect.SQLITE) return [...rows];
 		const booleanColumns = Object.entries(this.executor.meta.columns).filter(([, value]) => this.isBooleanColumnType(value)).map(([column]) => column);
-		if (booleanColumns.length === 0) return rows;
+		if (booleanColumns.length === 0) return [...rows];
 		return rows.map((row) => this.normalizeBooleanColumns(row, booleanColumns));
 	}
 	async hydrateRows(rows, compiled) {
@@ -1115,11 +1246,12 @@ __export(query_exports, {
 	Q: () => QBuilder,
 	QBuilder: () => QBuilder,
 	QueryCompiler: () => QueryCompiler,
+	QueryResult: () => QueryResult,
 	QuerySet: () => QuerySet,
 	compiler: () => compiler_exports,
 	domain: () => domain_exports
 });
 
 //#endregion
-export { OrmSqlSafetyAdapter, QBuilder, QueryCompiler, QuerySet, TableMetaFactory, compiler_exports, domain_exports, query_exports };
-//# sourceMappingURL=query-DYiJ5m_B.js.map
+export { InternalQNodeType, OrmSqlSafetyAdapter, QBuilder, QueryCompiler, QueryResult, QuerySet, TableMetaFactory, compiler_exports, domain_exports, isQNodeLike, query_exports };
+//# sourceMappingURL=query-FZJoSCg4.js.map