refactor: update readme & enhanced type informations

Author: 5alidz

README.md

@@ -53,12 +53,12 @@ export const Person = createSchema<IPerson>({
 
 ## Schema
 
-When you create a schema you will get a nice API to handle multiple use-cases in the client and the server.
+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 wether data is valid
+- `is(data: any): boolean` check if the data is valid
 - `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 data has errors otherwise returns data
-- `embed(config?: { optiona: boolean })` embeds the schema in other schemas
+- `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
 - `traverse(visitor, data?, eager?)` (advanced) see usage below.
 
 Continuing from the previous example:
@@ -70,7 +70,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 error with the same shape as the schema
+Person.produce(undefined); // throws an error with the same shape as the schema
 
 // embedding the person schema
 const GroupOfPeople = createSchema({
@@ -125,14 +125,40 @@ Check out the full validators API below:
 |           |                                 | options(optional): Object                                    |
 |           |                                 | - `optional` boolean default to false                        |
 
+### Custom validators
+
+You can use validators from `_` as building blocks for your custom validator:
+
+```js
+const alphaNumeric = validatorOpts =>
+  _.string({
+    pattern: [/^[a-zA-Z0-9]*$/, 'only-letters-and-number'],
+    ...validatorOpts,
+  });
+
+const email = validatorOpts =>
+  _.string({
+    pattern: [/^[^@]+@[^@]+\.[^@]+$/, 'invalid-email'],
+    ...validatorOpts,
+  });
+
+const Person = createSchema({
+  // ...
+  username: alphaNumeric({ maxLength: [20, 'username-too-long'] }),
+  email: email(),
+  alt_email: email({ optional: true }),
+  // ...
+});
+```
+
 ## Advanced usage
 
-In addition to validating data, you can also reuse your schema in other areas, like creating forms and TypeScript types.
+In addition to validating data, you can also reuse your schema in other areas, like creating forms UI for example,
 `traverse` function come-in handy to help you achieve that.
 
 ### Example
 
-In this example we will transform a schema to create meta-data to be used to create form UI elements.
+In this example, we will transform a schema to create meta-data to be used to create form UI elements.
 
 ```js
 const User = createSchema({
@@ -166,14 +192,14 @@ console.log(form_ui); /*
 
 ### How to traverse
 
-The return type of your visitor is important, and there is some few considerations:
+The return type of your visitor is important, and there are a few considerations:
 
-Returning `null` from a visitor signals to ignore this node from the end result, with the exception of:
+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.
 
-This means, to return something from `record` visitor you will need to visit its children 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, otherwise look at the next example.
+_Note_: in most cases defining only the primitive visitors is enough.
 
 Continuing from the previous `User` Example
 
@@ -183,30 +209,25 @@ Say We need this structure:
 {
   profile: {
     type: 'container',
-    children: {
-      username: { type: 'text', label: 'username' },
-      email: { type: 'text', label: 'email' },
-      age: { type: 'number', label: 'age' }
-    }
+    children: [
+      { type: 'text', label: 'username' },
+      { type: 'text', label: 'email' },
+      { type: 'number', label: 'age' }
+    ]
   }
 }
 */
-const customTraverse = (key: string, validator: Validator) => {
+const customTraverse = (key, validator) => {
   const type = validator.type;
 
-  if (type == 'string') {
-    return { type: key == 'email' ? key : 'text', label: key };
-  } else if (type == 'number') {
-    return { type: 'number', label: key };
-  } else if (type == 'record') {
-    const children = Object.entries(validator.shape).reduce((acc, [shapeKey, shapeValidator]) => {
-      acc[shapeKey] = customTraverse(shapeKey, shapeValidator); // visit children
-      return acc;
-    }, {});
-    return { type: 'container', children };
-  } else {
-    return null;
-  }
+  if (type == 'string') return { type: key == 'email' ? key : 'text', label: key };
+  if (type == 'number') return { type: 'number', label: key };
+  if (type == 'record')
+    return {
+      type: 'container',
+      children: Object.entries(validator.shape).map(entry => customTraverse(...entry)),
+    };
+  return null;
 };
 
 const form_ui = User.traverse({

src/helpers.ts

@@ -25,44 +25,54 @@ const optional = (v?: boolean) => (typeof v == 'boolean' ? v : false);
 
 const base = <T extends Helpers>(type: T, optional: boolean) => ({ type, optional });
 
-export function string(opts?: Partial<WithoutType<StringValidator>>): StringValidator {
+export type StringOptions = Partial<WithoutType<StringValidator>>;
+export type NumberOptions = Partial<WithoutType<NumberValidator>>;
+export type BooleanOptions = Partial<WithoutType<BooleanValidator>>;
+export type ListOptions = { optional?: boolean };
+export type ListofOptions = { optional?: boolean };
+export type RecordOptions = { optional?: boolean };
+export type RecordofOptions = { optional?: boolean };
+
+export function string(opts?: StringOptions): StringValidator {
   return {
     ...opts,
     ...base($string, optional(opts?.optional)),
   };
 }
 
-export function boolean(opts?: Partial<WithoutType<BooleanValidator>>): BooleanValidator {
+export function boolean(opts?: BooleanOptions): BooleanValidator {
   return base($boolean, optional(opts?.optional));
 }
-export function number(opts?: Partial<WithoutType<NumberValidator>>): NumberValidator {
+
+export function number(opts?: NumberOptions): NumberValidator {
   return {
     ...opts,
     ...base($number, optional(opts?.optional)),
   };
 }
-export function list(shape: Validator[], opts?: { optional?: boolean }): ListValidator {
+
+export function list<V extends Validator>(shape: V[], opts?: ListOptions): ListValidator {
   return {
     ...base($list, optional(opts?.optional)),
     shape,
   };
 }
-export function listof(of: Validator, opts?: { optional?: boolean }): ListofValidator {
+
+export function listof(of: Validator, opts?: ListofOptions): ListofValidator {
   return {
     ...base($listof, optional(opts?.optional)),
     of,
   };
 }
-export function record(
-  shape: { [key: string]: Validator },
-  opts?: { optional?: boolean }
-): RecordValidator {
+
+export function record(shape: { [key: string]: Validator }, opts?: RecordOptions): RecordValidator {
   return {
     ...base($record, optional(opts?.optional)),
     shape,
   };
 }
-export function recordof(of: Validator, opts?: { optional?: boolean }): RecordofValidator {
+
+export function recordof(of: Validator, opts?: RecordofOptions): RecordofValidator {
   return {
     ...base($recordof, optional(opts?.optional)),
     of,

src/traverse.ts

@@ -35,7 +35,7 @@ type IVisitor<T> = (
   key: string,
   v: T,
   value: any
-) => string | null | Record<string, any>;
+) => string | null | any[] | Record<string, any>;
 
 export interface Visitor {
   string?: IVisitor<StringValidator>;
@@ -108,14 +108,22 @@ function enter(
   return ObjectKeys(result).length > 0 ? result : null;
 }
 
+type Schema = { [key: string]: Validator };
+type SchemaFrom<T> = {
+  [K in keyof T]: Validator;
+};
+type FromTraverse<S extends Schema> = {
+  [K in keyof S]: ReturnType<VisitorFunction>;
+};
+
 export function traverse<T>(
-  schema: { [K in keyof T]: Validator },
+  schema: SchemaFrom<T>,
   visitor: Visitor,
   data: T,
   eager = false
-) {
+): Partial<FromTraverse<SchemaFrom<T>>> {
   const schemaKeys = ObjectKeys(schema) as (keyof T)[];
-  const parent = {} as Record<keyof T, any>;
+  const parent = {} as Partial<FromTraverse<SchemaFrom<T>>>;
   for (let i = 0; i < schemaKeys.length; i++) {
     const schemaKey = schemaKeys[i];
     const validator = schema[schemaKey];

src/validatorTypes.ts

@@ -9,7 +9,6 @@ interface StringOptions {
   minLength?: [number, string];
   maxLength?: [number, string];
   pattern?: [RegExp, string];
-  oneOf?: string[];
 }
 
 interface NumberOptions {