@guren/orm 2.14.0 → 2.15.1

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
@@ -1,3 +1,4 @@
1
+ import { DestructiveMigrationError, DestructiveMigrationMode } from "./migration-guard.js";
1
2
  import { SQL } from "drizzle-orm";
2
3
  import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
3
4
  import postgres from "postgres";
@@ -83,6 +84,8 @@ declare const SEAL_SCOPES: unique symbol;
83
84
  declare const READ_TRANSFORMS: unique symbol;
84
85
  /** Rows as the adapter read them, for the joins a relation loader makes. */
85
86
  declare const RAW_RESULTS: unique symbol;
87
+ /** A model's own relation definitions, for the serializer, which cannot import `Model`. */
88
+ declare const RELATION_DEFINITIONS: unique symbol;
86
89
  /** Explicit physical deletion, used by SoftDeletes.forceDelete. */
87
90
  declare const PHYSICAL_DELETE: unique symbol;
88
91
  /** A static delete run inside the model's lifecycle, shared with SoftDeletes. */
@@ -628,9 +631,14 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
628
631
  * that is refused; the builder repeats the check for its own callers.
629
632
  */
630
633
  private static assertFiltersSurvived;
631
- /** Applies hidden/visible filtering, accessors and appends. */
634
+ /**
635
+ * Applies hidden/visible filtering, accessors and appends, then each loaded
636
+ * relation's own model's hidden/visible to its rows, nested ones included.
637
+ */
632
638
  static serialize<T extends typeof Model>(this: T, record: TRecordFor<T>): PlainObject;
633
639
  static serializeMany<T extends typeof Model>(this: T, records: TRecordFor<T>[]): PlainObject[];
640
+ /** @internal The serializer's view of the relations, symbol-keyed like `[READ_TRANSFORMS]`. */
641
+ static [RELATION_DEFINITIONS](): ReadonlyMap<string, RelationDefinition>;
634
642
  static applyCasts<T extends PlainObject>(record: T): T;
635
643
  /** The one read-transform pass for a record, in order: casts then accessors. */
636
644
  protected static applyReadTransforms<T extends PlainObject>(record: T): T;
@@ -666,6 +674,12 @@ declare abstract class Model<TRecord extends PlainObject = PlainObject> {
666
674
  /** @throws ModelNotFoundException (404) when no record matches. */
667
675
  static findOrFail<T extends typeof Model>(this: T, id: TRecordFor<T>[keyof TRecordFor<T> & string], key?: keyof TRecordFor<T> & string, queryOptions?: ModelQueryOptions): Promise<TRecordFor<T>>;
668
676
  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>;
677
+ /**
678
+ * `find()` with its relations loaded ahead of the read transforms: a loader
679
+ * matches rows on raw key values, which a cast or an accessor on this model
680
+ * would have rewritten.
681
+ */
682
+ private static findRawWith;
669
683
  /**
670
684
  * Relations accept dot-notation paths (`comments.author`).
671
685
  * @throws ModelNotFoundException when no record matches.
@@ -1104,6 +1118,21 @@ interface ConnectionContext {
1104
1118
  */
1105
1119
  type ConnectionResolver = string | ((context?: ConnectionContext) => string | undefined);
1106
1120
  //#endregion
1121
+ //#region src/database-description.d.ts
1122
+ /**
1123
+ * Where a factory's database lives, judged without connecting (RFC 0033 §3): what lets
1124
+ * `guren browser:serve` refuse to boot an app against a database it cannot show is local.
1125
+ * Anything not positively local is `remote` or `unknown`, never `local`. The connection
1126
+ * string itself is never part of the result, since it can carry a password.
1127
+ */
1128
+ interface DatabaseDescription {
1129
+ dialect: 'postgres' | 'mysql' | 'sqlite' | 'd1';
1130
+ location: 'local' | 'remote' | 'unknown';
1131
+ reason?: string;
1132
+ /** The Workers binding a D1 factory names as a string; a closure is opaque, so it has none (RFC 0035 §2.1). */
1133
+ binding?: string;
1134
+ }
1135
+ //#endregion
1107
1136
  //#region src/migration-utils.d.ts
1108
1137
  /**
1109
1138
  * What one `migrateDatabase()` call had to work with. `db:migrate` reports
@@ -1133,6 +1162,8 @@ interface MigrationStatusEntry {
1133
1162
  * then deleted from disk (or migrated by another checkout). Absent otherwise.
1134
1163
  */
1135
1164
  orphaned?: boolean;
1165
+ /** The absolute `migration.sql` for a local migration; absent on an orphaned row. */
1166
+ path?: string;
1136
1167
  }
1137
1168
  //#endregion
1138
1169
  //#region src/seeder.d.ts
@@ -1182,6 +1213,12 @@ declare function defineSeeder<TDatabase = PostgresJsDatabase>(handler: SeederHan
1182
1213
  //#region src/postgres.d.ts
1183
1214
  interface PostgresDatabaseOptions {
1184
1215
  migrationsFolder: string | URL;
1216
+ /**
1217
+ * What a boot or `migrateDatabase()` does with a pending migration that drops,
1218
+ * narrows or renames without a `-- guren:allow-destructive` comment (RFC 0034):
1219
+ * `'warn'` (the v2 default) prints it and applies; `'refuse'` throws first.
1220
+ */
1221
+ destructiveMigrations?: DestructiveMigrationMode;
1185
1222
  connectionString?: ConnectionResolver;
1186
1223
  clientOptions?: postgres.Options<Record<string, never>>;
1187
1224
  seedersFolder?: string | URL;
@@ -1207,6 +1244,8 @@ interface PostgresDatabase {
1207
1244
  migrationStatus(): Promise<MigrationStatusEntry[]>;
1208
1245
  /** Whether the migrations folder holds a migration. Reads files only, never the database. */
1209
1246
  hasMigrations(): boolean;
1247
+ /** Where the database lives for `context`, without connecting (RFC 0033 §3); never carries the connection string. */
1248
+ describe(context?: ConnectionContext): DatabaseDescription;
1210
1249
  }
1211
1250
  declare function createPostgresDatabase(options: PostgresDatabaseOptions): PostgresDatabase;
1212
1251
  //#endregion
@@ -1214,6 +1253,12 @@ declare function createPostgresDatabase(options: PostgresDatabaseOptions): Postg
1214
1253
  type MySqlConnectionOptions = Record<string, unknown>;
1215
1254
  interface MySqlDatabaseOptions {
1216
1255
  migrationsFolder: string | URL;
1256
+ /**
1257
+ * What a boot or `migrateDatabase()` does with a pending migration that drops,
1258
+ * narrows or renames without a `-- guren:allow-destructive` comment (RFC 0034):
1259
+ * `'warn'` (the v2 default) prints it and applies; `'refuse'` throws first.
1260
+ */
1261
+ destructiveMigrations?: DestructiveMigrationMode;
1217
1262
  connectionString?: ConnectionResolver;
1218
1263
  clientOptions?: MySqlConnectionOptions;
1219
1264
  seedersFolder?: string | URL;
@@ -1239,12 +1284,20 @@ interface MySqlDatabase {
1239
1284
  migrationStatus(): Promise<MigrationStatusEntry[]>;
1240
1285
  /** Whether the migrations folder holds a migration. Reads files only, never the database. */
1241
1286
  hasMigrations(): boolean;
1287
+ /** Where the database lives for `context`, without connecting (RFC 0033 §3); never carries the connection string. */
1288
+ describe(context?: ConnectionContext): DatabaseDescription;
1242
1289
  }
1243
1290
  declare function createMySqlDatabase(options: MySqlDatabaseOptions): MySqlDatabase;
1244
1291
  //#endregion
1245
1292
  //#region src/sqlite.d.ts
1246
1293
  interface SqliteDatabaseOptions {
1247
1294
  migrationsFolder: string | URL;
1295
+ /**
1296
+ * What a boot or `migrateDatabase()` does with a pending migration that drops,
1297
+ * narrows or renames without a `-- guren:allow-destructive` comment (RFC 0034):
1298
+ * `'warn'` (the v2 default) prints it and applies; `'refuse'` throws first.
1299
+ */
1300
+ destructiveMigrations?: DestructiveMigrationMode;
1248
1301
  /** Path to the SQLite database file. Defaults to `./data/guren.db`. */
1249
1302
  filename?: ConnectionResolver;
1250
1303
  seedersFolder?: string | URL;
@@ -1274,17 +1327,19 @@ interface SqliteDatabase {
1274
1327
  migrationStatus(): Promise<MigrationStatusEntry[]>;
1275
1328
  /** Whether the migrations folder holds a migration. Reads files only, never the database. */
1276
1329
  hasMigrations(): boolean;
1330
+ /** Where the database lives for `context`, without connecting (RFC 0033 §3); never carries the connection string. */
1331
+ describe(context?: ConnectionContext): DatabaseDescription;
1277
1332
  }
1278
1333
  declare function createSqliteDatabase(options: SqliteDatabaseOptions): SqliteDatabase;
1279
1334
  //#endregion
1280
1335
  //#region src/d1.d.ts
1281
1336
  interface D1DatabaseOptions {
1282
1337
  /**
1283
- * Resolver returning the Cloudflare D1 binding. Bindings arrive with the
1284
- * first request on Workers, so this must be a deferred closure, e.g.
1285
- * `binding: () => getWorkersEnv<Env>().DB`.
1338
+ * The Cloudflare D1 binding: its name (`'DB'`), read from the Workers env the first
1339
+ * request captured, or a deferred closure such as `() => getWorkersEnv<Env>().DB`.
1340
+ * The name is what `describe()` reports, so the deploy can tell which binding it is.
1286
1341
  */
1287
- binding: () => unknown;
1342
+ binding: string | (() => unknown);
1288
1343
  /**
1289
1344
  * Drizzle-kit migrations folder. D1 migrations are applied out-of-band via
1290
1345
  * `wrangler d1 migrations apply` (point `d1_databases[].migrations_dir` here);
@@ -1312,6 +1367,8 @@ interface D1DatabaseHandle {
1312
1367
  migrationStatus(): Promise<never>;
1313
1368
  /** Always false: wrangler applies D1 migrations and the factory never seeds, so nothing at boot acts on them. */
1314
1369
  hasMigrations(): boolean;
1370
+ /** Always `unknown`; see its `reason`. */
1371
+ describe(): DatabaseDescription;
1315
1372
  }
1316
1373
  /**
1317
1374
  * Cloudflare D1 database factory. D1 speaks the SQLite dialect, so schemas
@@ -1324,6 +1381,12 @@ declare function createD1Database(options: D1DatabaseOptions): D1DatabaseHandle;
1324
1381
  type AwsDataApiPgDatabase$1 = import('drizzle-orm/aws-data-api/pg').AwsDataApiPgDatabase;
1325
1382
  interface AwsDataApiDatabaseOptions {
1326
1383
  migrationsFolder: string | URL;
1384
+ /**
1385
+ * What a boot or `migrateDatabase()` does with a pending migration that drops,
1386
+ * narrows or renames without a `-- guren:allow-destructive` comment (RFC 0034):
1387
+ * `'warn'` (the v2 default) prints it and applies; `'refuse'` throws first.
1388
+ */
1389
+ destructiveMigrations?: DestructiveMigrationMode;
1327
1390
  /** Database name. Falls back to the DATABASE_NAME environment variable. */
1328
1391
  database?: ConnectionResolver;
1329
1392
  /** Aurora cluster ARN. Falls back to the DATABASE_RESOURCE_ARN environment variable. */
@@ -1376,4 +1439,4 @@ declare function serializeRecord(record: PlainObject, options: {
1376
1439
  /** Serialize an array of records. */
1377
1440
  declare function serializeRecords(records: PlainObject[], options: Parameters<typeof serializeRecord>[1]): PlainObject[];
1378
1441
  //#endregion
1379
- export { type AccessorDefinitions, type AccessorFn, type AggregateFunction, type AvgValue, type AwsDataApiDatabase, type AwsDataApiDatabaseOptions, type AwsDataApiSeederContext, type BelongsToManyRecord, type BelongsToManyRelationResult, type BelongsToRecord, type BelongsToRelationResult, type BelongsToRequiredRecord, type CastType, type ConnectionContext, type D1DatabaseHandle, type D1DatabaseOptions, DrizzleAdapter, type DrizzleSelectQuery, 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 MigrationRunSummary, type MigrationStatusEntry, Model, type ModelHooks, ModelNotFoundException, type ModelObserver, type ModelObserverConstructor, type ModelPaginationMeta, type ModelQueryOptions, type ModelSetOptions, 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 OrmConnectionEnv, type PaginateOptions, type PaginatedResult, type PlainObject, type PostgresDatabase, type PostgresDatabaseOptions, type PostgresSeederContext, QueryBuilder, type QueryBuilderOptions, type ScopeFunction, type SeederContext, type SeederHandler, type SeederRunSummary, type SimpleCondition, SoftDeletes, type SoftDeletesStatic, type SqliteDatabase, type SqliteDatabaseOptions, type SqliteSeederContext, type SumValue, 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 };
1442
+ export { type AccessorDefinitions, type AccessorFn, type AggregateFunction, type AvgValue, type AwsDataApiDatabase, type AwsDataApiDatabaseOptions, type AwsDataApiSeederContext, type BelongsToManyRecord, type BelongsToManyRelationResult, type BelongsToRecord, type BelongsToRelationResult, type BelongsToRequiredRecord, type CastType, type ConnectionContext, type D1DatabaseHandle, type D1DatabaseOptions, type DatabaseDescription, DestructiveMigrationError, type DestructiveMigrationMode, DrizzleAdapter, type DrizzleSelectQuery, 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 MigrationRunSummary, type MigrationStatusEntry, Model, type ModelHooks, ModelNotFoundException, type ModelObserver, type ModelObserverConstructor, type ModelPaginationMeta, type ModelQueryOptions, type ModelSetOptions, 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 OrmConnectionEnv, type PaginateOptions, type PaginatedResult, type PlainObject, type PostgresDatabase, type PostgresDatabaseOptions, type PostgresSeederContext, QueryBuilder, type QueryBuilderOptions, type ScopeFunction, type SeederContext, type SeederHandler, type SeederRunSummary, type SimpleCondition, SoftDeletes, type SoftDeletesStatic, type SqliteDatabase, type SqliteDatabaseOptions, type SqliteSeederContext, type SumValue, 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 };