@cloudflare/cabidela 0.0.19 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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
+
+- Added support for $id, $ref and $defs - https://json-schema.org/understanding-json-schema/structuring
+- Added support for not - https://json-schema.org/understanding-json-schema/reference/combining#not
+
 ## [0.0.19] - 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.
 
@@ -180,9 +182,121 @@ example, using this schema:
 - The payload `{ moon: 10}` will be modified to `{ sun: 9000, moon: 10 }`.
 - The payload `{ saturn: 10}` will throw an error because no condition is met.
 
+### $id, $ref, $defs
+
+The keywords [$id](https://json-schema.org/understanding-json-schema/structuring#id), [$ref](https://json-schema.org/understanding-json-schema/structuring#dollarref) and [$defs](https://json-schema.org/understanding-json-schema/structuring#defs) can be used to build and maintain complex schemas where the reusable parts are defined in separate schemas.
+
+The following is the main schema and a `customer` sub-schema that defines the `contacts` and `address` properties.
+
+```js
+import { Cabidela } from "@cloudflare/cabidela";
+
+const schema = {
+  $id: "http://example.com/schemas/main",
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    contacts: { $ref: "customer#/contacts" },
+    address: { $ref: "customer#/address" },
+    balance: { $ref: "$defs#/balance" },
+  },
+  required: ["name", "contacts", "address"],
+  "$defs": {
+    "balance": {
+      type: "object",
+      prope      properties: {
+        currency: { type: "string" },
+        amount: { type: "number" },
+      },
+    }
+  }
+};
+
+const contactSchema = {
+  $id: "http://example.com/schemas/customer",
+  contacts: {
+    type: "object",
+    properties: {
+      email: { type: "string" },
+      phone: { type: "string" },
+    },
+    required: ["email", "phone"],
+  },
+  address: {
+    type: "object",
+    properties: {
+      street: { type: "string" },
+      city: { type: "string" },
+      zip: { type: "string" },
+      country: { type: "string" },
+    },
+    required: ["street", "city", "zip", "country"],
+  },
+};
+
+const cabidela = new Cabidela(schema, { subSchemas: [contactSchema] });
+
+cabidela.validate({
+  name: "John",
+  contacts: {
+    email: "john@example.com",
+    phone: "+123456789",
+  },
+  address: {
+    street: "123 Main St",
+    city: "San Francisco",
+    zip: "94105",
+    country: "USA",
+  },
+});
+```
+
+## 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.
+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.
 
 ```js
 const schema = {
@@ -204,7 +318,7 @@ const payload = {
 
 cabidela.validate(payload);
 // throws "Error: prompt required"
-````
+```
 
 ## Tests
 
@@ -262,7 +376,7 @@ Here are some results:
     59.75x faster than Ajv
 
   Cabidela - benchmarks/80-big-ops.bench.js > allOf, two properties
-    1701.95x faster than Ajv
+   1701.95x faster than Ajv
 
   Cabidela - benchmarks/80-big-ops.bench.js > allOf, two objects
     1307.04x faster than Ajv
@@ -285,10 +399,7 @@ npm run benchmark
 Cabidela supports most of JSON Schema specification, and should be useful for many applications, but it's not complete. **Currently** we do not support:
 
 - Multiple (array of) types `{ "type": ["number", "string"] }`
-- Regular expressions
 - Pattern properties
-- `not`
 - `dependentRequired`, `dependentSchemas`, `If-Then-Else`
-- `$ref`, `$defs` and `$id`
 
 yet.

package/dist/index.d.mts

@@ -1,7 +1,9 @@
 type CabidelaOptions = {
     applyDefaults?: boolean;
+    useMerge?: boolean;
     errorMessages?: boolean;
     fullErrors?: boolean;
+    subSchemas?: Array<any>;
 };
 type SchemaNavigation = {
     path: Array<string>;
@@ -15,10 +17,13 @@ type SchemaNavigation = {
     defaultsCallbacks: Array<any>;
 };
 declare class Cabidela {
-    schema: any;
-    options: CabidelaOptions;
+    private schema;
+    private options;
+    private definitions;
     constructor(schema: any, options?: CabidelaOptions);
     setSchema(schema: any): void;
+    addSchema(subSchema: any, combine?: boolean): void;
+    getSchema(): any;
     setOptions(options: CabidelaOptions): void;
     throw(message: string, needle: SchemaNavigation): void;
     parseAdditionalProperties(needle: SchemaNavigation, contextAdditionalProperties: any, contextEvaluatedProperties: Set<string>): number;

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 type CabidelaOptions = {
     applyDefaults?: boolean;
+    useMerge?: boolean;
     errorMessages?: boolean;
     fullErrors?: boolean;
+    subSchemas?: Array<any>;
 };
 type SchemaNavigation = {
     path: Array<string>;
@@ -15,10 +17,13 @@ type SchemaNavigation = {
     defaultsCallbacks: Array<any>;
 };
 declare class Cabidela {
-    schema: any;
-    options: CabidelaOptions;
+    private schema;
+    private options;
+    private definitions;
     constructor(schema: any, options?: CabidelaOptions);
     setSchema(schema: any): void;
+    addSchema(subSchema: any, combine?: boolean): void;
+    getSchema(): any;
     setOptions(options: CabidelaOptions): void;
     throw(message: string, needle: SchemaNavigation): void;
     parseAdditionalProperties(needle: SchemaNavigation, contextAdditionalProperties: any, contextEvaluatedProperties: Set<string>): number;

package/dist/index.js

@@ -25,6 +25,52 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/helpers.ts
+var parse$ref = (ref) => {
+  const parts = ref.split("#");
+  const $id = parts[0];
+  const $path = parts[1].split("/").filter((part) => part !== "");
+  return { $id, $path };
+};
+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) {
     return prev ? prev[curr] : void 0;
@@ -32,7 +78,7 @@ var resolvePayload = (path, obj) => {
   return { metadata: getMetaData(resolvedObject), resolvedObject };
 };
 var pathToString = (path) => {
-  return path.length == 0 ? `.` : path.map((item) => typeof item === "number" ? `[${item}]` : `.${item}`).join("");
+  return path.length == 0 ? `/` : path.map((item) => `/${item}`).join("");
 };
 var getMetaData = (value) => {
   let size = 0;
@@ -70,20 +116,52 @@ var getMetaData = (value) => {
 var Cabidela = class {
   schema;
   options;
+  definitions = {};
   constructor(schema, options) {
     this.schema = schema;
     this.options = {
       fullErrors: true,
+      subSchemas: [],
       applyDefaults: false,
       errorMessages: false,
       ...options || {}
     };
+    if (this.schema.hasOwnProperty("$defs")) {
+      this.definitions["$defs"] = this.schema["$defs"];
+      delete this.schema["$defs"];
+    }
+    if (this.options.subSchemas.length > 0) {
+      for (const subSchema of this.options.subSchemas) {
+        this.addSchema(subSchema, false);
+      }
+    }
+    if (this.options.useMerge || this.options.subSchemas.length > 0) {
+      traverseSchema(this.options, this.definitions, this.schema);
+    }
   }
   setSchema(schema) {
     this.schema = schema;
   }
+  addSchema(subSchema, combine = true) {
+    if (subSchema.hasOwnProperty("$id")) {
+      const url = URL.parse(subSchema["$id"]);
+      if (url) {
+        this.definitions[url.pathname.split("/").slice(-1)[0]] = subSchema;
+      } else {
+        throw new Error(
+          "subSchemas need a valid retrieval URI $id https://json-schema.org/understanding-json-schema/structuring#retrieval-uri"
+        );
+      }
+    } else {
+      throw new Error("subSchemas need $id https://json-schema.org/understanding-json-schema/structuring#id");
+    }
+    if (combine == true) traverseSchema(this.options, this.definitions, this.schema);
+  }
+  getSchema() {
+    return this.schema;
+  }
   setOptions(options) {
-    this.options = options;
+    this.options = { ...this.options, ...options };
   }
   throw(message, needle) {
     const error = `${message}${this.options.fullErrors && needle.absorvErrors !== true && needle.errors.size > 0 ? `: ${Array.from(needle.errors).join(", ")}` : ``}`;
@@ -109,7 +187,7 @@ var Cabidela = class {
     } else {
       for (let property of unevaluatedProperties) {
         if (this.parseSubSchema({
-          path: [property.split(".").slice(-1)[0]],
+          path: [property.split("/").slice(-1)[0]],
           schema: contextAdditionalProperties,
           payload: resolvedObject,
           evaluatedProperties: /* @__PURE__ */ new Set(),
@@ -175,7 +253,7 @@ var Cabidela = class {
       if (new Set(needle.schema.required.map((r) => pathToString([...needle.path, r]))).difference(
         needle.evaluatedProperties.union(localEvaluatedProperties)
       ).size > 0) {
-        this.throw(`required properties at '${pathToString(needle.path)}' is '${needle.schema.required}'`, needle);
+        this.throw(`required properties at '${pathToString(needle.path)}' are '${needle.schema.required}'`, needle);
       }
     }
     return matchCount ? true : false;
@@ -210,6 +288,20 @@ var Cabidela = class {
     if (needle.schema == void 0) {
       this.throw(`No schema for path '${pathToString(needle.path)}'`, needle);
     }
+    if (needle.schema.hasOwnProperty("not")) {
+      let pass = false;
+      try {
+        this.parseSubSchema({
+          ...needle,
+          schema: needle.schema.not
+        });
+      } catch (e) {
+        pass = true;
+      }
+      if (pass == false) {
+        this.throw(`not at '${pathToString(needle.path)}' not met`, needle);
+      }
+    }
     if (needle.schema.hasOwnProperty("oneOf")) {
       const rounds = this.parseList(needle.schema.oneOf, needle, (r) => r !== 1);
       if (rounds !== 1) {
@@ -322,6 +414,14 @@ var Cabidela = class {
             break;
         }
       }
+      if (needle.schema.hasOwnProperty("pattern")) {
+        let passes = false;
+        try {
+          if (new RegExp(needle.schema.pattern).test(resolvedObject)) passes = true;
+        } catch (e) {
+        }
+        if (!passes) this.throw(`'${pathToString(needle.path)}' failed test ${needle.schema.pattern} patttern`, needle);
+      }
       if (needle.carryProperties) {
         needle.evaluatedProperties.add(pathToString(needle.path));
       }

package/dist/index.mjs

@@ -1,4 +1,50 @@
 // src/helpers.ts
+var parse$ref = (ref) => {
+  const parts = ref.split("#");
+  const $id = parts[0];
+  const $path = parts[1].split("/").filter((part) => part !== "");
+  return { $id, $path };
+};
+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) {
     return prev ? prev[curr] : void 0;
@@ -6,7 +52,7 @@ var resolvePayload = (path, obj) => {
   return { metadata: getMetaData(resolvedObject), resolvedObject };
 };
 var pathToString = (path) => {
-  return path.length == 0 ? `.` : path.map((item) => typeof item === "number" ? `[${item}]` : `.${item}`).join("");
+  return path.length == 0 ? `/` : path.map((item) => `/${item}`).join("");
 };
 var getMetaData = (value) => {
   let size = 0;
@@ -44,20 +90,52 @@ var getMetaData = (value) => {
 var Cabidela = class {
   schema;
   options;
+  definitions = {};
   constructor(schema, options) {
     this.schema = schema;
     this.options = {
       fullErrors: true,
+      subSchemas: [],
       applyDefaults: false,
       errorMessages: false,
       ...options || {}
     };
+    if (this.schema.hasOwnProperty("$defs")) {
+      this.definitions["$defs"] = this.schema["$defs"];
+      delete this.schema["$defs"];
+    }
+    if (this.options.subSchemas.length > 0) {
+      for (const subSchema of this.options.subSchemas) {
+        this.addSchema(subSchema, false);
+      }
+    }
+    if (this.options.useMerge || this.options.subSchemas.length > 0) {
+      traverseSchema(this.options, this.definitions, this.schema);
+    }
   }
   setSchema(schema) {
     this.schema = schema;
   }
+  addSchema(subSchema, combine = true) {
+    if (subSchema.hasOwnProperty("$id")) {
+      const url = URL.parse(subSchema["$id"]);
+      if (url) {
+        this.definitions[url.pathname.split("/").slice(-1)[0]] = subSchema;
+      } else {
+        throw new Error(
+          "subSchemas need a valid retrieval URI $id https://json-schema.org/understanding-json-schema/structuring#retrieval-uri"
+        );
+      }
+    } else {
+      throw new Error("subSchemas need $id https://json-schema.org/understanding-json-schema/structuring#id");
+    }
+    if (combine == true) traverseSchema(this.options, this.definitions, this.schema);
+  }
+  getSchema() {
+    return this.schema;
+  }
   setOptions(options) {
-    this.options = options;
+    this.options = { ...this.options, ...options };
   }
   throw(message, needle) {
     const error = `${message}${this.options.fullErrors && needle.absorvErrors !== true && needle.errors.size > 0 ? `: ${Array.from(needle.errors).join(", ")}` : ``}`;
@@ -83,7 +161,7 @@ var Cabidela = class {
     } else {
       for (let property of unevaluatedProperties) {
         if (this.parseSubSchema({
-          path: [property.split(".").slice(-1)[0]],
+          path: [property.split("/").slice(-1)[0]],
           schema: contextAdditionalProperties,
           payload: resolvedObject,
           evaluatedProperties: /* @__PURE__ */ new Set(),
@@ -149,7 +227,7 @@ var Cabidela = class {
       if (new Set(needle.schema.required.map((r) => pathToString([...needle.path, r]))).difference(
         needle.evaluatedProperties.union(localEvaluatedProperties)
       ).size > 0) {
-        this.throw(`required properties at '${pathToString(needle.path)}' is '${needle.schema.required}'`, needle);
+        this.throw(`required properties at '${pathToString(needle.path)}' are '${needle.schema.required}'`, needle);
       }
     }
     return matchCount ? true : false;
@@ -184,6 +262,20 @@ var Cabidela = class {
     if (needle.schema == void 0) {
       this.throw(`No schema for path '${pathToString(needle.path)}'`, needle);
     }
+    if (needle.schema.hasOwnProperty("not")) {
+      let pass = false;
+      try {
+        this.parseSubSchema({
+          ...needle,
+          schema: needle.schema.not
+        });
+      } catch (e) {
+        pass = true;
+      }
+      if (pass == false) {
+        this.throw(`not at '${pathToString(needle.path)}' not met`, needle);
+      }
+    }
     if (needle.schema.hasOwnProperty("oneOf")) {
       const rounds = this.parseList(needle.schema.oneOf, needle, (r) => r !== 1);
       if (rounds !== 1) {
@@ -296,6 +388,14 @@ var Cabidela = class {
             break;
         }
       }
+      if (needle.schema.hasOwnProperty("pattern")) {
+        let passes = false;
+        try {
+          if (new RegExp(needle.schema.pattern).test(resolvedObject)) passes = true;
+        } catch (e) {
+        }
+        if (!passes) this.throw(`'${pathToString(needle.path)}' failed test ${needle.schema.pattern} patttern`, needle);
+      }
       if (needle.carryProperties) {
         needle.evaluatedProperties.add(pathToString(needle.path));
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/cabidela",
-  "version": "0.0.19",
+  "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"