@guren/orm 2.4.0 → 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -65,6 +65,17 @@ interface QueryBuilderOptions {
65
65
  selectFields?: readonly string[];
66
66
  trx?: unknown;
67
67
  }
68
+ /**
69
+ * A callback that further constrains the query used to fetch an eager-loaded
70
+ * relation. Registered through the object form of {@link QueryBuilder.with}.
71
+ */
72
+ type EagerLoadConstraint = (q: QueryBuilder) => void;
73
+ /**
74
+ * Constraint callbacks keyed by the relation path they constrain. A key names
75
+ * the exact level it applies to: `posts` constrains the head, `posts.comments`
76
+ * constrains the leaf.
77
+ */
78
+ type EagerLoadConstraints = ReadonlyMap<string, EagerLoadConstraint>;
68
79
  /**
69
80
  * Fluent query builder for the Guren ORM.
70
81
  *
@@ -192,6 +203,20 @@ declare class QueryBuilder<TRecord extends PlainObject = PlainObject, TResult ex
192
203
  * Supports string names, arrays, dot notation for nested relations,
193
204
  * and constraint callbacks.
194
205
  *
206
+ * A constraint callback receives the query builder used to fetch that
207
+ * relation, and runs after the foreign-key filter is already on it, so a
208
+ * `where()` narrows that filter. Each object key constrains exactly the
209
+ * level it names, in any order: `posts` constrains the head,
210
+ * `posts.comments` constrains the leaf and leaves `posts` unfiltered.
211
+ *
212
+ * Three things behave differently than they may look:
213
+ * - `orWhere()` at the top level of a callback *widens* the query rather
214
+ * than narrowing it, because it ORs against the foreign-key filter. Group
215
+ * it (`q.where((g) => g.where(...).orWhere(...))`) to keep it contained.
216
+ * - `select()` must include the column the relation is keyed on, or the
217
+ * loader cannot match rows back to their parent and the relation is empty.
218
+ * - `limit()` applies to the single batched query, not per parent record.
219
+ *
195
220
  * @example
196
221
  * // Simple
197
222
  * await User.where('active', true).with('posts').get()
@@ -201,8 +226,16 @@ declare class QueryBuilder<TRecord extends PlainObject = PlainObject, TResult ex
201
226
  *
202
227
  * // Nested (dot notation)
203
228
  * await User.where('active', true).with('posts.comments').get()
229
+ *
230
+ * // Constrained
231
+ * await User.newQuery().with({ posts: (q) => q.where('published', true) }).get()
232
+ *
233
+ * // Constrained at both levels
234
+ * await User.newQuery()
235
+ * .with({ posts: (q) => q.where('published', true), 'posts.comments': (q) => q.orderBy('id') })
236
+ * .get()
204
237
  */
205
- with(...relations: (string | Record<string, (q: QueryBuilder<any>) => void>)[]): this;
238
+ with(...relations: (string | Record<string, EagerLoadConstraint>)[]): this;
206
239
  /**
207
240
  * Execute the query and return all matching records.
208
241
  * @returns Array of matching records
@@ -313,8 +346,15 @@ declare class QueryBuilder<TRecord extends PlainObject = PlainObject, TResult ex
313
346
  /**
314
347
  * Load eager relations onto fetched results.
315
348
  * Supports dot notation for nested relations at any depth
316
- * (e.g., 'posts.comments.author') — the full path is delegated to
317
- * Model.loadRelationInto, which recurses through the relation chain.
349
+ * (e.g., 'posts.comments.author') — the paths are delegated to
350
+ * Model.loadRelationsInto, which recurses through the relation chain.
351
+ * Constraint callbacks registered by the object form of `with()` travel
352
+ * alongside, keyed by the path segment each one constrains.
353
+ *
354
+ * The builder's `trx` goes with it: a relation loaded for rows read inside
355
+ * a transaction has to be read on that same handle, or the parents come
356
+ * from the transaction and their children from the pool — which on
357
+ * Postgres/MySQL means uncommitted parents get a null relation back.
318
358
  */
319
359
  private readonly loadEagerRelations;
320
360
  }
@@ -916,7 +956,7 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
916
956
  * const post = await Post.findWith(1, 'author')
917
957
  * const post = await Post.findWith(1, ['author', 'tags'])
918
958
  */
919
- static findWith<T extends typeof Model, K extends RelationPath<T>>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], relations: K | readonly K[], key?: keyof TRecordFor<T> & string): Promise<(TRecordFor<T> & RelationTypePick<T, K | readonly K[]>) | null>;
959
+ static findWith<T extends typeof Model, K extends RelationPath<T>>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], relations: K | readonly K[], key?: keyof TRecordFor<T> & string, queryOptions?: ModelQueryOptions): Promise<(TRecordFor<T> & RelationTypePick<T, K | readonly K[]>) | null>;
920
960
  /**
921
961
  * Find a record by primary key with eager-loaded relations, or throw.
922
962
  *
@@ -931,7 +971,7 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
931
971
  * const post = await Post.findWithOrFail(1, ['author', 'tags'])
932
972
  * const post = await Post.findWithOrFail(1, 'comments.author') // nested
933
973
  */
934
- static findWithOrFail<T extends typeof Model, K extends RelationPath<T>>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], relations: K | readonly K[], key?: keyof TRecordFor<T> & string): Promise<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>;
974
+ static findWithOrFail<T extends typeof Model, K extends RelationPath<T>>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], relations: K | readonly K[], key?: keyof TRecordFor<T> & string, queryOptions?: ModelQueryOptions): Promise<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>;
935
975
  /**
936
976
  * Get the first record matching the conditions.
937
977
  *
@@ -1211,7 +1251,7 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
1211
1251
  * // result.data - Users with their posts loaded
1212
1252
  * // result.meta - Pagination metadata
1213
1253
  */
1214
- static withPaginate<T extends typeof Model, K extends RelationPath<T>>(this: T, relations: K | readonly K[], options?: PaginateOptions<TRecordFor<T>>): Promise<PaginatedResult<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>>;
1254
+ static withPaginate<T extends typeof Model, K extends RelationPath<T>>(this: T, relations: K | readonly K[], options?: PaginateOptions<TRecordFor<T>>, queryOptions?: ModelQueryOptions): Promise<PaginatedResult<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>>;
1215
1255
  /**
1216
1256
  * Create a new record.
1217
1257
  *
@@ -1309,7 +1349,7 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
1309
1349
  * // Nested relations via dot notation
1310
1350
  * const usersWithPostComments = await User.with('posts.comments')
1311
1351
  */
1312
- static with<T extends typeof Model, K extends RelationPath<T>>(this: T, relations: K | readonly K[], where?: WhereClauseFor<T>): Promise<Array<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>>;
1352
+ static with<T extends typeof Model, K extends RelationPath<T>>(this: T, relations: K | readonly K[], where?: WhereClauseFor<T>, queryOptions?: ModelQueryOptions): Promise<Array<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>>;
1313
1353
  /**
1314
1354
  * Fetch records with related record counts attached as `${name}Count`.
1315
1355
  * Counts hasMany/hasOne/morphMany children per record without attaching
@@ -1319,21 +1359,43 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
1319
1359
  * const users = await User.withCount('posts')
1320
1360
  * users[0].postsCount // number
1321
1361
  */
1322
- static withCount<T extends typeof Model, K extends RelationKey<T>>(this: T, relations: K | readonly K[], where?: WhereClauseFor<T>): Promise<Array<TRecordFor<T> & RelationCountPick<K | readonly K[]>>>;
1362
+ static withCount<T extends typeof Model, K extends RelationKey<T>>(this: T, relations: K | readonly K[], where?: WhereClauseFor<T>, queryOptions?: ModelQueryOptions): Promise<Array<TRecordFor<T> & RelationCountPick<K | readonly K[]>>>;
1323
1363
  /** @internal Attaches a `${name}Count` field for one relation. */
1324
- protected static loadRelationCountInto<T extends typeof Model>(this: T, records: Array<PlainObject>, relationName: string): Promise<void>;
1364
+ protected static loadRelationCountInto<T extends typeof Model>(this: T, records: Array<PlainObject>, relationName: string, queryOptions?: ModelQueryOptions): Promise<void>;
1325
1365
  /**
1326
1366
  * @internal Used by QueryBuilder for eager loading.
1327
1367
  * Supports nested paths with dot notation, e.g. `posts.comments`.
1368
+ *
1369
+ * Paths are grouped by their head segment so a relation shared by several
1370
+ * paths is loaded exactly once. Walking `posts.comments` and `posts.tags`
1371
+ * independently would load `posts` twice, and the loaders assign fresh
1372
+ * spread copies — so the second pass would replace the very row objects the
1373
+ * first had already attached children to, and only the last path would
1374
+ * survive.
1375
+ */
1376
+ static loadRelationsInto<T extends typeof Model>(this: T, records: Array<PlainObject>, relationNames: readonly string[], queryOptions?: ModelQueryOptions, constraints?: EagerLoadConstraints, pathPrefix?: string): Promise<void>;
1377
+ /**
1378
+ * @internal Public since it is reachable from generated code; kept for
1379
+ * backwards compatibility now that the eager loader walks whole path lists.
1380
+ * Internal callers should use {@link loadRelationsInto} instead.
1381
+ */
1382
+ static loadRelationInto<T extends typeof Model>(this: T, records: Array<PlainObject>, relationName: string, queryOptions?: ModelQueryOptions, constraints?: EagerLoadConstraints, pathPrefix?: string): Promise<void>;
1383
+ /**
1384
+ * Load one relation level and recurse into the tails beneath it.
1385
+ *
1386
+ * `constraints` are keyed by the full path of the level each one constrains,
1387
+ * so `pathPrefix` accumulates the path walked so far as the recursion
1388
+ * descends: at `posts.comments` the leaf looks itself up under that whole
1389
+ * key, not under `comments`.
1328
1390
  */
1329
- static loadRelationInto<T extends typeof Model>(this: T, records: Array<PlainObject>, relationName: string): Promise<void>;
1330
- protected static loadHasMany(records: Array<PlainObject>, definition: HasManyRelationDefinition): Promise<void>;
1331
- protected static loadHasOne(records: Array<PlainObject>, definition: HasOneRelationDefinition): Promise<void>;
1332
- protected static loadBelongsTo(records: Array<PlainObject>, definition: BelongsToRelationDefinition): Promise<void>;
1333
- protected static loadBelongsToMany(records: Array<PlainObject>, definition: BelongsToManyRelationDefinition): Promise<void>;
1334
- protected static loadHasManyThrough(records: Array<PlainObject>, definition: HasManyThroughRelationDefinition): Promise<void>;
1335
- protected static loadMorphMany(records: Array<PlainObject>, definition: MorphManyRelationDefinition): Promise<void>;
1336
- protected static loadMorphTo(records: Array<PlainObject>, definition: MorphToRelationDefinition): Promise<void>;
1391
+ protected static loadRelationLevel<T extends typeof Model>(this: T, records: Array<PlainObject>, head: string, tails: readonly string[], queryOptions?: ModelQueryOptions, constraints?: EagerLoadConstraints, pathPrefix?: string): Promise<void>;
1392
+ protected static loadHasMany(records: Array<PlainObject>, definition: HasManyRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
1393
+ protected static loadHasOne(records: Array<PlainObject>, definition: HasOneRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
1394
+ protected static loadBelongsTo(records: Array<PlainObject>, definition: BelongsToRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
1395
+ protected static loadBelongsToMany(records: Array<PlainObject>, definition: BelongsToManyRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
1396
+ protected static loadHasManyThrough(records: Array<PlainObject>, definition: HasManyThroughRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
1397
+ protected static loadMorphMany(records: Array<PlainObject>, definition: MorphManyRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
1398
+ protected static loadMorphTo(records: Array<PlainObject>, definition: MorphToRelationDefinition, queryOptions?: ModelQueryOptions, constraint?: EagerLoadConstraint): Promise<void>;
1337
1399
  }
1338
1400
  type TRecordFor<T extends typeof Model> = T extends {
1339
1401
  recordType: infer R;
@@ -1908,4 +1970,4 @@ declare function serializeRecord(record: PlainObject, options: {
1908
1970
  /** Serialize an array of records. */
1909
1971
  declare function serializeRecords(records: PlainObject[], options: Parameters<typeof serializeRecord>[1]): PlainObject[];
1910
1972
 
1911
- export { type AccessorDefinitions, type AccessorFn, type AwsDataApiDatabase, type AwsDataApiDatabaseOptions, type AwsDataApiSeederContext, type BelongsToManyRecord, type BelongsToManyRelationResult, type BelongsToRecord, type BelongsToRelationResult, type BelongsToRequiredRecord, type CastType, type D1DatabaseHandle, type D1DatabaseOptions, DrizzleAdapter, type FindManyOptions, GlobalScopeRegistry, type GroupCondition, type HasManyRecord, type HasManyRelationResult, type HasManyThroughRecord, type HasManyThroughRelationResult, type HasOneRecord, type HasOneRelationResult, type HookCallback, type HookName, type InferModelInsert, type InferModelRecord, MassAssignmentException, type MigrationStatusEntry, Model, type ModelHooks, ModelNotFoundException, type ModelObserver, type ModelObserverConstructor, type ModelPaginationMeta, type MorphManyRecord, type MorphManyRelationResult, type MorphToRecord, type MorphToRelationResult, type MutatorDefinitions, type MutatorFn, type MySqlDatabase, type MySqlDatabaseOptions, type MySqlSeederContext, type ORMAdapter, type ORMAdapterAdvanced, type OrderByClause, type OrderByInput, type OrderDefinition, type OrderDirection, type PaginateOptions, type PaginatedResult, type PlainObject, type PostgresDatabase, type PostgresDatabaseOptions, type PostgresSeederContext, QueryBuilder, type QueryBuilderOptions, type ScopeFunction, type SeederContext, type SeederHandler, type SimpleCondition, SoftDeletes, type SoftDeletesStatic, type SqliteDatabase, type SqliteDatabaseOptions, type SqliteSeederContext, type TransactionHandle, type TransactionModelScope, type WhereClause, type WhereCondition, type WhereGroupCallback, type WhereOperator, type WithRelations, applyAccessors, applyMutators, buildDrizzleConditions, createAwsDataApiDatabase, createD1Database, createMySqlDatabase, createPostgresDatabase, createSqliteDatabase, defineModel, defineSeeder, executeHook, executeObservers, loadSeeders, runSeeders, serializeRecord, serializeRecords };
1973
+ export { type AccessorDefinitions, type AccessorFn, type AwsDataApiDatabase, type AwsDataApiDatabaseOptions, type AwsDataApiSeederContext, type BelongsToManyRecord, type BelongsToManyRelationResult, type BelongsToRecord, type BelongsToRelationResult, type BelongsToRequiredRecord, type CastType, type D1DatabaseHandle, type D1DatabaseOptions, DrizzleAdapter, type EagerLoadConstraint, type FindManyOptions, GlobalScopeRegistry, type GroupCondition, type HasManyRecord, type HasManyRelationResult, type HasManyThroughRecord, type HasManyThroughRelationResult, type HasOneRecord, type HasOneRelationResult, type HookCallback, type HookName, type InferModelInsert, type InferModelRecord, MassAssignmentException, type MigrationStatusEntry, Model, type ModelHooks, ModelNotFoundException, type ModelObserver, type ModelObserverConstructor, type ModelPaginationMeta, type ModelQueryOptions, type MorphManyRecord, type MorphManyRelationResult, type MorphToRecord, type MorphToRelationResult, type MutatorDefinitions, type MutatorFn, type MySqlDatabase, type MySqlDatabaseOptions, type MySqlSeederContext, type ORMAdapter, type ORMAdapterAdvanced, type OrderByClause, type OrderByInput, type OrderDefinition, type OrderDirection, type PaginateOptions, type PaginatedResult, type PlainObject, type PostgresDatabase, type PostgresDatabaseOptions, type PostgresSeederContext, QueryBuilder, type QueryBuilderOptions, type ScopeFunction, type SeederContext, type SeederHandler, type SimpleCondition, SoftDeletes, type SoftDeletesStatic, type SqliteDatabase, type SqliteDatabaseOptions, type SqliteSeederContext, type TransactionHandle, type TransactionModelScope, type WhereClause, type WhereCondition, type WhereGroupCallback, type WhereOperator, type WithRelations, applyAccessors, applyMutators, buildDrizzleConditions, createAwsDataApiDatabase, createD1Database, createMySqlDatabase, createPostgresDatabase, createSqliteDatabase, defineModel, defineSeeder, executeHook, executeObservers, loadSeeders, runSeeders, serializeRecord, serializeRecords };
package/dist/index.js CHANGED
@@ -512,7 +512,6 @@ var QueryBuilder = class _QueryBuilder {
512
512
  adapter;
513
513
  eagerLoad = [];
514
514
  eagerLoadConstraints = /* @__PURE__ */ new Map();
515
- // eslint-disable-line @typescript-eslint/no-explicit-any
516
515
  constructor(modelClass, options = {}) {
517
516
  this.modelClass = modelClass;
518
517
  this.table = modelClass.resolveTable();
@@ -667,6 +666,20 @@ var QueryBuilder = class _QueryBuilder {
667
666
  * Supports string names, arrays, dot notation for nested relations,
668
667
  * and constraint callbacks.
669
668
  *
669
+ * A constraint callback receives the query builder used to fetch that
670
+ * relation, and runs after the foreign-key filter is already on it, so a
671
+ * `where()` narrows that filter. Each object key constrains exactly the
672
+ * level it names, in any order: `posts` constrains the head,
673
+ * `posts.comments` constrains the leaf and leaves `posts` unfiltered.
674
+ *
675
+ * Three things behave differently than they may look:
676
+ * - `orWhere()` at the top level of a callback *widens* the query rather
677
+ * than narrowing it, because it ORs against the foreign-key filter. Group
678
+ * it (`q.where((g) => g.where(...).orWhere(...))`) to keep it contained.
679
+ * - `select()` must include the column the relation is keyed on, or the
680
+ * loader cannot match rows back to their parent and the relation is empty.
681
+ * - `limit()` applies to the single batched query, not per parent record.
682
+ *
670
683
  * @example
671
684
  * // Simple
672
685
  * await User.where('active', true).with('posts').get()
@@ -676,6 +689,14 @@ var QueryBuilder = class _QueryBuilder {
676
689
  *
677
690
  * // Nested (dot notation)
678
691
  * await User.where('active', true).with('posts.comments').get()
692
+ *
693
+ * // Constrained
694
+ * await User.newQuery().with({ posts: (q) => q.where('published', true) }).get()
695
+ *
696
+ * // Constrained at both levels
697
+ * await User.newQuery()
698
+ * .with({ posts: (q) => q.where('published', true), 'posts.comments': (q) => q.orderBy('id') })
699
+ * .get()
679
700
  */
680
701
  with(...relations) {
681
702
  for (const rel of relations) {
@@ -708,11 +729,12 @@ var QueryBuilder = class _QueryBuilder {
708
729
  async first() {
709
730
  const prev = this.options.limitValue;
710
731
  this.options.limitValue = 1;
711
- const results = await this.executeQuery();
712
- this.options.limitValue = prev;
713
- if (results.length === 0) return null;
714
- const loaded = await this.loadEagerRelations(results);
715
- return loaded[0];
732
+ try {
733
+ const results = await this.get();
734
+ return results[0] ?? null;
735
+ } finally {
736
+ this.options.limitValue = prev;
737
+ }
716
738
  }
717
739
  /**
718
740
  * Execute the query and return the first matching record, or throw.
@@ -754,9 +776,13 @@ var QueryBuilder = class _QueryBuilder {
754
776
  const prevOffset = this.options.offsetValue;
755
777
  this.options.limitValue = sanitizedPerPage;
756
778
  this.options.offsetValue = offset;
757
- const data = await this.executeQuery();
758
- this.options.limitValue = prevLimit;
759
- this.options.offsetValue = prevOffset;
779
+ let data;
780
+ try {
781
+ data = await this.get();
782
+ } finally {
783
+ this.options.limitValue = prevLimit;
784
+ this.options.offsetValue = prevOffset;
785
+ }
760
786
  const from = total === 0 ? 0 : offset + 1;
761
787
  const to = total === 0 ? 0 : offset + data.length;
762
788
  const meta = {
@@ -952,16 +978,25 @@ var QueryBuilder = class _QueryBuilder {
952
978
  /**
953
979
  * Load eager relations onto fetched results.
954
980
  * Supports dot notation for nested relations at any depth
955
- * (e.g., 'posts.comments.author') — the full path is delegated to
956
- * Model.loadRelationInto, which recurses through the relation chain.
981
+ * (e.g., 'posts.comments.author') — the paths are delegated to
982
+ * Model.loadRelationsInto, which recurses through the relation chain.
983
+ * Constraint callbacks registered by the object form of `with()` travel
984
+ * alongside, keyed by the path segment each one constrains.
985
+ *
986
+ * The builder's `trx` goes with it: a relation loaded for rows read inside
987
+ * a transaction has to be read on that same handle, or the parents come
988
+ * from the transaction and their children from the pool — which on
989
+ * Postgres/MySQL means uncommitted parents get a null relation back.
957
990
  */
958
991
  loadEagerRelations = async (results) => {
959
992
  if (this.eagerLoad.length === 0 || results.length === 0) return results;
960
993
  const copies = results.map((r) => ({ ...r }));
961
- const model = this.modelClass;
962
- for (const relation of this.eagerLoad) {
963
- await model.loadRelationInto(copies, relation);
964
- }
994
+ await this.modelClass.loadRelationsInto(
995
+ copies,
996
+ this.eagerLoad,
997
+ { trx: this.options.trx },
998
+ this.eagerLoadConstraints
999
+ );
965
1000
  return copies;
966
1001
  };
967
1002
  };
@@ -1572,29 +1607,25 @@ var Model = class _Model {
1572
1607
  }
1573
1608
  return record;
1574
1609
  }
1575
- static async findWith(id, relations, key) {
1576
- const record = await this.find(id, key);
1610
+ static async findWith(id, relations, key, queryOptions) {
1611
+ const record = await this.find(id, key, queryOptions);
1577
1612
  if (record == null) return null;
1578
1613
  const relationList = normalizeRelations(relations);
1579
1614
  if (relationList.length === 0) {
1580
1615
  return record;
1581
1616
  }
1582
1617
  const copy = { ...record };
1583
- for (const rel of relationList) {
1584
- await this.loadRelationInto([copy], rel);
1585
- }
1618
+ await this.loadRelationsInto([copy], relationList, queryOptions);
1586
1619
  return copy;
1587
1620
  }
1588
- static async findWithOrFail(id, relations, key) {
1589
- const record = await this.findOrFail(id, key);
1621
+ static async findWithOrFail(id, relations, key, queryOptions) {
1622
+ const record = await this.findOrFail(id, key, queryOptions);
1590
1623
  const relationList = normalizeRelations(relations);
1591
1624
  if (relationList.length === 0) {
1592
1625
  return record;
1593
1626
  }
1594
1627
  const copy = { ...record };
1595
- for (const rel of relationList) {
1596
- await this.loadRelationInto([copy], rel);
1597
- }
1628
+ await this.loadRelationsInto([copy], relationList, queryOptions);
1598
1629
  return copy;
1599
1630
  }
1600
1631
  /**
@@ -2034,16 +2065,14 @@ var Model = class _Model {
2034
2065
  };
2035
2066
  return { data, meta };
2036
2067
  }
2037
- static async withPaginate(relations, options = {}) {
2038
- const result = await this.paginate(options);
2068
+ static async withPaginate(relations, options = {}, queryOptions) {
2069
+ const result = await this.paginate(options, queryOptions);
2039
2070
  const relationList = normalizeRelations(relations);
2040
2071
  if (relationList.length === 0 || result.data.length === 0) {
2041
2072
  return result;
2042
2073
  }
2043
2074
  const records = result.data.map((record) => ({ ...record }));
2044
- for (const relationName of relationList) {
2045
- await this.loadRelationInto(records, relationName);
2046
- }
2075
+ await this.loadRelationsInto(records, relationList, queryOptions);
2047
2076
  return {
2048
2077
  data: records,
2049
2078
  meta: result.meta
@@ -2249,8 +2278,8 @@ var Model = class _Model {
2249
2278
  }
2250
2279
  return fallbackBuilder.from(table);
2251
2280
  }
2252
- static async with(relations, where) {
2253
- const records = where ? await this.where(where) : await this.all();
2281
+ static async with(relations, where, queryOptions) {
2282
+ const records = where ? await this.newQuery(queryOptions).where(where).get() : await this.all(queryOptions);
2254
2283
  if (!records.length) {
2255
2284
  return records;
2256
2285
  }
@@ -2259,25 +2288,23 @@ var Model = class _Model {
2259
2288
  return records;
2260
2289
  }
2261
2290
  const copies = records.map((record) => ({ ...record }));
2262
- for (const relationName of relationList) {
2263
- await this.loadRelationInto(copies, relationName);
2264
- }
2291
+ await this.loadRelationsInto(copies, relationList, queryOptions);
2265
2292
  return copies;
2266
2293
  }
2267
- static async withCount(relations, where) {
2268
- const records = where ? await this.where(where) : await this.all();
2294
+ static async withCount(relations, where, queryOptions) {
2295
+ const records = where ? await this.newQuery(queryOptions).where(where).get() : await this.all(queryOptions);
2269
2296
  if (!records.length) {
2270
2297
  return records;
2271
2298
  }
2272
2299
  const relationList = normalizeRelations(relations);
2273
2300
  const copies = records.map((record) => ({ ...record }));
2274
2301
  for (const relationName of relationList) {
2275
- await this.loadRelationCountInto(copies, relationName);
2302
+ await this.loadRelationCountInto(copies, relationName, queryOptions);
2276
2303
  }
2277
2304
  return copies;
2278
2305
  }
2279
2306
  /** @internal Attaches a `${name}Count` field for one relation. */
2280
- static async loadRelationCountInto(records, relationName) {
2307
+ static async loadRelationCountInto(records, relationName, queryOptions) {
2281
2308
  if (relationName.includes(".")) {
2282
2309
  throw new Error(`${this.name}: withCount does not support nested relation "${relationName}".`);
2283
2310
  }
@@ -2296,7 +2323,7 @@ var Model = class _Model {
2296
2323
  );
2297
2324
  const counts = /* @__PURE__ */ new Map();
2298
2325
  if (values.length > 0) {
2299
- const relatedRecords = await related.where({ [foreignKey]: values });
2326
+ const relatedRecords = await related.newQuery(queryOptions).where({ [foreignKey]: values });
2300
2327
  for (const item of relatedRecords) {
2301
2328
  const key = item[foreignKey];
2302
2329
  counts.set(key, (counts.get(key) ?? 0) + 1);
@@ -2309,7 +2336,7 @@ var Model = class _Model {
2309
2336
  }
2310
2337
  case "morphMany": {
2311
2338
  const withRelation = records.map((record) => ({ ...record }));
2312
- await this.loadRelationInto(withRelation, relationName);
2339
+ await this.loadRelationInto(withRelation, relationName, queryOptions);
2313
2340
  for (const [index, record] of records.entries()) {
2314
2341
  const value = withRelation[index]?.[relationName];
2315
2342
  record[countField] = Array.isArray(value) ? value.length : 0;
@@ -2324,7 +2351,7 @@ var Model = class _Model {
2324
2351
  );
2325
2352
  const ownerKeys = /* @__PURE__ */ new Set();
2326
2353
  if (values.length > 0) {
2327
- const owners = await related.where({ [ownerKey]: values });
2354
+ const owners = await related.newQuery(queryOptions).where({ [ownerKey]: values });
2328
2355
  for (const owner of owners) {
2329
2356
  ownerKeys.add(owner[ownerKey]);
2330
2357
  }
@@ -2344,37 +2371,79 @@ var Model = class _Model {
2344
2371
  /**
2345
2372
  * @internal Used by QueryBuilder for eager loading.
2346
2373
  * Supports nested paths with dot notation, e.g. `posts.comments`.
2374
+ *
2375
+ * Paths are grouped by their head segment so a relation shared by several
2376
+ * paths is loaded exactly once. Walking `posts.comments` and `posts.tags`
2377
+ * independently would load `posts` twice, and the loaders assign fresh
2378
+ * spread copies — so the second pass would replace the very row objects the
2379
+ * first had already attached children to, and only the last path would
2380
+ * survive.
2381
+ */
2382
+ static async loadRelationsInto(records, relationNames, queryOptions, constraints, pathPrefix = "") {
2383
+ if (relationNames.length === 0) return;
2384
+ const groups = /* @__PURE__ */ new Map();
2385
+ for (const path of relationNames) {
2386
+ const [head, ...rest] = path.split(".");
2387
+ const tails = groups.get(head) ?? [];
2388
+ groups.set(head, tails);
2389
+ if (rest.length > 0) {
2390
+ const tail = rest.join(".");
2391
+ if (!tails.includes(tail)) {
2392
+ tails.push(tail);
2393
+ }
2394
+ }
2395
+ }
2396
+ for (const [head, tails] of groups) {
2397
+ await this.loadRelationLevel(records, head, tails, queryOptions, constraints, pathPrefix);
2398
+ }
2399
+ }
2400
+ /**
2401
+ * @internal Public since it is reachable from generated code; kept for
2402
+ * backwards compatibility now that the eager loader walks whole path lists.
2403
+ * Internal callers should use {@link loadRelationsInto} instead.
2347
2404
  */
2348
- static async loadRelationInto(records, relationName) {
2349
- const [head, ...rest] = relationName.split(".");
2405
+ static async loadRelationInto(records, relationName, queryOptions, constraints, pathPrefix = "") {
2406
+ await this.loadRelationsInto(records, [relationName], queryOptions, constraints, pathPrefix);
2407
+ }
2408
+ /**
2409
+ * Load one relation level and recurse into the tails beneath it.
2410
+ *
2411
+ * `constraints` are keyed by the full path of the level each one constrains,
2412
+ * so `pathPrefix` accumulates the path walked so far as the recursion
2413
+ * descends: at `posts.comments` the leaf looks itself up under that whole
2414
+ * key, not under `comments`.
2415
+ */
2416
+ static async loadRelationLevel(records, head, tails, queryOptions, constraints, pathPrefix = "") {
2350
2417
  const definition = this.getRelationDefinition(head);
2351
2418
  if (!definition) {
2352
2419
  throw new Error(`${this.name}: unknown relation "${head}".`);
2353
2420
  }
2421
+ const currentPath = pathPrefix ? `${pathPrefix}.${head}` : head;
2422
+ const constraint = constraints?.get(currentPath);
2354
2423
  switch (definition.type) {
2355
2424
  case "hasMany":
2356
- await this.loadHasMany(records, definition);
2425
+ await this.loadHasMany(records, definition, queryOptions, constraint);
2357
2426
  break;
2358
2427
  case "hasOne":
2359
- await this.loadHasOne(records, definition);
2428
+ await this.loadHasOne(records, definition, queryOptions, constraint);
2360
2429
  break;
2361
2430
  case "belongsTo":
2362
- await this.loadBelongsTo(records, definition);
2431
+ await this.loadBelongsTo(records, definition, queryOptions, constraint);
2363
2432
  break;
2364
2433
  case "belongsToMany":
2365
- await this.loadBelongsToMany(records, definition);
2434
+ await this.loadBelongsToMany(records, definition, queryOptions, constraint);
2366
2435
  break;
2367
2436
  case "hasManyThrough":
2368
- await this.loadHasManyThrough(records, definition);
2437
+ await this.loadHasManyThrough(records, definition, queryOptions, constraint);
2369
2438
  break;
2370
2439
  case "morphMany":
2371
- await this.loadMorphMany(records, definition);
2440
+ await this.loadMorphMany(records, definition, queryOptions, constraint);
2372
2441
  break;
2373
2442
  case "morphTo":
2374
- await this.loadMorphTo(records, definition);
2443
+ await this.loadMorphTo(records, definition, queryOptions, constraint);
2375
2444
  break;
2376
2445
  }
2377
- if (rest.length === 0) {
2446
+ if (tails.length === 0) {
2378
2447
  return;
2379
2448
  }
2380
2449
  if (definition.type === "morphTo") {
@@ -2398,24 +2467,24 @@ var Model = class _Model {
2398
2467
  return;
2399
2468
  }
2400
2469
  const related = await resolveModelReference(definition.related);
2401
- await related.loadRelationInto(children, rest.join("."));
2470
+ await related.loadRelationsInto(children, tails, queryOptions, constraints, currentPath);
2402
2471
  }
2403
- static async loadHasMany(records, definition) {
2472
+ static async loadHasMany(records, definition, queryOptions, constraint) {
2404
2473
  const { foreignKey, localKey, name } = definition;
2405
2474
  const related = await resolveModelReference(definition.related);
2406
- await loadRelationData(records, name, related, localKey, foreignKey, true);
2475
+ await loadRelationData(records, name, related, localKey, foreignKey, true, queryOptions, constraint);
2407
2476
  }
2408
- static async loadHasOne(records, definition) {
2477
+ static async loadHasOne(records, definition, queryOptions, constraint) {
2409
2478
  const { foreignKey, localKey, name } = definition;
2410
2479
  const related = await resolveModelReference(definition.related);
2411
- await loadRelationData(records, name, related, localKey, foreignKey, false);
2480
+ await loadRelationData(records, name, related, localKey, foreignKey, false, queryOptions, constraint);
2412
2481
  }
2413
- static async loadBelongsTo(records, definition) {
2482
+ static async loadBelongsTo(records, definition, queryOptions, constraint) {
2414
2483
  const { foreignKey, ownerKey, name } = definition;
2415
2484
  const related = await resolveModelReference(definition.related);
2416
- await loadRelationData(records, name, related, foreignKey, ownerKey, false);
2485
+ await loadRelationData(records, name, related, foreignKey, ownerKey, false, queryOptions, constraint);
2417
2486
  }
2418
- static async loadBelongsToMany(records, definition) {
2487
+ static async loadBelongsToMany(records, definition, queryOptions, constraint) {
2419
2488
  const { pivotTable, foreignPivotKey, relatedPivotKey, parentKey, relatedKey, name } = definition;
2420
2489
  const related = await resolveModelReference(definition.related);
2421
2490
  const parentValues = Array.from(
@@ -2430,7 +2499,7 @@ var Model = class _Model {
2430
2499
  const adapter = this.getAdapter();
2431
2500
  const pivotRows = await adapter.findMany(pivotTable, {
2432
2501
  where: { [foreignPivotKey]: parentValues }
2433
- });
2502
+ }, queryOptions);
2434
2503
  const pivotMap = /* @__PURE__ */ new Map();
2435
2504
  const allRelatedIds = /* @__PURE__ */ new Set();
2436
2505
  for (const row of pivotRows) {
@@ -2446,9 +2515,10 @@ var Model = class _Model {
2446
2515
  }
2447
2516
  return;
2448
2517
  }
2449
- const relatedRecords = await related.where({
2450
- [relatedKey]: Array.from(allRelatedIds)
2451
- });
2518
+ const relatedRecords = await applyEagerConstraint(
2519
+ related.newQuery(queryOptions).where({ [relatedKey]: Array.from(allRelatedIds) }),
2520
+ constraint
2521
+ );
2452
2522
  const relatedMap = /* @__PURE__ */ new Map();
2453
2523
  for (const item of relatedRecords) {
2454
2524
  relatedMap.set(item[relatedKey], { ...item });
@@ -2463,7 +2533,7 @@ var Model = class _Model {
2463
2533
  record[name] = relatedIds.map((id) => relatedMap.get(id)).filter((item) => item != null);
2464
2534
  }
2465
2535
  }
2466
- static async loadHasManyThrough(records, definition) {
2536
+ static async loadHasManyThrough(records, definition, queryOptions, constraint) {
2467
2537
  const { firstKey, secondKey, localKey, secondLocalKey, name } = definition;
2468
2538
  const related = await resolveModelReference(definition.related);
2469
2539
  const through = await resolveModelReference(definition.through);
@@ -2476,7 +2546,7 @@ var Model = class _Model {
2476
2546
  }
2477
2547
  return;
2478
2548
  }
2479
- const throughRecords = await through.where({
2549
+ const throughRecords = await through.newQuery(queryOptions).where({
2480
2550
  [firstKey]: localValues
2481
2551
  });
2482
2552
  const throughMap = /* @__PURE__ */ new Map();
@@ -2494,9 +2564,10 @@ var Model = class _Model {
2494
2564
  }
2495
2565
  return;
2496
2566
  }
2497
- const relatedRecords = await related.where({
2498
- [secondKey]: Array.from(allThroughIds)
2499
- });
2567
+ const relatedRecords = await applyEagerConstraint(
2568
+ related.newQuery(queryOptions).where({ [secondKey]: Array.from(allThroughIds) }),
2569
+ constraint
2570
+ );
2500
2571
  const relatedByKey = /* @__PURE__ */ new Map();
2501
2572
  for (const item of relatedRecords) {
2502
2573
  const key = item[secondKey];
@@ -2518,7 +2589,7 @@ var Model = class _Model {
2518
2589
  record[name] = items;
2519
2590
  }
2520
2591
  }
2521
- static async loadMorphMany(records, definition) {
2592
+ static async loadMorphMany(records, definition, queryOptions, constraint) {
2522
2593
  const { morphName, localKey, name } = definition;
2523
2594
  const related = await resolveModelReference(definition.related);
2524
2595
  const typeColumn = `${morphName}Type`;
@@ -2531,12 +2602,13 @@ var Model = class _Model {
2531
2602
  for (const record of records) record[name] = [];
2532
2603
  return;
2533
2604
  }
2534
- const allRelated = await related.where({
2535
- [typeColumn]: parentType,
2536
- [idColumn]: localValues
2537
- });
2605
+ const allRelated = await applyEagerConstraint(
2606
+ related.newQuery(queryOptions).where({ [typeColumn]: parentType, [idColumn]: localValues }),
2607
+ constraint
2608
+ );
2538
2609
  const map = /* @__PURE__ */ new Map();
2539
2610
  for (const item of allRelated) {
2611
+ if (item[typeColumn] !== parentType) continue;
2540
2612
  const key = item[idColumn];
2541
2613
  if (!map.has(key)) map.set(key, []);
2542
2614
  map.get(key).push({ ...item });
@@ -2546,7 +2618,7 @@ var Model = class _Model {
2546
2618
  record[name] = key != null ? map.get(key) ?? [] : [];
2547
2619
  }
2548
2620
  }
2549
- static async loadMorphTo(records, definition) {
2621
+ static async loadMorphTo(records, definition, queryOptions, constraint) {
2550
2622
  const { morphName, name } = definition;
2551
2623
  const typeColumn = `${morphName}Type`;
2552
2624
  const idColumn = `${morphName}Id`;
@@ -2564,7 +2636,10 @@ var Model = class _Model {
2564
2636
  const modelClass = morphMap[type];
2565
2637
  if (!modelClass) continue;
2566
2638
  const uniqueIds = Array.from(new Set(ids));
2567
- const results = await modelClass.where({ id: uniqueIds });
2639
+ const results = await applyEagerConstraint(
2640
+ modelClass.newQuery(queryOptions).where({ id: uniqueIds }),
2641
+ constraint
2642
+ );
2568
2643
  const idMap = /* @__PURE__ */ new Map();
2569
2644
  for (const r of results) idMap.set(r.id, { ...r });
2570
2645
  resolved.set(type, idMap);
@@ -2580,7 +2655,11 @@ var Model = class _Model {
2580
2655
  }
2581
2656
  }
2582
2657
  };
2583
- async function loadRelationData(records, name, related, parentKey, relatedKey, isArray) {
2658
+ async function applyEagerConstraint(query, constraint) {
2659
+ constraint?.(query);
2660
+ return await query;
2661
+ }
2662
+ async function loadRelationData(records, name, related, parentKey, relatedKey, isArray, queryOptions, constraint) {
2584
2663
  const values = Array.from(
2585
2664
  new Set(records.map((r) => r[parentKey]).filter((v) => v != null))
2586
2665
  );
@@ -2590,7 +2669,10 @@ async function loadRelationData(records, name, related, parentKey, relatedKey, i
2590
2669
  }
2591
2670
  return;
2592
2671
  }
2593
- const relatedRecords = await related.where({ [relatedKey]: values });
2672
+ const relatedRecords = await applyEagerConstraint(
2673
+ related.newQuery(queryOptions).where({ [relatedKey]: values }),
2674
+ constraint
2675
+ );
2594
2676
  const map = /* @__PURE__ */ new Map();
2595
2677
  for (const item of relatedRecords) {
2596
2678
  const key = item[relatedKey];
@@ -3424,6 +3506,13 @@ import { fileURLToPath as fileURLToPath4 } from "url";
3424
3506
  function isInMemory(dbPath) {
3425
3507
  return dbPath === ":memory:" || dbPath === "" || dbPath.startsWith("file::memory:");
3426
3508
  }
3509
+ var CONNECTION_URI = /^(?!file:)[a-z][a-z0-9+.-]+:\/\//i;
3510
+ function assertNotConnectionUri(dbPath, source) {
3511
+ if (!CONNECTION_URI.test(dbPath)) return;
3512
+ throw new Error(
3513
+ `createSqliteDatabase() received a connection URI where it expects a file path: ${dbPath} (from ${source}). Left alone it would be created as a directory tree and migrated into silently. Pass a path such as "./data/guren.db", or ":memory:".`
3514
+ );
3515
+ }
3427
3516
  function createSqliteDatabase(options) {
3428
3517
  const { migrationsFolder, filename, seedersFolder, relations } = options;
3429
3518
  const resolvedMigrationsFolder = migrationsFolder instanceof URL ? fileURLToPath4(migrationsFolder) : resolve5(String(migrationsFolder));
@@ -3433,7 +3522,16 @@ function createSqliteDatabase(options) {
3433
3522
  const callSite = new Error().stack;
3434
3523
  function resolveFilename() {
3435
3524
  const value = typeof filename === "function" ? filename() : filename;
3436
- return value ?? process.env.DATABASE_URL ?? "./data/guren.db";
3525
+ if (value != null) {
3526
+ assertNotConnectionUri(value, 'the "filename" option');
3527
+ return value;
3528
+ }
3529
+ const fromEnv = process.env.DATABASE_URL;
3530
+ if (fromEnv != null) {
3531
+ assertNotConnectionUri(fromEnv, "DATABASE_URL");
3532
+ return fromEnv;
3533
+ }
3534
+ return "./data/guren.db";
3437
3535
  }
3438
3536
  const database2 = singleFlight(async () => {
3439
3537
  const dbPath = resolveFilename();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guren/orm",
3
- "version": "2.4.0",
3
+ "version": "2.5.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {