@guren/orm 1.0.0 → 1.1.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
@@ -185,7 +185,7 @@ declare class QueryBuilder<TRecord extends PlainObject = PlainObject, TResult ex
185
185
  /**
186
186
  * Execute the query and return the first matching record, or throw.
187
187
  * @returns The first record
188
- * @throws Error if no record matches
188
+ * @throws ModelNotFoundException (404) if no record matches
189
189
  */
190
190
  firstOrFail(): Promise<TResult>;
191
191
  /**
@@ -822,7 +822,7 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
822
822
  * const post = await Post.findWith(1, 'author')
823
823
  * const post = await Post.findWith(1, ['author', 'tags'])
824
824
  */
825
- static findWith<T extends typeof Model, K extends RelationKey<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>;
825
+ 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>;
826
826
  /**
827
827
  * Find a record by primary key with eager-loaded relations, or throw.
828
828
  *
@@ -835,8 +835,9 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
835
835
  * @example
836
836
  * const post = await Post.findWithOrFail(1, 'author')
837
837
  * const post = await Post.findWithOrFail(1, ['author', 'tags'])
838
+ * const post = await Post.findWithOrFail(1, 'comments.author') // nested
838
839
  */
839
- static findWithOrFail<T extends typeof Model, K extends RelationKey<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[]>>;
840
+ 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[]>>;
840
841
  /**
841
842
  * Get the first record matching the conditions.
842
843
  *
@@ -1107,7 +1108,7 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
1107
1108
  * // result.data - Users with their posts loaded
1108
1109
  * // result.meta - Pagination metadata
1109
1110
  */
1110
- static withPaginate<T extends typeof Model, K extends RelationKey<T>>(this: T, relations: K | readonly K[], options?: PaginateOptions<TRecordFor<T>>): Promise<PaginatedResult<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>>;
1111
+ 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[]>>>;
1111
1112
  /**
1112
1113
  * Create a new record.
1113
1114
  *
@@ -1201,8 +1202,11 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
1201
1202
  *
1202
1203
  * // With filtering
1203
1204
  * const activeUsersWithPosts = await User.with('posts', { status: 'active' })
1205
+ *
1206
+ * // Nested relations via dot notation
1207
+ * const usersWithPostComments = await User.with('posts.comments')
1204
1208
  */
1205
- static with<T extends typeof Model, K extends RelationKey<T>>(this: T, relations: K | readonly K[], where?: WhereClauseFor<T>): Promise<Array<TRecordFor<T> & RelationTypePick<T, K | readonly K[]>>>;
1209
+ 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[]>>>;
1206
1210
  /**
1207
1211
  * Fetch records with related record counts attached as `${name}Count`.
1208
1212
  * Counts hasMany/hasOne/morphMany children per record without attaching
@@ -1236,6 +1240,8 @@ type TCreateFor<T extends typeof Model> = T extends {
1236
1240
  } ? R extends PlainObject ? R : PlainObject : PlainObject;
1237
1241
  type WhereClauseFor<T extends typeof Model> = WhereClause<TRecordFor<T>>;
1238
1242
  type FieldFor<T extends typeof Model> = keyof TRecordFor<T> & string;
1243
+ type RelationPath<T extends typeof Model> = RelationKey<T> | `${RelationKey<T>}.${string}`;
1244
+ type RelationHead<Name> = Name extends `${infer Head}.${string}` ? Head : Name;
1239
1245
  type RelationTypesFor<T extends typeof Model> = T extends {
1240
1246
  relationTypes: infer R;
1241
1247
  } ? R extends RelationShape ? R : {} : {};
@@ -1243,7 +1249,7 @@ type RelationKey<T extends typeof Model> = keyof RelationTypesFor<T> & string;
1243
1249
  type RelationKeyOrString<T extends typeof Model> = RelationKey<T> extends never ? string : RelationKey<T>;
1244
1250
  type RelationNameUnion<Names> = Names extends readonly (infer Items)[] ? Items : Names;
1245
1251
  type RelationTypePick<T extends typeof Model, Names> = {
1246
- [K in RelationNameUnion<Names> & string & keyof RelationTypesFor<T>]: RelationTypesFor<T>[K];
1252
+ [K in RelationHead<RelationNameUnion<Names>> & string & keyof RelationTypesFor<T>]: RelationTypesFor<T>[K];
1247
1253
  };
1248
1254
  type RelationCountPick<Names> = {
1249
1255
  [K in RelationNameUnion<Names> & string as `${K}Count`]: number;
@@ -1319,6 +1325,15 @@ type BelongsToRelationResult<T extends typeof Model> = TRecordFor<T> | null;
1319
1325
  type HasManyRecord<TRecord extends PlainObject> = TRecord[];
1320
1326
  /** Utility type for belongsTo relation data shape. */
1321
1327
  type BelongsToRecord<TRecord extends PlainObject> = TRecord | null;
1328
+ /**
1329
+ * Utility type for belongsTo relations backed by a NOT NULL foreign key,
1330
+ * where the parent is guaranteed to exist once loaded. Declare with the
1331
+ * `declare` modifier so no runtime placeholder value is needed:
1332
+ *
1333
+ * @example
1334
+ * declare static relationTypes: { author: BelongsToRequiredRecord<UserRecord> }
1335
+ */
1336
+ type BelongsToRequiredRecord<TRecord extends PlainObject> = TRecord;
1322
1337
  /** Type for hasOne relation results (single record or null). */
1323
1338
  type HasOneRelationResult<T extends typeof Model> = TRecordFor<T> | null;
1324
1339
  /** Type for belongsToMany relation results (array of related records). */
@@ -1340,7 +1355,7 @@ type MorphToRelationResult = PlainObject | null;
1340
1355
  /** Utility type for morphTo relation data shape. */
1341
1356
  type MorphToRecord = PlainObject | null;
1342
1357
  /** Utility type: model record with specified relations merged. */
1343
- type WithRelations<T extends typeof Model, K extends RelationKey<T> | readonly RelationKey<T>[]> = TRecordFor<T> & RelationTypePick<T, K>;
1358
+ type WithRelations<T extends typeof Model, K extends RelationPath<T> | readonly RelationPath<T>[]> = TRecordFor<T> & RelationTypePick<T, K>;
1344
1359
  type ModelClassWithTable<TTable extends TableShape, TBase extends typeof Model = typeof Model, TCreate extends PlainObject = InferModelInsert<TTable> & TCreateFor<TBase>> = TBase & {
1345
1360
  readonly table: TTable;
1346
1361
  readonly recordType: InferModelRecord<TTable>;
@@ -1359,7 +1374,7 @@ declare function defineModel<TTable extends TableShape, TBase extends typeof Mod
1359
1374
  }): ModelClassWithTable<TTable, TBase, TCreate>;
1360
1375
 
1361
1376
  /**
1362
- * Exception thrown when a model is not found via findOrFail.
1377
+ * Exception thrown when a model is not found via findOrFail or firstOrFail.
1363
1378
  *
1364
1379
  * Carries a `statusCode` of 404 so that framework exception handlers
1365
1380
  * can render it as a proper HTTP 404 without coupling to the ORM package.
@@ -1368,7 +1383,7 @@ declare class ModelNotFoundException extends Error {
1368
1383
  readonly statusCode = 404;
1369
1384
  readonly modelName: string;
1370
1385
  readonly modelId: unknown;
1371
- constructor(modelName: string, id: unknown, key?: string);
1386
+ constructor(modelName: string, id?: unknown, key?: string);
1372
1387
  }
1373
1388
 
1374
1389
  /**
@@ -1599,4 +1614,4 @@ declare function serializeRecord(record: PlainObject, options: {
1599
1614
  /** Serialize an array of records. */
1600
1615
  declare function serializeRecords(records: PlainObject[], options: Parameters<typeof serializeRecord>[1]): PlainObject[];
1601
1616
 
1602
- export { type AccessorDefinitions, type AccessorFn, type BelongsToManyRecord, type BelongsToManyRelationResult, type BelongsToRecord, type BelongsToRelationResult, type CastType, 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 ORMAdapter, type ORMAdapterAdvanced, type OrderByClause, type OrderByInput, type OrderDefinition, type OrderDirection, type PaginateOptions, type PaginatedResult, type PlainObject, type PostgresDatabase, type PostgresDatabaseOptions, QueryBuilder, type QueryBuilderOptions, type ScopeFunction, type SeederContext, type SeederHandler, type SimpleCondition, SoftDeletes, type SoftDeletesStatic, type SqliteDatabase, type SqliteDatabaseOptions, type TransactionHandle, type TransactionModelScope, type WhereClause, type WhereCondition, type WhereOperator, type WithRelations, applyAccessors, applyMutators, buildDrizzleConditions, createMySqlDatabase, createPostgresDatabase, createSqliteDatabase, defineModel, defineSeeder, executeHook, executeObservers, loadSeeders, runSeeders, serializeRecord, serializeRecords };
1617
+ export { type AccessorDefinitions, type AccessorFn, type BelongsToManyRecord, type BelongsToManyRelationResult, type BelongsToRecord, type BelongsToRelationResult, type BelongsToRequiredRecord, type CastType, 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 ORMAdapter, type ORMAdapterAdvanced, type OrderByClause, type OrderByInput, type OrderDefinition, type OrderDirection, type PaginateOptions, type PaginatedResult, type PlainObject, type PostgresDatabase, type PostgresDatabaseOptions, QueryBuilder, type QueryBuilderOptions, type ScopeFunction, type SeederContext, type SeederHandler, type SimpleCondition, SoftDeletes, type SoftDeletesStatic, type SqliteDatabase, type SqliteDatabaseOptions, type TransactionHandle, type TransactionModelScope, type WhereClause, type WhereCondition, type WhereOperator, type WithRelations, applyAccessors, applyMutators, buildDrizzleConditions, createMySqlDatabase, createPostgresDatabase, createSqliteDatabase, defineModel, defineSeeder, executeHook, executeObservers, loadSeeders, runSeeders, serializeRecord, serializeRecords };
package/dist/index.js CHANGED
@@ -495,7 +495,7 @@ var ModelNotFoundException = class extends Error {
495
495
  modelName;
496
496
  modelId;
497
497
  constructor(modelName, id, key = "id") {
498
- super(`${modelName} not found for ${key}=${String(id)}`);
498
+ super(id === void 0 ? `${modelName} not found` : `${modelName} not found for ${key}=${String(id)}`);
499
499
  this.name = "ModelNotFoundException";
500
500
  this.modelName = modelName;
501
501
  this.modelId = id;
@@ -708,12 +708,12 @@ var QueryBuilder = class {
708
708
  /**
709
709
  * Execute the query and return the first matching record, or throw.
710
710
  * @returns The first record
711
- * @throws Error if no record matches
711
+ * @throws ModelNotFoundException (404) if no record matches
712
712
  */
713
713
  async firstOrFail() {
714
714
  const record = await this.first();
715
715
  if (record === null) {
716
- throw new Error(`${this.modelClass.name} not found`);
716
+ throw new ModelNotFoundException(this.modelClass.name);
717
717
  }
718
718
  return record;
719
719
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guren/orm",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {