@jskit-ai/database-runtime 0.1.251 → 0.1.253

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.
@@ -1,16 +1,26 @@
1
1
  import { normalizeCanonicalRecordIdText } from "@jskit-ai/kernel/shared/support/normalize";
2
2
 
3
- function resolveQueryOptions(options = {}) {
3
+ /**
4
+ * The transaction a repository or service call runs in: its options' `trx`,
5
+ * or null for a call outside one (a call may pass no options).
6
+ * @param {{ trx?: import("../server/types.js").RuntimeKnexTransaction | null } | null} [options]
7
+ * @returns {import("../server/types.js").RuntimeKnexTransaction | null}
8
+ */
9
+ function resolveTransaction(options) {
4
10
  if (!options || typeof options !== "object") {
5
- return {
6
- trx: null,
7
- forUpdate: false
8
- };
11
+ return null;
9
12
  }
13
+ return options.trx || null;
14
+ }
10
15
 
16
+ /**
17
+ * A query's transaction (see resolveTransaction) and whether it locks the rows it reads.
18
+ * @param {{ trx?: import("../server/types.js").RuntimeKnexTransaction | null, forUpdate?: boolean } | null} [options]
19
+ */
20
+ function resolveQueryOptions(options) {
11
21
  return {
12
- trx: options.trx || null,
13
- forUpdate: options.forUpdate === true
22
+ trx: resolveTransaction(options),
23
+ forUpdate: options?.forUpdate === true
14
24
  };
15
25
  }
16
26
 
@@ -21,6 +31,7 @@ function resolveRepoClient(dbClient, options = {}) {
21
31
 
22
32
  function applyForUpdate(query, options = {}) {
23
33
  const { forUpdate } = resolveQueryOptions(options);
34
+ // readable-check: allow method-probe - platform object: a Knex query builder that cannot lock rows is used as is
24
35
  if (forUpdate && typeof query?.forUpdate === "function") {
25
36
  return query.forUpdate();
26
37
  }
@@ -151,9 +162,12 @@ function toDbJson(value) {
151
162
  return JSON.stringify(value);
152
163
  }
153
164
 
154
- // True when the error reports a transaction the database aborted, and rolled
155
- // back in full, as a deadlock victim. A wrapper that reports its transaction
156
- // committed (json-rest-api's transactionOutcome) never is one.
165
+ /**
166
+ * True when the error reports a transaction the database aborted, and rolled
167
+ * back in full, as a deadlock victim. A wrapper that reports its transaction
168
+ * committed (json-rest-api's transactionOutcome) never is one.
169
+ * @param {unknown} error
170
+ */
157
171
  function isDeadlockError(error) {
158
172
  const seen = new Set();
159
173
  while (error && typeof error === "object" && !seen.has(error)) {
@@ -170,8 +184,14 @@ function isDeadlockError(error) {
170
184
  return false;
171
185
  }
172
186
 
173
- // Runs a whole transaction again when the database chose it as a deadlock
174
- // victim, so `run` must be safe to repeat: no external effects inside it.
187
+ /**
188
+ * Runs a whole transaction again when the database chose it as a deadlock
189
+ * victim, so `run` must be safe to repeat: no external effects inside it.
190
+ * @template T
191
+ * @param {() => Promise<T>} run
192
+ * @param {{ retries?: number }} [options]
193
+ * @returns {Promise<T>}
194
+ */
175
195
  async function retryDeadlocks(run, { retries = 3 } = {}) {
176
196
  for (let attempt = 1; ; attempt += 1) {
177
197
  try {
@@ -193,6 +213,7 @@ async function runInTransaction(knex, callback, options = {}) {
193
213
  throw new TypeError("runInTransaction requires knex client.");
194
214
  }
195
215
 
216
+ // readable-check: allow method-probe - platform object: a Knex client without transaction() runs the callback on itself
196
217
  if (typeof knex.transaction !== "function") {
197
218
  return callback(knex);
198
219
  }
@@ -210,6 +231,21 @@ function createWithTransaction(knex) {
210
231
  };
211
232
  }
212
233
 
234
+ /**
235
+ * Joins the caller's transaction or opens one: runs work in the call's
236
+ * `options.trx` when the caller holds a transaction, else in the one that
237
+ * withTransaction opens.
238
+ * @template T
239
+ * @param {{ trx?: import("../server/types.js").RuntimeKnexTransaction | null }} options The call's options.
240
+ * @param {(work: (trx: import("../server/types.js").RuntimeKnexTransaction) => Promise<T>) => Promise<T>} withTransaction
241
+ * The repository's withTransaction: opens a transaction and runs work in it.
242
+ * @param {(trx: import("../server/types.js").RuntimeKnexTransaction) => Promise<T>} work
243
+ * @returns {Promise<T>}
244
+ */
245
+ function joinOrOpenTransaction(options, withTransaction, work) {
246
+ return options.trx ? work(options.trx) : withTransaction(work);
247
+ }
248
+
213
249
  function requireSqlIdentifier(value, label) {
214
250
  const identifier = String(value || "").trim();
215
251
  if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(identifier)) {
@@ -247,6 +283,7 @@ async function lockScopedRecordId({
247
283
  }
248
284
 
249
285
  export {
286
+ resolveTransaction,
250
287
  resolveQueryOptions,
251
288
  resolveRepoClient,
252
289
  applyForUpdate,
@@ -261,5 +298,6 @@ export {
261
298
  retryDeadlocks,
262
299
  runInTransaction,
263
300
  createWithTransaction,
301
+ joinOrOpenTransaction,
264
302
  lockScopedRecordId
265
303
  };
@@ -1,16 +1,19 @@
1
- import { normalizeObject } from "@jskit-ai/kernel/shared/support/normalize";
2
1
  import { retryDeadlocks } from "./repositoryOptions.js";
3
2
 
4
- class TransactionManager {
5
- constructor({ knex } = {}) {
6
- if (!knex || typeof knex.transaction !== "function") {
7
- throw new TypeError("TransactionManager requires knex with transaction().");
8
- }
9
-
10
- this.knex = knex;
11
- }
12
-
13
- async inTransaction(work, { trx = null } = {}) {
3
+ /**
4
+ * Runs work in a transaction of the database's Knex instance, retrying deadlocks,
5
+ * or in the transaction the caller already holds.
6
+ * @param {object} dependencies
7
+ * @param {import("../server/types.js").RuntimeKnex} dependencies.knex
8
+ */
9
+ function createTransactionManager({ knex }) {
10
+ /**
11
+ * @template T
12
+ * @param {(trx: import("../server/types.js").RuntimeKnexTransaction) => Promise<T>} work
13
+ * @param {{ trx?: import("../server/types.js").RuntimeKnexTransaction | null }} [options] A transaction to run in instead of a new one.
14
+ */
15
+ async function inTransaction(work, { trx = null } = {}) {
16
+ // readable-check: allow method-probe - input validation: the caller hands over the work to run
14
17
  if (typeof work !== "function") {
15
18
  throw new TypeError("inTransaction requires a callback function.");
16
19
  }
@@ -19,14 +22,10 @@ class TransactionManager {
19
22
  return work(trx);
20
23
  }
21
24
 
22
- return retryDeadlocks(() => this.knex.transaction(async (nextTrx) => {
23
- return work(nextTrx);
24
- }));
25
+ return retryDeadlocks(() => knex.transaction((nextTrx) => work(nextTrx)));
25
26
  }
26
- }
27
27
 
28
- function createTransactionManager(options = {}) {
29
- return new TransactionManager(normalizeObject(options));
28
+ return Object.freeze({ inTransaction });
30
29
  }
31
30
 
32
- export { TransactionManager, createTransactionManager };
31
+ export { createTransactionManager };
@@ -47,7 +47,7 @@ test("runDatabaseSetup migrates before one explicit app seed transaction", async
47
47
  test("runDatabaseSetup supports applications with no seed operation", async () => {
48
48
  const { calls, knex } = fakeKnex({ migrationResult: [0, []] });
49
49
 
50
- assert.deepEqual(await runDatabaseSetup({ knex }), {
50
+ assert.deepEqual(await runDatabaseSetup({ knex, environment: {} }), {
51
51
  batch: 0,
52
52
  migrations: [],
53
53
  seeded: false
@@ -58,7 +58,13 @@ test("runDatabaseSetup supports applications with no seed operation", async () =
58
58
  test("runDatabaseSetup rejects a non-function seed", async () => {
59
59
  const { knex } = fakeKnex();
60
60
  await assert.rejects(
61
- () => runDatabaseSetup({ knex, seed: "seed" }),
61
+ () => runDatabaseSetup({ knex, seed: "seed", environment: {} }),
62
62
  /seed must be a function/u
63
63
  );
64
64
  });
65
+
66
+ test("runDatabaseSetup requires the application's environment", async () => {
67
+ const { calls, knex } = fakeKnex();
68
+ await assert.rejects(() => runDatabaseSetup({ knex, seed() {} }), /requires the application's environment/u);
69
+ assert.deepEqual(calls, [], "Nothing is migrated");
70
+ });
@@ -1,6 +1,6 @@
1
1
  import test from "node:test";
2
2
  import assert from "node:assert/strict";
3
- import { findDuplicateEntryError, isDuplicateEntryError } from "../src/shared/duplicateEntry.js";
3
+ import { findDuplicateEntryError, isDuplicateEntryError, isLostDuplicateInsertRace } from "../src/shared/duplicateEntry.js";
4
4
 
5
5
  test("isDuplicateEntryError matches mysql and postgres duplicate signatures", () => {
6
6
  assert.equal(isDuplicateEntryError({ code: "ER_DUP_ENTRY" }), true);
@@ -31,3 +31,13 @@ test("duplicate classification terminates on missing, primitive and cyclic cause
31
31
  assert.equal(isDuplicateEntryError(error), false);
32
32
  }
33
33
  });
34
+
35
+ test("isLostDuplicateInsertRace is a rolled-back duplicate insert outside a caller's transaction", () => {
36
+ const lostRace = { transactionOutcome: "rolledBack", code: "ER_DUP_ENTRY" };
37
+
38
+ assert.equal(isLostDuplicateInsertRace(lostRace, {}), true);
39
+ assert.equal(isLostDuplicateInsertRace(lostRace, { trx: () => {} }), false);
40
+ assert.equal(isLostDuplicateInsertRace({ ...lostRace, transactionOutcome: "pending" }, {}), false);
41
+ assert.equal(isLostDuplicateInsertRace({ transactionOutcome: "rolledBack", code: "ER_PARSE_ERROR" }, {}), false);
42
+ assert.equal(isLostDuplicateInsertRace(undefined, {}), false);
43
+ });
@@ -0,0 +1,92 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import knexFactory from "knex";
4
+ import {
5
+ addMissingForeignKey,
6
+ dropForeignKeyIfPresent,
7
+ hasForeignKey
8
+ } from "../src/server/foreignKeyMigrations.js";
9
+
10
+ // Runs in a disposable PostgreSQL schema of the test database: run with DB_NAME set to TEST_DB_NAME
11
+ // (and the usual DB_HOST, DB_PORT, DB_USER and DB_PASSWORD) and DB_CLIENT unset or pg.
12
+ const TEST_DB_NAME = process.env.TEST_DB_NAME?.trim();
13
+ const ON_TEST_DATABASE = Boolean(TEST_DB_NAME) && process.env.DB_NAME === TEST_DB_NAME;
14
+ const POSTGRES_CLIENT = !process.env.DB_CLIENT || process.env.DB_CLIENT === "pg";
15
+ const SKIP = ON_TEST_DATABASE && POSTGRES_CLIENT ? false : "not on a PostgreSQL test database (DB_NAME=$TEST_DB_NAME)";
16
+
17
+ const KEY = { tableName: "children", columnName: "parent_id", parentTable: "parents", onDelete: "SET NULL" };
18
+
19
+ async function testDatabase(t) {
20
+ const schema = `foreign_key_test_${process.pid}_${Date.now()}`;
21
+ const connection = {
22
+ host: process.env.DB_HOST,
23
+ port: Number(process.env.DB_PORT) || 5432,
24
+ user: process.env.DB_USER,
25
+ password: process.env.DB_PASSWORD,
26
+ database: TEST_DB_NAME
27
+ };
28
+ const admin = knexFactory({ client: "pg", connection });
29
+ await admin.raw("create schema ??", [schema]);
30
+ const knex = knexFactory({ client: "pg", connection, searchPath: [schema] });
31
+ t.after(async () => {
32
+ await knex.destroy();
33
+ await admin.raw("drop schema ?? cascade", [schema]);
34
+ await admin.destroy();
35
+ });
36
+ await knex.schema.createTable("parents", (table) => table.integer("id").primary());
37
+ await knex.schema.createTable("children", (table) => {
38
+ table.increments("id");
39
+ table.integer("parent_id").nullable();
40
+ });
41
+ await knex("parents").insert({ id: 1 });
42
+ await knex("children").insert([{ parent_id: 1 }, { parent_id: null }]);
43
+ return knex;
44
+ }
45
+
46
+ async function keyCount(knex) {
47
+ const { rows } = await knex.raw(
48
+ "SELECT count(*) AS keys FROM pg_constraint WHERE contype = 'f' AND conrelid = to_regclass('children')"
49
+ );
50
+ return Number(rows[0].keys);
51
+ }
52
+
53
+ test("addMissingForeignKey on PostgreSQL adds a missing key once, refuses rows without a parent and deletes nothing", { skip: SKIP }, async (t) => {
54
+ const knex = await testDatabase(t);
55
+
56
+ assert.equal(await addMissingForeignKey(knex, KEY), true);
57
+ assert.equal(await hasForeignKey(knex, KEY), true);
58
+ assert.equal(await addMissingForeignKey(knex, KEY), false);
59
+ assert.equal(await keyCount(knex), 1);
60
+
61
+ assert.equal(await dropForeignKeyIfPresent(knex, KEY), true);
62
+ assert.equal(await dropForeignKeyIfPresent(knex, KEY), false);
63
+ assert.equal(await keyCount(knex), 0);
64
+
65
+ await knex("children").insert({ parent_id: 9 });
66
+ await assert.rejects(
67
+ addMissingForeignKey(knex, KEY),
68
+ /children\.parent_id foreign key to parents\.id: 1 children row\(s\) have a parent_id with no parents row/u
69
+ );
70
+ assert.equal((await knex("children")).length, 3);
71
+ assert.equal(await keyCount(knex), 0);
72
+
73
+ await assert.rejects(
74
+ addMissingForeignKey(knex, { ...KEY, parentTable: "guardians" }),
75
+ /children\.parent_id foreign key: the guardians table does not exist/u
76
+ );
77
+ });
78
+
79
+ test("PostgreSQL foreign key helpers find and drop a key by the name the database holds", { skip: SKIP }, async (t) => {
80
+ const knex = await testDatabase(t);
81
+ await knex.raw(
82
+ "ALTER TABLE children ADD CONSTRAINT children_parent_link FOREIGN KEY (parent_id) REFERENCES parents (id)"
83
+ );
84
+
85
+ assert.equal(await hasForeignKey(knex, KEY), true);
86
+ assert.equal(await addMissingForeignKey(knex, KEY), false);
87
+ assert.equal(await keyCount(knex), 1);
88
+
89
+ assert.equal(await dropForeignKeyIfPresent(knex, KEY), true);
90
+ assert.equal(await keyCount(knex), 0);
91
+ assert.equal(await hasForeignKey(knex, KEY), false);
92
+ });
@@ -0,0 +1,48 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import knexFactory from "knex";
4
+ import {
5
+ addMissingForeignKey,
6
+ dropForeignKeyIfPresent,
7
+ hasForeignKey
8
+ } from "../src/server/foreignKeyMigrations.js";
9
+
10
+ const KEY = { tableName: "children", columnName: "parent_id", parentTable: "parents", onDelete: "SET NULL" };
11
+
12
+ async function keyCount(knex) {
13
+ return (await knex.raw("PRAGMA foreign_key_list(children)")).length;
14
+ }
15
+
16
+ test("addMissingForeignKey adds a missing key once, refuses rows without a parent and deletes nothing", async (t) => {
17
+ const knex = knexFactory({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
18
+ t.after(() => knex.destroy());
19
+ await knex.schema.createTable("parents", (table) => table.integer("id").primary());
20
+ await knex.schema.createTable("children", (table) => {
21
+ table.increments("id");
22
+ table.integer("parent_id").nullable();
23
+ });
24
+ await knex("parents").insert({ id: 1 });
25
+ await knex("children").insert([{ parent_id: 1 }, { parent_id: null }]);
26
+
27
+ assert.equal(await addMissingForeignKey(knex, KEY), true);
28
+ assert.equal(await hasForeignKey(knex, KEY), true);
29
+ assert.equal(await addMissingForeignKey(knex, KEY), false);
30
+ assert.equal(await keyCount(knex), 1);
31
+
32
+ assert.equal(await dropForeignKeyIfPresent(knex, KEY), true);
33
+ assert.equal(await dropForeignKeyIfPresent(knex, KEY), false);
34
+ assert.equal(await keyCount(knex), 0);
35
+
36
+ await knex("children").insert({ parent_id: 9 });
37
+ await assert.rejects(
38
+ addMissingForeignKey(knex, KEY),
39
+ /children\.parent_id foreign key to parents\.id: 1 children row\(s\) have a parent_id with no parents row/u
40
+ );
41
+ assert.equal((await knex("children")).length, 3);
42
+ assert.equal(await keyCount(knex), 0);
43
+
44
+ await assert.rejects(
45
+ addMissingForeignKey(knex, { ...KEY, parentTable: "guardians" }),
46
+ /children\.parent_id foreign key: the guardians table does not exist/u
47
+ );
48
+ });
@@ -1,8 +1,9 @@
1
1
  import assert from "node:assert/strict";
2
- import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
2
+ import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
3
3
  import os from "node:os";
4
4
  import path from "node:path";
5
5
  import test from "node:test";
6
+ import knexFactory from "knex";
6
7
  import {
7
8
  createKnexMigrationConfig,
8
9
  createKnexMigrationConfigFromApp,
@@ -42,6 +43,13 @@ test("createKnexMigrationConfig fixes PostgreSQL without requiring DB_CLIENT", (
42
43
  assert.equal(config.connection.port, 5432);
43
44
  });
44
45
 
46
+ test("createKnexMigrationConfig requires the application's environment instead of reading DB_* from nothing", () => {
47
+ assert.throws(
48
+ () => createKnexMigrationConfig({ client: "mysql2", appRoot: "/srv/catalogue" }),
49
+ /requires the application's environment/u
50
+ );
51
+ });
52
+
45
53
  test("installed package migrations run from their owning packages without copied projections", async (context) => {
46
54
  const appRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-package-migrations-"));
47
55
  context.after(async () => {
@@ -49,7 +57,7 @@ test("installed package migrations run from their owning packages without copied
49
57
  });
50
58
 
51
59
  const packageRoot = path.join(appRoot, "node_modules", "@example", "accounts-core");
52
- await mkdir(path.join(packageRoot, "migrations"), { recursive: true });
60
+ await mkdir(path.join(packageRoot, "migrations", "constraints"), { recursive: true });
53
61
  await writeFile(path.join(appRoot, "package.json"), JSON.stringify({
54
62
  dependencies: { "@example/accounts-core": "1.0.0" }
55
63
  }));
@@ -73,8 +81,273 @@ test("installed package migrations run from their owning packages without copied
73
81
  appRoot
74
82
  });
75
83
  assert.deepEqual(config.migrations.directory, [
76
- path.join(appRoot, "migrations"),
77
84
  path.join(packageRoot, "migrations"),
85
+ path.join(appRoot, "migrations"),
86
+ path.join(packageRoot, "migrations", "constraints"),
87
+ path.join(appRoot, "migrations", "constraints")
88
+ ]);
89
+ });
90
+
91
+ test("a fresh database runs package migrations before the application's, then its constraints", async (context) => {
92
+ const appRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-migration-order-"));
93
+ const packageRoot = path.join(appRoot, "node_modules", "@example", "accounts-core");
94
+ await mkdir(path.join(packageRoot, "migrations"), { recursive: true });
95
+ await mkdir(path.join(appRoot, "migrations", "constraints"), { recursive: true });
96
+ await writeFile(path.join(appRoot, "package.json"), JSON.stringify({
97
+ dependencies: { "@example/accounts-core": "1.0.0" }
98
+ }));
99
+ await writeFile(path.join(packageRoot, "package.json"), JSON.stringify({
100
+ name: "@example/accounts-core",
101
+ version: "1.0.0",
102
+ jskit: { kind: "runtime", migrations: { directories: ["migrations"] } }
103
+ }));
104
+ await writeFile(path.join(packageRoot, "migrations", "accounts_initial.cjs"),
105
+ "exports.up = (knex) => knex.schema.createTable(\"users\", (table) => table.increments(\"id\"));\nexports.down = () => {};\n");
106
+ await writeFile(path.join(appRoot, "migrations", "20260101000000_books.cjs"), [
107
+ "exports.up = async (knex) => {",
108
+ " await knex(\"users\").insert({ id: 1 });",
109
+ " await knex.schema.createTable(\"books\", (table) => table.integer(\"user_id\").references(\"id\").inTable(\"users\"));",
110
+ "};",
111
+ "exports.down = () => {};",
112
+ ""
113
+ ].join("\n"));
114
+ await writeFile(path.join(appRoot, "migrations", "constraints", "20200101000000_books_index.cjs"),
115
+ "exports.up = (knex) => knex.schema.alterTable(\"books\", (table) => table.index([\"user_id\"]));\nexports.down = () => {};\n");
116
+
117
+ const { migrations } = await createKnexMigrationConfigFromApp({
118
+ client: "pg",
119
+ environment: connectionEnvironment,
120
+ appRoot
121
+ });
122
+ const knex = knexFactory({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true, migrations });
123
+ context.after(async () => {
124
+ await knex.destroy();
125
+ await rm(appRoot, { recursive: true, force: true });
126
+ });
127
+
128
+ await knex.migrate.latest();
129
+ assert.deepEqual(await knex("knex_migrations").orderBy("id").pluck("name"), [
130
+ "accounts_initial.cjs",
131
+ "20260101000000_books.cjs",
132
+ "20200101000000_books_index.cjs"
133
+ ]);
134
+ });
135
+
136
+ test("a package constraints migration references the application's users table on a fresh database", async (context) => {
137
+ const appRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-package-constraints-"));
138
+ const packageRoot = path.join(appRoot, "node_modules", "@example", "notes-core");
139
+ await mkdir(path.join(packageRoot, "migrations", "constraints"), { recursive: true });
140
+ await mkdir(path.join(appRoot, "migrations", "constraints"), { recursive: true });
141
+ await writeFile(path.join(appRoot, "package.json"), JSON.stringify({
142
+ dependencies: { "@example/notes-core": "1.0.0" }
143
+ }));
144
+ await writeFile(path.join(packageRoot, "package.json"), JSON.stringify({
145
+ name: "@example/notes-core",
146
+ version: "1.0.0",
147
+ jskit: { kind: "runtime", migrations: { directories: ["migrations"] } }
148
+ }));
149
+ await writeFile(path.join(packageRoot, "migrations", "notes_initial.cjs"), [
150
+ "exports.up = (knex) => knex.schema.createTable(\"notes\", (table) => {",
151
+ " table.increments(\"id\");",
152
+ " table.integer(\"user_id\").notNullable();",
153
+ "});",
154
+ "exports.down = () => {};",
155
+ ""
156
+ ].join("\n"));
157
+ await writeFile(path.join(appRoot, "migrations", "20260101000000_users.cjs"), [
158
+ "exports.up = async (knex) => {",
159
+ " await knex.schema.createTable(\"users\", (table) => table.increments(\"id\"));",
160
+ " await knex(\"users\").insert({ id: 1 });",
161
+ "};",
162
+ "exports.down = () => {};",
163
+ ""
164
+ ].join("\n"));
165
+ await writeFile(path.join(packageRoot, "migrations", "constraints", "notes_users_foreign_key.cjs"), [
166
+ "exports.up = async (knex) => {",
167
+ " await knex.schema.alterTable(\"notes\", (table) => table.foreign(\"user_id\").references(\"id\").inTable(\"users\"));",
168
+ " await knex(\"notes\").insert({ user_id: (await knex(\"users\").first(\"id\")).id });",
169
+ "};",
170
+ "exports.down = () => {};",
171
+ ""
172
+ ].join("\n"));
173
+ await writeFile(path.join(appRoot, "migrations", "constraints", "20200101000000_notes_index.cjs"),
174
+ "exports.up = (knex) => knex.schema.alterTable(\"notes\", (table) => table.index([\"user_id\"]));\nexports.down = () => {};\n");
175
+
176
+ const { migrations } = await createKnexMigrationConfigFromApp({
177
+ client: "pg",
178
+ environment: connectionEnvironment,
179
+ appRoot
180
+ });
181
+ const knex = knexFactory({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true, migrations });
182
+ context.after(async () => {
183
+ await knex.destroy();
184
+ await rm(appRoot, { recursive: true, force: true });
185
+ });
186
+
187
+ await knex.migrate.latest();
188
+ assert.deepEqual(await knex("knex_migrations").orderBy("id").pluck("name"), [
189
+ "notes_initial.cjs",
190
+ "20260101000000_users.cjs",
191
+ "notes_users_foreign_key.cjs",
192
+ "20200101000000_notes_index.cjs"
193
+ ]);
194
+ const foreignKeys = await knex.raw("PRAGMA foreign_key_list(notes)");
195
+ assert.deepEqual(foreignKeys.map(({ table, from, to }) => ({ table, from, to })), [
196
+ { table: "users", from: "user_id", to: "id" }
197
+ ]);
198
+ });
199
+
200
+ // An app whose node_modules hold the given JSKIT packages, each with its migration directories.
201
+ async function createAppWithPackages(context, packages) {
202
+ const appRoot = await mkdtemp(path.join(os.tmpdir(), "jskit-migrations-after-"));
203
+ context.after(() => rm(appRoot, { recursive: true, force: true }));
204
+ await writeFile(path.join(appRoot, "package.json"), JSON.stringify({
205
+ dependencies: Object.fromEntries(packages.map(({ name }) => [name, "1.0.0"]))
206
+ }));
207
+ const directoryOf = {};
208
+ for (const { name, migrations, files = {} } of packages) {
209
+ const packageRoot = path.join(appRoot, "node_modules", ...name.split("/"));
210
+ await mkdir(packageRoot, { recursive: true });
211
+ await writeFile(path.join(packageRoot, "package.json"), JSON.stringify({
212
+ name,
213
+ version: "1.0.0",
214
+ jskit: { kind: "runtime", ...(migrations ? { migrations } : {}) }
215
+ }));
216
+ for (const directory of migrations?.directories || []) {
217
+ await mkdir(path.join(packageRoot, directory), { recursive: true });
218
+ directoryOf[`${name}:${directory}`] = path.join(packageRoot, directory);
219
+ }
220
+ for (const [file, source] of Object.entries(files)) {
221
+ await mkdir(path.dirname(path.join(packageRoot, file)), { recursive: true });
222
+ await writeFile(path.join(packageRoot, file), source);
223
+ }
224
+ }
225
+ return { appRoot, directoryOf };
226
+ }
227
+
228
+ test("without jskit.migrations.after, package migration directories keep their path order", async (context) => {
229
+ const { appRoot, directoryOf } = await createAppWithPackages(context, [
230
+ { name: "@example/units-core", migrations: { directories: ["migrations"] } },
231
+ { name: "@example/assets-core", migrations: { directories: ["migrations", "reference"] } },
232
+ { name: "@example/plain-core" }
233
+ ]);
234
+ assert.deepEqual(await discoverPackageMigrationDirectories({ appRoot }), [
235
+ directoryOf["@example/assets-core:migrations"],
236
+ directoryOf["@example/assets-core:reference"],
237
+ directoryOf["@example/units-core:migrations"]
238
+ ]);
239
+ });
240
+
241
+ test("a package's migrations and constraints run after those of the packages its jskit.migrations.after names", async (context) => {
242
+ const { appRoot, directoryOf } = await createAppWithPackages(context, [
243
+ {
244
+ name: "@example/assets-core",
245
+ migrations: { directories: ["migrations", "reference"], after: ["@example/units-core", "@example/plain-core"] },
246
+ files: { "migrations/constraints/assets_units.cjs": "exports.up = async () => {};\n" }
247
+ },
248
+ { name: "@example/notes-core", migrations: { directories: ["migrations"] } },
249
+ {
250
+ name: "@example/units-core",
251
+ migrations: { directories: ["migrations"] },
252
+ files: { "migrations/constraints/units_users.cjs": "exports.up = async () => {};\n" }
253
+ },
254
+ { name: "@example/plain-core" }
255
+ ]);
256
+ const packageDirectories = [
257
+ directoryOf["@example/units-core:migrations"],
258
+ directoryOf["@example/assets-core:migrations"],
259
+ directoryOf["@example/assets-core:reference"],
260
+ directoryOf["@example/notes-core:migrations"]
261
+ ];
262
+ assert.deepEqual(await discoverPackageMigrationDirectories({ appRoot }), packageDirectories);
263
+ const { migrations } = await createKnexMigrationConfigFromApp({ client: "mysql2", environment: connectionEnvironment, appRoot });
264
+ assert.deepEqual(migrations.directory, [
265
+ ...packageDirectories,
266
+ path.join(appRoot, "migrations"),
267
+ path.join(directoryOf["@example/units-core:migrations"], "constraints"),
268
+ path.join(directoryOf["@example/assets-core:migrations"], "constraints"),
78
269
  path.join(appRoot, "migrations", "constraints")
79
270
  ]);
80
271
  });
272
+
273
+ test("after is followed depth first, each prerequisite in the order it is listed", async (context) => {
274
+ const { appRoot, directoryOf } = await createAppWithPackages(context, [
275
+ { name: "@example/a-core", migrations: { directories: ["migrations"], after: ["@example/d-core", "@example/c-core"] } },
276
+ { name: "@example/b-core", migrations: { directories: ["migrations"] } },
277
+ { name: "@example/c-core", migrations: { directories: ["migrations"], after: ["@example/e-core"] } },
278
+ { name: "@example/d-core", migrations: { directories: ["migrations"] } },
279
+ { name: "@example/e-core", migrations: { directories: ["migrations"] } }
280
+ ]);
281
+ assert.deepEqual(await discoverPackageMigrationDirectories({ appRoot }), [
282
+ "@example/d-core", "@example/e-core", "@example/c-core", "@example/a-core", "@example/b-core"
283
+ ].map((name) => directoryOf[`${name}:migrations`]));
284
+ });
285
+
286
+ test("a fresh database runs a package's migrations after the package whose table they use", async (context) => {
287
+ const { appRoot } = await createAppWithPackages(context, [
288
+ {
289
+ name: "@example/assets-core",
290
+ migrations: { directories: ["migrations"], after: ["@example/units-core"] },
291
+ files: {
292
+ "migrations/assets_initial.cjs": [
293
+ "exports.up = async (knex) => {",
294
+ " await knex.schema.createTable(\"assets\", (table) => table.integer(\"unit_id\").references(\"id\").inTable(\"units\"));",
295
+ " await knex(\"assets\").insert({ unit_id: (await knex(\"units\").first(\"id\")).id });",
296
+ "};",
297
+ "exports.down = () => {};",
298
+ ""
299
+ ].join("\n")
300
+ }
301
+ },
302
+ {
303
+ name: "@example/units-core",
304
+ migrations: { directories: ["migrations"] },
305
+ files: {
306
+ "migrations/units_initial.cjs": [
307
+ "exports.up = async (knex) => {",
308
+ " await knex.schema.createTable(\"units\", (table) => table.increments(\"id\"));",
309
+ " await knex(\"units\").insert({ id: 1 });",
310
+ "};",
311
+ "exports.down = () => {};",
312
+ ""
313
+ ].join("\n")
314
+ }
315
+ }
316
+ ]);
317
+ await mkdir(path.join(appRoot, "migrations", "constraints"), { recursive: true });
318
+ const { migrations } = await createKnexMigrationConfigFromApp({ client: "pg", environment: connectionEnvironment, appRoot });
319
+ const knex = knexFactory({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true, migrations });
320
+ context.after(() => knex.destroy());
321
+
322
+ await knex.migrate.latest();
323
+ assert.deepEqual(await knex("knex_migrations").orderBy("id").pluck("name"), ["units_initial.cjs", "assets_initial.cjs"]);
324
+ assert.deepEqual(await knex("assets").pluck("unit_id"), [1]);
325
+ });
326
+
327
+ test("packages whose migrations each name the other in after are rejected with the cycle", async (context) => {
328
+ const { appRoot } = await createAppWithPackages(context, [
329
+ { name: "@example/a-core", migrations: { directories: ["migrations"], after: ["@example/b-core"] } },
330
+ { name: "@example/b-core", migrations: { directories: ["migrations"], after: ["@example/a-core"] } }
331
+ ]);
332
+ await assert.rejects(
333
+ () => discoverPackageMigrationDirectories({ appRoot }),
334
+ /Package migrations cannot each run after the other: @example\/a-core -> @example\/b-core -> @example\/a-core\./
335
+ );
336
+ });
337
+
338
+ test("jskit.migrations.after names other installed JSKIT packages, beside the package's directories", async (context) => {
339
+ const cases = [
340
+ [{ directories: ["migrations"], after: ["@example/missing-core"] }, /names @example\/missing-core, which is not an installed JSKIT package/],
341
+ [{ directories: ["migrations"], after: ["@example/a-core"] }, /after names the package itself/],
342
+ [{ directories: ["migrations"], after: "@example/b-core" }, /after must be an array of package names/],
343
+ [{ directories: ["migrations"], after: [" "] }, /after must be an array of package names/],
344
+ [{ after: ["@example/b-core"] }, /after needs jskit\.migrations\.directories/]
345
+ ];
346
+ for (const [migrations, message] of cases) {
347
+ const { appRoot } = await createAppWithPackages(context, [
348
+ { name: "@example/a-core", migrations },
349
+ { name: "@example/b-core", migrations: { directories: ["migrations"] } }
350
+ ]);
351
+ await assert.rejects(() => discoverPackageMigrationDirectories({ appRoot }), message);
352
+ }
353
+ });