test and document

src/schemas/settings/README.md

@@ -0,0 +1,27 @@
+# Settings migration
+
+Migrations are needed when changing the structure of existing settings file such as renaming or deleting keys.
+
+If you're simply adding new options to the settings file, a migration is not needed. In this case, extend the latest schema available.
+
+## Creating a new migration
+
+For when a new migration is needed:
+
+1. Create a directory for the new version (e.g. `/v2`).
+2. Declare the new schema with appropriate changes.
+3. In `/v2/index.ts`, implement a `migrate` function that takes a `v2` schema and returns a `v3` schema.
+4. Update `/schemas/settings/index.ts` to use the new version:
+
+```ts
+function migrate(settings: z.infer<typeof AnySettingSchema>) {
+
+case '2.0':
+  return migrate(v2.migrate(settings))
+
+}
+```
+
+5. Update `src/types/settings.ts` to use types from the new version.
+6. Update the default settings in `src/settings.ts` according to the new schema.
+7. Make changes to the remaining implementation to use the new schema.

src/schemas/settings/index.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { migrate } from '.'
+import * as v1 from './v1'
+
+describe('Settings migration', () => {
+  it('should migrate from v1 to latest', () => {
+    const v1Settings: v1.AppSettings = {
+      version: '1.0',
+      proxy: {
+        mode: 'regular',
+        port: 6000,
+        automaticallyFindPort: true,
+      },
+      recorder: {
+        detectBrowserPath: true,
+      },
+      windowState: {
+        width: 1200,
+        height: 800,
+        x: 0,
+        y: 0,
+        isMaximized: true,
+      },
+      usageReport: {
+        enabled: true,
+      },
+      appearance: {
+        theme: 'system',
+      },
+    }
+
+    expect(migrate(v1Settings).version).toBe('2.0')
+  })
+})

src/schemas/settings/index.ts

@@ -8,7 +8,7 @@ const AnySettingSchema = z.discriminatedUnion('version', [
   v2.AppSettingsSchema,
 ])
 
-function migrate(settings: z.infer<typeof AnySettingSchema>) {
+export function migrate(settings: z.infer<typeof AnySettingSchema>) {
   switch (settings.version) {
     case '1.0':
       return migrate(v1.migrate(settings))

src/schemas/settings/v1/index.ts

@@ -121,3 +121,5 @@ export function migrate(
     appearance: settings.appearance,
   }
 }
+
+export type AppSettings = z.infer<typeof AppSettingsSchema>