@lucania/schema 1.0.8 → 2.0.1

package/README.md

@@ -1,90 +1,64 @@
 # Schema
----
 | TECHNICAL | |
 |:-:|-|
 | _noun_ | _a representation of a plan or theory in the form of an outline or model._|
 
 This library allows you to specify the schema for your data, and get compile time typings _(help from your IDE)_ and runtime validation _(throw errors if your data isn't in the right format)_.
 
-With this library, everything is built from "Schema Primitives" _(henceforth referred to as "Primitives")_, out of the box, all of the JavaScript primitive types are implemented, but this set of _Primitives_ can be extended for your use case. The JavaScript `Date` is also a supported _Primitive_. All of your schema objects will be built from this extensible set of _Primitives_.
-
-|_Primitives_|
-|:-:|
-|`undefined`|
-|`boolean`|
-|`number`|
-|`bigint`|
-|`string`|
-|`symbol`|
-|`any`|
-|`Date`|
-
-## Validation with a Primitive
+With this library, you create objects that serve as a blueprint for what your data should look like. These objects are called `Schema`s.
+
+|_Schema Type_|Description|Usage|Example Data|
+|:-:|:-|:-|:-|
+|`StringSchema`|Used to represent a string.|`$.String(required?: boolean, default?: StringSource)`|`"Moaaz"`, `"The cow jumped over the moon."`|
+|`NumberSchema`|Used to represent a number.|`$.Number(required?: boolean, default?: NumberSource)`|`-30`, `0`, `10`
+|`BooleanSchema`|Used to represent a boolean.|`$.Boolean(required?: boolean, default?: BooleanSource)`|`true`, `false`
+|`DateSchema`|Used to represent a Date.|`$.Date(required?: boolean, default?: DateSource)`|`new Date(2000, 9, 29)`, `new Date("1998-09-04")`
+|`ObjectSchema`|Used to represent an Object.|`$.Object(subschema: { <key>: Schema }, required?: boolean, default?: ObjectSource)`|`<depends on subschema>`, `{ name: "Jeremy", age: 23 }`, `{ make: "Toyota", model: "Sienna", year: 2011 }`
+|`ArraySchema`|Used to represent an array|`$.Array(subschema: Schema, required?: boolean, default?: ArraySource)`|`<depends on subschema>`, `[]`, `[1, 2, 3]`, `["Ben", "Amit", "Dean"]`
+|`EnumerationSchema`|Used to represent an enumeration value, otherwise known as a set of possible strings values.|`$.Enumeration(members: Members, required?: boolean, default?: EnumerationSource)`|`<depends on members>`, `"MAGENTA"`, `"CA"`, `"male"`
+|`OrSetSchema`|Used to represent a value that should be validated by one of many possible schemas. This is used to represent a value that is allowed to be multiple types.|`$.OrSet(members: Members, required?: boolean, default?: OrSetSource)`|`<depends on members>`
+|`DynamicObjectSchema`|Used to represent an object that could have many different keys.|`$.DynamicObject(subschema: Schema, required?: boolean, default?: DynamicObjectSource)`|`{ <any key>: <depends on subschema> }`
+|`AnySchema`|Used to represent a value that could be any type.|`$.Any(required?: boolean, default?: AnySource)`|`1`, `"Omar"`, `false`, `{}`, `[]`, `<any type>`
+
+## Validation
+The simplest possible validation:
 ```typescript
-import { Schema } from "@lucania/schema";
+import { $ } from "@lucania/schema";
+
+// Create a Schema to represent a number.
+const numberSchema = $.Number();
 
+// Some data with an unknown type, likely coming from a file, network or untyped library.
 const dataOfUnknownType: any = 123;
-const dataOfNumberType = Schema.validate("number", dataOfUnknownType);
-```
 
-With _Primitives_, you can now start building more complex data structures. There are multiple way to represent different scenarios. This is done with the following constructs.
+// Using our number Schema to validate that our untyped data is what we expect it to be, a number. "dataOfNumberType" now has the "number" type.
+const dataOfNumberType = numberSchema.validate(dataOfUnknownType);
+```
 
-| _Constructs_ |_Structure_|_TLDR_|
-|:-:|:-:|:-:|
-|`Meta`|`{ type: <Primitive or another Construct>, required: boolean, default?: <default value>, validate: <validator> }`|A meta object to describe the nature of a section within a schema.|
-|`Array`|`[ <Primitive or another Construct> ]`|Represents an array within a schema.|
-|`Hierarchy`|`{ [ <Any keys needed> ]: <Primitive or another Construct> }`|Represents nested object hierarchy within a schema.|
-|`Compound`|`[ <Primitive or another Construct>, "or", <Primitive or another Construct> ]`| Represents union types. Currently can be used with "and" or "or". |
-|`Dynamic`|`{ $: <Primitive or another Construct> }`|Represents a object with dynamic keys. (Produces the TypeScript type `{ [Key: string]: any }`)|
+With this collection of Schemas, we can now start building more complex data structures. There are multiple way to represent different scenarios. This is done with the following constructs.
 
-## Creating Schema
-These primitives and constructs can come together to allow you to define your own schema.
+## Creating Hierarchical Schema
+These schemas can come together to allow you to define a blueprint for more complex data structures.
 ```typescript
-import { Schema } from "@lucania/schema";
-
-/* ↓ Schema Definition */
-const PersonSchema = Schema.build({
-    name: /* ← Hierarchy ↓ */ {
-        first: /* ← Meta ↓ */ {
-            type: "string" /* ← Primitive */,
-            required: true
-        },
-        middle: { type: "string", required: false },
-        last: { type: "string", required: true }
-    },
-    favoriteNumber: ["bigint" /* ← Primitive */, "or", "number"] /* ← Compound */,
-    age: {
-        type: "number",
-        required: false,
-        validate: (age: number, rawData: any) => {
-            const birthDate = Schema.validate({ type: "Date", required: false }, rawData.birthDate);
-            if (birthDate === undefined) {
-                return undefined;
-            } else {
-                const now = new Date();
-                const expectedAge = (now.getTime() - birthDate.getTime()) / 1000 / 60 / 60 / 24 / 365.25;
-                Schema.assert(Math.floor(expectedAge) === age);
-                return age;
-            }
-        }
-    },
-    birthDate: {
-        type: "Date",
-        required: false
-    }
+import { $ } from "@lucania/schema";
+
+const WeaponSchema = $.Object({
+    damage: $.Number(true).clamp(0, 100),
+    forged: $.Date(false),
+    affixtures: $.DynamicObject($.String())
 });
 
-const WeaponSchema = Schema.build({
-    damage: "number" /* ← Primitive */,
-    owners: ["string"] /* ← Array */,
-    forged: /* ← Meta ↓ */ {
-        type: "Date",
-        required: false
-    },
-    affixtures: /* ← Dynamic ↓ */ {
-        $: "string"
-    }
+const PersonSchema = $.Object({
+    name: $.Object({
+        first: $.String(true),
+        middle: $.String(false),
+        last: $.String(true)
+    }),
+    favoriteNumber: $.Number(true).ensure((data, pass) => data % 2 === 0, "Your favorite number must be a multiple of 2!"),
+    age: $.Number(true).min(16, "You must be at least 16 years old!").max(100, "You must be at most 100 years old!"),
+    weapon: WeaponSchema
 });
+
 ```
 
 ## Using Schema
@@ -95,25 +69,8 @@ With the schema definitions created, they can be used to validate data where the
 import fs from "fs";
 
 const personData = JSON.parse(fs.readFileSync("person.json", "utf8"));
-const person = Schema.validate(PersonSchema, personData);
-```
-`person` now has the following compile-time type annotation based on [`PersonSchema`](#creating-schema).
+const person = PersonSchema.validate(personData);
 ```
-const person: {
-    name: {
-        first: string;
-        last: string;
-    } & {
-        middle?: string | undefined;
-    };
-    favoriteNumber: number | bigint;
-}
-```
-At runtime, the object parsed from the `person.json` file will be validated to match this generated typing. If it does not match, a `Schema.ValidationError` will be thrown.
-
-## To-Do
+`person` now has the following compile-time type annotation based on [`PersonSchema`](#creating-hierarchical-schema).
 
- * Documentation:
-   * Extending _Primitive_ set.
-   * Defining a default value / function in Meta
-   * Defining a validator in Meta
+At runtime, the object parsed from the `person.json` file will be validated to match this generated typing. If it does not match, a `Schema.ValidationError` will be thrown.

package/build/builder.d.ts

@@ -0,0 +1,48 @@
+import { BaseSchemaAny } from "./typing/extended";
+import { DefaultValue, ModelValue, TypedMembers } from "./typing/toolbox";
+import { AnySchema } from "./schema/AnySchema";
+import { ArraySchema, ArraySource } from "./schema/ArraySchema";
+import { BooleanSchema, BooleanSource } from "./schema/BooleanSchema";
+import { DateSchema, DateSource } from "./schema/DateSchema";
+import { DynamicObjectSchema, DynamicObjectSource } from "./schema/DynamicObjectSchema";
+import { EnumerationSchema } from "./schema/EnumerationSchema";
+import { NumberSchema, NumberSource } from "./schema/NumberSchema";
+import { ObjectSchema, ObjectSource, ObjectSubschema } from "./schema/ObjectSchema";
+import { OrSetSchema, OrSetSchemaSource } from "./schema/OrSetSchema";
+import { StringSchema, StringSource } from "./schema/StringSchema";
+import { BaseSchema, SourceValue } from ".";
+export declare namespace Schema {
+    function String(): StringSchema<true, undefined>;
+    function String<Required extends boolean>(required: Required): StringSchema<Required, undefined>;
+    function String<Required extends boolean, Default extends DefaultValue<StringSource>>(required: Required, defaultValue: Default): StringSchema<Required, Default>;
+    function Number(): NumberSchema<true, undefined>;
+    function Number<Required extends boolean>(required: Required): NumberSchema<Required, undefined>;
+    function Number<Required extends boolean, Default extends DefaultValue<NumberSource>>(required: Required, defaultValue: Default): NumberSchema<Required, Default>;
+    function Boolean(): BooleanSchema<true, undefined>;
+    function Boolean<Required extends boolean>(required: Required): BooleanSchema<Required, undefined>;
+    function Boolean<Required extends boolean, Default extends DefaultValue<BooleanSource>>(required: Required, defaultValue: Default): BooleanSchema<Required, Default>;
+    function Date(): DateSchema<true, undefined>;
+    function Date<Required extends boolean>(required: Required): DateSchema<Required, undefined>;
+    function Date<Required extends boolean, Default extends DefaultValue<DateSource>>(required: Required, defaultValue: Default): DateSchema<Required, Default>;
+    function Any(): AnySchema<true, undefined>;
+    function Any<Required extends boolean>(required: Required): AnySchema<Required, undefined>;
+    function Any<Required extends boolean, Default extends DefaultValue<any>>(required: Required, defaultValue: Default): AnySchema<Required, Default>;
+    function Object<Subschema extends ObjectSubschema>(subschema: Subschema): ObjectSchema<Subschema, true, undefined>;
+    function Object<Subschema extends ObjectSubschema, Required extends boolean>(subschema: Subschema, required: Required): ObjectSchema<Subschema, Required, undefined>;
+    function Object<Subschema extends ObjectSubschema, Required extends boolean, Default extends DefaultValue<ObjectSource<Subschema>>>(subschema: Subschema, required: Required, defaultValue: Default): ObjectSchema<Subschema, Required, Default>;
+    function Array<Subschema extends BaseSchemaAny>(subschema: Subschema): ArraySchema<Subschema, true, undefined>;
+    function Array<Subschema extends BaseSchemaAny, Required extends boolean>(subschema: Subschema, required: Required): ArraySchema<Subschema, Required, undefined>;
+    function Array<Subschema extends BaseSchemaAny, Required extends boolean, Default extends DefaultValue<ArraySource<Subschema>>>(subschema: Subschema, required: Required, defaultValue: Default): ArraySchema<Subschema, Required, Default>;
+    function Enumeration<Members extends string[]>(subschema: TypedMembers<Members>): EnumerationSchema<Members, true, undefined>;
+    function Enumeration<Members extends string[], Required extends boolean>(subschema: TypedMembers<Members>, required: Required): EnumerationSchema<Members, Required, undefined>;
+    function Enumeration<Members extends string[], Required extends boolean, Default extends DefaultValue<Members[number]>>(subschema: TypedMembers<Members>, required: Required, defaultValue: Default): EnumerationSchema<Members, Required, Default>;
+    function DynamicObject<Subschema extends BaseSchemaAny>(subschema: Subschema): DynamicObjectSchema<Subschema, true, undefined>;
+    function DynamicObject<Subschema extends BaseSchemaAny, Required extends boolean>(subschema: Subschema, required: Required): DynamicObjectSchema<Subschema, Required, undefined>;
+    function DynamicObject<Subschema extends BaseSchemaAny, Required extends boolean, Default extends DefaultValue<DynamicObjectSource<Subschema>>>(subschema: Subschema, required: Required, defaultValue: Default): DynamicObjectSchema<Subschema, Required, Default>;
+    function OrSet<MemberSchemas extends BaseSchemaAny[]>(subschema: TypedMembers<MemberSchemas>): OrSetSchema<MemberSchemas, true, undefined>;
+    function OrSet<MemberSchemas extends BaseSchemaAny[], Required extends boolean>(subschema: TypedMembers<MemberSchemas>, required: Required): OrSetSchema<MemberSchemas, Required, undefined>;
+    function OrSet<MemberSchemas extends BaseSchemaAny[], Required extends boolean, Default extends DefaultValue<OrSetSchemaSource<MemberSchemas>>>(subschema: TypedMembers<MemberSchemas>, required: Required, defaultValue: Default): OrSetSchema<MemberSchemas, Required, Default>;
+    function Members<Members extends any[]>(...members: Members): TypedMembers<Members>;
+    type Model<Schema extends BaseSchemaAny> = Schema extends BaseSchema<infer Source, infer Model, infer Require, infer Default> ? (ModelValue<Source, Model, Require, Default>) : never;
+    type Source<Schema extends BaseSchemaAny> = Schema extends BaseSchema<infer Source, any, infer Require, infer Default> ? (SourceValue<Source, Require, Default>) : never;
+}

package/build/error/ValidationError.d.ts

@@ -0,0 +1,5 @@
+import { ValidationPass } from "./ValidationPass";
+export declare class ValidationError extends Error {
+    readonly pass: ValidationPass;
+    constructor(pass: ValidationPass, message: string);
+}

package/build/error/ValidationPass.d.ts

@@ -0,0 +1,17 @@
+import { DefaultValue, SourceValue } from "../typing/toolbox";
+import { BaseSchemaAny } from "../typing/extended";
+import { ValidationError } from "./ValidationError";
+export declare class ValidationPass {
+    readonly originalSchema: BaseSchemaAny;
+    readonly originalSource: SourceValue<any, boolean, DefaultValue<any>>;
+    private _path;
+    private _schema;
+    private _source;
+    constructor(originalSchema: BaseSchemaAny, originalSource: SourceValue<any, boolean, DefaultValue<any>>);
+    get path(): string[];
+    get schema(): BaseSchemaAny;
+    get source(): any;
+    next(path: string[], schema: BaseSchemaAny, source: SourceValue<any, boolean, DefaultValue<any>>): ValidationPass;
+    assert(condition: boolean, message: string): void;
+    getError(message?: string): ValidationError;
+}

package/build/index.d.ts

@@ -1,100 +1,17 @@
-export declare namespace Schema {
-    interface Map {
-        undefined: undefined;
-        boolean: boolean;
-        number: number;
-        bigint: bigint;
-        string: string;
-        symbol: symbol;
-        any: any;
-        Date: Date;
-    }
-    type Converter<From, To> = (from: From) => To;
-    interface ConversionMap {
-        boolean: [number, bigint, string];
-        number: [boolean, bigint, string, Date];
-        bigint: [number, string];
-        string: [boolean, number, bigint, any, Date];
-        any: [string];
-        Date: [number, bigint, string];
-    }
-    type Primitive = keyof Map;
-    type OrCompound = [Any, "or", Any];
-    type AndCompound = [Any, "and", Any];
-    type Dynamic = {
-        $: Any;
-    };
-    type Array = [Any];
-    type Hierarchy = {
-        [Key: string]: Any;
-    };
-    type Most = Primitive | OrCompound | AndCompound | Dynamic | Array | Hierarchy;
-    type TypedMeta<Schema extends Most> = {
-        type: Schema;
-        required: boolean;
-        validate?: Validator<Model<Schema>>;
-        default?: Model<Schema> | (() => Model<Schema>);
-    };
-    type Meta = TypedMeta<Most>;
-    type Any = Primitive | OrCompound | AndCompound | Meta | Dynamic | Array | Hierarchy;
-    type Validator<Type> = (value: Type, data: any) => Type;
-    type Merge<ObjectA, ObjectB> = (keyof ObjectA extends never ? ObjectB : keyof ObjectB extends never ? ObjectA : ObjectA & ObjectB);
-    type Model<Schema extends Schema.Any> = (Schema.Any extends Schema ? unknown : Schema extends Primitive ? Map[Schema] : Schema extends OrCompound ? Model<Schema[0]> | Model<Schema[2]> : Schema extends AndCompound ? Model<Schema[0]> & Model<Schema[2]> : Schema extends Meta ? (Schema extends TypedMeta<infer MetaType> ? (Schema.Most extends MetaType ? unknown : Schema["required"] extends false ? Model<MetaType> | undefined : Model<MetaType>) : never) : Schema extends Dynamic ? {
-        [Key: string]: Model<Schema["$"]>;
-    } : Schema extends Array ? Model<Schema[0]>[] : Schema extends Hierarchy ? Merge<{
-        [Key in keyof Schema as Existent<Schema[Key]> extends true ? Key : never]: Model<Schema[Key]>;
-    }, {
-        [Key in keyof Schema as Existent<Schema[Key]> extends true ? never : Key]?: Model<Schema[Key]>;
-    }> : any);
-    type Source<Schema extends Schema.Any> = (Schema.Any extends Schema ? unknown : Schema extends Primitive ? Converted<Schema> : Schema extends OrCompound ? Source<Schema[0]> | Source<Schema[2]> : Schema extends AndCompound ? Source<Schema[0]> & Source<Schema[2]> : Schema extends Meta ? Source<Schema["type"]> : Schema extends Dynamic ? {
-        [Key: string]: Source<Schema["$"]>;
-    } : Schema extends Array ? Source<Schema[0]>[] : Schema extends Hierarchy ? Merge<{
-        [Key in keyof Schema as Optionality<Schema[Key]> extends true ? never : Key]: Source<Schema[Key]>;
-    }, {
-        [Key in keyof Schema as Optionality<Schema[Key]> extends true ? Key : never]?: Source<Schema[Key]>;
-    }> : any);
-    type Converted<Schema extends Schema.Primitive> = (Schema extends keyof ConversionMap ? ConversionMap[Schema][number] | Map[Schema] : Map[Schema]);
-    type Existent<Schema extends Schema.Any> = (Schema.Any extends Schema ? unknown : Schema extends Schema.Meta ? (Schema["required"] extends true ? true : (Schema extends {
-        default: any;
-    } ? true : false)) : Schema extends Schema.Array ? Existent<Schema[0]> : true);
-    type Optionality<Schema extends Schema.Any> = (Schema.Any extends Schema ? unknown : Schema extends Schema.Meta ? (Schema["required"] extends true ? (Schema extends {
-        default: any;
-    } ? true : false) : true) : Schema extends Schema.Array ? Optionality<Schema[0]> : false);
-    function registerConverter<FromTypeName extends keyof ConversionMap, ToTypeName extends keyof Map>(fromTypeName: FromTypeName, toTypeName: ToTypeName, converter: Converter<Map[FromTypeName], Map[ToTypeName]>): void;
-    function registerPrimitive<TypeName extends keyof Map>(typeName: TypeName): void;
-    function isSchemaPrimitive(value: any): value is Schema.Primitive;
-    function isSchemaOrCompound(value: any): value is Schema.OrCompound;
-    function isSchemaAndCompound(value: any): value is Schema.AndCompound;
-    function isSchemaMeta(value: any): value is Schema.Meta;
-    function isSchemaDynamic(value: any): value is Schema.Dynamic;
-    function isSchemaArray(value: any): value is Schema.Array;
-    function isSchemaHierarchy(value: any): value is Schema.Hierarchy;
-    function isSchema(value: any): value is Schema.Any;
-    function getType(value: any): string;
-    function build<Schema extends Schema.Any>(schema: Schema): Schema;
-    function validate<Schema extends Any>(schema: Schema, source: Source<Schema>): Model<Schema>;
-    function clone<Schema extends Schema.Any>(schema: Schema): Schema;
-    function assert(condition: boolean, message?: string): asserts condition;
-    type ValidationErrorType = "missing" | "incorrectType" | "invalidSchema" | "failedCustomValidator";
-    class Error extends globalThis.Error {
-        constructor(message?: string);
-    }
-    class ValidationError extends Error {
-        readonly type: ValidationErrorType;
-        readonly source: any;
-        readonly schema: Schema.Any;
-        readonly originalSource: any;
-        readonly originalSchema: Schema.Any;
-        readonly path: string[];
-        readonly customMessage?: string;
-        /**
-         * @param message The error message.
-         * @param type The type of validation error.
-         * @param source The data that failed validation.
-         * @param path The path to the value that failed validation.
-         */
-        constructor(type: ValidationErrorType, schema: Schema.Any, source: any, path: string[], originalSchema: Schema.Any, originalSource: any, customMessage?: string);
-        static getExpectedString(schema: Schema.Any): string;
-        static getMessage(type: ValidationErrorType, source: any, schema: Schema.Any, path: string[]): string;
-    }
-}
+export * from "./builder";
+export { Schema as $ } from "./builder";
+export * from "./error/ValidationError";
+export * from "./error/ValidationPass";
+export * from "./schema/AnySchema";
+export * from "./schema/ArraySchema";
+export * from "./schema/BaseSchema";
+export * from "./schema/BooleanSchema";
+export * from "./schema/DateSchema";
+export * from "./schema/DynamicObjectSchema";
+export * from "./schema/EnumerationSchema";
+export * from "./schema/NumberSchema";
+export * from "./schema/ObjectSchema";
+export * from "./schema/OrSetSchema";
+export * from "./schema/StringSchema";
+export * from "./typing/extended";
+export * from "./typing/toolbox";