@oliasoft-open-source/node-json-migrator 5.7.0-beta-2 → 5.8.0-beta-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/README.md CHANGED
@@ -181,15 +181,6 @@ and [merge requests](https://gitlab.com/oliasoft-open-source/node-json-migrator/
181
181
  - to build: `npm run buld` (this transpile a production build to the `dist` directory)
182
182
  - the build `dist` directory should be committed
183
183
 
184
- ## Migrating selected records
185
-
186
- Pass `recordIds` to `migrateAll()` to restrict the usual migration eligibility checks to a list of IDs.
187
- An empty list selects zero records. Omitting `recordIds` checks the entire entity table.
188
-
189
- For multiple batches, call `const migrateBatch = await prepareMigrationRun(options)` once with the configuration
190
- and callbacks. Call `await migrateBatch(recordIds)` for each batch. The migrator prepares one plan for the run.
191
- Each batch returns the number of eligible records.
192
-
193
184
  ## Concurrent database migrations
194
185
 
195
186
  `migrateAll()` accepts `config.concurrency`, a positive integer that defaults to `1` (sequential processing).
@@ -205,3 +196,27 @@ additional connections can still exhaust the pool and leave migrations waiting f
205
196
 
206
197
  When version history is missing from the database, records share a cached Git history lookup per migration run.
207
198
  The lookup is lazy. Failed lookups are removed from the cache so retries can try again. A new run starts with an empty cache.
199
+
200
+ ## Single-record database migrations
201
+
202
+ `migrateOne({ id, config, beforeMigrateRecord, afterMigrateRecord, validateRecord })` prepares the plan and migrates
203
+ one persisted record. Each call prepares its own plan; there is no public runner or shared prepared plan.
204
+ The optional request-specific `validateRecord` callback runs on the locked row before migration side effects.
205
+ The caller must authorize access before calling `migrateOne` and re-read and authorize the committed row before serving it.
206
+
207
+ Results have a `status`: `current`, `migrated`, `not-found`, `incompatible`, `conflict`, or `failed`.
208
+ The last three include `error`; they do not establish readiness. The caller owns error handling and any retry.
209
+ This API requires a registered, unchanged plan and rejects `dry` and `force`.
210
+ Unlike CLI preparation it does not rewrite files or deployment metadata, and resolves historical versions using the same database/Git fallback as batch migration.
211
+ Unknown or incompatible history blocks the record before migration callbacks.
212
+
213
+ Single-record and batch migration share the same transaction and optimistic update checks. A row lock and current-version
214
+ recheck prevent concurrent migration callers from applying the same transition twice. Callbacks still need to handle
215
+ external effects, such as Blob writes, that PostgreSQL cannot roll back.
216
+
217
+ The single-record operation checks the deployment migration table under the row lock and rejects a different target.
218
+ This is not release coordination: a deployment can replace that table after the check. Callers must coordinate old/new
219
+ server rollout separately. Readiness also does not prevent a later application writer from restoring stale JSON.
220
+
221
+ Run `pnpm run test:postgres` with `MIGRATOR_TEST_DATABASE_URL` pointing to a disposable database.
222
+ Without this variable, the PostgreSQL tests are skipped.
package/dist/index.d.mts CHANGED
@@ -42,7 +42,6 @@ type TRecordDetails = {
42
42
  version: string;
43
43
  currentPlan?: TPlan;
44
44
  };
45
- type TRecordIds = readonly TRecordDetails['id'][];
46
45
  type TRecordDetailsList = TRecordDetails[];
47
46
  type TEntityColumnNames = {
48
47
  id: string;
@@ -137,19 +136,51 @@ declare const migrate: ({
137
136
  }>;
138
137
  //#endregion
139
138
  //#region src/migrate-all/migrate-all.d.ts
140
- type MigrationRunOptions = {
139
+ /**
140
+ * Migrate all records (only use via command line interface)
141
+ */
142
+ declare const migrateAll: ({
143
+ config,
144
+ beforeMigrateRecord,
145
+ afterMigrateRecord,
146
+ onMigrationErrors
147
+ }: {
141
148
  config: TConfig;
142
149
  beforeMigrateRecord: TBeforeMigrateRecord;
143
150
  afterMigrateRecord: TAfterMigrateRecord;
144
151
  onMigrationErrors: TOnMigrationErrors;
152
+ }) => Promise<void>;
153
+ //#endregion
154
+ //#region src/migrate-record/migrate-one.d.ts
155
+ type TSingleRecordMigrationResult = {
156
+ status: 'current';
157
+ } | {
158
+ status: 'migrated';
159
+ } | {
160
+ status: 'not-found';
161
+ } | {
162
+ status: 'incompatible';
163
+ error: unknown;
164
+ } | {
165
+ status: 'conflict';
166
+ error: unknown;
167
+ } | {
168
+ status: 'failed';
169
+ error: unknown;
145
170
  };
146
- declare const prepareMigrationRun: (options: MigrationRunOptions) => Promise<(recordIds: TRecordIds) => Promise<number>>;
147
- declare const migrateAll: ({
148
- recordIds,
149
- ...options
150
- }: MigrationRunOptions & {
151
- recordIds?: TRecordIds;
152
- }) => Promise<number>;
171
+ declare const migrateOne: ({
172
+ id,
173
+ validateRecord,
174
+ config,
175
+ beforeMigrateRecord,
176
+ afterMigrateRecord
177
+ }: {
178
+ id: string | number;
179
+ validateRecord?: (record: TRecord) => void | Promise<void>;
180
+ config: TConfig;
181
+ beforeMigrateRecord: TBeforeMigrateRecord;
182
+ afterMigrateRecord: TAfterMigrateRecord;
183
+ }) => Promise<TSingleRecordMigrationResult>;
153
184
  //#endregion
154
185
  //#region src/pipe/pipe.d.ts
155
186
  /**
@@ -174,4 +205,4 @@ declare const printVersionHistory: ({
174
205
  config: TConfig;
175
206
  }) => Promise<void>;
176
207
  //#endregion
177
- export { type TAfterMigrateRecord, type TAfterMigrateRecordPayload, type TBeforeMigrateRecord, type TBeforeMigrateRecordPayload, type TConfig, type TEntityColumnNames, type TMetaData, type TMigration, type TMigrationErrorPayload, type TOnMigrationErrors, type TOnMigrationErrorsPayload, type TPayload, type TPlan, type TPlanEntry, type TRecord, type TRecordDetails, type TRecordDetailsList, checkMigrationPlan, createMigration, getPlannedMigrations, getPlannedVersion, getVersions, migrate, migrateAll, pipe, prepareMigrationRun, printVersionHistory };
208
+ export { type TAfterMigrateRecord, type TAfterMigrateRecordPayload, type TBeforeMigrateRecord, type TBeforeMigrateRecordPayload, type TConfig, type TEntityColumnNames, type TMetaData, type TMigration, type TMigrationErrorPayload, type TOnMigrationErrors, type TOnMigrationErrorsPayload, type TPayload, type TPlan, type TPlanEntry, type TRecord, type TRecordDetails, type TRecordDetailsList, type TSingleRecordMigrationResult, checkMigrationPlan, createMigration, getPlannedMigrations, getPlannedVersion, getVersions, migrate, migrateAll, migrateOne, pipe, printVersionHistory };
package/dist/index.mjs CHANGED
@@ -89,6 +89,44 @@ function memoize(fn, options = {}) {
89
89
  //#region node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/function/noop.mjs
90
90
  function noop() {}
91
91
  //#endregion
92
+ //#region node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/compat/_internal/getSymbols.mjs
93
+ function getSymbols(object) {
94
+ return Object.getOwnPropertySymbols(object).filter((symbol) => Object.prototype.propertyIsEnumerable.call(object, symbol));
95
+ }
96
+ //#endregion
97
+ //#region node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/compat/_internal/getTag.mjs
98
+ function getTag(value) {
99
+ if (value == null) return value === void 0 ? "[object Undefined]" : "[object Null]";
100
+ return Object.prototype.toString.call(value);
101
+ }
102
+ //#endregion
103
+ //#region node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/compat/_internal/tags.mjs
104
+ const regexpTag = "[object RegExp]";
105
+ const stringTag = "[object String]";
106
+ const numberTag = "[object Number]";
107
+ const booleanTag = "[object Boolean]";
108
+ const symbolTag = "[object Symbol]";
109
+ const dateTag = "[object Date]";
110
+ const mapTag = "[object Map]";
111
+ const setTag = "[object Set]";
112
+ const arrayTag = "[object Array]";
113
+ const functionTag = "[object Function]";
114
+ const arrayBufferTag = "[object ArrayBuffer]";
115
+ const objectTag = "[object Object]";
116
+ const errorTag = "[object Error]";
117
+ const dataViewTag = "[object DataView]";
118
+ const uint8ArrayTag = "[object Uint8Array]";
119
+ const uint8ClampedArrayTag = "[object Uint8ClampedArray]";
120
+ const uint16ArrayTag = "[object Uint16Array]";
121
+ const uint32ArrayTag = "[object Uint32Array]";
122
+ const bigUint64ArrayTag = "[object BigUint64Array]";
123
+ const int8ArrayTag = "[object Int8Array]";
124
+ const int16ArrayTag = "[object Int16Array]";
125
+ const int32ArrayTag = "[object Int32Array]";
126
+ const bigInt64ArrayTag = "[object BigInt64Array]";
127
+ const float32ArrayTag = "[object Float32Array]";
128
+ const float64ArrayTag = "[object Float64Array]";
129
+ //#endregion
92
130
  //#region node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/predicate/isPlainObject.mjs
93
131
  function isPlainObject(value) {
94
132
  if (!value || typeof value !== "object") return false;
@@ -136,6 +174,117 @@ function isEqualsSameValueZero(value, other) {
136
174
  return value === other || Number.isNaN(value) && Number.isNaN(other);
137
175
  }
138
176
  //#endregion
177
+ //#region node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/predicate/isEqualWith.mjs
178
+ function isEqualWith(a, b, areValuesEqual) {
179
+ return isEqualWithImpl(a, b, void 0, void 0, void 0, void 0, areValuesEqual);
180
+ }
181
+ function isEqualWithImpl(a, b, property, aParent, bParent, stack, areValuesEqual) {
182
+ const result = areValuesEqual(a, b, property, aParent, bParent, stack);
183
+ if (result !== void 0) return result;
184
+ if (typeof a === typeof b) switch (typeof a) {
185
+ case "bigint":
186
+ case "string":
187
+ case "boolean":
188
+ case "symbol":
189
+ case "undefined": return a === b;
190
+ case "number": return a === b || Object.is(a, b);
191
+ case "function": return a === b;
192
+ case "object": return areObjectsEqual(a, b, stack, areValuesEqual);
193
+ }
194
+ return areObjectsEqual(a, b, stack, areValuesEqual);
195
+ }
196
+ function areObjectsEqual(a, b, stack, areValuesEqual) {
197
+ if (Object.is(a, b)) return true;
198
+ let aTag = getTag(a);
199
+ let bTag = getTag(b);
200
+ if (aTag === "[object Arguments]") aTag = objectTag;
201
+ if (bTag === "[object Arguments]") bTag = objectTag;
202
+ if (aTag !== bTag) return false;
203
+ switch (aTag) {
204
+ case stringTag: return a.toString() === b.toString();
205
+ case numberTag: return isEqualsSameValueZero(a.valueOf(), b.valueOf());
206
+ case booleanTag:
207
+ case dateTag:
208
+ case symbolTag: return Object.is(a.valueOf(), b.valueOf());
209
+ case regexpTag: return a.source === b.source && a.flags === b.flags;
210
+ case functionTag: return a === b;
211
+ }
212
+ stack = stack ?? /* @__PURE__ */ new Map();
213
+ const aStack = stack.get(a);
214
+ const bStack = stack.get(b);
215
+ if (aStack != null && bStack != null) return aStack === b;
216
+ stack.set(a, b);
217
+ stack.set(b, a);
218
+ try {
219
+ switch (aTag) {
220
+ case mapTag:
221
+ if (a.size !== b.size) return false;
222
+ for (const [key, value] of a.entries()) if (!b.has(key) || !isEqualWithImpl(value, b.get(key), key, a, b, stack, areValuesEqual)) return false;
223
+ return true;
224
+ case setTag: {
225
+ if (a.size !== b.size) return false;
226
+ const aValues = Array.from(a.values());
227
+ const bValues = Array.from(b.values());
228
+ for (let i = 0; i < aValues.length; i++) {
229
+ const aValue = aValues[i];
230
+ const index = bValues.findIndex((bValue) => {
231
+ return isEqualWithImpl(aValue, bValue, void 0, a, b, stack, areValuesEqual);
232
+ });
233
+ if (index === -1) return false;
234
+ bValues.splice(index, 1);
235
+ }
236
+ return true;
237
+ }
238
+ case arrayTag:
239
+ case uint8ArrayTag:
240
+ case uint8ClampedArrayTag:
241
+ case uint16ArrayTag:
242
+ case uint32ArrayTag:
243
+ case bigUint64ArrayTag:
244
+ case int8ArrayTag:
245
+ case int16ArrayTag:
246
+ case int32ArrayTag:
247
+ case bigInt64ArrayTag:
248
+ case float32ArrayTag:
249
+ case float64ArrayTag:
250
+ if (typeof Buffer !== "undefined" && Buffer.isBuffer(a) !== Buffer.isBuffer(b)) return false;
251
+ if (a.length !== b.length) return false;
252
+ for (let i = 0; i < a.length; i++) if (!isEqualWithImpl(a[i], b[i], i, a, b, stack, areValuesEqual)) return false;
253
+ return true;
254
+ case arrayBufferTag:
255
+ if (a.byteLength !== b.byteLength) return false;
256
+ return areObjectsEqual(new Uint8Array(a), new Uint8Array(b), stack, areValuesEqual);
257
+ case dataViewTag:
258
+ if (a.byteLength !== b.byteLength || a.byteOffset !== b.byteOffset) return false;
259
+ return areObjectsEqual(new Uint8Array(a), new Uint8Array(b), stack, areValuesEqual);
260
+ case errorTag: return a.name === b.name && a.message === b.message;
261
+ case objectTag: {
262
+ if (!(areObjectsEqual(a.constructor, b.constructor, stack, areValuesEqual) || isPlainObject(a) && isPlainObject(b))) return false;
263
+ const aKeys = [...Object.keys(a), ...getSymbols(a)];
264
+ const bKeys = [...Object.keys(b), ...getSymbols(b)];
265
+ if (aKeys.length !== bKeys.length) return false;
266
+ for (let i = 0; i < aKeys.length; i++) {
267
+ const propKey = aKeys[i];
268
+ const aProp = a[propKey];
269
+ if (!Object.hasOwn(b, propKey)) return false;
270
+ const bProp = b[propKey];
271
+ if (!isEqualWithImpl(aProp, bProp, propKey, a, b, stack, areValuesEqual)) return false;
272
+ }
273
+ return true;
274
+ }
275
+ default: return false;
276
+ }
277
+ } finally {
278
+ stack.delete(a);
279
+ stack.delete(b);
280
+ }
281
+ }
282
+ //#endregion
283
+ //#region node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/predicate/isEqual.mjs
284
+ function isEqual(a, b) {
285
+ return isEqualWith(a, b, noop);
286
+ }
287
+ //#endregion
139
288
  //#region node_modules/.pnpm/es-toolkit@1.45.1/node_modules/es-toolkit/dist/predicate/isLength.mjs
140
289
  function isLength(value) {
141
290
  return Number.isSafeInteger(value) && value >= 0;
@@ -4299,8 +4448,7 @@ const filterRecordsWithNoPendingMigrations = ({ records, latestPlan }) => {
4299
4448
  return latestPlan.some((p) => !currentHashes.has(p.fileHash));
4300
4449
  });
4301
4450
  };
4302
- const getRecordList = async (db, entity, entityTableName, entityColumnNames, latestVersion, latestPlan, recordIds) => {
4303
- if (recordIds?.length === 0) return [];
4451
+ const getRecordList = async (db, entity, entityTableName, entityColumnNames, latestVersion, latestPlan) => {
4304
4452
  const query = `
4305
4453
  SELECT
4306
4454
  e.$(entityIdColumn:name) AS id,
@@ -4311,12 +4459,10 @@ const getRecordList = async (db, entity, entityTableName, entityColumnNames, lat
4311
4459
  FROM $(entityTable:name) e
4312
4460
  LEFT JOIN $(entityVersionsTable:name) v_current
4313
4461
  ON v_current.version = e.$(entityVersionColumn:name)
4314
- WHERE (
4462
+ WHERE
4315
4463
  e.$(entityVersionColumn:name) IS NULL
4316
4464
  OR e.$(entityVersionColumn:name) = ''
4317
4465
  OR e.$(entityVersionColumn:name) <> $(latestVersion)
4318
- )
4319
- ${recordIds === void 0 ? "" : "AND e.$(entityIdColumn:name) IN ($(recordIds:csv))"}
4320
4466
  `;
4321
4467
  const params = {
4322
4468
  entityTable: entityTableName,
@@ -4325,8 +4471,7 @@ const getRecordList = async (db, entity, entityTableName, entityColumnNames, lat
4325
4471
  entityNameColumn: entityColumnNames.name,
4326
4472
  entityCreatedColumn: entityColumnNames.created,
4327
4473
  entityVersionColumn: entityColumnNames.version,
4328
- latestVersion,
4329
- recordIds
4474
+ latestVersion
4330
4475
  };
4331
4476
  return filterRecordsWithNoPendingMigrations({
4332
4477
  records: (await db.any(query, params)).map((r) => ({
@@ -4341,13 +4486,14 @@ const getRecord = async (t, entityTableName, entityColumnNames, entityId) => {
4341
4486
  SELECT *
4342
4487
  FROM $(entityTable:name)
4343
4488
  WHERE $(entityIdColumn:name) = $(entityId)
4489
+ FOR UPDATE
4344
4490
  `;
4345
4491
  const params = {
4346
4492
  entityTable: entityTableName,
4347
4493
  entityId,
4348
4494
  entityIdColumn: entityColumnNames.id
4349
4495
  };
4350
- return t.one(query, params);
4496
+ return t.oneOrNone(query, params);
4351
4497
  };
4352
4498
  const updateRecord = async (t, entityTableName, entityColumnNames, entityId, currentVersion, nextData, nextVersion, etag) => {
4353
4499
  const useEtag = typeof etag === "number";
@@ -4872,53 +5018,70 @@ const migrateWithPlan = async ({ payload, config, metaData, preparedPlan, transa
4872
5018
  };
4873
5019
  };
4874
5020
  //#endregion
5021
+ //#region src/migrate-record/migrate-record.ts
5022
+ var MigrationConflictError = class extends Error {};
5023
+ const migrateRecord = async ({ id, config, preparedPlan, loadHistoricalPlans, loadExecutedMigrations, beforeMigrateRecord, afterMigrateRecord, validateRecord }) => {
5024
+ const { dry } = config;
5025
+ return config.database.tx(async (transaction) => {
5026
+ const currentRecord = await getRecord(transaction, config.entityTableName, config.entityColumnNames, id);
5027
+ if (!currentRecord) return { status: "not-found" };
5028
+ await validateRecord?.(currentRecord, transaction);
5029
+ const { [config.entityColumnNames.payload]: payload, [config.entityColumnNames.etag]: etag, [config.entityColumnNames.version]: currentVersion } = currentRecord;
5030
+ if (!config.force && preparedPlan && currentVersion === preparedPlan.nextVersion) return { status: "current" };
5031
+ await beforeMigrateRecord({
5032
+ currentRecord,
5033
+ transaction,
5034
+ dry
5035
+ });
5036
+ const { nextPayload, nextVersion } = await migrateWithPlan({
5037
+ payload,
5038
+ transaction,
5039
+ preparedPlan,
5040
+ loadHistoricalPlans,
5041
+ loadExecutedMigrations,
5042
+ config: {
5043
+ ...config,
5044
+ version: currentVersion
5045
+ },
5046
+ metaData: omit(currentRecord, [config.entityColumnNames.payload])
5047
+ });
5048
+ if (!dry) {
5049
+ const nextRecord = await updateRecord(transaction, config?.entityTableName, config?.entityColumnNames, id, currentVersion, nextPayload, nextVersion, etag);
5050
+ if (!nextRecord) {
5051
+ const expectedEtag = typeof etag === "number" ? `, etag=${JSON.stringify(etag)}` : "";
5052
+ throw new MigrationConflictError(`Failed to patch record with newest migration - The record was probably updated while migrating... Expected version=${JSON.stringify(currentVersion)}${expectedEtag}.`);
5053
+ }
5054
+ await afterMigrateRecord({
5055
+ currentRecord,
5056
+ nextRecord,
5057
+ transaction,
5058
+ dry
5059
+ });
5060
+ }
5061
+ return { status: "migrated" };
5062
+ });
5063
+ };
5064
+ //#endregion
4875
5065
  //#region src/migrate-all/migrate-all.ts
4876
5066
  const MAX_ATTEMPTS = 3;
4877
5067
  const validateConcurrency = (concurrency) => {
4878
5068
  if (!Number.isSafeInteger(concurrency) || concurrency < 1) throw new Error("Migration concurrency must be a positive integer");
4879
5069
  };
4880
- /**
4881
- * Migrate an entity record in the database
4882
- */
4883
- const migrateRecord = async ({ record, attempt, config, preparedPlan, loadHistoricalPlans, loadExecutedMigrations, beforeMigrateRecord, afterMigrateRecord }) => {
4884
- const { dry } = config;
5070
+ const migrateRecordAttempt = async ({ record, attempt, config, preparedPlan, loadHistoricalPlans, loadExecutedMigrations, beforeMigrateRecord, afterMigrateRecord }) => {
4885
5071
  console.log(chalk.gray(` ${record.name}`));
4886
5072
  try {
4887
- await config.database.tx(async (transaction) => {
4888
- const currentRecord = await getRecord(transaction, config.entityTableName, config.entityColumnNames, record.id);
4889
- const { [config.entityColumnNames.payload]: payload, [config.entityColumnNames.etag]: etag, [config.entityColumnNames.version]: currentVersion } = currentRecord;
4890
- await beforeMigrateRecord({
4891
- currentRecord,
4892
- transaction,
4893
- dry
4894
- });
4895
- const { nextPayload: nextData, nextVersion } = await migrateWithPlan({
4896
- payload,
4897
- transaction,
4898
- preparedPlan,
4899
- loadHistoricalPlans,
4900
- loadExecutedMigrations,
4901
- config: {
4902
- ...config,
4903
- version: currentVersion,
4904
- printPendingFileNames: true
4905
- },
4906
- metaData: omit(currentRecord, [config.entityColumnNames.payload])
4907
- });
4908
- if (!dry) {
4909
- const nextRecord = await updateRecord(transaction, config?.entityTableName, config?.entityColumnNames, record.id, currentVersion, nextData, nextVersion, etag);
4910
- if (!nextRecord) {
4911
- const expectedEtag = typeof etag === "number" ? `, etag=${JSON.stringify(etag)}` : "";
4912
- throw new Error(`Failed to patch record with newest migration - The record was probably updated while migrating... Expected version=${JSON.stringify(currentVersion)}${expectedEtag}.`);
4913
- }
4914
- await afterMigrateRecord({
4915
- currentRecord,
4916
- nextRecord,
4917
- transaction,
4918
- dry
4919
- });
4920
- }
4921
- });
5073
+ if ((await migrateRecord({
5074
+ id: record.id,
5075
+ config: {
5076
+ ...config,
5077
+ printPendingFileNames: true
5078
+ },
5079
+ preparedPlan,
5080
+ loadHistoricalPlans,
5081
+ loadExecutedMigrations,
5082
+ beforeMigrateRecord,
5083
+ afterMigrateRecord
5084
+ })).status === "not-found") throw new Error("Record no longer exists");
4922
5085
  return null;
4923
5086
  } catch (error) {
4924
5087
  const migrationErrorPayload = {
@@ -4964,7 +5127,7 @@ const migrateRecords = async ({ recordList, config, preparedPlan, beforeMigrateR
4964
5127
  let attempt = 0;
4965
5128
  while (attempt < MAX_ATTEMPTS) {
4966
5129
  attempt += 1;
4967
- const migrationErrorPayload = await migrateRecord({
5130
+ const migrationErrorPayload = await migrateRecordAttempt({
4968
5131
  record,
4969
5132
  attempt,
4970
5133
  config,
@@ -4993,34 +5156,77 @@ const migrateRecords = async ({ recordList, config, preparedPlan, beforeMigrateR
4993
5156
  console.log(chalk.yellow(`Completed ${config?.entity ?? "entity"} migrations (some failed)${config?.dry ? " [dry-run, no output written]" : ""} ✓`));
4994
5157
  } else console.log(chalk.green(`Completed ${config?.entity ?? "entity"} migrations (success)${config?.dry ? " [dry-run, no output written]" : ""} ✓`));
4995
5158
  };
4996
- const prepareRun = async ({ config: runConfig, beforeMigrateRecord, afterMigrateRecord, onMigrationErrors }) => {
4997
- const config = { ...runConfig };
5159
+ /**
5160
+ * Migrate all records (only use via command line interface)
5161
+ */
5162
+ const migrateAll = async ({ config, beforeMigrateRecord, afterMigrateRecord, onMigrationErrors }) => {
4998
5163
  validateConcurrency(config.concurrency ?? 1);
4999
- const plan = await PlanModule.getPlannedMigrations({ config });
5000
- const { validatedPlan: latestPlan, nextVersion: latestVersion } = plan;
5001
- return async (recordIds) => {
5002
- const recordList = await getRecordList(config?.database, config?.entity, config?.entityTableName, config?.entityColumnNames, latestVersion, latestPlan, recordIds);
5003
- if (recordIds !== void 0 && recordList.length === 0) return 0;
5004
- await migrateRecords({
5005
- config,
5006
- preparedPlan: plan,
5007
- recordList,
5164
+ const preparedPlan = await PlanModule.getPlannedMigrations({ config });
5165
+ const { validatedPlan: latestPlan, nextVersion: latestVersion } = preparedPlan;
5166
+ await migrateRecords({
5167
+ config,
5168
+ preparedPlan,
5169
+ recordList: await getRecordList(config?.database, config?.entity, config?.entityTableName, config?.entityColumnNames, latestVersion, latestPlan),
5170
+ beforeMigrateRecord,
5171
+ afterMigrateRecord,
5172
+ onMigrationErrors
5173
+ });
5174
+ };
5175
+ //#endregion
5176
+ //#region src/migrate-record/migrate-one.ts
5177
+ var IncompatibleMigrationError = class extends Error {};
5178
+ const migrateOne = async ({ id, validateRecord, config, beforeMigrateRecord, afterMigrateRecord }) => {
5179
+ try {
5180
+ if (config.dry || config.force || !config.database) throw new Error("Single-record migration requires a database and does not support dry or force");
5181
+ const runConfig = {
5182
+ ...config,
5183
+ entityColumnNames: { ...config.entityColumnNames },
5184
+ printPendingFileNames: false
5185
+ };
5186
+ const preparedPlan = await PlanModule.getPlannedMigrations({ config: {
5187
+ ...runConfig,
5188
+ dry: true
5189
+ } });
5190
+ const registeredPlan = await readPlanFromDatabase({
5191
+ database: runConfig.database,
5192
+ entity: runConfig.entity,
5193
+ version: preparedPlan.nextVersion
5194
+ });
5195
+ if (preparedPlan.planHasChanged || !isEqual(registeredPlan, preparedPlan.validatedPlan)) throw new Error("The server migration plan must be current and registered by the deployment migrator");
5196
+ let executedMigrations;
5197
+ return await migrateRecord({
5198
+ id,
5199
+ config: runConfig,
5200
+ preparedPlan,
5008
5201
  beforeMigrateRecord,
5009
5202
  afterMigrateRecord,
5010
- onMigrationErrors
5203
+ loadExecutedMigrations: async () => executedMigrations,
5204
+ validateRecord: async (record, transaction) => {
5205
+ await validateRecord?.(record);
5206
+ if (!isEqual(sortPlanEntries(await getMigrationRecords(transaction, runConfig.entity)), preparedPlan.validatedPlan)) throw new IncompatibleMigrationError("The deployed migration target differs from this server");
5207
+ const version = record[runConfig.entityColumnNames.version];
5208
+ executedMigrations = await getExecutedMigrationsFromVersion(transaction, runConfig.pgpHelpers, runConfig.entity, runConfig.directory, version, preparedPlan.nextVersion, preparedPlan.plannedMigrations, GitModule.getHistoricalPlansFromGit);
5209
+ if (!executedMigrations.every((entry) => {
5210
+ return preparedPlan.plannedMigrations.some((migration) => {
5211
+ return migration.fileName === entry.fileName && migration.sequence === entry.sequence && (migration.fileHash === entry.fileHash || migration.skippedFileHashes?.includes(entry.fileHash));
5212
+ });
5213
+ })) throw new IncompatibleMigrationError("Record migration history is incompatible with this server");
5214
+ }
5011
5215
  });
5012
- return recordList.length;
5013
- };
5014
- };
5015
- const prepareMigrationRun = async (options) => {
5016
- const migrateRecordsForRun = await prepareRun(options);
5017
- return (recordIds) => {
5018
- if (!Array.isArray(recordIds)) throw new TypeError("A migration batch requires an array of record IDs");
5019
- return migrateRecordsForRun(recordIds);
5020
- };
5021
- };
5022
- const migrateAll = async ({ recordIds, ...options }) => {
5023
- return (await prepareRun(options))(recordIds);
5216
+ } catch (error) {
5217
+ if (error instanceof IncompatibleMigrationError) return {
5218
+ status: "incompatible",
5219
+ error
5220
+ };
5221
+ if (error instanceof MigrationConflictError) return {
5222
+ status: "conflict",
5223
+ error
5224
+ };
5225
+ return {
5226
+ status: "failed",
5227
+ error
5228
+ };
5229
+ }
5024
5230
  };
5025
5231
  //#endregion
5026
5232
  //#region src/history/history.ts
@@ -5076,4 +5282,4 @@ const printVersionHistory = async ({ config }) => {
5076
5282
  }
5077
5283
  };
5078
5284
  //#endregion
5079
- export { checkMigrationPlan, createMigration, getPlannedMigrations, getPlannedVersion, getVersions, migrate, migrateAll, pipe, prepareMigrationRun, printVersionHistory };
5285
+ export { checkMigrationPlan, createMigration, getPlannedMigrations, getPlannedVersion, getVersions, migrate, migrateAll, migrateOne, pipe, printVersionHistory };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oliasoft-open-source/node-json-migrator",
3
- "version": "5.7.0-beta-2",
3
+ "version": "5.8.0-beta-1",
4
4
  "description": "A library for JSON migrations",
5
5
  "homepage": "https://oliasoft-open-source.gitlab.io/node-json-migrator",
6
6
  "bugs": {
@@ -78,6 +78,7 @@
78
78
  "lint:fix": "oxlint --fix",
79
79
  "test": "pnpm run test:unit && pnpm run test:integration",
80
80
  "test:integration": "node --disable-warning=DEP0205 --import @oxc-node/core/register --test \"test/integration.test.ts\"",
81
+ "test:postgres": "node --disable-warning=DEP0205 --import @oxc-node/core/register --test \"test/single-record-postgres.test.ts\"",
81
82
  "test:unit": "node --disable-warning=DEP0205 --import @oxc-node/core/register --test --experimental-test-coverage \"src/**/*.test.ts\"",
82
83
  "types:check": "tsc"
83
84
  }