@guren/orm 1.0.0-rc.9 → 1.0.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/drizzle.d.ts CHANGED
@@ -1,3 +1,3 @@
1
1
  export { SQL, sql } from 'drizzle-orm';
2
- export { PgColumn, PgTable, bigint, boolean, integer, pgTable, serial, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core';
2
+ export { PgColumn, PgTable, bigint, boolean, integer, jsonb, pgTable, serial, text, timestamp, uniqueIndex } from 'drizzle-orm/pg-core';
3
3
  export { MySqlColumn, MySqlTable, datetime, int, mysqlTable, varchar } from 'drizzle-orm/mysql-core';
package/dist/drizzle.js CHANGED
@@ -8,6 +8,7 @@ import {
8
8
  bigint,
9
9
  timestamp,
10
10
  boolean,
11
+ jsonb,
11
12
  uniqueIndex
12
13
  } from "drizzle-orm/pg-core";
13
14
  import {
@@ -22,6 +23,7 @@ export {
22
23
  datetime,
23
24
  int,
24
25
  integer,
26
+ jsonb,
25
27
  mysqlTable,
26
28
  pgTable,
27
29
  serial,
package/dist/index.d.ts CHANGED
@@ -195,17 +195,37 @@ declare class QueryBuilder<TRecord extends PlainObject = PlainObject, TResult ex
195
195
  count(): Promise<number>;
196
196
  /**
197
197
  * Paginate the query results.
198
- * @param page - Page number (1-based, default: 1)
199
- * @param perPage - Records per page (default: 15)
200
- * @returns Paginated result with data and metadata
198
+ *
199
+ * Accepts either positional arguments or the same options object shape as
200
+ * `Model.paginate()` so the two APIs stay interchangeable:
201
+ *
202
+ * @example
203
+ * await Post.where('published', true).paginate(2, 10)
204
+ * await Post.where('published', true).paginate({ page: 2, perPage: 10 })
201
205
  */
202
206
  paginate(page?: number, perPage?: number): Promise<PaginatedResult<TResult>>;
207
+ paginate(options: {
208
+ page?: number;
209
+ perPage?: number;
210
+ }): Promise<PaginatedResult<TResult>>;
203
211
  /**
204
212
  * Bulk update records matching the current conditions.
213
+ *
214
+ * Mass-assignment protection applies exactly as in `Model.update()`:
215
+ * with a `fillable` allowlist, out-of-allowlist keys throw a
216
+ * MassAssignmentException. Note that bulk updates skip model hooks,
217
+ * observers, mutators, and casts by design.
218
+ *
205
219
  * @param data - Data to set on matching records
206
220
  * @returns The updated record (adapter-dependent)
207
221
  */
208
222
  update(data: PlainObject): Promise<TRecord>;
223
+ /**
224
+ * Bulk update bypassing mass-assignment protection. Use for trusted,
225
+ * server-side-assembled data — never for raw request input.
226
+ */
227
+ forceUpdate(data: PlainObject): Promise<TRecord>;
228
+ private runBulkUpdate;
209
229
  /**
210
230
  * Bulk delete records matching the current conditions.
211
231
  * @returns Number of deleted records (adapter-dependent)
@@ -234,7 +254,9 @@ declare class QueryBuilder<TRecord extends PlainObject = PlainObject, TResult ex
234
254
  private toSimpleWhereClause;
235
255
  /**
236
256
  * Load eager relations onto fetched results.
237
- * Supports dot notation for nested relations (e.g., 'posts.comments').
257
+ * Supports dot notation for nested relations at any depth
258
+ * (e.g., 'posts.comments.author') — the full path is delegated to
259
+ * Model.loadRelationInto, which recurses through the relation chain.
238
260
  */
239
261
  private readonly loadEagerRelations;
240
262
  }
@@ -423,7 +445,7 @@ interface PaginateOptions<TRecord extends PlainObject = PlainObject> {
423
445
  orderBy?: OrderByInput<TRecord>;
424
446
  }
425
447
  /** Pagination metadata returned with paginated results. */
426
- interface PaginationMeta {
448
+ interface ModelPaginationMeta {
427
449
  /** Total number of records matching the query */
428
450
  total: number;
429
451
  /** Number of records per page */
@@ -444,7 +466,7 @@ interface PaginatedResult<TRecord extends PlainObject = PlainObject> {
444
466
  /** Records for the current page */
445
467
  data: TRecord[];
446
468
  /** Pagination metadata */
447
- meta: PaginationMeta;
469
+ meta: ModelPaginationMeta;
448
470
  }
449
471
  /**
450
472
  * Interface for ORM adapters that power the Model class.
@@ -569,7 +591,12 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
569
591
  static casts?: Record<string, CastType>;
570
592
  /**
571
593
  * Whitelist of fields allowed for mass assignment.
572
- * If set, only these fields will be accepted in `create()` and `update()`.
594
+ * If set, `create()` and `update()` accept only these fields — input
595
+ * containing any other key throws a MassAssignmentException so bugs
596
+ * (and injection attempts) surface immediately instead of being
597
+ * silently discarded. Use `forceCreate()` / `forceUpdate()` for
598
+ * trusted server-side data, or set `strictFillable = false` to
599
+ * restore silent discarding.
573
600
  *
574
601
  * @example
575
602
  * class User extends Model<UserRecord> {
@@ -577,6 +604,12 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
577
604
  * }
578
605
  */
579
606
  static fillable?: string[];
607
+ /**
608
+ * When `fillable` is set, controls what happens to input fields outside
609
+ * the allowlist: `true` (default) throws a MassAssignmentException,
610
+ * `false` silently discards them (pre-1.0 behavior).
611
+ */
612
+ static strictFillable?: boolean;
580
613
  /**
581
614
  * Blacklist of fields excluded from mass assignment.
582
615
  * Defaults to `['id']`. Ignored if `fillable` is set.
@@ -1088,6 +1121,20 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
1088
1121
  * })
1089
1122
  */
1090
1123
  static create<T extends typeof Model>(this: T, data: TCreateFor<T>, writeOptions?: ModelWriteOptions): Promise<TRecordFor<T>>;
1124
+ /**
1125
+ * Create a record bypassing mass-assignment protection. Use for trusted,
1126
+ * server-side-assembled data (OAuth account linking, seeders, system
1127
+ * records) — never for raw request input.
1128
+ *
1129
+ * @example
1130
+ * const user = await User.forceCreate({
1131
+ * name: profile.name,
1132
+ * email: profile.email,
1133
+ * passwordHash: `oauth:${provider}:${profile.id}`,
1134
+ * })
1135
+ */
1136
+ static forceCreate<T extends typeof Model>(this: T, data: TCreateFor<T>, writeOptions?: ModelWriteOptions): Promise<TRecordFor<T>>;
1137
+ protected static runCreate<T extends typeof Model>(this: T, data: TCreateFor<T>, writeOptions: ModelWriteOptions | undefined, applyFillable: boolean): Promise<TRecordFor<T>>;
1091
1138
  /**
1092
1139
  * Update records matching the conditions.
1093
1140
  *
@@ -1099,6 +1146,12 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
1099
1146
  * await User.update({ id: 1 }, { name: 'Jane Doe' })
1100
1147
  */
1101
1148
  static update<T extends typeof Model>(this: T, where: WhereClauseFor<T>, data: Partial<TCreateFor<T>>, writeOptions?: ModelWriteOptions): Promise<TRecordFor<T>>;
1149
+ /**
1150
+ * Update records bypassing mass-assignment protection. Use for trusted,
1151
+ * server-side-assembled data — never for raw request input.
1152
+ */
1153
+ static forceUpdate<T extends typeof Model>(this: T, where: WhereClauseFor<T>, data: Partial<TCreateFor<T>>, writeOptions?: ModelWriteOptions): Promise<TRecordFor<T>>;
1154
+ protected static runUpdate<T extends typeof Model>(this: T, where: WhereClauseFor<T>, data: Partial<TCreateFor<T>>, writeOptions: ModelWriteOptions | undefined, applyFillable: boolean): Promise<TRecordFor<T>>;
1102
1155
  /**
1103
1156
  * Delete records matching the conditions.
1104
1157
  *
@@ -1150,7 +1203,22 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
1150
1203
  * const activeUsersWithPosts = await User.with('posts', { status: 'active' })
1151
1204
  */
1152
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[]>>>;
1153
- /** @internal Used by QueryBuilder for eager loading. */
1206
+ /**
1207
+ * Fetch records with related record counts attached as `${name}Count`.
1208
+ * Counts hasMany/hasOne/morphMany children per record without attaching
1209
+ * the related rows themselves; belongsTo yields 0 or 1.
1210
+ *
1211
+ * @example
1212
+ * const users = await User.withCount('posts')
1213
+ * users[0].postsCount // number
1214
+ */
1215
+ 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[]>>>;
1216
+ /** @internal Attaches a `${name}Count` field for one relation. */
1217
+ protected static loadRelationCountInto<T extends typeof Model>(this: T, records: Array<PlainObject>, relationName: string): Promise<void>;
1218
+ /**
1219
+ * @internal Used by QueryBuilder for eager loading.
1220
+ * Supports nested paths with dot notation, e.g. `posts.comments`.
1221
+ */
1154
1222
  static loadRelationInto<T extends typeof Model>(this: T, records: Array<PlainObject>, relationName: string): Promise<void>;
1155
1223
  protected static loadHasMany(records: Array<PlainObject>, definition: HasManyRelationDefinition): Promise<void>;
1156
1224
  protected static loadHasOne(records: Array<PlainObject>, definition: HasOneRelationDefinition): Promise<void>;
@@ -1174,9 +1242,12 @@ type RelationTypesFor<T extends typeof Model> = T extends {
1174
1242
  type RelationKey<T extends typeof Model> = keyof RelationTypesFor<T> & string;
1175
1243
  type RelationKeyOrString<T extends typeof Model> = RelationKey<T> extends never ? string : RelationKey<T>;
1176
1244
  type RelationNameUnion<Names> = Names extends readonly (infer Items)[] ? Items : Names;
1177
- type RelationTypePick<T extends typeof Model, Names> = RelationNameUnion<Names> extends infer Keys ? Keys extends string ? {
1178
- [K in Keys & keyof RelationTypesFor<T>]: RelationTypesFor<T>[K];
1179
- } : {} : {};
1245
+ type RelationTypePick<T extends typeof Model, Names> = {
1246
+ [K in RelationNameUnion<Names> & string & keyof RelationTypesFor<T>]: RelationTypesFor<T>[K];
1247
+ };
1248
+ type RelationCountPick<Names> = {
1249
+ [K in RelationNameUnion<Names> & string as `${K}Count`]: number;
1250
+ };
1180
1251
  interface TransactionModelScope<T extends typeof Model> {
1181
1252
  readonly trx: TransactionHandle;
1182
1253
  all(): Promise<TRecordFor<T>[]>;
@@ -1300,6 +1371,18 @@ declare class ModelNotFoundException extends Error {
1300
1371
  constructor(modelName: string, id: unknown, key?: string);
1301
1372
  }
1302
1373
 
1374
+ /**
1375
+ * Thrown when mass assignment receives fields outside the model's
1376
+ * `fillable` allowlist. Silently discarding them hides bugs (a typo'd
1377
+ * fillable entry surfaces as a NOT NULL violation much later) and can
1378
+ * mask injection attempts, so strict models fail loudly instead.
1379
+ */
1380
+ declare class MassAssignmentException extends Error {
1381
+ readonly model: string;
1382
+ readonly fields: string[];
1383
+ constructor(model: string, fields: string[]);
1384
+ }
1385
+
1303
1386
  /**
1304
1387
  * Interface describing the static methods added by the SoftDeletes mixin.
1305
1388
  */
@@ -1409,65 +1492,98 @@ declare const DrizzleAdapter: ORMAdapterAdvanced & {
1409
1492
  */
1410
1493
  declare function buildDrizzleConditions(table: unknown, conditions: WhereCondition[]): SQL | undefined;
1411
1494
 
1495
+ interface MigrationStatusEntry {
1496
+ name: string;
1497
+ applied: boolean;
1498
+ appliedAt: Date | null;
1499
+ }
1500
+
1412
1501
  type ConnectionResolver$2 = string | (() => string | undefined);
1413
- interface PostgresDatabaseOptions<TSchema extends Record<string, unknown>> {
1414
- schema: TSchema;
1502
+ interface PostgresDatabaseOptions {
1415
1503
  migrationsFolder: string | URL;
1416
1504
  connectionString?: ConnectionResolver$2;
1417
1505
  clientOptions?: postgres.Options<Record<string, never>>;
1418
1506
  seedersFolder?: string | URL;
1507
+ /**
1508
+ * Drizzle relations for RQB v2 (`db.query.*`).
1509
+ * Build with `defineRelations(schema, ...)` from `drizzle-orm`,
1510
+ * or with `relations()` from `drizzle-orm/_relations` for the RQB v1 partial-upgrade path.
1511
+ */
1512
+ relations?: Record<string, unknown>;
1419
1513
  }
1420
- interface PostgresDatabase<TSchema extends Record<string, unknown>> {
1421
- getDatabase(): Promise<PostgresJsDatabase<TSchema>>;
1514
+ interface PostgresDatabase {
1515
+ getDatabase(): Promise<PostgresJsDatabase>;
1422
1516
  migrateDatabase(): Promise<void>;
1423
1517
  closeDatabase(): Promise<void>;
1424
1518
  configureOrm(): Promise<void>;
1425
1519
  seedDatabase(): Promise<void>;
1520
+ /** Drops the public schema (and the drizzle tracker schema) so migrations can be re-applied from scratch. */
1521
+ resetDatabase(): Promise<void>;
1522
+ /** Per-migration applied state derived from the drizzle-kit journal and drizzle.__drizzle_migrations. */
1523
+ migrationStatus(): Promise<MigrationStatusEntry[]>;
1426
1524
  }
1427
- declare function createPostgresDatabase<TSchema extends Record<string, unknown>>(options: PostgresDatabaseOptions<TSchema>): PostgresDatabase<TSchema>;
1525
+ declare function createPostgresDatabase(options: PostgresDatabaseOptions): PostgresDatabase;
1428
1526
 
1429
1527
  type ConnectionResolver$1 = string | (() => string | undefined);
1430
1528
  type MySqlConnectionOptions = Record<string, unknown>;
1431
- interface MySqlDatabaseOptions<TSchema extends Record<string, unknown>> {
1432
- schema: TSchema;
1529
+ interface MySqlDatabaseOptions {
1433
1530
  migrationsFolder: string | URL;
1434
1531
  connectionString?: ConnectionResolver$1;
1435
1532
  clientOptions?: MySqlConnectionOptions;
1436
1533
  seedersFolder?: string | URL;
1534
+ /**
1535
+ * Drizzle relations for RQB v2 (`db.query.*`).
1536
+ * Build with `defineRelations(schema, ...)` from `drizzle-orm`,
1537
+ * or with `relations()` from `drizzle-orm/_relations` for the RQB v1 partial-upgrade path.
1538
+ */
1539
+ relations?: Record<string, unknown>;
1437
1540
  }
1438
- interface MySqlDatabase<TSchema extends Record<string, unknown>> {
1439
- getDatabase(): Promise<MySql2Database<TSchema>>;
1541
+ interface MySqlDatabase {
1542
+ getDatabase(): Promise<MySql2Database>;
1440
1543
  migrateDatabase(): Promise<void>;
1441
1544
  closeDatabase(): Promise<void>;
1442
1545
  configureOrm(): Promise<void>;
1443
1546
  seedDatabase(): Promise<void>;
1547
+ /** Drops every table (including the drizzle migration tracker) so migrations can be re-applied from scratch. */
1548
+ resetDatabase(): Promise<void>;
1549
+ /** Per-migration applied state derived from the drizzle-kit journal and the __drizzle_migrations table. */
1550
+ migrationStatus(): Promise<MigrationStatusEntry[]>;
1444
1551
  }
1445
- declare function createMySqlDatabase<TSchema extends Record<string, unknown>>(options: MySqlDatabaseOptions<TSchema>): MySqlDatabase<TSchema>;
1552
+ declare function createMySqlDatabase(options: MySqlDatabaseOptions): MySqlDatabase;
1446
1553
 
1447
1554
  type ConnectionResolver = string | (() => string | undefined);
1448
- interface SqliteDatabaseOptions<TSchema extends Record<string, unknown>> {
1449
- schema: TSchema;
1555
+ interface SqliteDatabaseOptions {
1450
1556
  migrationsFolder: string | URL;
1451
1557
  /** Path to the SQLite database file. Defaults to `./data/guren.db`. */
1452
1558
  filename?: ConnectionResolver;
1453
1559
  seedersFolder?: string | URL;
1560
+ /**
1561
+ * Drizzle relations for RQB v2 (`db.query.*`).
1562
+ * Build with `defineRelations(schema, ...)` from `drizzle-orm`,
1563
+ * or with `relations()` from `drizzle-orm/_relations` for the RQB v1 partial-upgrade path.
1564
+ */
1565
+ relations?: Record<string, unknown>;
1454
1566
  }
1455
- interface SqliteDatabase<TSchema extends Record<string, unknown>> {
1567
+ interface SqliteDatabase {
1456
1568
  getDatabase(): Promise<unknown>;
1457
1569
  migrateDatabase(): Promise<void>;
1458
1570
  closeDatabase(): Promise<void>;
1459
1571
  configureOrm(): Promise<void>;
1460
1572
  seedDatabase(): Promise<void>;
1573
+ /** Drops every table (including the drizzle migration tracker) so migrations can be re-applied from scratch. */
1574
+ resetDatabase(): Promise<void>;
1575
+ /** Per-migration applied state derived from the drizzle-kit journal and the __drizzle_migrations table. */
1576
+ migrationStatus(): Promise<MigrationStatusEntry[]>;
1461
1577
  }
1462
- declare function createSqliteDatabase<TSchema extends Record<string, unknown>>(options: SqliteDatabaseOptions<TSchema>): SqliteDatabase<TSchema>;
1578
+ declare function createSqliteDatabase(options: SqliteDatabaseOptions): SqliteDatabase;
1463
1579
 
1464
- interface SeederContext<TSchema extends Record<string, unknown>> {
1465
- db: PostgresJsDatabase<TSchema>;
1580
+ interface SeederContext {
1581
+ db: PostgresJsDatabase;
1466
1582
  }
1467
- type SeederHandler<TSchema extends Record<string, unknown>> = (context: SeederContext<TSchema>) => unknown;
1468
- declare function loadSeeders<TSchema extends Record<string, unknown>>(directory: string | URL): Promise<Array<SeederHandler<TSchema>>>;
1469
- declare function runSeeders<TSchema extends Record<string, unknown>>(db: PostgresJsDatabase<TSchema>, directory: string | URL): Promise<void>;
1470
- declare function defineSeeder<TSchema extends Record<string, unknown>>(handler: SeederHandler<TSchema>): SeederHandler<TSchema>;
1583
+ type SeederHandler = (context: SeederContext) => unknown;
1584
+ declare function loadSeeders(directory: string | URL): Promise<Array<SeederHandler>>;
1585
+ declare function runSeeders(db: PostgresJsDatabase, directory: string | URL): Promise<void>;
1586
+ declare function defineSeeder(handler: SeederHandler): SeederHandler;
1471
1587
 
1472
1588
  /**
1473
1589
  * Serialize a model record for API/JSON output.
@@ -1483,4 +1599,4 @@ declare function serializeRecord(record: PlainObject, options: {
1483
1599
  /** Serialize an array of records. */
1484
1600
  declare function serializeRecords(records: PlainObject[], options: Parameters<typeof serializeRecord>[1]): PlainObject[];
1485
1601
 
1486
- 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, Model, type ModelHooks, ModelNotFoundException, type ModelObserver, type ModelObserverConstructor, 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 PaginationMeta, 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 };
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 };