Add migrator service.

Author: jameswilddev

index.ts

@@ -64,6 +64,7 @@ export { HorizontallySymmetricalSafeAreaView } from './react-native/components/H
 export { intercalateRendered } from './react-native/utilities/intercalateRendered'
 export { isRenderedByReact } from './react-native/utilities/isRenderedByReact'
 export { logger } from './react-native/services/logger'
+export { Migrator } from './react-native/services/Migrator'
 export { nop } from './react-native/utilities/nop'
 export { PermissionHelper } from './react-native/services/PermissionHelper'
 export { PictureHelper } from './react-native/services/PictureHelper'
@@ -132,6 +133,9 @@ export type { KeyableTableCell } from './react-native/types/KeyableTableCell'
 export type { LimitedHeightProps } from './react-native/types/LimitedHeightProps'
 export type { LimitedWidthProps } from './react-native/types/LimitedWidthProps'
 export type { LoggerInterface } from './react-native/types/LoggerInterface'
+export type { MigratableState } from './react-native/types/MigratableState'
+export type { MigrationList } from './react-native/types/MigrationList'
+export type { MigratorInterface } from './react-native/types/MigratorInterface'
 export type { MinimumHeightProps } from './react-native/types/MinimumHeightProps'
 export type { MinimumWidthProps } from './react-native/types/MinimumWidthProps'
 export type { NonKeyableTableCell } from './react-native/types/NonKeyableTableCell'

package-lock.json

@@ -59,7 +59,7 @@
   "sideEffects": false,
   "dependencies": {
     "events": "3.3.0",
-    "expo": "~51.0.22",
+    "expo": "~51.0.24",
     "expo-constants": "~16.0.2",
     "expo-crypto": "~13.0.2",
     "expo-file-system": "~17.0.1",

package.json

@@ -0,0 +1,45 @@
+import type { MigratableState } from '../../types/MigratableState'
+import type { MigrationList } from '../../types/MigrationList'
+import type { MigratorInterface } from '../../types/MigratorInterface'
+import type { Json } from '../../types/Json'
+
+/**
+ * Executes migrations.
+ * @template T The data to be migrated.
+ */
+export class Migrator<T> implements MigratorInterface<T> {
+  /**
+   * @param migrationList The migrations to execute.
+   */
+  constructor (private readonly migrationList: MigrationList) {}
+
+  executionRequired (state: MigratableState<T>): boolean {
+    return !Object.prototype.hasOwnProperty.call(state, 'executedMigrationUuids') ||
+    state.executedMigrationUuids === undefined ||
+    this.migrationList.some(migration => !(state.executedMigrationUuids as readonly string[]).includes(migration[0]))
+  }
+
+  execute (state: MigratableState<T>): MigratableState<T> {
+    let initial = state
+
+    if (!Object.prototype.hasOwnProperty.call(initial, 'executedMigrationUuids') || initial.executedMigrationUuids === undefined) {
+      initial = { ...initial, executedMigrationUuids: [] }
+    }
+
+    let next = initial as { readonly executedMigrationUuids: readonly string[] } & Readonly<Record<string | number, Json>>
+
+    for (const migration of this.migrationList) {
+      if (!next.executedMigrationUuids.includes(migration[0])) {
+        next = {
+          ...migration[1](next),
+          executedMigrationUuids: [
+            ...next.executedMigrationUuids,
+            migration[0]
+          ]
+        }
+      }
+    }
+
+    return next as MigratableState<T>
+  }
+}

react-native/services/Migrator/index.tsx

@@ -0,0 +1,38 @@
+# `react-native-app-helpers/Migrator`
+
+Executes migrations.
+
+## Usage
+
+```tsx
+import { Migrator, MigratableState } from "react-native-app-helpers";
+
+type State = { readonly items: ReadonlyArray<number> }
+
+const state: MigratableState<State> = {
+  executedMigrationUuids: ['1b69c28f-454e-4511-aa05-596fe5ae23a8']
+}
+
+const migrator = new Migrator<State>([
+  ['b4dac8cd-af18-4e7d-a723-27f61d368228', (previous) => ({
+    ...previous,
+    items: [...previous.items, 1],
+  })],
+  ['1b69c28f-454e-4511-aa05-596fe5ae23a8', (previous) => ({
+    ...previous,
+    items: [...previous.items, 2],
+  })],
+  ['b07bc75d-1ba2-4bf7-b510-51a93d554a56', (previous) => ({
+    ...previous,
+    items: [...previous.items, 3],
+  })],
+]);
+
+console.log(migrator.executionRequired(state));
+console.log(migrator.execute(state));
+```
+
+## Interface
+
+This package also exports a `MigratorInterface` type which can be used to
+substitute other types in place of this class (for unit tests, for example).

react-native/services/Migrator/readme.md

@@ -0,0 +1,59 @@
+import { Migrator } from '../../..'
+
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type State = { readonly items: readonly number[] }
+
+const migrator = new Migrator<State>([
+  ['b4dac8cd-af18-4e7d-a723-27f61d368228', (previous) => ({
+    ...previous,
+    items: [...(previous['items'] as readonly number[]), 1]
+  })],
+  ['1b69c28f-454e-4511-aa05-596fe5ae23a8', (previous) => ({
+    ...previous,
+    items: [...(previous['items'] as readonly number[]), 2]
+  })],
+  ['b07bc75d-1ba2-4bf7-b510-51a93d554a56', (previous) => ({
+    ...previous,
+    items: [...(previous['items'] as readonly number[]), 3],
+    executedMigrationUuids: 'overwritten'
+  })]
+])
+
+test('execution is required when migrations do not exist', () => {
+  expect(migrator.executionRequired({
+    items: []
+  })).toBeTruthy()
+})
+
+test('execution is not required when all migrations have executed', () => {
+  expect(migrator.executionRequired({
+    executedMigrationUuids: ['1b69c28f-454e-4511-aa05-596fe5ae23a8', 'b4dac8cd-af18-4e7d-a723-27f61d368228', 'b07bc75d-1ba2-4bf7-b510-51a93d554a56'],
+    items: []
+  })).toBeFalsy()
+})
+
+test('execution is required when at least one migration has not been executed', () => {
+  expect(migrator.executionRequired({
+    executedMigrationUuids: ['1b69c28f-454e-4511-aa05-596fe5ae23a8'],
+    items: []
+  })).toBeTruthy()
+})
+
+test('all unexecuted migrations are ran in order', () => {
+  expect(migrator.execute({
+    executedMigrationUuids: ['1b69c28f-454e-4511-aa05-596fe5ae23a8'],
+    items: []
+  })).toEqual({
+    executedMigrationUuids: ['1b69c28f-454e-4511-aa05-596fe5ae23a8', 'b4dac8cd-af18-4e7d-a723-27f61d368228', 'b07bc75d-1ba2-4bf7-b510-51a93d554a56'],
+    items: [1, 3]
+  })
+})
+
+test('all migrations are ran in order', () => {
+  expect(migrator.execute({
+    items: []
+  })).toEqual({
+    executedMigrationUuids: ['b4dac8cd-af18-4e7d-a723-27f61d368228', '1b69c28f-454e-4511-aa05-596fe5ae23a8', 'b07bc75d-1ba2-4bf7-b510-51a93d554a56'],
+    items: [1, 2, 3]
+  })
+})

react-native/services/Migrator/unit.tsx

@@ -0,0 +1,11 @@
+/**
+ * Represents data which can have migrations ran against it.
+ * @template T The data which can have migrations ran against it.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type MigratableState<T> = {
+  /**
+   * The UUIDs of all executed migrations.
+   */
+  readonly executedMigrationUuids?: readonly string[]
+} & T

react-native/types/MigratableState/index.tsx

@@ -0,0 +1,18 @@
+# `react-native-app-helpers/MigratableState`
+
+Represents data which can have migrations ran against it.
+
+## Usage
+
+```tsx
+import type { MigratableState } from "react-native-app-helpers";
+
+type ExampleData = {
+  readonly exampleKey: 'exampleValue';
+};
+
+const example: MigratableState<ExampleData> = {
+  exampleKey: 'exampleValue',
+  executedMigrationUuids: [],
+};
+```

react-native/types/MigratableState/readme.md

@@ -0,0 +1,7 @@
+import type { Json } from '../Json'
+
+/**
+ * A list of migrations to be ran in order.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type MigrationList = ReadonlyArray<readonly [string, (previous: Readonly<Record<string | number, Json>>) => Readonly<Record<string | number, Json>>]>

react-native/types/MigrationList/index.tsx

@@ -0,0 +1,24 @@
+# `react-native-app-helpers/MigrationList`
+
+A list of migrations to be ran in order.
+
+## Usage
+
+```tsx
+import type { MigrationList } from "react-native-app-helpers";
+
+const migrationList: MigrationList = [
+  ['b4dac8cd-af18-4e7d-a723-27f61d368228', (previous) => ({
+    ...previous,
+    exampleChangeAKey: 'exampleChangeAValue',
+  })],
+  ['1b69c28f-454e-4511-aa05-596fe5ae23a8', (previous) => ({
+    ...previous,
+    exampleChangeBKey: 'exampleChangeBValue',
+  })],
+  ['b07bc75d-1ba2-4bf7-b510-51a93d554a56', (previous) => ({
+    ...previous,
+    exampleChangeCKey: 'exampleChangeCValue',
+  })],
+]
+```