Merge pull request #489 from json-schema-tools/feat/immutable

feat: immutable by default with option to mutate

.node-version

@@ -1 +1 @@
-16.17.0
+18.14.2

README.md

@@ -17,6 +17,7 @@ The input schema, as well as all of its subschemas must have titles. Their title
 Features:
  - Cyclic schemas become cyclic references
  - Completely synchronous
+ - immutable by default, option to mutate in place.
  - No external dependencies
  - Fully typed against the generated [meta-schema typings](https://github.com/json-schema-tools/meta-schema/)
  - magically makes your json schema smaller.

src/index.test.ts

@@ -103,21 +103,6 @@ describe("referencer", () => {
     expect(props.anotherFoo.$ref).toBe("#/definitions/foo");
   });
 
-  it("does mutate the input schema", () => {
-    const testSchema = {
-      title: "foo",
-      type: "object",
-      properties: { bar: { title: "bar", type: "number" } },
-    };
-
-    const reffed = referencer(testSchema as JSONSchema) as JSONSchemaObject;
-
-    const props = reffed.properties as Properties;
-
-    expect(props.bar.$ref).toBe("#/definitions/bar");
-    expect(reffed).toBe(testSchema);
-  });
-
   it("already has some refs with dupes", () => {
     const testSchema = {
       title: "anyOfTheThings",
@@ -163,4 +148,37 @@ describe("referencer", () => {
     expect(defs.allOfFoo.allOf[1].$ref).toBe("#/definitions/baz");
     expect(defs.baz.properties.cba.$ref).toBe("#/definitions/cba");
   });
+
+  describe("Mutable", () => {
+    it("does not mutate the input schema", () => {
+      const testSchema = Object.freeze({
+        title: "foo",
+        type: "object",
+        properties: { bar: { title: "bar", type: "number" } },
+      });
+
+      const reffed = referencer(testSchema as JSONSchema) as JSONSchemaObject;
+
+      const props = reffed.properties as Properties;
+
+      expect(props.bar.$ref).toBe("#/definitions/bar");
+      expect(reffed).not.toBe(testSchema);
+    });
+
+    it("does mutate the input schema when options.mutate === true", () => {
+      const testSchema = {
+        title: "foo",
+        type: "object",
+        properties: { bar: { title: "bar", type: "number" } },
+      };
+
+      const reffed = referencer(testSchema as JSONSchema, { mutate: true }) as JSONSchemaObject;
+
+      const props = reffed.properties as Properties;
+
+      expect(props.bar.$ref).toBe("#/definitions/bar");
+      expect(reffed).toBe(testSchema);
+    });
+
+  });
 });

src/index.ts

@@ -52,6 +52,20 @@ export class NoTitleError implements Error {
   }
 }
 
+/**
+ * Options that can be passed into the Referencer.
+ */
+export interface ReferencerOptions {
+  /**
+   * If true, the schema passed in will be referenced in-place, mutating the original. Default is false.
+   */
+  mutate?: boolean;
+}
+
+const defaultReferencerOptions = {
+  mutate: false,
+};
+
 /**
  * Returns the schema where all subschemas have been replaced with $refs and added to definitions.
  *
@@ -67,10 +81,10 @@ export class NoTitleError implements Error {
  * @category SchemaImprover
  *
  */
-export default function referencer(s: JSONSchema): JSONSchema {
+export default function referencer(s: JSONSchema, options: ReferencerOptions = defaultReferencerOptions): JSONSchema {
   const definitions: any = {};
 
-  traverse(
+  let newS = traverse(
     s,
     (subSchema: JSONSchema, isRootCycle: boolean) => {
       let t = "";
@@ -117,12 +131,16 @@ export default function referencer(s: JSONSchema): JSONSchema {
 
       return subSchema;
     },
-    { mutable: true, skipFirstMutation: true },
+    { mutable: options.mutate, skipFirstMutation: true },
   );
 
-  if (typeof s === "object" && Object.keys(definitions).length > 0) {
-    s.definitions = { ...s.definitions, ...definitions };
+  if (options.mutate === true) {
+    newS = s;
+  }
+
+  if (typeof newS === "object" && Object.keys(definitions).length > 0) {
+    newS.definitions = { ...newS.definitions, ...definitions };
   }
 
-  return s;
+  return newS;
 }