@serum-enterprises/schema 3.2.0-beta.0 → 4.0.0-alpha.0

package/README.md

@@ -1,22 +1,38 @@
-# Schema
+# Schema Framework
 
-Modern Schema Validation Library inspired by Joi.dev
+A flexible Schema Framework for building validation libraries. 
+
+This library provides the core infrastructure for schema validation, including base classes, error handling, and logical operations (Union, Intersect, etc.). To use it for actual data validation (like JSON, Strings, Numbers), you should use a plugin library like `@serum-enterprises/schema-json`.
 
 ## Installation
 
 ```bash
-npm install --save @serum-enterprises/schema@3.0.0-beta.1
+npm install @serum-enterprises/schema
 ```
 
-## Usage
+You will likely also want a plugin:
 
-```typescript
-import {Schema} from '@serum-enterprises/schema';
+```bash
+npm install @serum-enterprises/schema-json
+```
 
-const schema = Schema.Object.nullable().shape({
-	name: Schema.String,
-	age: Schema.Number.integer().min(18).max(99),
-	friends: Schema.Array.every(Schema.String)
+## Example (with Schema-JSON)
+
+```typescript
+import {Domain} from '@serum-enterprises/schema';
+import * as JSONSchema from '@serum-enterprises/schema-json';
+
+// Create a Domain with the JSON Plugin
+const Schema = Domain.create({
+    JSON: JSONSchema.Registry
+}, [
+    JSONSchema.Operations
+]);
+
+const schema = Schema.JSON.Object.shape({
+	name: Schema.JSON.String,
+	age: Schema.JSON.Number.integer().min(18).max(99),
+	friends: Schema.JSON.Array.every(Schema.JSON.String)
 }).exact();
 
 const person = schema.validate({name: 'John', age: 20, friends: ["Jane", "Mary"]});
@@ -26,9 +42,15 @@ console.log(person.age);
 console.log(person.friends.join(', '));
 ```
 
-## API
+## Features
+
+- **Extensible**: Register custom validators and operations through the Domain system.
+- **Composable**: Build complex schemas using logical operations like `Union` and `Intersect`.
+- **Plugin-based**: Keep your bundle small by only including the validators you need.
+
+## Plugin Libraries
 
-Please check [index.d.ts](./types/index.d.ts) for the full API.
+- [`@serum-enterprises/schema-json`](../Schema-JSON): Validators for standard JSON types (String, Number, Object, Array, etc.).
 
 ## LICENSE
 

package/dist/index.cjs

@@ -0,0 +1,62 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var index_exports = {};
+__export(index_exports, {
+  AssertError: () => import_errors.AssertError,
+  DefinitionError: () => import_errors.DefinitionError,
+  Domain: () => import_Domain.Domain,
+  DomainError: () => import_errors.DomainError,
+  InferDefinitionType: () => import_types.InferDefinitionType,
+  InferValidatorReturnType: () => import_types.InferValidatorReturnType,
+  IntersectValidator: () => import_validators.IntersectValidator,
+  IntersectValidatorDefinition: () => import_validators.IntersectValidatorDefinition,
+  NeverValidator: () => import_validators.NeverValidator,
+  NeverValidatorDefinition: () => import_validators.NeverValidatorDefinition,
+  UnionValidator: () => import_validators.UnionValidator,
+  UnionValidatorDefinition: () => import_validators.UnionValidatorDefinition,
+  UnknownValidator: () => import_validators.UnknownValidator,
+  UnknownValidatorDefinition: () => import_validators.UnknownValidatorDefinition,
+  Validator: () => import_Validator.Validator,
+  ValidatorClass: () => import_Validator.ValidatorClass
+});
+module.exports = __toCommonJS(index_exports);
+var import_Validator = require("./Validator");
+var import_errors = require("./lib/errors");
+var import_Domain = require("./Domain");
+var import_validators = require("./validators");
+var import_types = require("./lib/types");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AssertError,
+  DefinitionError,
+  Domain,
+  DomainError,
+  InferDefinitionType,
+  InferValidatorReturnType,
+  IntersectValidator,
+  IntersectValidatorDefinition,
+  NeverValidator,
+  NeverValidatorDefinition,
+  UnionValidator,
+  UnionValidatorDefinition,
+  UnknownValidator,
+  UnknownValidatorDefinition,
+  Validator,
+  ValidatorClass
+});

package/dist/index.mjs

@@ -0,0 +1,32 @@
+import { Validator, ValidatorClass } from "./Validator";
+import { AssertError, DefinitionError, DomainError } from "./lib/errors";
+import { Domain } from "./Domain";
+import {
+  NeverValidator,
+  NeverValidatorDefinition,
+  UnknownValidator,
+  UnknownValidatorDefinition,
+  UnionValidator,
+  UnionValidatorDefinition,
+  IntersectValidator,
+  IntersectValidatorDefinition
+} from "./validators";
+import { InferDefinitionType, InferValidatorReturnType } from "./lib/types";
+export {
+  AssertError,
+  DefinitionError,
+  Domain,
+  DomainError,
+  InferDefinitionType,
+  InferValidatorReturnType,
+  IntersectValidator,
+  IntersectValidatorDefinition,
+  NeverValidator,
+  NeverValidatorDefinition,
+  UnionValidator,
+  UnionValidatorDefinition,
+  UnknownValidator,
+  UnknownValidatorDefinition,
+  Validator,
+  ValidatorClass
+};

package/dist/types/Domain.d.ts

@@ -0,0 +1,23 @@
+import { Validator, ValidatorClass } from "./Validator";
+import { Operations } from "./lib/Operations";
+import { IntersectValidator, NeverValidator, UnionValidator, UnknownValidator } from "./validators";
+export type ReadonlyValidatorRegistry = {
+    readonly validators: Readonly<Record<string, ValidatorClass>>;
+};
+type DynamicDomain<R extends Readonly<Record<string, ReadonlyValidatorRegistry>>> = Domain & R;
+export declare class Domain {
+    static create<const R extends Readonly<Record<string, ReadonlyValidatorRegistry>>>(registries: R, operations: readonly Operations[]): DynamicDomain<R>;
+    private readonly _registry;
+    private readonly _operations;
+    constructor(validatorRegistries: Readonly<Record<string, ReadonlyValidatorRegistry>>, operations: readonly Operations[]);
+    get Never(): NeverValidator;
+    get Unknown(): UnknownValidator;
+    get Union(): UnionValidator;
+    get Intersect(): IntersectValidator;
+    normalize(validator: Validator): Validator;
+    merge(a: Validator, b: Validator): Validator;
+    isEqual(a: Validator, b: Validator): boolean;
+    isSubset(a: Validator, b: Validator): boolean;
+    fromJSON(definition: unknown, path?: string): Validator;
+}
+export {};

package/dist/types/Validator.d.ts

@@ -0,0 +1,13 @@
+import type { Domain } from './Domain';
+import type { Definition, UnknownDefinition } from './lib/types';
+export interface ValidatorClass<V extends Validator = Validator> {
+    fromJSON(data: UnknownDefinition, path: string, domain: Domain): V;
+    new (): V;
+}
+export declare abstract class Validator<T = unknown> {
+    abstract assert(data: unknown, path?: string): asserts data is T;
+    validate(data: unknown, path?: string): T;
+    test(data: unknown, path?: string): data is T;
+    abstract clone(): this;
+    abstract toJSON(): Definition;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export { Validator, ValidatorClass } from './Validator';
+export { AssertError, DefinitionError, DomainError } from './lib/errors';
+export { Domain } from './Domain';
+export { NeverValidator, NeverValidatorDefinition, UnknownValidator, UnknownValidatorDefinition, UnionValidator, UnionValidatorDefinition, IntersectValidator, IntersectValidatorDefinition } from './validators';
+export { InferDefinitionType, InferValidatorReturnType } from './lib/types';

package/dist/types/lib/Operations.d.ts

@@ -0,0 +1,36 @@
+import { Validator, ValidatorClass } from '../Validator';
+export type UnaryValidatorOperation = (validator: Validator, registry: Operations) => Validator;
+export type BinaryValidatorOperation = (a: Validator, b: Validator, registry: Operations) => Validator;
+export type BinaryBooleanOperation = (a: Validator, b: Validator, registry: Operations) => boolean;
+export interface ReadonlyOperationsRegistry {
+    normalize: ReadonlyMap<ValidatorClass, UnaryValidatorOperation>;
+    merge: ReadonlyMap<ValidatorClass, ReadonlyMap<ValidatorClass, BinaryValidatorOperation>>;
+    isEqual: ReadonlyMap<ValidatorClass, ReadonlyMap<ValidatorClass, BinaryBooleanOperation>>;
+    isSubset: ReadonlyMap<ValidatorClass, ReadonlyMap<ValidatorClass, BinaryBooleanOperation>>;
+}
+export declare class Operations {
+    readonly registry: ReadonlyOperationsRegistry;
+    static merge(operations: readonly Operations[]): Operations;
+    private static _cloneMap;
+    private static _cloneMatrix;
+    private static _mergeMaps;
+    private static _mergeMatrices;
+    constructor(registry?: ReadonlyOperationsRegistry);
+    private _lookupNormalizeOperation;
+    private _lookupMergeOperation;
+    private _lookupIsEqualOperation;
+    private _lookupIsSubsetOperation;
+    normalize(validator: Validator): Validator;
+    merge(a: Validator, b: Validator): Validator;
+    isEqual(a: Validator, b: Validator): boolean;
+    isSubset(a: Validator, b: Validator): boolean;
+    private _normalizeUnion;
+    private _normalizeIntersect;
+    private _flattenUnion;
+    private _flattenIntersect;
+    private _deduplicateValidators;
+    private _isEqual;
+    private _isEqualValidatorSet;
+    private _merge;
+    private _isSubset;
+}

package/dist/types/lib/errors.d.ts

@@ -0,0 +1,11 @@
+export declare class AssertError extends Error {
+    constructor(message: string, path?: string, cause?: Record<string, unknown>);
+}
+export declare class DefinitionError extends Error {
+    constructor(message: string, path?: string, cause?: Record<string, unknown>);
+}
+export declare class MergeError extends Error {
+    constructor(message: string, path?: string, cause?: Record<string, unknown>);
+}
+export declare class DomainError extends Error {
+}

package/dist/types/lib/types.d.ts

@@ -0,0 +1,13 @@
+import type { Validator, ValidatorClass } from '../Validator';
+export interface Definition {
+    type: string;
+}
+export type UnknownDefinition = Definition & Record<string, unknown>;
+export type InferDefinitionType<V> = V extends {
+    toJSON(): infer D;
+} ? D : never;
+export type InferValidatorInstanceType<C> = C extends ValidatorClass<infer V> ? V : never;
+export type InferValidatorReturnType<V> = V extends Validator<infer T> ? T : unknown;
+export type InferListDefinitionType<T extends readonly Validator[]> = {
+    [K in keyof T]: InferDefinitionType<T[K]>;
+};

package/dist/types/validators/Intersect.d.ts

@@ -0,0 +1,20 @@
+import { Validator } from '../Validator';
+import type { Domain } from '../Domain';
+import { Definition, InferListDefinitionType, InferValidatorReturnType, UnknownDefinition } from '../lib/types';
+export interface IntersectValidatorDefinition<VARIANTS extends readonly Definition[] = readonly Definition[]> extends Definition {
+    type: 'intersect';
+    variants: VARIANTS;
+}
+export declare class IntersectValidator<VARIANTS = unknown, VARIANTSDEFINITION extends readonly Definition[] = readonly Definition[]> extends Validator<VARIANTS> {
+    readonly rules: {
+        readonly variants: readonly Validator[];
+    };
+    static fromJSON(definition: UnknownDefinition, path: string | undefined, domain: Domain): IntersectValidator;
+    constructor(rules?: {
+        readonly variants: readonly Validator[];
+    });
+    variants<const V extends Validator[]>(variants: V): IntersectValidator<InferValidatorReturnType<V[number]>, InferListDefinitionType<V>>;
+    assert(data: unknown, path?: string): asserts data is VARIANTS;
+    clone(): this;
+    toJSON(): IntersectValidatorDefinition<VARIANTSDEFINITION>;
+}

package/dist/types/validators/Never.d.ts

@@ -0,0 +1,12 @@
+import { Validator } from '../Validator';
+import type { Domain } from '../Domain';
+import type { Definition, UnknownDefinition } from "../lib/types";
+export interface NeverValidatorDefinition extends Definition {
+    type: 'never';
+}
+export declare class NeverValidator extends Validator<never> {
+    static fromJSON(_definition: UnknownDefinition, _path: string | undefined, _domain: Domain): NeverValidator;
+    assert(_data: unknown, path?: string): asserts _data is never;
+    clone(): this;
+    toJSON(): NeverValidatorDefinition;
+}

package/dist/types/validators/Union.d.ts

@@ -0,0 +1,20 @@
+import { Validator } from '../Validator';
+import type { Domain } from '../Domain';
+import { Definition, InferListDefinitionType, InferValidatorReturnType, UnknownDefinition } from '../lib/types';
+export interface UnionValidatorDefinition<VARIANTS extends readonly Definition[] = readonly Definition[]> extends Definition {
+    type: 'union';
+    variants: VARIANTS;
+}
+export declare class UnionValidator<VARIANTS = unknown, VARIANTSDEFINITION extends readonly Definition[] = readonly Definition[]> extends Validator<VARIANTS> {
+    readonly rules: {
+        readonly variants: readonly Validator[];
+    };
+    static fromJSON(definition: UnknownDefinition, path: string | undefined, schemaDomain: Domain): UnionValidator;
+    constructor(rules?: {
+        readonly variants: readonly Validator[];
+    });
+    variants<const V extends Validator[]>(variants: V): UnionValidator<InferValidatorReturnType<V[number]>, InferListDefinitionType<V>>;
+    assert(data: unknown, path?: string): asserts data is VARIANTS;
+    clone(): this;
+    toJSON(): UnionValidatorDefinition<VARIANTSDEFINITION>;
+}

package/dist/types/validators/Unknown.d.ts

@@ -0,0 +1,12 @@
+import { Validator } from '../Validator';
+import type { Domain } from '../Domain';
+import type { Definition, UnknownDefinition } from "../lib/types";
+export interface UnknownValidatorDefinition extends Definition {
+    type: 'unknown';
+}
+export declare class UnknownValidator extends Validator {
+    static fromJSON(_definition: UnknownDefinition, _path: string | undefined, _domain: Domain): UnknownValidator;
+    assert(_data: unknown, _path?: string): asserts _data is unknown;
+    clone(): this;
+    toJSON(): UnknownValidatorDefinition;
+}

package/dist/types/validators/index.d.ts

@@ -0,0 +1,4 @@
+export { NeverValidator, NeverValidatorDefinition } from './Never';
+export { UnionValidator, UnionValidatorDefinition } from './Union';
+export { IntersectValidator, IntersectValidatorDefinition } from './Intersect';
+export { UnknownValidator, UnknownValidatorDefinition } from './Unknown';

package/package.json

@@ -1,16 +1,27 @@
 {
 	"name": "@serum-enterprises/schema",
-	"version": "3.2.0-beta.0",
+	"version": "4.0.0-alpha.0",
 	"engines": {
-		"node": ">=24.0.0"
+		"node": ">=16.0.0"
 	},
 	"description": "Modern Schema Validation Library inspired by Joi.dev",
-	"main": "./build/index.js",
-	"types": "./types/index.d.ts",
+	"main": "./dist/index.cjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/index.esm",
+			"require": "./dist/index.cjs",
+			"default": "./dist/index.esm"
+		}
+	},
 	"scripts": {
-		"prebuild": "tsc",
-		"build": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=build/index.js --sourcemap",
-		"test": "jest"
+		"build:types": "tsc -p tsconfig.build.json",
+		"build:cjs": "esbuild src/index.ts --platform=node --format=cjs --outfile=./dist/index.cjs",
+		"build:esm": "esbuild src/index.ts --platform=neutral --format=esm --outfile=./dist/index.mjs",
+		"build": "npm run build:types && npm run build:cjs && npm run build:esm",
+		"pretest": "esbuild './src/index.ts' './tests/**/*.test.ts' --sourcemap --platform=node --format=cjs --outdir=./build",
+		"test": "jest --testMatch '**/*.test.js' --roots build/tests"
 	},
 	"repository": {
 		"type": "git",
@@ -23,13 +34,13 @@
 	},
 	"devDependencies": {
 		"@types/jest": "^30.0.0",
-		"@types/node": "^25.3.0",
-		"esbuild": "^0.27.3",
-		"jest": "^30.2.0",
-		"typescript": "^5.9.3"
+		"@types/node": "^25.6.0",
+		"esbuild": "^0.28.0",
+		"jest": "^30.3.0",
+		"typescript": "^6.0.2"
 	},
 	"dependencies": {
 		"@serum-enterprises/json": "^3.1.0",
-		"@serum-enterprises/option": "^3.0.1"
+		"@serum-enterprises/option": "^3.4.1"
 	}
 }