schema-shield 1.0.0 → 1.0.1

package/README.md

@@ -4,14 +4,33 @@
 
 SchemaShield is a secure interpreter for JSON Schema engineered for strict environments and complex domain logic. It prioritizes **architectural stability** and **developer experience** over raw synthetic throughput.
 
-- **Security by Design:** Zero Code Generation. Fully compatible with strict Content Security Policy (CSP).
-- **Production Stability:** Stack-safe traversal. Designed to minimize stack usage and reduce the risk of stack overflows, even on deeply nested schemas.
-- **Domain Integrated:** Validates runtime objects (Classes, Dates, Streams) alongside serialized JSON.
-- **Transparent Debugging:** Pure JavaScript execution means clean stack traces and no black-box generated code.
+> 🏆 **Fastest JSON Schema Validator on Bun** — 2.5x faster than ajv, 4x faster than schemasafe
+> 
+> 📊 **#3 fastest on Node.js** — 70% ajv speed, 50x faster than jsonschema
+
+## Quick Start
+
+```javascript
+import { SchemaShield } from "schema-shield";
+
+const validator = new SchemaShield().compile({
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    age: { type: "number" }
+  }
+});
+
+validator({ name: "John", age: 30 });
+// { valid: true, data: { name: "John", age: 30 } }
+
+validator({ name: "John", age: "30" });
+// { valid: false, error: ValidationError }
+```
 
 ## Table of Contents
 
-- [Table of Contents](#table-of-contents)
+- [Quick Start](#quick-start)
 - [Why SchemaShield?](#why-schemashield)
   - [Comparison with Other Approaches](#comparison-with-other-approaches)
 - [Usage](#usage)
@@ -47,6 +66,7 @@ SchemaShield is a secure interpreter for JSON Schema engineered for strict envir
 - [Known Limitations](#known-limitations)
   - [1. Dynamic ID Scope Resolution (Scope Alteration)](#1-dynamic-id-scope-resolution-scope-alteration)
   - [2. Unicode Length Validation](#2-unicode-length-validation)
+  - [3. Conservative Equality Path (Performance Trade-off)](#3-conservative-equality-path-performance-trade-off)
 - [Testing](#testing)
 - [Contribute](#contribute)
 - [Legal](#legal)
@@ -70,7 +90,7 @@ Most validators optimize for "operations per second" in synthetic benchmarks, of
 | Feature                       | SchemaShield                                        | JIT Compilers                    | Classic Interpreters  |
 | :---------------------------- | :-------------------------------------------------- | :------------------------------- | :-------------------- |
 | **Architecture**              | **Secure Flat Interpreter**                         | JIT Compiler (eval/new Function) | Recursive Interpreter |
-| **Relative Speed**            | **High (~60%)**                                     | Reference (100%)                 | Low (1% - 20%)        |
+| **Relative Speed**            | **High (~70%)**                                     | Reference (100%)                 | Low (1% - 20%)        |
 | **CSP Compliance**            | **Native (100% Safe)**                              | Requires Build Config            | Variable              |
 | **Edge Ready**                | **Native**                                          | Complex Setup                    | Variable              |
 | **Stack Safety**              | **Minimized stack usage (non-recursive core loop)** | Risk of Overflow                 | Risk of Overflow      |
@@ -193,19 +213,19 @@ In runtimes using JavaScriptCore (like Bun), SchemaShield outperforms JIT compil
 | Validator          | Relative Speed | Context      |
 | :----------------- | :------------- | :----------- |
 | **SchemaShield**   | **100%**       | **Fastest**  |
-| ajv                | ~55%           | JIT Compiler |
-| @exodus/schemasafe | ~12%           | Interpreter  |
+| ajv                | ~40%           | JIT Compiler |
+| @exodus/schemasafe | ~24%           | Interpreter  |
 | jsonschema         | ~2%            | Legacy       |
 
 ### 2. Standard Runtimes (Node.js)
 
-In V8-based environments (Node.js), SchemaShield maintains elite performance for a secure interpreter, being roughly **50x faster** than legacy libraries.
+In V8-based environments (Node.js), SchemaShield maintains elite performance for a secure interpreter, being roughly **70x faster** than legacy libraries.
 
 | Validator          | Relative Speed | Context             |
 | :----------------- | :------------- | :------------------ |
 | ajv                | 100%           | Reference (JIT)     |
-| @exodus/schemasafe | ~75%           | Interpreter         |
-| **SchemaShield**   | **~60%**       | **Secure Standard** |
+| @exodus/schemasafe | ~74%           | Interpreter         |
+| **SchemaShield**   | **~70%**       | **Secure Standard** |
 | jsonschema         | ~1%            | Legacy              |
 
 **Key Takeaway:** SchemaShield delivers consistent high performance in Node.js without the security risks, memory leaks, or "cold start" latency associated with code generation.
@@ -504,7 +524,6 @@ Take into account that the error must be generated using the `defineError` funct
 
 - `message`: A string that describes the validation error.
 - `options`: An optional object with properties that provide more context for the error:
-
   - `item`?: An optional value representing the final item in the path where the validation error occurred. (e.g. index of an array item)
   - `cause`?: An optional `ValidationError` (or `true` in fail-fast mode) that represents the cause of the current error.
   - `data`?: An optional value representing the data that caused the validation error.
@@ -1086,6 +1105,13 @@ SchemaShield validates `minLength` and `maxLength` based on JavaScript's `length
 
 - **Impact:** Emoji or surrogate pairs may be counted as length 2.
 
+### 3. Conservative Equality Path (Performance Trade-off)
+
+For keywords like `enum`, `const`, and `uniqueItems`, SchemaShield prioritizes exact structural comparisons to preserve predictable behavior.
+
+- **Impact:** For very large arrays or enums with many complex objects, this conservative path can be slower than aggressive hashing strategies.
+- **Future Option:** An opt-in aggressive mode based on structural hashing/bucketing could improve throughput in those extreme cases, but it is intentionally not enabled by default to avoid edge-case semantic divergence.
+
 ## Testing
 
 SchemaShield prioritizes reliability and accuracy in JSON Schema validation by using the [JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite).

package/dist/formats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../lib/formats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAwCzC,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,KAAK,CAoM1D,CAAC"}
+{"version":3,"file":"formats.d.ts","sourceRoot":"","sources":["../lib/formats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AA8TzC,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,KAAK,CA4O1D,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /****************** Path: lib/index.ts ******************/
-import { DefineErrorFunction, ValidationError } from "./utils";
-export { ValidationError } from "./utils";
-export { deepClone } from "./utils";
+import { DefineErrorFunction, ValidationError } from "./utils/main-utils";
+export { ValidationError } from "./utils/main-utils";
+export { deepCloneUnfreeze as deepClone } from "./utils/deep-freeze";
 export type Result = void | ValidationError | true;
 export interface KeywordFunction {
     (schema: CompiledSchema, data: any, defineError: DefineErrorFunction, instance: SchemaShield): Result;
@@ -43,11 +43,22 @@ export declare class SchemaShield {
     getType(type: string): TypeFunction | false;
     addFormat(name: string, validator: FormatFunction, overwrite?: boolean): void;
     getFormat(format: string): FormatFunction | false;
+    isDefaultFormatValidator(format: string, validator: FormatFunction): boolean;
     addKeyword(name: string, validator: KeywordFunction, overwrite?: boolean): void;
     getKeyword(keyword: string): KeywordFunction | false;
     getSchemaRef(path: string): CompiledSchema | undefined;
     getSchemaById(id: string): CompiledSchema | undefined;
     compile(schema: any): Validator;
+    private isPlainObject;
+    private isTrivialAlwaysValidSubschema;
+    private shallowArrayEquals;
+    private flattenAssociativeBranches;
+    private flattenSingleWrapperOneOf;
+    private normalizeSchemaForCompile;
+    private markSchemaHasRef;
+    private shouldSkipKeyword;
+    private hasRequiredDefaults;
+    private isDefaultTypeValidator;
     private compileSchema;
     isSchemaLike(subSchema: any): boolean;
     private linkReferences;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,OAAO,EACL,mBAAmB,EACnB,eAAe,EAMhB,MAAM,SAAS,CAAC;AAMjB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,eAAe,GAAG,IAAI,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,CACE,MAAM,EAAE,cAAc,EACtB,IAAI,EAAE,GAAG,EACT,WAAW,EAAE,mBAAmB,EAChC,QAAQ,EAAE,YAAY,GACrB,MAAM,CAAC;CACX;AAED,MAAM,WAAW,YAAY;IAC3B,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,CAAC,IAAI,EAAE,GAAG,GAAG;QACX,IAAI,EAAE,GAAG,CAAC;QACV,KAAK,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;QACrC,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,cAAc,EAAE,cAAc,CAAC;CAChC;AAOD,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,UAAU,CAA0C;IAC5D,OAAO,CAAC,QAAQ,CAAiB;gBAErB,EACV,SAAiB,EACjB,QAAe,EAChB,GAAE;QACD,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACf;IAqBN,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,UAAQ;IAOhE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,KAAK;IAI3C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,SAAS,UAAQ;IAOpE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,KAAK;IAIjD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,UAAQ;IAOtE,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,KAAK;IAIpD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAOtD,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIrD,OAAO,CAAC,MAAM,EAAE,GAAG,GAAG,SAAS;IAkC/B,OAAO,CAAC,aAAa;IAgMrB,YAAY,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO;IAerC,OAAO,CAAC,cAAc;CA4DvB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"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"}