feat: add optional clone method to FormatPlugin interface

This method is used to clone the object returned by `read` before
passing it to `update`.

This is useful when the object returned by `read` is not trivially
cloneable. One use case is when trying to preserve comments in a JSONC
file using the `comment-json` package, which uses symbol properties on
the object to store comments. The default `clone` method would not
preserve these symbol properties, so a custom `clone` method is needed.

Fixes #10

README.md

@@ -71,6 +71,11 @@ const ignoreFormat = createFormat({
     const unique = (array) => Array.from(new Set() < T[number] > array).sort()
     await fs.writeFile(resolvedPath, unique(expected).join('\n'), 'utf8')
   },
+  // Optional: define a 'clone' function to control how the result of 'read' is cloned before being passed to 'update'
+  // Defaults to `structuredClone`[1] if available, otherwise `v8.deserialize(v8.serialize(obj))`.
+  clone(actual) {
+    return myCustomClone(actual)
+  },
 })
 
 export default async (_workspaceDir) => {

src/index.ts

@@ -88,7 +88,11 @@ export async function performUpdates<
           _writeProjectManifest: writeProjectManifest,
         }
         const actual = (await fileExists(resolvedPath)) ? await formatPlugin.read(formatHandlerOptions) : null
-        const expected = await formatPlugin.update(clone(actual), updateFile as any, formatHandlerOptions)
+        const expected = await formatPlugin.update(
+          formatPlugin.clone ? formatPlugin.clone(actual, formatHandlerOptions) : clone(actual),
+          updateFile as any,
+          formatHandlerOptions,
+        )
         const equal =
           (actual == null && expected == null) ||
           (actual != null && expected != null && (await formatPlugin.equal(expected, actual, formatHandlerOptions)))

src/updater/formatPlugin.ts

@@ -24,6 +24,13 @@ export interface FormatPlugin<Content> {
 
   /** Called only if write is required (`--test` isn't specified, `expected != null` and `expected` is not equal to `actual`) */
   write(expected: Content, options: FormatPluginFnOptions): PromiseOrValue<void>
+
+  /**
+   * Used to clone the object returned by `read` before passing it to `update`.
+   * Defaults to `structuredClone`[1] if available, otherwise `v8.deserialize(v8.serialize(obj))`.
+   * [1]: https://developer.mozilla.org/en-US/docs/web/api/structuredclone
+   */
+  clone?<Content>(value: Content, options: FormatPluginFnOptions): Content
 }
 
 export interface FormatPluginFnOptions {