@json-schema-tools/referencer 1.1.2 → 1.2.1

package/README.md

@@ -9,7 +9,7 @@
   </span>
 </center>
 
-Referencer is a package that exports a single function - a function that accepts and returns a JSON Schema. The returned schema is 'flat', as in, any subschemas of the schema have been converted into $refs. Further, any of the subschemas' subschema are also $reffed, recurively until everything is a $ref, and the definition section is fully populated.
+Referencer is a package that exports a single function - a function that accepts and returns a JSON Schema. The returned schema is 'flat', as in, any subschemas of the schema have been converted into $refs. Further, any of the subschemas' subschema are also $reffed, recursively until everything is a $ref, and the definition section is fully populated.
 
 The input schema may have refs, but the refs must already be in the definitions section.
 The input schema, as well as all of its subschemas must have titles. Their titles must also be unique for their content. We would like to use $id, but it has special meaning and therefor title is used as the unique identifier on-which schemas will be referenced.

package/build/index.d.ts

@@ -1,5 +1,5 @@
 import { JSONSchema } from "@json-schema-tools/meta-schema";
-export declare const stringifyCircular: (obj: any) => string;
+export declare const stringifyCircular: (obj: unknown) => string;
 export declare class NoTitleError implements Error {
     name: string;
     message: string;
@@ -13,6 +13,11 @@ export interface ReferencerOptions {
      * If true, the schema passed in will be referenced in-place, mutating the original. Default is false.
      */
     mutate?: boolean;
+    /**
+     * By setting this to `true`, only complex types (`object`) will be replaced.
+     * @default false
+     */
+    onlyComplex?: boolean;
 }
 /**
  * Returns the schema where all subschemas have been replaced with $refs and added to definitions.
@@ -22,6 +27,7 @@ export interface ReferencerOptions {
  * exists in the input schema's definitions object.
  *
  * @param s The schema to create references for (ie 'flatten' it)
+ * @param options The custom options
  *
  * @returns input schema where subschemas are turned into refs (recursively)
  *

package/build/index.js

@@ -15,10 +15,51 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NoTitleError = exports.stringifyCircular = void 0;
+exports.default = referencer;
 var traverse_1 = __importDefault(require("@json-schema-tools/traverse"));
 var deleteAllProps = function (o) {
     Object.keys(o)
-        .forEach(function (k) { delete o[k]; });
+        .forEach(function (k) { if (k !== 'title')
+        delete o[k]; });
+};
+var isObject = function (obj) {
+    return obj && obj === Object(obj);
+};
+var isComplex = function (obj) {
+    // TODO: evaluate if `array` should be considered complex
+    return (obj.type === 'object' && typeof obj.properties === 'object');
+};
+var hasReference = function (obj) {
+    return typeof obj.$ref === 'string' && obj.$ref.length > 0 && obj.$ref.indexOf("#") !== -1;
+};
+/**
+ * Replaces direct references to the root schema with a $ref to its definition.
+ *
+ * Since @json-schema-tools/traverse 1.12, a cycle back to the root invokes the
+ * mutation with the root's mutable copy (not the original schema), and the return
+ * value becomes the new root. The cycle site therefore cannot be fixed from inside
+ * the callback; instead the callback records the root definition and this post-pass
+ * swaps every remaining identity-reference to the root for the $ref.
+ */
+var breakRootCycles = function (root, originalRoot, title) {
+    var visited = new Set();
+    var visit = function (node) {
+        if (typeof node !== "object" || node === null || visited.has(node)) {
+            return;
+        }
+        visited.add(node);
+        for (var _i = 0, _a = Object.keys(node); _i < _a.length; _i++) {
+            var key = _a[_i];
+            var child = node[key];
+            if (child === root || child === originalRoot) {
+                node[key] = { $ref: "#/definitions/".concat(title) };
+            }
+            else {
+                visit(child);
+            }
+        }
+    };
+    visit(root);
 };
 var stringifyCircular = function (obj) {
     var cache = [];
@@ -41,13 +82,13 @@ var NoTitleError = /** @class */ (function () {
         try {
             schemaStr = JSON.stringify(schema);
         }
-        catch (e) {
+        catch (_a) {
             schemaStr = (0, exports.stringifyCircular)(schema);
         }
         try {
             parentSchemaStr = JSON.stringify(parentSchema);
         }
-        catch (e) {
+        catch (_b) {
             parentSchemaStr = (0, exports.stringifyCircular)(parentSchema);
         }
         this.message = [
@@ -75,6 +116,7 @@ var defaultReferencerOptions = {
  * exists in the input schema's definitions object.
  *
  * @param s The schema to create references for (ie 'flatten' it)
+ * @param options The custom options
  *
  * @returns input schema where subschemas are turned into refs (recursively)
  *
@@ -84,54 +126,84 @@ var defaultReferencerOptions = {
  */
 function referencer(s, options) {
     if (options === void 0) { options = defaultReferencerOptions; }
+    var _a = options.onlyComplex, onlyComplex = _a === void 0 ? false : _a, _b = options.mutate, mutate = _b === void 0 ? false : _b;
     var definitions = {};
+    // Set when a cycle back to the root schema is found. Kept as a flag because
+    // traverse >= 1.12 reports the root cycle against the root's mutable copy
+    // (whose return value becomes the new root), so the cycle site is repaired
+    // in a post-pass via breakRootCycles instead of inside the callback.
+    var rootCycleTitle;
     var newS = (0, traverse_1.default)(s, function (subSchema, isRootCycle) {
         var t = "";
-        if (isRootCycle && subSchema !== true && subSchema !== false) {
-            if (subSchema.$ref) {
-                var title = subSchema.$ref.replace("#/definitions/", "");
+        if (!isObject(subSchema)) { // For schema that is boolean
+            if (onlyComplex) {
+                return subSchema;
+            }
+            if (subSchema === true) {
+                t = "AlwaysTrue";
+                definitions[t] = true;
+            }
+            else if (subSchema === false) {
+                t = "AlwaysFalse";
+                definitions[t] = false;
+            }
+            return subSchema;
+        }
+        // Otherwise it is a object schema
+        var objectSchema = subSchema;
+        if (isRootCycle) {
+            if (objectSchema.$ref) {
+                var title = objectSchema.$ref.replace("#/definitions/", "");
                 var hasDefForRef = definitions[title];
                 if (hasDefForRef === undefined) {
-                    throw new Error("Encountered unknown $ref: ".concat(subSchema.$ref));
+                    throw new Error("Encountered unknown $ref: ".concat(objectSchema.$ref));
                 }
-                return subSchema;
+                return objectSchema;
             }
-            if (subSchema === s) {
+            if (objectSchema === s) {
                 definitions[s.title] = { $ref: "#" };
                 return { $ref: "#/definitions/".concat(s.title) };
             }
-            definitions[subSchema.title] = __assign({}, subSchema);
-            subSchema.$ref = "#/definitions/".concat(subSchema.title);
-            return subSchema;
-        }
-        if (subSchema === true) {
-            t = "AlwaysTrue";
-            definitions[t] = true;
-        }
-        else if (subSchema === false) {
-            t = "AlwaysFalse";
-            definitions[t] = false;
-        }
-        else if (subSchema.$ref !== undefined && subSchema.$ref.indexOf("#") !== -1) {
-            return subSchema;
+            // A cycle back to the root schema. Since traverse 1.12 the callback
+            // receives the root's mutable copy rather than the original schema,
+            // so the root is detected by title (titles are unique by contract)
+            // instead of object identity. The cycle site itself is repaired by
+            // breakRootCycles after traversal, because the callback's return
+            // value now becomes the new root.
+            if (objectSchema.title === s.title) {
+                var rootTitle = s.title;
+                if (typeof rootTitle !== "string") {
+                    // A cycle back to the root cannot be represented without a title
+                    // to key the definition by (see #585).
+                    throw new NoTitleError(objectSchema, s);
+                }
+                definitions[rootTitle] = { $ref: "#" };
+                rootCycleTitle = rootTitle;
+                return objectSchema;
+            }
+            definitions[objectSchema.title] = __assign({}, objectSchema);
+            objectSchema.$ref = "#/definitions/".concat(objectSchema.title);
+            return objectSchema;
         }
-        else {
-            if (typeof subSchema.title !== "string") {
-                throw new NoTitleError(subSchema, s);
+        if (!hasReference(objectSchema) && (!onlyComplex || isComplex(objectSchema))) {
+            if (typeof objectSchema.title !== "string") {
+                throw new NoTitleError(objectSchema, s);
             }
-            t = subSchema.title;
-            definitions[t] = __assign({}, subSchema);
-            deleteAllProps(subSchema);
-            subSchema.$ref = "#/definitions/".concat(t);
+            t = objectSchema.title;
+            definitions[t] = __assign({}, objectSchema);
+            deleteAllProps(objectSchema);
+            objectSchema.$ref = "#/definitions/".concat(t);
         }
-        return subSchema;
-    }, { mutable: options.mutate, skipFirstMutation: true });
-    if (options.mutate === true) {
+        return objectSchema;
+    }, { mutable: mutate, skipFirstMutation: true });
+    if (mutate === true) {
         newS = s;
     }
     if (typeof newS === "object" && Object.keys(definitions).length > 0) {
         newS.definitions = __assign(__assign({}, newS.definitions), definitions);
     }
+    if (rootCycleTitle !== undefined && typeof newS === "object" && newS !== null) {
+        breakRootCycles(newS, s, rootCycleTitle);
+    }
     return newS;
 }
-exports.default = referencer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-schema-tools/referencer",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "main": "build/index.js",
   "publishConfig": {
     "access": "public"
@@ -8,9 +8,10 @@
   "scripts": {
     "build": "npm run build:code && typedoc --out docs && touch docs/.nojekyll",
     "build:code": "tsc",
-    "lint": "eslint . --ext .ts",
+    "lint": "eslint .",
     "test": "npm run test:unit",
-    "test:unit": "jest --coverage"
+    "test:unit": "jest --coverage --runInBand",
+    "coverage:bump": "jest-it-up"
   },
   "author": "BelfordZ <belfordz66@gmail.com>",
   "license": "Apache-2.0",
@@ -26,22 +27,24 @@
     "!build/**/*.test.*"
   ],
   "devDependencies": {
-    "@json-schema-tools/dereferencer": "^1.6.2",
-    "@json-schema-tools/meta-schema": "^1.7.0",
-    "@json-schema-tools/titleizer": "^1.0.8",
-    "@json-schema-tools/transpiler": "^1.10.3",
+    "@eslint/js": "^9.9.1",
+    "@json-schema-tools/dereferencer": "^1.6.3",
+    "@json-schema-tools/meta-schema": "^1.7.5",
+    "@json-schema-tools/titleizer": "^1.0.9",
+    "@json-schema-tools/transpiler": "^1.10.4",
     "@types/jest": "^29.2.0",
-    "@types/node": "^20.12.7",
-    "@typescript-eslint/eslint-plugin": "^5.41.0",
-    "@typescript-eslint/parser": "^5.41.0",
-    "eslint": "^8.26.0",
+    "@types/node": "^22.5.0",
+    "@typescript-eslint/eslint-plugin": "^8.2.0",
+    "@typescript-eslint/parser": "^8.2.0",
+    "eslint": "^10.12.0",
     "jest": "^29.2.2",
-    "ts-jest": "^29.0.3",
-    "typedoc": "^0.25.13",
-    "typescript": "^5.4.4"
+    "jest-it-up": "^4.0.1",
+    "ts-jest": "^29.2.5",
+    "typedoc": "^0.28.20",
+    "typescript": "^5.5.4"
   },
   "dependencies": {
-    "@json-schema-tools/traverse": "^1.10.1"
+    "@json-schema-tools/traverse": "^1.15.1"
   },
   "homepage": "https://github.com/json-schema-tools/referencer#readme",
   "description": "Get a copy of a JSON Schema where all subschemas are turned into `$ref`s with corresponding definitions section."