fix: helper better type support & insure primitives is required

Author: 5alidz

README.md

@@ -1,13 +1,13 @@
 # Tiny Schema Validator
 
+small, practical, and type-safe Schema validator.
+
 [![GitHub license](https://img.shields.io/github/license/5alidz/tiny-schema-validator)](https://github.com/5alidz/tiny-schema-validator/blob/master/LICENSE) ![Minzipped size](https://img.shields.io/bundlephobia/minzip/tiny-schema-validator.svg)
 
-- installation
-- usage
-- schema
-- validators
-- advanced usage
-- caveats
+## History
+
+This started as a side-project for me to learn about advanced TypeScript topics and was never intended to be an npm package,
+but I liked how it turned up and decided that it might be useful to use in my future projects.
 
 ## Installation
 
@@ -33,29 +33,18 @@ export const Person = createSchema({
 });
 ```
 
-and in TypeScript
+and in TypeScript everything is the same, but to get the data type inferred from the schema you can do this:
 
 ```ts
-import { createSchema, _ } from 'tiny-schema-validator';
-
-interface IPerson {
-  name: string;
-  age: number;
-  email: string;
-}
-
-export const Person = createSchema<IPerson>({
-  name: _.string({ maxLength: [100, 'too-long'], minLength: [2, 'too-short'] }),
-  age: _.number({ max: [150, 'too-old'], min: [13, 'too-young']}),
-  email: _.string({ pattern: [/^[^@]+@[^@]+\.[^@]+$/, 'invalid-email']});
-});
+//  PersonType { name: string; age: number; email: string; }
+export type PersonType = ReturnType<typeof Person.produce>;
 ```
 
 ## Schema
 
 When you create a schema, you will get a nice API to handle multiple use-cases in the client and the server.
 
-- `is(data: any): boolean` check if the data is valid
+- `is(data: any): boolean` check if the data is valid (eager evaluation)
 - `validate(data: any): Errors` errors returned has the same shape as the schema you defined (does not throw)
 - `produce(data: any): data` throws an error when the data is invalid. otherwise, it returns data
 - `embed(config?: { optional: boolean })` embeds the schema in other schemas
@@ -70,7 +59,7 @@ Person.is({ name: 'john', age: 42, email: '[email protected]' }); // true
 Person.validate({}); // { name: 'invalid-type', age: 'invalid-type', email: 'invalid-type' }
 Person.validate({ name: 'john', age: 42, email: '[email protected]' }); // null
 
-Person.produce(undefined); // throws an error with the same shape as the schema
+Person.produce(undefined); // throws { name: 'invalid-type' }
 
 // embedding the person schema
 const GroupOfPeople = createSchema({
@@ -127,26 +116,27 @@ Check out the full validators API below:
 
 ### Custom validators
 
-You can use validators from `_` as building blocks for your custom validator:
+To create custom validators that does not break type inference:
+
+- use validators from `_` as building blocks for your custom validator.
+- your custom validator should define an `optional` and `required` functions.
+
+Example of creating custom validators:
 
 ```js
-const alphaNumeric = validatorOpts =>
-  _.string({
+const alphaNumeric = (() => {
+  const config = {
     pattern: [/^[a-zA-Z0-9]*$/, 'only-letters-and-number'],
-    ...validatorOpts,
-  });
-
-const email = validatorOpts =>
-  _.string({
-    pattern: [/^[^@]+@[^@]+\.[^@]+$/, 'invalid-email'],
-    ...validatorOpts,
-  });
+  };
+  return {
+    required: additional => _.string({ ...additional, ...config, optional: false }), // inferred as Required
+    optional: additional => _.string({ ...additional, ...config, optional: true }), // inferred as Optional
+  };
+})();
 
 const Person = createSchema({
   // ...
-  username: alphaNumeric({ maxLength: [20, 'username-too-long'] }),
-  email: email(),
-  alt_email: email({ optional: true }),
+  username: alphaNumeric.required({ maxLength: [20, 'username-too-long'] }),
   // ...
 });
 ```
@@ -169,14 +159,16 @@ const User = createSchema({
 });
 
 const form_ui = User.traverse({
-  number(path, key) {
+  number({ path, key }) {
     if (path.includes('profile')) return { type: 'number', label: key };
     return null; // otherwise ignore
   },
-  string(path, key) {
+  string({ path, key }) {
     if (path.includes('profile')) return { type: 'text', label: key };
     return null; // otherwise ignore
   },
+  // this is required to get the type of "profile" correct
+  record: () => null,
 });
 
 console.log(form_ui); /* 
@@ -197,9 +189,7 @@ The return type of your visitor is important, and there are a few considerations
 Returning `null` from visitor signals to ignore this node from the result, with the exception:
 `record | recordof | list | listof`, returning `null` signals to continue down recursively.
 
-So to return something from `record` visitor you will need to visit its children recursively.
-
-_Note_: in most cases defining only the primitive visitors is enough.
+So to return something from `record` visitor for example, you will need to visit its children recursively.
 
 Continuing from the previous `User` Example
 
@@ -231,8 +221,8 @@ const customTraverse = (key, validator) => {
 };
 
 const form_ui = User.traverse({
-  record(path, key, recordValidator) {
-    return customTraverse(key, recordValidator);
+  record({ path, key, validator }) {
+    return customTraverse(key, validator);
   },
 });
 ```
@@ -252,3 +242,7 @@ _.list([_.number({ optional: true /* THIS IS IGNORED */ }), _.number()]);
 const list = createSchema({ list: _.listof(_.string()) });
 list.validate({ list: ['string', 42, 'string'] }); // { list: { 1: 'invalid-type' } }
 ```
+
+## Recursive types
+
+Currently there's no easy way to create recursive types, if you think you could help, PRs are welcome

src/helpers.ts

@@ -20,13 +20,11 @@ import {
 } from './validatorTypes';
 import { $boolean, $list, $listof, $number, $record, $recordof, $string } from './constants';
 
-export function string(config: { optional: true } & Omit<StringOptions, 'type'>): O<StringOptions>;
-export function string(config: { optional: false } & Omit<StringOptions, 'type'>): R<StringOptions>;
-export function string(
-  config: { optional?: boolean } & Omit<StringOptions, 'type'>
-): StringValidator;
-export function string(config: Omit<StringOptions, 'type'>): R<StringOptions>;
 export function string(): R<StringOptions>;
+export function string(config: Omit<StringOptions, 'type'>): R<StringOptions>;
+export function string(config: { optional: false } & Omit<StringOptions, 'type'>): R<StringOptions>;
+export function string(config: { optional: true } & Omit<StringOptions, 'type'>): O<StringOptions>;
+
 export function string(
   config?: { optional?: boolean } & Omit<StringOptions, 'type'>
 ): StringValidator {
@@ -37,13 +35,11 @@ export function string(
   };
 }
 
+export function number(): R<NumberOptions>;
+export function number(config: Omit<NumberOptions, 'type'>): R<NumberOptions>;
 export function number(config: { optional: true } & Omit<NumberOptions, 'type'>): O<NumberOptions>;
 export function number(config: { optional: false } & Omit<NumberOptions, 'type'>): R<NumberOptions>;
-export function number(
-  config: { optional?: boolean } & Omit<NumberOptions, 'type'>
-): NumberValidator;
-export function number(config: Omit<NumberOptions, 'type'>): R<NumberOptions>;
-export function number(): R<NumberOptions>;
+
 export function number(
   config?: { optional?: boolean } & Omit<NumberOptions, 'type'>
 ): NumberValidator {
@@ -54,46 +50,63 @@ export function number(
   };
 }
 
+export function boolean(): R<BooleanOptions>;
 export function boolean(config: { optional: true }): O<BooleanOptions>;
 export function boolean(config: { optional: false }): R<BooleanOptions>;
-export function boolean(): R<BooleanOptions>;
+
 export function boolean(config?: { optional: boolean }): BooleanValidator {
   return {
     type: $boolean,
     optional: !!config?.optional,
   };
 }
 
-export function list<T extends Validator[]>(list: T): R<ListOptions<T>>;
-export function list<T extends Validator[]>(
+export function list<T extends R<Validator>[]>(list: T): R<ListOptions<T>>;
+export function list<T extends R<Validator>[]>(
   list: T,
   config: { optional: false }
 ): R<ListOptions<T>>;
-export function list<T extends Validator[]>(list: T, config: { optional: true }): O<ListOptions<T>>;
-export function list<T extends Validator[]>(
+export function list<T extends R<Validator>[]>(
+  list: T,
+  config: { optional: true }
+): O<ListOptions<T>>;
+
+export function list<T extends R<Validator>[]>(
   list: T,
   config?: { optional: boolean }
 ): ListValidator<T> {
-  return { type: $list, optional: !!config?.optional, shape: list };
+  return {
+    type: $list,
+    optional: !!config?.optional,
+    shape: list.map(v => ({ ...v, optional: false })) as T,
+  };
 }
 
-export function listof<T extends Validator>(v: T): R<ListofOptions<T>>;
-export function listof<T extends Validator>(v: T, config: { optional: false }): R<ListofOptions<T>>;
-export function listof<T extends Validator>(v: T, config: { optional: true }): O<ListofOptions<T>>;
-export function listof<T extends Validator>(
+export function listof<T extends R<Validator>>(v: T): R<ListofOptions<T>>;
+export function listof<T extends R<Validator>>(
+  v: T,
+  config: { optional: false }
+): R<ListofOptions<T>>;
+export function listof<T extends R<Validator>>(
+  v: T,
+  config: { optional: true }
+): O<ListofOptions<T>>;
+
+export function listof<T extends R<Validator>>(
   v: T,
   config?: { optional: boolean }
 ): ListofValidator<T> {
   return {
     type: $listof,
     optional: !!config?.optional,
-    of: v,
+    of: { ...v, optional: false },
   };
 }
 
 export function record<T extends Schema>(s: T): R<RecordOptions<T>>;
 export function record<T extends Schema>(s: T, config: { optional: false }): R<RecordOptions<T>>;
 export function record<T extends Schema>(s: T, config: { optional: true }): O<RecordOptions<T>>;
+
 export function record<T extends Schema>(s: T, config?: { optional: boolean }): RecordValidator<T> {
   return {
     type: $record,
@@ -102,22 +115,23 @@ export function record<T extends Schema>(s: T, config?: { optional: boolean }):
   };
 }
 
-export function recordof<T extends Validator>(v: T): R<RecordofOptions<T>>;
-export function recordof<T extends Validator>(
+export function recordof<T extends R<Validator>>(v: T): R<RecordofOptions<T>>;
+export function recordof<T extends R<Validator>>(
   v: T,
   config: { optional: false }
 ): R<RecordofOptions<T>>;
-export function recordof<T extends Validator>(
+export function recordof<T extends R<Validator>>(
   v: T,
   config: { optional: true }
 ): O<RecordofOptions<T>>;
-export function recordof<T extends Validator>(
+
+export function recordof<T extends R<Validator>>(
   v: T,
   config?: { optional: boolean }
 ): RecordofValidator<T> {
   return {
     type: $recordof,
-    of: v,
+    of: { ...v, optional: false },
     optional: !!config?.optional,
   };
 }

test/index.test.ts

@@ -14,7 +14,10 @@ describe('createSchema throws when', () => {
 
 describe('eager validation', () => {
   const s = createSchema({
-    a: _.record({ b: _.string(), c: _.record({ d: _.number(), e: _.number() }) }),
+    a: _.record({
+      b: _.string({ optional: true }),
+      c: _.record({ d: _.number(), e: _.number({ optional: true }) }),
+    }),
   });
 
   test('test 1', () => {

test/traverse.test.ts

@@ -8,6 +8,28 @@ describe('traverse', () => {
     profile: _.record({ username: _.string(), email: _.string(), age: _.number() }),
   });
 
+  test('basic test', () => {
+    const form_ui = Person.traverse({
+      number({ path, key }) {
+        if (path.includes('profile')) return { type: 'number', label: key };
+        return null; // otherwise ignore
+      },
+      string({ path, key }) {
+        if (path.includes('profile')) return { type: 'text', label: key };
+        return null; // otherwise ignore
+      },
+      record: () => null,
+    });
+
+    expect(form_ui).toStrictEqual({
+      profile: {
+        username: { type: 'text', label: 'username' },
+        email: { type: 'text', label: 'email' },
+        age: { type: 'number', label: 'age' },
+      },
+    });
+  });
+
   test('custom traverse 1', () => {
     const customTraverse = (key: string, validator: Validator) => {
       if (validator.type == 'string') {
@@ -79,27 +101,7 @@ describe('traverse', () => {
     });
   });
 
-  test('readme example 2', () => {
-    const profileFormInputsData = Person.traverse({
-      number({ path, key }) {
-        if (path.includes('profile')) return { type: 'number', label: key };
-        return null; // otherwise ignore
-      },
-      string({ path, key }) {
-        if (path.includes('profile')) return { type: 'text', label: key };
-        return null; // otherwise ignore
-      },
-      record() {
-        return 'ignore children';
-      },
-    });
-
-    expect(profileFormInputsData).toStrictEqual({
-      profile: 'ignore children',
-    });
-  });
-
-  test('readme example', () => {
+  test('defining only primitive visitor', () => {
     const profileFormInputsData = Person.traverse({
       number({ path, key }) {
         if (path.includes('profile')) return { type: 'number', label: key };