z-schema 8.5.0 → 9.0.1

package/README.md

@@ -8,6 +8,7 @@
 
 - [What](#what)
 - [Versions](#versions)
+- [Getting started](#getting-started)
 - [Usage](#usage)
 - [Features](#features)
 - [Options](#options)
@@ -22,28 +23,40 @@ What is a JSON Schema? Find here: [https://json-schema.org/](https://json-schema
 
 - v6 - old version which has been around a long time, supports JSON Schema draft-04
 - v7 - modernized version (to ESM module with Typescript) which passes all tests from JSON Schema Test Suite for draft-04
-- v8 - by default assumes all schemas without $schema tag are draft-04, the old behaviour from v7 can be explicitly turned on by specifying `validator = new ZSchema({ version: 'none' });`
+- v8 - by default assumes all schemas without $schema tag are draft-04, the old behaviour from v7 can be explicitly turned on by specifying `validator = ZSchema.create({ version: 'none' });`
+- v9 - new api, `new ZSchema()` replaced by `ZSchema.create()` for initialization
 
-## Usage
+## Getting started
 
 Validator will try to perform sync validation when possible for speed, but supports async callbacks when they are necessary.
 
 ### ESM and Typescript:
 
-```javascript
+```typescript
 import ZSchema from 'z-schema';
-const validator = new ZSchema();
-console.log(validator.validate(1, { type: 'number' })); // true
-console.log(validator.validate(1, { type: 'string' })); // false
+const validator = ZSchema.create();
 ```
 
 ### CommonJs:
 
 ```javascript
 const ZSchema = require('z-schema');
-const validator = new ZSchema();
-console.log(validator.validate(1, { type: 'number' })); // true
-console.log(validator.validate(1, { type: 'string' })); // false
+const validator = ZSchema.create();
+```
+
+### Browser:
+
+```html
+<script type="text/javascript" src="z-schema/umd/ZSchema.min.js"></script>
+<script type="text/javascript">
+  var validator = ZSchema.create();
+  try {
+    validator.validate('string', { type: 'string' });
+    console.log('Validation passed');
+  } catch (error) {
+    console.log('Validation failed:', error.details);
+  }
+</script>
 ```
 
 ### CLI:
@@ -56,14 +69,68 @@ z-schema mySchema.json myJson.json
 z-schema --strictMode mySchema.json myJson.json
 ```
 
+## Usage
+
+### Schema Validation
+
+You can pre-validate and compile schemas using the `validateSchema` method. This is useful for server startup to ensure all schemas are valid and to resolve `$ref` references between schemas.
+
+```javascript
+const schemas = [
+  {
+    id: 'personDetails',
+    type: 'object',
+    properties: {
+      firstName: { type: 'string' },
+      lastName: { type: 'string' },
+    },
+    required: ['firstName', 'lastName'],
+  },
+  {
+    id: 'addressDetails',
+    type: 'object',
+    properties: {
+      street: { type: 'string' },
+      city: { type: 'string' },
+    },
+    required: ['street', 'city'],
+  },
+  {
+    id: 'personWithAddress',
+    allOf: [{ $ref: 'personDetails' }, { $ref: 'addressDetails' }],
+  },
+];
+
+try {
+  validator.validateSchema(schemas);
+  console.log('All schemas are valid and compiled');
+} catch (error) {
+  console.log('Schema validation failed:', error.details);
+}
+```
+
 ### Sync mode:
 
+The `validate` method automatically compiles and validates the schema before validating the JSON data against it. For better performance, you can pre-compile schemas using `validateSchema` during initialization.
+
 ```javascript
-var valid = validator.validate(json, schema);
-// this will return a native error object with name and message
-var error = validator.getLastError();
-// this will return an array of validation errors encountered
-var errors = validator.getLastErrors();
+try {
+  validator.validate(json, schema);
+  // validation passed
+} catch (error) {
+  // this will return a native error object with name and message
+  console.log(error.name); // 'z-schema validation error'
+  console.log(error.message); // common error message
+  // this will return an array of validation errors encountered
+  console.log(error.details); // array of detailed errors
+}
+
+// Or use validateSafe for object-based result
+const result = validator.validateSafe(json, schema);
+if (!result.valid) {
+  console.log(result.errs); // array of error objects
+}
+
 ...
 ```
 
@@ -80,7 +147,7 @@ import ZSchema from 'z-schema';
 import db from './db';
 
 // Initialize ZSchema
-const validator = new ZSchema();
+const validator = ZSchema.create();
 
 // Register async and sync format validators
 validator.registerFormat('user-exists', async (input: unknown): Promise<boolean> => {
@@ -137,56 +204,52 @@ const payload = {
 
 // Validate asynchronously
 try {
-  await validator.validateAsync(payload, personSchema);
+  const validator = ZSchema.create({ async: true });
+  await validator.validate(payload, personSchema);
   console.log('✅ Validation successful!');
 } catch (err) {
   console.log('❌ Validation failed:', err);
 }
 
 // or validate without try-catch
-const res = await validator.validateAsyncSafe(payload, personSchema);
+const validator = ZSchema.create({ async: true, safe: true });
+const res = await validator.validate(payload, personSchema);
 if (res.valid) {
   console.log('✅ Validation successful!');
 } else {
-  console.log('❌ Validation failed:', res.errs);
+  console.log('❌ Validation failed:', res.err);
 }
 ```
 
-### Browser:
-
-```html
-<script type="text/javascript" src="z-schema/umd/ZSchema.min.js"></script>
-<script type="text/javascript">
-  var validator = new ZSchema();
-  console.log(validator.validate('string', { type: 'string' }));
-</script>
-```
-
 ### Remote references and schemas:
 
 In case you have some remote references in your schemas, you have to download those schemas before using validator.
 Otherwise you'll get `UNRESOLVABLE_REFERENCE` error when trying to compile a schema.
 
 ```javascript
-var validator = new ZSchema();
+var validator = ZSchema.create();
 var json = {};
 var schema = { "$ref": "http://json-schema.org/draft-04/schema#" };
 
-var valid = validator.validate(json, schema);
-var errors = validator.getLastErrors();
-// valid === false
-// errors.length === 1
-// errors[0].code === "UNRESOLVABLE_REFERENCE"
+try {
+  validator.validate(json, schema);
+  // This won't reach here due to unresolvable reference
+} catch (error) {
+  // error.details will contain the validation errors
+  console.log(error.details[0].code); // "UNRESOLVABLE_REFERENCE"
+}
 
 var requiredUrl = "http://json-schema.org/draft-04/schema";
 request(requiredUrl, function (error, response, body) {
 
     validator.setRemoteReference(requiredUrl, JSON.parse(body));
 
-    var valid = validator.validate(json, schema);
-    var errors = validator.getLastErrors();
-    // valid === true
-    // errors === undefined
+    try {
+      validator.validate(json, schema);
+      // validation passed
+    } catch (error) {
+      // shouldn't happen after setting remote reference
+    }
 
 }
 ```

package/bin/z-schema

@@ -44,10 +44,11 @@ program
 
 var options = {};
 var defaultOptions = ZSchema.getDefaultOptions();
+var programOptions = program._optionValues; // { breakOnFirstError: true }
 
 for (var key in defaultOptions) {
-  if (program[key]) {
-    options[key] = program[key];
+  if (programOptions[key] != null) {
+    options[key] = programOptions[key];
   }
 }
 
@@ -72,28 +73,31 @@ function readJson(fileName) {
   return ret;
 }
 
-var validator = new ZSchema(options);
+var validator = ZSchema.create(options);
 var schemaFilePath = program.args.shift();
 var schema = readJson(schemaFilePath);
+schema.id = schemaFilePath;
 
 function validateWithAutomaticDownloads(filePath, data, schema, callback) {
   var lastResult;
+  var lastErrors;
 
   function finish() {
-    callback(validator.getLastErrors(), lastResult);
+    callback(lastErrors, lastResult);
   }
 
   function validate() {
     if (data !== undefined) {
-      lastResult = validator.validate(data, schema);
+      var result = validator.validateSafe(data, schema);
+      lastResult = result.valid;
+      lastErrors = result.valid ? null : result.err.details;
     } else {
-      lastResult = validator.validateSchema(schema);
+      var result = validator.validateSchemaSafe(schema);
+      lastResult = result.valid;
+      lastErrors = result.valid ? null : result.err.details;
     }
 
-    // console.log(lastResult);
-    // console.log(JSON.stringify(validator.getLastErrors(), null, 4));
-
-    var missingReferences = validator.getMissingRemoteReferences();
+    var missingReferences = validator.getMissingRemoteReferences(result.err);
     if (missingReferences.length > 0) {
       var finished = 0;
       missingReferences.forEach(function (url) {
@@ -150,7 +154,7 @@ function validateJsons() {
   var json = readJson(filePath);
   validateWithAutomaticDownloads(filePath, json, schema, function (errs, isValid) {
     if (!isValid) {
-      console.log(JSON.stringify(validator.getLastErrors(), null, 4));
+      console.log(JSON.stringify(errs, null, 4));
       console.log('json #' + i + ' validation failed');
       process.exitCode = 1;
     } else {
@@ -163,7 +167,7 @@ function validateJsons() {
 // validate schema
 validateWithAutomaticDownloads(schemaFilePath, undefined, schema, function (errs, isValid) {
   if (!isValid) {
-    console.log(JSON.stringify(validator.getLastErrors(), null, 4));
+    console.log(JSON.stringify(errs, null, 4));
     console.log('schema validation failed');
     process.exit(1);
   } else {