@cloudflare/cabidela 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.2] - 2025-03-07
+
+### Added
+
+- $merge support - see README for more information
+
 ## [0.1.1] - 2025-02-26
 
 ### Added

package/README.md

@@ -71,6 +71,8 @@ Cabidela takes a JSON-Schema and optional configuration flags:
 - `applyDefaults`: boolean - If true, the validator will apply default values to the input object. Default is false.
 - `errorMessages`: boolean - If true, the validator will use custom `errorMessage` messages from the schema. Default is false.
 - `fullErrors`: boolean - If true, the validator will be more verbose when throwing errors for complex schemas (example: anyOf, oneOf's), set to false for shorter exceptions. Default is true.
+- `useMerge`: boolean - Set to true if you want to use the `$merge` keyword. Default is false. See below for more information.
+- `subSchema`: any[] - An optional array of sub-schemas that can be used with `$id` and `$ref`. See below for more information.
 
 Returns a validation object.
 
@@ -249,6 +251,49 @@ cabidela.validate({
 });
 ```
 
+## Combined schemas and $merge
+
+The standard way of combining and extending schemas is by using the [`allOf`](https://json-schema.org/understanding-json-schema/reference/combining#allOf) (AND), [`anyOf`](https://json-schema.org/understanding-json-schema/reference/combining#anyOf) (OR), [`oneOf`](https://json-schema.org/understanding-json-schema/reference/combining#oneOf) (XOR) and [`not`](https://json-schema.org/understanding-json-schema/reference/combining#not) keywords, all supported by this library.
+
+Cabidela supports an additional keyword `$merge` (inspired by [Ajv](https://ajv.js.org/guide/combining-schemas.html#merge-and-patch-keywords)) that allows you to merge two objects. This is useful when you want to extend a schema with additional properties and `allOf`` is not enough.
+
+Here's how it works:
+
+```json
+{
+  "$merge": {
+    "source": {
+      "type": "object",
+      "properties": { "p": { "type": "string" } },
+      "additionalProperties": false
+    },
+    "with": {
+      "properties": { "q": { "type": "number" } }
+    }
+  }
+}
+```
+
+Resolves to:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "q": {
+      "type": "number"
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+To use `$merge` set the `useMerge` flag to true when creating the instance.
+
+```js
+new Cabidela(schema, { useMerge: true });
+```
+
 ## Custom errors
 
 If the new instance options has the `errorMessages` flag set to true, you can use the property `errorMessage` in the schema to define custom error messages.

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 type CabidelaOptions = {
     applyDefaults?: boolean;
+    useMerge?: boolean;
     errorMessages?: boolean;
     fullErrors?: boolean;
     subSchemas?: Array<any>;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 type CabidelaOptions = {
     applyDefaults?: boolean;
+    useMerge?: boolean;
     errorMessages?: boolean;
     fullErrors?: boolean;
     subSchemas?: Array<any>;

package/dist/index.js

@@ -31,25 +31,45 @@ var parse$ref = (ref) => {
   const $path = parts[1].split("/").filter((part) => part !== "");
   return { $id, $path };
 };
-var traverseSchema = (definitions, obj, cb = () => {
-}) => {
-  Object.keys(obj).forEach((key) => {
-    if (obj[key] !== null && typeof obj[key] === "object") {
-      traverseSchema(definitions, obj[key], (value) => {
-        obj[key] = value;
-      });
-    } else {
-      if (key === "$ref") {
-        const { $id, $path } = parse$ref(obj[key]);
-        const { resolvedObject } = resolvePayload($path, definitions[$id]);
-        if (resolvedObject) {
-          cb(resolvedObject);
-        } else {
-          throw new Error(`Could not resolve '${obj[key]}' $ref`);
+function deepMerge(target, source) {
+  const result = Array.isArray(target) && Array.isArray(source) ? target.concat(source) : { ...target, ...source };
+  for (const key of Object.keys(result)) {
+    result[key] = typeof target[key] == "object" && typeof source[key] == "object" ? deepMerge(target[key], source[key]) : structuredClone(result[key]);
+  }
+  return result;
+}
+var traverseSchema = (options, definitions, obj, cb) => {
+  let hits;
+  do {
+    hits = 0;
+    Object.keys(obj).forEach((key) => {
+      if (obj[key] !== null && typeof obj[key] === "object") {
+        traverseSchema(options, definitions, obj[key], (value) => {
+          hits++;
+          obj[key] = value;
+        });
+        if (options.useMerge && key === "$merge") {
+          const merge = deepMerge(obj[key].source, obj[key].with);
+          if (cb) {
+            cb(merge);
+          } else {
+            Object.assign(obj, merge);
+            delete obj[key];
+          }
+        }
+      } else {
+        if (key === "$ref") {
+          const { $id, $path } = parse$ref(obj[key]);
+          const { resolvedObject } = resolvePayload($path, definitions[$id]);
+          if (resolvedObject) {
+            cb(resolvedObject);
+          } else {
+            throw new Error(`Could not resolve '${obj[key]}' $ref`);
+          }
         }
       }
-    }
-  });
+    });
+  } while (hits > 0);
 };
 var resolvePayload = (path, obj) => {
   let resolvedObject = path.reduce(function(prev, curr) {
@@ -114,7 +134,9 @@ var Cabidela = class {
       for (const subSchema of this.options.subSchemas) {
         this.addSchema(subSchema, false);
       }
-      traverseSchema(this.definitions, this.schema);
+    }
+    if (this.options.useMerge || this.options.subSchemas.length > 0) {
+      traverseSchema(this.options, this.definitions, this.schema);
     }
   }
   setSchema(schema) {
@@ -133,7 +155,7 @@ var Cabidela = class {
     } else {
       throw new Error("subSchemas need $id https://json-schema.org/understanding-json-schema/structuring#id");
     }
-    if (combine == true) traverseSchema(this.definitions, this.schema);
+    if (combine == true) traverseSchema(this.options, this.definitions, this.schema);
   }
   getSchema() {
     return this.schema;

package/dist/index.mjs

@@ -5,25 +5,45 @@ var parse$ref = (ref) => {
   const $path = parts[1].split("/").filter((part) => part !== "");
   return { $id, $path };
 };
-var traverseSchema = (definitions, obj, cb = () => {
-}) => {
-  Object.keys(obj).forEach((key) => {
-    if (obj[key] !== null && typeof obj[key] === "object") {
-      traverseSchema(definitions, obj[key], (value) => {
-        obj[key] = value;
-      });
-    } else {
-      if (key === "$ref") {
-        const { $id, $path } = parse$ref(obj[key]);
-        const { resolvedObject } = resolvePayload($path, definitions[$id]);
-        if (resolvedObject) {
-          cb(resolvedObject);
-        } else {
-          throw new Error(`Could not resolve '${obj[key]}' $ref`);
+function deepMerge(target, source) {
+  const result = Array.isArray(target) && Array.isArray(source) ? target.concat(source) : { ...target, ...source };
+  for (const key of Object.keys(result)) {
+    result[key] = typeof target[key] == "object" && typeof source[key] == "object" ? deepMerge(target[key], source[key]) : structuredClone(result[key]);
+  }
+  return result;
+}
+var traverseSchema = (options, definitions, obj, cb) => {
+  let hits;
+  do {
+    hits = 0;
+    Object.keys(obj).forEach((key) => {
+      if (obj[key] !== null && typeof obj[key] === "object") {
+        traverseSchema(options, definitions, obj[key], (value) => {
+          hits++;
+          obj[key] = value;
+        });
+        if (options.useMerge && key === "$merge") {
+          const merge = deepMerge(obj[key].source, obj[key].with);
+          if (cb) {
+            cb(merge);
+          } else {
+            Object.assign(obj, merge);
+            delete obj[key];
+          }
+        }
+      } else {
+        if (key === "$ref") {
+          const { $id, $path } = parse$ref(obj[key]);
+          const { resolvedObject } = resolvePayload($path, definitions[$id]);
+          if (resolvedObject) {
+            cb(resolvedObject);
+          } else {
+            throw new Error(`Could not resolve '${obj[key]}' $ref`);
+          }
         }
       }
-    }
-  });
+    });
+  } while (hits > 0);
 };
 var resolvePayload = (path, obj) => {
   let resolvedObject = path.reduce(function(prev, curr) {
@@ -88,7 +108,9 @@ var Cabidela = class {
       for (const subSchema of this.options.subSchemas) {
         this.addSchema(subSchema, false);
       }
-      traverseSchema(this.definitions, this.schema);
+    }
+    if (this.options.useMerge || this.options.subSchemas.length > 0) {
+      traverseSchema(this.options, this.definitions, this.schema);
     }
   }
   setSchema(schema) {
@@ -107,7 +129,7 @@ var Cabidela = class {
     } else {
       throw new Error("subSchemas need $id https://json-schema.org/understanding-json-schema/structuring#id");
     }
-    if (combine == true) traverseSchema(this.definitions, this.schema);
+    if (combine == true) traverseSchema(this.options, this.definitions, this.schema);
   }
   getSchema() {
     return this.schema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/cabidela",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Cabidela is a small, fast, eval-less, Cloudflare Workers compatible, dynamic JSON Schema validator",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -27,6 +27,9 @@
     "README.md",
     "CHANGELOG.md"
   ],
+  "prettier": {
+    "embeddedLanguageFormatting": "auto"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/cloudflare/cabidela.git"
@@ -39,6 +42,7 @@
     "@vitest/ui": "^3.0.3",
     "ajv": "^8.17.1",
     "ajv-errors": "^3.0.0",
+    "ajv-merge-patch": "^5.0.1",
     "tsup": "^8.3.6",
     "typescript": "^5.7.3",
     "vitest": "^3.0.3"