@jskit-ai/database-runtime 0.1.252 → 0.1.254

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jskit-ai/database-runtime",
3
- "version": "0.1.252",
3
+ "version": "0.1.254",
4
4
  "type": "module",
5
5
  "scripts": {
6
6
  "test": "node --test --test-concurrency=1"
@@ -9,6 +9,8 @@
9
9
  "./server/providers/DatabaseProvider": "./src/server/providers/DatabaseProvider.js",
10
10
  "./server/databaseSetup": "./src/server/databaseSetup.js",
11
11
  "./server/knexMigrationConfig": "./src/server/knexMigrationConfig.js",
12
+ "./server/foreignKeyMigrations": "./src/server/foreignKeyMigrations.js",
13
+ "./server/types": "./src/server/types.js",
12
14
  "./shared": "./src/shared/index.js",
13
15
  "./shared/dateUtils": "./src/shared/dateUtils.js",
14
16
  "./shared/databaseClient": "./src/shared/databaseClient.js",
@@ -27,7 +29,8 @@
27
29
  "runtime.database"
28
30
  ],
29
31
  "requires": [
30
- "runtime.database.driver"
32
+ "runtime.database.driver",
33
+ "runtime.env"
31
34
  ]
32
35
  },
33
36
  "runtime": {
@@ -58,15 +61,23 @@
58
61
  "subpath": "./server/knexMigrationConfig",
59
62
  "summary": "Builds fixed-dialect Knex migration configuration and discovers immutable migrations directly from installed JSKIT packages."
60
63
  },
64
+ {
65
+ "subpath": "./server/foreignKeyMigrations",
66
+ "summary": "Adds a single-column foreign key only when it is missing, refusing rows without a parent, for constraints migrations on fresh and already-migrated databases."
67
+ },
61
68
  {
62
69
  "subpath": "./shared",
63
70
  "summary": "Exports shared repository helpers (transactions, record ids, JSON columns, visibility, duplicate-entry detection and date/time serialization)."
71
+ },
72
+ {
73
+ "subpath": "./server/types",
74
+ "summary": "Types of the runtime.database capability and of the runtime.database.driver contract every driver package implements, for features that require them."
64
75
  }
65
76
  ]
66
77
  }
67
78
  }
68
79
  },
69
80
  "peerDependencies": {
70
- "@jskit-ai/kernel": "0.2.3"
81
+ "@jskit-ai/kernel": "0.2.5"
71
82
  }
72
83
  }
@@ -0,0 +1,46 @@
1
+ import { normalizeDatabaseClient, toKnexClientId } from "../shared/databaseClient.js";
2
+ import { resolveKnexConnectionFromEnvironment } from "../shared/databaseConnection.js";
3
+ import { createTransactionManager } from "../shared/transactionManager.js";
4
+ import { loadKnexFactory } from "./knexFactory.js";
5
+
6
+ /** @param {import("./types.js").RuntimeDatabaseDriver} driver */
7
+ function resolveDriverDialectId(driver) {
8
+ const dialectId = normalizeDatabaseClient(driver.DIALECT_ID, { allowEmpty: true });
9
+ if (!dialectId) {
10
+ throw new Error("The installed database driver did not expose a valid dialect id.");
11
+ }
12
+ return dialectId;
13
+ }
14
+
15
+ /**
16
+ * The database connection every feature shares: the installed driver, its Knex client and a transaction manager.
17
+ * @param {object} dependencies
18
+ * @param {import("./types.js").RuntimeDatabaseDriver} dependencies.driver
19
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} dependencies.env
20
+ */
21
+ function createDatabase({ driver, env }) {
22
+ const dialectId = resolveDriverDialectId(driver);
23
+ const configuredClient = normalizeDatabaseClient(env.DB_CLIENT, { allowEmpty: true });
24
+ if (configuredClient && configuredClient !== dialectId) {
25
+ throw new Error(`DB_CLIENT="${configuredClient}" does not match installed database driver "${dialectId}".`);
26
+ }
27
+
28
+ /** @type {import("./types.js").RuntimeKnex} */
29
+ const knex = loadKnexFactory()({
30
+ client: toKnexClientId(dialectId),
31
+ connection: resolveKnexConnectionFromEnvironment(env, {
32
+ client: dialectId,
33
+ defaultPort: dialectId === "pg" ? 5432 : 3306,
34
+ context: "database runtime"
35
+ })
36
+ });
37
+ const transactionManager = createTransactionManager({ knex });
38
+
39
+ return Object.freeze({
40
+ driver,
41
+ knex,
42
+ transactionManager
43
+ });
44
+ }
45
+
46
+ export { createDatabase };
@@ -9,23 +9,39 @@ function normalizeMigrationResult(result) {
9
9
  const migrations = Array.isArray(migrationValues)
10
10
  ? migrationValues.map((value) => String(value || "").trim()).filter(Boolean)
11
11
  : [];
12
- return Object.freeze({ batch, migrations: Object.freeze(migrations) });
12
+ return Object.freeze({
13
+ batch,
14
+ migrations: Object.freeze(migrations)
15
+ });
13
16
  }
14
17
 
15
- async function runDatabaseSetup({ knex, seed, appRoot = process.cwd(), environment = process.env } = {}) {
16
- if (!knex || typeof knex !== "function" || typeof knex.migrate?.latest !== "function") {
17
- throw new TypeError("runDatabaseSetup requires a Knex instance.");
18
+ /**
19
+ * Migrates the database an application's Knex instance reaches, then runs its seed, if any, in one transaction.
20
+ * @param {object} options
21
+ * @param {import("./types.js").RuntimeKnex} options.knex
22
+ * @param {(context: { knex: import("./types.js").RuntimeKnexTransaction, appRoot: string, environment: import("@jskit-ai/kernel/server/types").RuntimeEnv }) => unknown} [options.seed]
23
+ * @param {string} [options.appRoot]
24
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The application's environment, such as `process.env`.
25
+ */
26
+ async function runDatabaseSetup({ knex, seed, appRoot = process.cwd(), environment }) {
27
+ // readable-check: allow method-probe - input validation: the application passes its own Knex instance
28
+ if (typeof knex !== "function" || typeof knex.transaction !== "function") {
29
+ throw new TypeError("runDatabaseSetup requires the application's Knex instance.");
30
+ }
31
+ if (!environment) {
32
+ throw new TypeError("runDatabaseSetup requires the application's environment, such as process.env.");
18
33
  }
19
- if (typeof seed !== "undefined" && seed !== null && typeof seed !== "function") {
34
+ // readable-check: allow method-probe - input validation: the application may pass its own seed
35
+ if (seed != null && typeof seed !== "function") {
20
36
  throw new TypeError("runDatabaseSetup seed must be a function when supplied.");
21
37
  }
22
38
 
23
39
  const migrationResult = normalizeMigrationResult(await knex.migrate.latest());
24
- if (typeof seed !== "function") {
25
- return Object.freeze({ ...migrationResult, seeded: false });
26
- }
27
- if (typeof knex.transaction !== "function") {
28
- throw new TypeError("runDatabaseSetup requires Knex transaction support for seeding.");
40
+ if (seed == null) {
41
+ return Object.freeze({
42
+ ...migrationResult,
43
+ seeded: false
44
+ });
29
45
  }
30
46
 
31
47
  await runInTransaction(knex, async (transaction) => {
@@ -36,16 +52,29 @@ async function runDatabaseSetup({ knex, seed, appRoot = process.cwd(), environme
36
52
  }));
37
53
  });
38
54
 
39
- return Object.freeze({ ...migrationResult, seeded: true });
55
+ return Object.freeze({
56
+ ...migrationResult,
57
+ seeded: true
58
+ });
40
59
  }
41
60
 
61
+ /**
62
+ * Migrates the database the application's environment names, with the application's and its
63
+ * installed packages' migrations, then runs its seed, if any.
64
+ * @param {object} options
65
+ * @param {string} options.client The dialect id: "mysql2" or "pg".
66
+ * @param {string} [options.appRoot]
67
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The application's environment, such as `process.env`.
68
+ * @param {string} [options.migrationsDirectory]
69
+ * @param {Parameters<typeof runDatabaseSetup>[0]["seed"]} [options.seed]
70
+ */
42
71
  async function prepareDatabaseFromApp({
43
72
  client,
44
73
  appRoot = process.cwd(),
45
- environment = process.env,
74
+ environment,
46
75
  migrationsDirectory = "migrations",
47
76
  seed
48
- } = {}) {
77
+ }) {
49
78
  const normalizedAppRoot = path.resolve(appRoot);
50
79
  const config = await createKnexMigrationConfigFromApp({
51
80
  client,
@@ -0,0 +1,122 @@
1
+ import { detectDialectFromClient } from "../shared/dialect.js";
2
+
3
+ /**
4
+ * A single-column foreign key that a constraints migration adds once its parent table exists.
5
+ * @typedef {object} ForeignKey
6
+ * @property {string} tableName
7
+ * @property {string} columnName
8
+ * @property {string} parentTable
9
+ * @property {string} [parentColumn] Defaults to "id".
10
+ * @property {string} [name] Defaults to Knex's `<table>_<column>_foreign`.
11
+ * @property {string} [onDelete]
12
+ * @property {string} [onUpdate]
13
+ */
14
+
15
+ /**
16
+ * The name of the foreign key that links the column to the parent column, whatever that name is,
17
+ * or null when no key does. SQLite keys have no name, so a SQLite key's is "".
18
+ * @param {import("./types.js").RuntimeKnex} knex
19
+ * @param {ForeignKey} key
20
+ * @returns {Promise<string | null>}
21
+ */
22
+ async function findForeignKeyName(knex, { tableName, columnName, parentTable, parentColumn = "id" }) {
23
+ const dialect = detectDialectFromClient(knex);
24
+ if (dialect === "mysql") {
25
+ const row = await knex("information_schema.KEY_COLUMN_USAGE")
26
+ .whereRaw("TABLE_SCHEMA = DATABASE()")
27
+ .where({
28
+ TABLE_NAME: tableName,
29
+ COLUMN_NAME: columnName,
30
+ REFERENCED_TABLE_NAME: parentTable,
31
+ REFERENCED_COLUMN_NAME: parentColumn
32
+ })
33
+ .first("CONSTRAINT_NAME");
34
+ return row ? row.CONSTRAINT_NAME : null;
35
+ }
36
+ if (dialect === "postgres") {
37
+ const { rows } = await knex.raw(
38
+ `SELECT c.conname FROM pg_constraint c
39
+ JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = c.conkey[1]
40
+ JOIN pg_attribute p ON p.attrelid = c.confrelid AND p.attnum = c.confkey[1]
41
+ WHERE c.contype = 'f' AND cardinality(c.conkey) = 1
42
+ AND c.conrelid = to_regclass(?) AND c.confrelid = to_regclass(?)
43
+ AND a.attname = ? AND p.attname = ?`,
44
+ [tableName, parentTable, columnName, parentColumn]
45
+ );
46
+ return rows.length > 0 ? rows[0].conname : null;
47
+ }
48
+ if (dialect.includes("sqlite")) {
49
+ const keys = await knex.raw("PRAGMA foreign_key_list(??)", [tableName]);
50
+ return keys.some((key) => key.table === parentTable && key.from === columnName && key.to === parentColumn)
51
+ ? ""
52
+ : null;
53
+ }
54
+ throw new Error(`Foreign key migrations do not support the ${dialect || "unknown"} dialect.`);
55
+ }
56
+
57
+ /**
58
+ * Whether a foreign key already links the column to the parent column, whatever its name.
59
+ * @param {import("./types.js").RuntimeKnex} knex
60
+ * @param {ForeignKey} key
61
+ */
62
+ async function hasForeignKey(knex, key) {
63
+ return (await findForeignKeyName(knex, key)) !== null;
64
+ }
65
+
66
+ /**
67
+ * Adds the foreign key unless it already exists, so a constraints migration runs on a fresh
68
+ * database and on one an earlier migration already gave the key. Refuses, naming the table, column
69
+ * and count, when rows have no parent; it never deletes data.
70
+ * @param {import("./types.js").RuntimeKnex} knex
71
+ * @param {ForeignKey} key
72
+ * @returns {Promise<boolean>} Whether it added the key.
73
+ */
74
+ async function addMissingForeignKey(knex, key) {
75
+ const { tableName, columnName, parentTable, parentColumn = "id", name, onDelete, onUpdate } = key;
76
+ if (await hasForeignKey(knex, key)) {
77
+ return false;
78
+ }
79
+ if (!(await knex.schema.hasTable(parentTable))) {
80
+ throw new Error(`Cannot add the ${tableName}.${columnName} foreign key: the ${parentTable} table does not exist.`);
81
+ }
82
+ const [{ orphans }] = await knex(tableName)
83
+ .whereNotNull(columnName)
84
+ .whereNotExists(
85
+ knex(parentTable).select(knex.raw("1")).whereRaw("??.?? = ??.??", [parentTable, parentColumn, tableName, columnName])
86
+ )
87
+ .count({ orphans: "*" });
88
+ if (Number(orphans) > 0) {
89
+ throw new Error(
90
+ `Cannot add the ${tableName}.${columnName} foreign key to ${parentTable}.${parentColumn}: ` +
91
+ `${orphans} ${tableName} row(s) have a ${columnName} with no ${parentTable} row. ` +
92
+ "Repair or remove those rows, then migrate again; the migration deletes nothing."
93
+ );
94
+ }
95
+ await knex.schema.alterTable(tableName, (table) => {
96
+ const reference = table.foreign(columnName, name).references(parentColumn).inTable(parentTable);
97
+ if (onDelete) reference.onDelete(onDelete);
98
+ if (onUpdate) reference.onUpdate(onUpdate);
99
+ });
100
+ return true;
101
+ }
102
+
103
+ /**
104
+ * Drops the foreign key when it exists, for a constraints migration's down().
105
+ * @param {import("./types.js").RuntimeKnex} knex
106
+ * @param {ForeignKey} key
107
+ * @returns {Promise<boolean>} Whether it dropped the key.
108
+ */
109
+ async function dropForeignKeyIfPresent(knex, key) {
110
+ const name = await findForeignKeyName(knex, key);
111
+ if (name === null) {
112
+ return false;
113
+ }
114
+ // Knex's SQLite table rebuild finds the key by its column (its name is ""); the others drop it by
115
+ // the name the database holds, which may differ from key.name.
116
+ await knex.schema.alterTable(key.tableName, (table) => {
117
+ table.dropForeign(key.columnName, name || undefined);
118
+ });
119
+ return true;
120
+ }
121
+
122
+ export { addMissingForeignKey, dropForeignKeyIfPresent, hasForeignKey };
@@ -11,6 +11,7 @@ function loadKnexFactory() {
11
11
  const knexFactory =
12
12
  typeof moduleValue === "function"
13
13
  ? moduleValue
14
+ // readable-check: allow method-probe - platform object: a required module is the factory or an ES namespace that holds it
14
15
  : typeof moduleValue?.default === "function"
15
16
  ? moduleValue.default
16
17
  : null;
@@ -7,13 +7,29 @@ import {
7
7
  } from "../shared/databaseClient.js";
8
8
  import { resolveKnexConnectionFromEnvironment } from "../shared/databaseConnection.js";
9
9
 
10
+ /**
11
+ * The Knex configuration for migrating the database the application's environment names.
12
+ * @param {object} options
13
+ * @param {string} options.client The dialect id: "mysql2" or "pg".
14
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The application's environment, such as `process.env`.
15
+ * @param {string} [options.appRoot]
16
+ * @param {string} [options.migrationsDirectory]
17
+ * @param {readonly string[]} [options.packageMigrationDirectories]
18
+ * @param {readonly string[]} [options.packageConstraintDirectories]
19
+ */
10
20
  function createKnexMigrationConfig({
11
21
  client,
12
- environment = process.env,
22
+ environment,
13
23
  appRoot = process.cwd(),
14
24
  migrationsDirectory = "migrations",
15
- packageMigrationDirectories = []
16
- } = {}) {
25
+ // readable-check: allow dependency-default - data: a list of directory paths, not a collaborator
26
+ packageMigrationDirectories = [],
27
+ // readable-check: allow dependency-default - data: a list of directory paths, not a collaborator
28
+ packageConstraintDirectories = []
29
+ }) {
30
+ if (!environment) {
31
+ throw new TypeError("createKnexMigrationConfig requires the application's environment, such as process.env.");
32
+ }
17
33
  const dialectId = normalizeDatabaseClient(client);
18
34
  const resolvedMigrationsDirectory = path.resolve(appRoot, migrationsDirectory);
19
35
 
@@ -25,9 +41,12 @@ function createKnexMigrationConfig({
25
41
  context: "knex migrations"
26
42
  }),
27
43
  migrations: {
44
+ // Packages create the tables application migrations build on; package constraints
45
+ // can then reference application tables such as users.
28
46
  directory: [
29
- resolvedMigrationsDirectory,
30
47
  ...packageMigrationDirectories.map((directory) => path.resolve(directory)),
48
+ resolvedMigrationsDirectory,
49
+ ...packageConstraintDirectories.map((directory) => path.resolve(directory)),
31
50
  path.join(resolvedMigrationsDirectory, "constraints")
32
51
  ],
33
52
  extension: "cjs",
@@ -45,12 +64,88 @@ async function directoryExists(directory) {
45
64
  }
46
65
  }
47
66
 
67
+ /**
68
+ * A package's `jskit.migrations.after`: the installed JSKIT packages whose
69
+ * migrations its own follow, or none.
70
+ * @param {{ packageId: string, packageMetadata: Record<string, any> }} installedPackage
71
+ * @param {ReadonlySet<string>} installedPackageIds
72
+ */
73
+ function migrationsAfterOf({ packageId, packageMetadata }, installedPackageIds) {
74
+ const { directories, after: declared } = packageMetadata.migrations ?? {};
75
+ if (declared === undefined) {
76
+ return [];
77
+ }
78
+ if (directories === undefined) {
79
+ throw new TypeError(`${packageId} package.json#jskit.migrations.after needs jskit.migrations.directories.`);
80
+ }
81
+ if (!Array.isArray(declared) || declared.some((entry) => typeof entry !== "string" || !entry.trim())) {
82
+ throw new TypeError(`${packageId} package.json#jskit.migrations.after must be an array of package names.`);
83
+ }
84
+ const after = declared.map((entry) => entry.trim());
85
+ for (const prerequisite of after) {
86
+ if (prerequisite === packageId) {
87
+ throw new TypeError(`${packageId} package.json#jskit.migrations.after names the package itself.`);
88
+ }
89
+ if (!installedPackageIds.has(prerequisite)) {
90
+ throw new Error(
91
+ `${packageId} package.json#jskit.migrations.after names ${prerequisite}, which is not an installed JSKIT package.`
92
+ );
93
+ }
94
+ }
95
+ return after;
96
+ }
97
+
98
+ /**
99
+ * Package migration directories in path order, except that a directory of a
100
+ * package whose `jskit.migrations.after` names other packages runs after all of
101
+ * their directories. With no `after` the path order is unchanged.
102
+ * @param {readonly string[]} directories
103
+ * @param {ReadonlyMap<string, string>} packageIdOf the package that declares each directory
104
+ * @param {ReadonlyMap<string, readonly string[]>} afterOf each package's `after`
105
+ */
106
+ function orderPackageMigrationDirectories(directories, packageIdOf, afterOf) {
107
+ const directoriesOf = new Map();
108
+ for (const directory of directories) {
109
+ const packageId = packageIdOf.get(directory);
110
+ directoriesOf.set(packageId, [...(directoriesOf.get(packageId) || []), directory]);
111
+ }
112
+ const ordered = [];
113
+ const states = new Map();
114
+
115
+ function visit(directory, ancestry) {
116
+ const packageId = packageIdOf.get(directory);
117
+ if (states.get(directory) === "ordered") {
118
+ return;
119
+ }
120
+ if (states.get(directory) === "visiting") {
121
+ throw new Error(`Package migrations cannot each run after the other: ${[...ancestry, packageId].join(" -> ")}.`);
122
+ }
123
+ states.set(directory, "visiting");
124
+ for (const prerequisite of afterOf.get(packageId) || []) {
125
+ for (const prerequisiteDirectory of directoriesOf.get(prerequisite) || []) {
126
+ visit(prerequisiteDirectory, [...ancestry, packageId]);
127
+ }
128
+ }
129
+ states.set(directory, "ordered");
130
+ ordered.push(directory);
131
+ }
132
+
133
+ for (const directory of directories) {
134
+ visit(directory, []);
135
+ }
136
+ return ordered;
137
+ }
138
+
48
139
  async function discoverPackageMigrationDirectories({ appRoot = process.cwd() } = {}) {
49
140
  const normalizedAppRoot = path.resolve(appRoot);
50
- const directories = [];
141
+ const installedPackages = await discoverInstalledPackages({ appRoot: normalizedAppRoot });
142
+ const installedPackageIds = new Set(installedPackages.map(({ packageId }) => packageId));
143
+ const packageIdOf = new Map();
144
+ const afterOf = new Map();
51
145
 
52
- for (const installedPackage of await discoverInstalledPackages({ appRoot: normalizedAppRoot })) {
146
+ for (const installedPackage of installedPackages) {
53
147
  const declaredDirectories = installedPackage.packageMetadata?.migrations?.directories;
148
+ afterOf.set(installedPackage.packageId, migrationsAfterOf(installedPackage, installedPackageIds));
54
149
  if (typeof declaredDirectories === "undefined") {
55
150
  continue;
56
151
  }
@@ -84,20 +179,46 @@ async function discoverPackageMigrationDirectories({ appRoot = process.cwd() } =
84
179
  `${installedPackage.packageId} declares a missing package migration directory: ${relativeDirectory}.`
85
180
  );
86
181
  }
87
- directories.push(absoluteDirectory);
182
+ if (!packageIdOf.has(absoluteDirectory)) {
183
+ packageIdOf.set(absoluteDirectory, installedPackage.packageId);
184
+ }
88
185
  }
89
186
  }
90
187
 
91
- return Object.freeze([...new Set(directories)].sort((left, right) => left.localeCompare(right)));
188
+ const pathOrder = [...packageIdOf.keys()].sort((left, right) => left.localeCompare(right));
189
+ return Object.freeze(orderPackageMigrationDirectories(pathOrder, packageIdOf, afterOf));
190
+ }
191
+
192
+ /**
193
+ * A package's migration directory may hold a constraints/ subdirectory; it runs after the
194
+ * application's migrations/, like the application's own migrations/constraints/.
195
+ * @param {readonly string[]} packageMigrationDirectories
196
+ */
197
+ async function packageConstraintDirectoriesOf(packageMigrationDirectories) {
198
+ const directories = [];
199
+ for (const directory of packageMigrationDirectories) {
200
+ const constraintsDirectory = path.join(directory, "constraints");
201
+ if (await directoryExists(constraintsDirectory)) {
202
+ directories.push(constraintsDirectory);
203
+ }
204
+ }
205
+ return Object.freeze(directories);
92
206
  }
93
207
 
94
- async function createKnexMigrationConfigFromApp(options = {}) {
208
+ /**
209
+ * The Knex migration configuration of an application: its own migrations and those of every
210
+ * installed JSKIT package that declares some.
211
+ * @param {Omit<Parameters<typeof createKnexMigrationConfig>[0],
212
+ * "packageMigrationDirectories" | "packageConstraintDirectories">} options
213
+ */
214
+ async function createKnexMigrationConfigFromApp(options) {
95
215
  const appRoot = path.resolve(options.appRoot || process.cwd());
96
216
  const packageMigrationDirectories = await discoverPackageMigrationDirectories({ appRoot });
97
217
  return createKnexMigrationConfig({
98
218
  ...options,
99
219
  appRoot,
100
- packageMigrationDirectories
220
+ packageMigrationDirectories,
221
+ packageConstraintDirectories: await packageConstraintDirectoriesOf(packageMigrationDirectories)
101
222
  });
102
223
  }
103
224
 
@@ -1,43 +1,5 @@
1
1
  import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
2
- import { normalizeDatabaseClient, toKnexClientId } from "../../shared/databaseClient.js";
3
- import { resolveKnexConnectionFromEnvironment } from "../../shared/databaseConnection.js";
4
- import { createTransactionManager } from "../../shared/transactionManager.js";
5
- import { loadKnexFactory } from "../knexFactory.js";
6
-
7
- function resolveDriverDialectId(driver) {
8
- const dialectId = normalizeDatabaseClient(
9
- driver?.DIALECT_ID || driver?.dialectId || driver?.dialect || driver?.getDialectId?.(),
10
- { allowEmpty: true }
11
- );
12
- if (!dialectId) {
13
- throw new Error("The installed database driver did not expose a valid dialect id.");
14
- }
15
- return dialectId;
16
- }
17
-
18
- function createDatabase({ driver, env }) {
19
- const dialectId = resolveDriverDialectId(driver);
20
- const configuredClient = normalizeDatabaseClient(env.DB_CLIENT, { allowEmpty: true });
21
- if (configuredClient && configuredClient !== dialectId) {
22
- throw new Error(`DB_CLIENT="${configuredClient}" does not match installed database driver "${dialectId}".`);
23
- }
24
-
25
- const knex = loadKnexFactory()({
26
- client: toKnexClientId(dialectId),
27
- connection: resolveKnexConnectionFromEnvironment(env, {
28
- client: dialectId,
29
- defaultPort: dialectId === "pg" ? 5432 : 3306,
30
- context: "database runtime"
31
- })
32
- });
33
- const transactionManager = createTransactionManager({ knex });
34
-
35
- return Object.freeze({
36
- driver,
37
- knex,
38
- transactionManager
39
- });
40
- }
2
+ import { createDatabase } from "../database.js";
41
3
 
42
4
  const DatabaseProvider = defineProvider({
43
5
  id: "runtime.database",
@@ -48,14 +10,20 @@ const DatabaseProvider = defineProvider({
48
10
  provides: {
49
11
  database: "runtime.database"
50
12
  },
13
+ /**
14
+ * @param {object} dependencies
15
+ * @param {import("../types.js").RuntimeDatabaseDriver} dependencies.driver
16
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} dependencies.env
17
+ */
51
18
  setup({ driver, env }) {
52
19
  return { database: createDatabase({ driver, env }) };
53
20
  },
21
+ /**
22
+ * @param {unknown} _dependencies
23
+ * @param {{ outputs: { database: import("../types.js").RuntimeDatabase } }} lifecycle
24
+ */
54
25
  async shutdown(_dependencies, { outputs }) {
55
- const knex = outputs.database?.knex;
56
- if (knex && typeof knex.destroy === "function") {
57
- await knex.destroy();
58
- }
26
+ await outputs.database.knex.destroy();
59
27
  }
60
28
  });
61
29
 
@@ -0,0 +1,20 @@
1
+ // The types of the database capabilities, for features that require them.
2
+
3
+ /** @typedef {ReturnType<typeof import("./database.js").createDatabase>} RuntimeDatabase */
4
+ /** @typedef {import("knex").Knex} RuntimeKnex A Knex client: the one `runtime.database` shares, or one an application passes in. */
5
+ /** @typedef {RuntimeDatabase["transactionManager"]} RuntimeTransactionManager The transaction manager `runtime.database` shares. */
6
+ /** @typedef {import("knex").Knex.Transaction} RuntimeKnexTransaction A Knex transaction: the `trx` a repository or service call runs in, as the transaction manager hands it to its work. */
7
+ /** @typedef {import("knex").Knex.QueryBuilder} RuntimeKnexQueryBuilder A Knex query that a hook or helper narrows. */
8
+
9
+ /**
10
+ * The `runtime.database.driver` capability: the shared exports of the
11
+ * installed dialect package (`@jskit-ai/database-runtime-mysql` or
12
+ * `@jskit-ai/database-runtime-postgres`). Each driver package implements this
13
+ * contract; `runtime.database` reads its dialect from it.
14
+ * @typedef {object} RuntimeDatabaseDriver
15
+ * @property {string} DIALECT_ID The dialect id: "mysql2" or "pg".
16
+ * @property {(knex: RuntimeKnex, options?: { tableName?: string, idColumn?: string }) => Promise<object>} [introspectCrudTableSnapshot]
17
+ * Reads a table's columns for CRUD generation; the MySQL driver has it.
18
+ */
19
+
20
+ export {};
@@ -46,4 +46,18 @@ function isDuplicateEntryError(error, options) {
46
46
  return findDuplicateEntryError(error, options) !== null;
47
47
  }
48
48
 
49
- export { findDuplicateEntryError, isDuplicateEntryError };
49
+ /**
50
+ * True when an insert lost a race to a concurrent insert of the same row,
51
+ * outside a caller's transaction: the call held no `options.trx`, its own
52
+ * transaction rolled back in full (json-rest-api's `transactionOutcome`), and
53
+ * the error is a duplicate entry. The caller may then read the winner's row.
54
+ * Inside a caller's transaction the failed statement cannot be recovered, so
55
+ * it is never such a race.
56
+ * @param {{ transactionOutcome?: string } | null | undefined} error
57
+ * @param {{ trx?: unknown }} options The insert call's options.
58
+ */
59
+ function isLostDuplicateInsertRace(error, options) {
60
+ return !options.trx && error?.transactionOutcome === "rolledBack" && isDuplicateEntryError(error);
61
+ }
62
+
63
+ export { findDuplicateEntryError, isDuplicateEntryError, isLostDuplicateInsertRace };
@@ -9,9 +9,10 @@ export {
9
9
  } from "./dateUtils.js";
10
10
  export { normalizeDialect, detectDialectFromClient } from "./dialect.js";
11
11
  export { normalizeDatabaseClient, toKnexClientId } from "./databaseClient.js";
12
- export { findDuplicateEntryError, isDuplicateEntryError } from "./duplicateEntry.js";
12
+ export { findDuplicateEntryError, isDuplicateEntryError, isLostDuplicateInsertRace } from "./duplicateEntry.js";
13
13
  export { DEFAULT_VISIBILITY_COLUMNS, applyVisibility, applyVisibilityOwners } from "./visibility.js";
14
14
  export {
15
+ resolveTransaction,
15
16
  resolveQueryOptions,
16
17
  resolveRepoClient,
17
18
  applyForUpdate,
@@ -26,5 +27,6 @@ export {
26
27
  retryDeadlocks,
27
28
  runInTransaction,
28
29
  createWithTransaction,
30
+ joinOrOpenTransaction,
29
31
  lockScopedRecordId
30
32
  } from "./repositoryOptions.js";