uql-orm 0.98.0 → 0.99.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.
@@ -53,7 +53,7 @@ export async function main(args = process.argv.slice(2)) {
53
53
  break;
54
54
  }
55
55
  case 'pending': {
56
- const pending = (await migrator.pending()).map((migration) => migration.name);
56
+ const pending = await migrator.pending();
57
57
  print(...(pending.length ? ['Pending migrations:', ...listed(pending, '○')] : ['No pending migrations.']));
58
58
  break;
59
59
  }
@@ -19,13 +19,12 @@ export declare class Migrator {
19
19
  /** The schema generator, loaded on first use: MongoDB's needs its optional peer. */
20
20
  getSchemaGenerator(): Promise<SchemaGenerator>;
21
21
  /**
22
- * Get all discovered migrations from the migrations directory
22
+ * The migration files by name, the names the storage records as run, and those on disk it does not, all in
23
+ * name order. Read from names alone: a file is imported only when it is about to run.
23
24
  */
24
- getMigrations(): Promise<Migration<Querier>[]>;
25
- /** The migrations on disk the storage records as run (`applied`) or not (`pending`), and every name it records. */
26
25
  private journal;
27
- /** The migrations not yet run. */
28
- pending(): Promise<Migration<Querier>[]>;
26
+ /** The names of the migrations not yet run, in the order `up` runs them. */
27
+ pending(): Promise<string[]>;
29
28
  /**
30
29
  * Get list of executed migrations
31
30
  */
@@ -44,7 +43,10 @@ export declare class Migrator {
44
43
  to?: string;
45
44
  step?: number;
46
45
  }): Promise<MigrationResult[]>;
47
- /** Runs the list narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over the executed reversed. */
46
+ /**
47
+ * Runs the names narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over
48
+ * the executed reversed. Every one is loaded before any runs, so a file that cannot be leaves the database as it was.
49
+ */
48
50
  private runInOrder;
49
51
  /**
50
52
  * Run a single migration, in a transaction where the dialect has one for it and the migration has not
@@ -140,18 +142,10 @@ export declare class Migrator {
140
142
  pending: string[];
141
143
  executed: string[];
142
144
  }>;
143
- /**
144
- * Get migration files from the migrations directory
145
- */
146
- getMigrationFiles(): Promise<string[]>;
147
- /**
148
- * Load a migration from a file
149
- */
150
- loadMigration(fileName: string): Promise<Migration<Querier> | undefined>;
151
- /**
152
- * Check if an object is a valid migration
153
- */
154
- isMigration(obj: unknown): obj is MigrationDefinition<Querier>;
145
+ /** The migration files in the migrations directory, by the name each runs as; none where it is missing. */
146
+ private migrationFiles;
147
+ /** The migration `name`, from its `file`: a missing file, one that fails to import, or one exporting no migration throws. */
148
+ private loadMigration;
155
149
  }
156
150
  /**
157
151
  * Helper function to define a migration with proper typing
@@ -45,31 +45,16 @@ export class Migrator {
45
45
  return this.schemaGenerator;
46
46
  }
47
47
  /**
48
- * Get all discovered migrations from the migrations directory
48
+ * The migration files by name, the names the storage records as run, and those on disk it does not, all in
49
+ * name order. Read from names alone: a file is imported only when it is about to run.
49
50
  */
50
- async getMigrations() {
51
- const files = await this.getMigrationFiles();
52
- const migrations = [];
53
- for (const file of files) {
54
- const migration = await this.loadMigration(file);
55
- if (migration) {
56
- migrations.push(migration);
57
- }
58
- }
59
- // Sort by name (which typically includes timestamp)
60
- return migrations.sort((a, b) => a.name.localeCompare(b.name));
61
- }
62
- /** The migrations on disk the storage records as run (`applied`) or not (`pending`), and every name it records. */
63
51
  async journal() {
64
- const [migrations, executed] = await Promise.all([this.getMigrations(), this.storage.executed()]);
52
+ const [files, recorded] = await Promise.all([this.migrationFiles(), this.storage.executed()]);
53
+ const executed = recorded.toSorted();
65
54
  const ran = new Set(executed);
66
- return {
67
- executed,
68
- applied: migrations.filter((migration) => ran.has(migration.name)),
69
- pending: migrations.filter((migration) => !ran.has(migration.name)),
70
- };
55
+ return { files, executed, pending: [...files.keys()].sort().filter((name) => !ran.has(name)) };
71
56
  }
72
- /** The migrations not yet run. */
57
+ /** The names of the migrations not yet run, in the order `up` runs them. */
73
58
  async pending() {
74
59
  return (await this.journal()).pending;
75
60
  }
@@ -83,19 +68,24 @@ export class Migrator {
83
68
  * Run all pending migrations
84
69
  */
85
70
  async up(options = {}) {
86
- return this.runInOrder(await this.pending(), 'up', options);
71
+ const { files, pending } = await this.journal();
72
+ return this.runInOrder(files, pending, 'up', options);
87
73
  }
88
74
  /**
89
75
  * Rollback migrations
90
76
  */
91
77
  async down(options = {}) {
92
- return this.runInOrder((await this.journal()).applied.reverse(), 'down', options);
78
+ const { files, executed } = await this.journal();
79
+ return this.runInOrder(files, executed.reverse(), 'down', options);
93
80
  }
94
- /** Runs the list narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over the executed reversed. */
95
- async runInOrder(migrations, direction, options) {
96
- let selected = migrations;
81
+ /**
82
+ * Runs the names narrowed by `to`/`step`, stopping at the first failure: `up` over the pending, `down` over
83
+ * the executed reversed. Every one is loaded before any runs, so a file that cannot be leaves the database as it was.
84
+ */
85
+ async runInOrder(files, names, direction, options) {
86
+ let selected = names;
97
87
  if (options.to) {
98
- const toIndex = selected.findIndex((m) => m.name === options.to);
88
+ const toIndex = selected.indexOf(options.to);
99
89
  if (toIndex === -1) {
100
90
  throw new UqlUsageError(`Migration '${options.to}' not found`);
101
91
  }
@@ -104,8 +94,9 @@ export class Migrator {
104
94
  if (options.step !== undefined) {
105
95
  selected = selected.slice(0, options.step);
106
96
  }
97
+ const migrations = await Promise.all(selected.map((name) => this.loadMigration(name, files.get(name))));
107
98
  const results = [];
108
- for (const migration of selected) {
99
+ for (const migration of migrations) {
109
100
  const result = await this.runMigration(migration, direction);
110
101
  results.push(result);
111
102
  if (!result.success) {
@@ -472,58 +463,54 @@ export class Migrator {
472
463
  */
473
464
  async status() {
474
465
  const { pending, executed } = await this.journal();
475
- return { pending: pending.map((migration) => migration.name), executed };
466
+ return { pending, executed };
476
467
  }
477
- /**
478
- * Get migration files from the migrations directory
479
- */
480
- async getMigrationFiles() {
468
+ /** The migration files in the migrations directory, by the name each runs as; none where it is missing. */
469
+ async migrationFiles() {
470
+ let entries;
481
471
  try {
482
- const files = await readdir(this.migrationsPath);
483
- return files
484
- .filter((f) => /\.(ts|js|mjs)$/.test(f))
485
- .filter((f) => !f.endsWith('.d.ts'))
486
- .sort();
472
+ entries = await readdir(this.migrationsPath);
487
473
  }
488
474
  catch (error) {
489
475
  if (error.code === 'ENOENT') {
490
- return [];
476
+ return new Map();
491
477
  }
492
478
  throw error;
493
479
  }
494
- }
495
- /**
496
- * Load a migration from a file
497
- */
498
- async loadMigration(fileName) {
499
- const filePath = join(this.migrationsPath, fileName);
500
- const fileUrl = pathToFileURL(filePath).href;
501
- try {
502
- const module = await import(fileUrl);
503
- const migration = module.default ?? module;
504
- if (this.isMigration(migration)) {
505
- return {
506
- name: basename(fileName, extname(fileName)),
507
- up: migration.up.bind(migration),
508
- down: migration.down.bind(migration),
509
- transaction: migration.transaction,
510
- };
480
+ const files = new Map();
481
+ for (const file of entries.filter((entry) => /\.(ts|js|mjs)$/.test(entry) && !entry.endsWith('.d.ts'))) {
482
+ const name = basename(file, extname(file));
483
+ const other = files.get(name);
484
+ if (other) {
485
+ throw new UqlUsageError(`Migrations ${other} and ${file} share the name '${name}'`);
511
486
  }
512
- this.logger.logWarn(`Warning: ${fileName} is not a valid migration`);
513
- return undefined;
514
- }
515
- catch (error) {
516
- this.logger.logError(`Error loading migration ${fileName}: ${error.message}`, error);
517
- return undefined;
487
+ files.set(name, file);
518
488
  }
489
+ return files;
519
490
  }
520
- /**
521
- * Check if an object is a valid migration
522
- */
523
- isMigration(obj) {
524
- return isRecord(obj) && typeof obj['up'] === 'function' && typeof obj['down'] === 'function';
491
+ /** The migration `name`, from its `file`: a missing file, one that fails to import, or one exporting no migration throws. */
492
+ async loadMigration(name, file) {
493
+ if (!file) {
494
+ throw new UqlUsageError(`Migration '${name}' is recorded as run but has no file in ${this.migrationsPath}`);
495
+ }
496
+ const module = await import(pathToFileURL(join(this.migrationsPath, file)).href).catch((error) => {
497
+ throw new UqlUsageError(`Migration ${file} failed to load: ${error.message}`, { cause: error });
498
+ });
499
+ const migration = module.default ?? module;
500
+ if (!isMigrationDefinition(migration)) {
501
+ throw new UqlUsageError(`Migration ${file} exports no migration: \`up\` and \`down\` functions, as its default export or its own`);
502
+ }
503
+ return {
504
+ name,
505
+ up: migration.up.bind(migration),
506
+ down: migration.down.bind(migration),
507
+ transaction: migration.transaction,
508
+ };
525
509
  }
526
510
  }
511
+ function isMigrationDefinition(value) {
512
+ return isRecord(value) && typeof value['up'] === 'function' && typeof value['down'] === 'function';
513
+ }
527
514
  /** The local time a migration file is named by, `YYYYMMDDHHmmss`, so names sort in the order they were made. */
528
515
  function timestamp() {
529
516
  const now = new Date();
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "homepage": "https://uql-orm.dev",
4
4
  "description": "JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, SQL Server, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
5
5
  "license": "MIT",
6
- "version": "0.98.0",
6
+ "version": "0.99.0",
7
7
  "type": "module",
8
8
  "engines": {
9
9
  "node": ">=24"