@lucania/schema 2.0.0 → 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/schema/ObjectSchema.d.ts

@@ -1,4 +1,4 @@
-import type { DefaultValue, Merge, ModelValue, SourceRequirement, SourceValue } from "../typing/toolbox";
+import type { DefaultValue, Merge, ModelRequirement, ModelValue, SourceRequirement, SourceValue } from "../typing/toolbox";
 import { ValidationPass } from "../error/ValidationPass";
 import { BaseSchemaAny } from "../typing/extended";
 import { BaseSchema } from "./BaseSchema";
@@ -10,9 +10,11 @@ export type ObjectSource<Subschema extends ObjectSubschema> = (Merge<{
 }, {
     [Key in keyof Subschema as SourceRequirement<Subschema[Key]> extends false ? Key : never]?: (Subschema[Key] extends BaseSchema<infer Source, any, infer Required, infer Default> ? (SourceValue<Source, Required, Default>) : never);
 }>);
-export type ObjectModel<Subschema extends ObjectSubschema> = {
-    [Key in keyof Subschema]: Subschema[Key] extends BaseSchema<infer Source, infer Model, infer Required, infer Default> ? (ModelValue<Source, Model, Required, Default>) : never;
-};
+export type ObjectModel<Subschema extends ObjectSubschema> = (Merge<{
+    [Key in keyof Subschema as ModelRequirement<Subschema[Key]> extends true ? Key : never]: (Subschema[Key] extends BaseSchema<infer Source, infer Model, infer Required, infer Default> ? (ModelValue<Source, Model, Required, Default>) : never);
+}, {
+    [Key in keyof Subschema as ModelRequirement<Subschema[Key]> extends false ? Key : never]?: (Subschema[Key] extends BaseSchema<infer Source, infer Model, infer Required, infer Default> ? (ModelValue<Source, Model, Required, Default>) : never);
+}>);
 export declare class ObjectSchema<Subschema extends ObjectSubschema, Required extends boolean, Default extends DefaultValue<ObjectSource<Subschema>>> extends BaseSchema<ObjectSource<Subschema>, ObjectModel<Subschema>, Required, Default> {
     readonly subschema: Subschema;
     constructor(subschema: Subschema, required: Required, defaultValue: Default);

package/build/typing/toolbox.d.ts

@@ -3,6 +3,7 @@ import { BaseSchema } from "../schema/BaseSchema";
 import { BaseSchemaAny } from "./extended";
 export type SourceRequirement<Layout extends BaseSchemaAny> = (Layout extends BaseSchema<any, any, infer Required, infer Default> ? (Required extends true ? (Default extends undefined ? true : false) : (false)) : never);
 export type SourceValue<Source, Required extends boolean, Default extends DefaultValue<Source>> = (Required extends true ? (undefined extends Default ? (Source) : (Source | undefined)) : Source | undefined);
+export type ModelRequirement<Layout extends BaseSchemaAny> = (Layout extends BaseSchema<any, any, infer Required, infer Default> ? (Required extends true ? (true) : (Default extends undefined ? false : true)) : never);
 export type ModelValue<Source, Model, Required extends boolean, Default extends DefaultValue<Source>> = (Required extends true ? Model : Default extends undefined ? Model | undefined : Model);
 export type DefaultValue<Type> = undefined | Type | ((pass: ValidationPass) => Type);
 export type TypedMembers<Members> = {
@@ -21,6 +22,9 @@ export type AdditionalValidatorAfterType = ("beforeConversion" | "afterConversio
  */
 export type AdditionalValidatorType = AdditionalValidatorBeforeType | AdditionalValidatorAfterType;
 export type AdditionalValidator<Type> = (data: Type, pass: ValidationPass) => Type;
+/**
+ * Represents a pass to ensure that your data meets a condition. Return true if your data is ensured to meet condition, false otherwise.
+ */
 export type EnsureValidator<Type> = (data: Type, pass: ValidationPass) => boolean;
 export type AdditionalValidationPasses<Source, Model> = {
     beforeAll: AdditionalValidator<Source>[];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lucania/schema",
-    "version": "2.0.0",
+    "version": "2.0.1",
     "description": "A schema module for compile-time and runtime type checking.",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -37,4 +37,4 @@
         "tslib": "^2.6.2",
         "typescript": "^5.3.3"
     }
-}
+}