@sourcemeta/blaze 15.1.0 → 15.3.0

package/README.md

@@ -18,30 +18,24 @@ npm install --save @sourcemeta/blaze
 
 ## Usage
 
-Blaze evaluates pre-compiled schema templates. Compile your JSON Schema using
+Blaze evaluates pre-compiled schema templates. Compile your JSON Schema with
 the [JSON Schema CLI](https://github.com/sourcemeta/jsonschema) (see the
 [`compile`](https://github.com/sourcemeta/jsonschema/blob/main/docs/compile.markdown)
-command):
+command), then load the resulting template and validate instances against it.
+The mode (fast or exhaustive) is fixed at compile time, not evaluation time.
 
 ```sh
 npm install --global @sourcemeta/jsonschema
-
-cat > schema.json <<'EOF'
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "properties": {
-    "name": { "type": "string" },
-    "age": { "type": "integer" }
-  },
-  "required": [ "name" ]
-}
-EOF
-
 jsonschema compile schema.json --fast > template.json
 ```
 
-Then validate instances:
+Pass a string as the second argument to `validate` to receive a JSON object
+that follows the JSON Schema [Standard Output Format](https://json-schema.org/draft/2020-12/json-schema-core#name-output-formatting)
+instead of a boolean. Two formats are supported:
+[`'flag'`](https://json-schema.org/draft/2020-12/json-schema-core#name-flag)
+(validity only) and
+[`'basic'`](https://json-schema.org/draft/2020-12/json-schema-core#name-basic)
+(errors and annotations):
 
 ```javascript
 import { readFileSync } from "node:fs";
@@ -50,24 +44,25 @@ import { Blaze } from "@sourcemeta/blaze";
 const template =
   JSON.parse(readFileSync("template.json", "utf-8"));
 const evaluator = new Blaze(template);
+const instance = { name: "John", age: 30 };
 
-// true or false
-console.log(evaluator.validate({ name: "John", age: 30 }));
-```
+// Plain boolean
+evaluator.validate(instance);
 
-With an evaluation callback for tracing:
+// { valid: true } or { valid: false }
+evaluator.validate(instance, "flag");
 
-```javascript
-const instance = { name: "John", age: 30 };
-const result = evaluator.validate(instance,
-  (type, valid, instruction,
-   evaluatePath, instanceLocation, annotation) => {
-    console.log(type, evaluatePath,
-      instanceLocation, valid);
-  });
-console.log(result); // true or false
+// { valid: true, annotations?: [ ... ] }
+// { valid: false, errors: [ ... ] }
+evaluator.validate(instance, "basic");
 ```
 
+For lower-level integration, `validate` also accepts a callback that fires for
+every instruction with `(type, valid, instruction, evaluatePath,
+instanceLocation, annotation)`. The exported `describe(valid, instruction,
+evaluatePath, instanceLocation, instance, annotation)` helper turns any such
+event into a human-readable message.
+
 ### Parsing large integers
 
 JavaScript's