@cleverbrush/schema 1.0.0-beta.5 → 1.1.0

package/dist/builders/ObjectSchemaBuilder.d.ts

@@ -1,83 +1,312 @@
-import { ISchemaBuilder, SchemaBuilder } from './SchemaBuilder.js';
-import { Schema, Validator, InferType, MakeOptional, MakeRequired, MakeNullable, MakeNotNullable } from '../schema.js';
-export interface IObjectSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TNoUnknownProperties extends boolean = true, TProperties = {}, TMapToType = undefined> extends ISchemaBuilder<TRequired, TNullable> {
-    optional(): IObjectSchemaBuilder<false, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    required(): IObjectSchemaBuilder<true, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    nullable(): IObjectSchemaBuilder<TRequired, true, TNoUnknownProperties, TProperties, TMapToType>;
-    notNullable(): IObjectSchemaBuilder<TRequired, false, TNoUnknownProperties, TProperties, TMapToType>;
-    addProps<T extends Record<string, any>>(val?: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties & T, TMapToType>;
-    removeProp<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T>, TMapToType>;
-    canHaveUnknownProps(): IObjectSchemaBuilder<TRequired, TNullable, false, TProperties, TMapToType>;
-    noUnknownProps(): IObjectSchemaBuilder<TRequired, TNullable, true, TProperties, TMapToType>;
-    setPropPreprocessor<T extends keyof TProperties | '*', S = T extends keyof TProperties ? ((value: any) => undefined | InferType<TProperties[T]> | Promise<InferType<TProperties[T]>>) | string : (value: InferType<this>) => void | Promise<void>>(property: T, validator: S): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    unsetPropPreprocessor<T extends keyof TProperties | '*'>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    clearPropsPreprocessors(): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    makeAllPropsOptional<T extends keyof TProperties>(): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, {
-        [k in T]: MakeOptional<TProperties[k]>;
-    }, TMapToType>;
-    makePropOptional<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T> & {
-        [k in T]: MakeOptional<TProperties[k]>;
-    }, TMapToType>;
-    makePropRequired<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T> & {
-        [k in T]: MakeRequired<TProperties[k]>;
-    }, TMapToType>;
-    makePropNullable<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T> & {
-        [k in T]: MakeNullable<TProperties[k]>;
-    }, TMapToType>;
-    makePropNotNullable<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T> & {
-        [k in T]: MakeNotNullable<TProperties[k]>;
-    }, TMapToType>;
-    mapToType<T>(): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, T>;
-    clearMapToType(): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, undefined>;
-}
-export declare class ObjectSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TNoUnknownProperties extends boolean = true, TProperties = {}, TMapToType = undefined> extends SchemaBuilder<TRequired, TNullable> implements IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, TMapToType> {
-    protected readonly type = "object";
-    protected noUnknownProperties?: TNoUnknownProperties;
-    protected properties?: TProperties;
-    protected preprocessors?: {
-        [S in keyof TProperties | '*']?: S extends keyof TProperties ? ((value: any) => undefined | InferType<TProperties[S]> | Promise<InferType<TProperties[S]>>) | string : (value: InferType<TProperties>) => void | Promise<void>;
-    };
-    clone(): this;
-    get _schema(): Schema;
+import { InferType, SchemaBuilder, ValidationContext, ValidationResult } from './SchemaBuilder.js';
+type ObjectSchemaBuilderProps<T extends Record<string, SchemaBuilder> = {}, TRequired extends boolean = true> = ReturnType<ObjectSchemaBuilder<T, TRequired>['introspect']>;
+type ObjectSchemaBuilderCreateProps<T extends Record<string, SchemaBuilder> = {}, TRequired extends boolean = true> = Partial<ObjectSchemaBuilderProps<T, TRequired>>;
+type Id<T> = T extends infer U ? {
+    [K in keyof U]: U[K];
+} : never;
+export type RespectPropsOptionality<T extends Record<string, SchemaBuilder<any, any>>> = {
+    [K in RequiredProps<T>]: InferType<T[K]>;
+} & {
+    [K in NotRequiredProps<T>]?: InferType<T[K]>;
+};
+type MakeChildrenRequired<T extends Record<string, SchemaBuilder<any, any>>> = {
+    [K in keyof T]: ReturnType<T[K]['required']>;
+};
+type MakeChildrenOptional<T extends Record<string, SchemaBuilder<any, any>>> = {
+    [K in keyof T]: ReturnType<T[K]['optional']>;
+};
+type MakeChildOptional<T extends Record<any, SchemaBuilder<any, any>>, TProp extends keyof T> = {
+    [K in keyof T]: K extends TProp ? ReturnType<T[K]['optional']> : T[K];
+};
+type MakeChildRequired<T extends Record<any, SchemaBuilder<any, any>>, TProp extends keyof T> = {
+    [K in keyof T]: K extends TProp ? ReturnType<T[K]['required']> : T[K];
+};
+type ModifyPropSchema<T extends Record<any, SchemaBuilder<any, any>>, TProp extends keyof T, TSchema extends SchemaBuilder<any, any>> = {
+    [K in keyof T]: K extends TProp ? TSchema : T[K];
+};
+/**
+ * Object schema builder class. Similar to the `object` type
+ * in JS. Allows to define a schema for `object` value.
+ * Should be used to validate objects with specific properties.
+ * Properties should be defined as their own schema builders.
+ * You can use any `SchemaBuilder` e.g. `string()`, `number()`,
+ * `boolean()`, `array()`, `object()`, etc. to define properties.
+ * Which means that you can define nested objects and arrays of
+ * any complexity.
+ *
+ * **NOTE** this class is exported only to give opportunity to extend it
+ * by inheriting. It is not recommended to create an instance of this class
+ * directly. Use {@link object | object()} function instead.
+ *
+ * @example
+ * ```ts
+ * const schema = object({
+ *    name: string(),
+ *    age: number()
+ * });
+ *
+ * const result = await schema.validate({
+ *   name: 'John',
+ *   age: 30
+ * });
+ *
+ * // result.valid === true
+ * // result.object === { name: 'John', age: 30 }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const schema = object({
+ *   name: string(),
+ *   age: number().optional()
+ * });
+ *
+ * const result = await schema.validate({
+ *  name: 'John'
+ * });
+ * // result.valid === true
+ * // result.object === { name: 'John' }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const schema = object({
+ *  name: string(),
+ *  age: number();
+ * });
+ * const result = await schema.validate({
+ *  name: 'John'
+ * });
+ *
+ * // result.valid === false
+ * // result.errors[0].message === "is expected to have property 'age'"
+ * ```
+ *
+ * @example
+ * ```ts
+ * const schema = object({
+ * name: string(),
+ * address: object({
+ *     city: string(),
+ *     country: string()
+ *   })
+ * });
+ * const result = await schema.validate({
+ * name: 'John',
+ * address: {
+ *    city: 'New York',
+ *    country: 'USA'
+ *  }
+ * });
+ * // result.valid === true
+ * // result.object === {
+ * //   name: 'John',
+ * //   address: {
+ * //     city: 'New York',
+ * //     country: 'USA'
+ * //   }
+ * // }
+ * ```
+ * @see {@link object}
+ */
+export declare class ObjectSchemaBuilder<TProperties extends Record<string, SchemaBuilder<any, any>> = {}, TRequired extends boolean = true, TExplicitType = undefined> extends SchemaBuilder<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType, TRequired> {
+    #private;
+    static create<P extends Record<string, SchemaBuilder>, R extends boolean>(props: ObjectSchemaBuilderCreateProps<P, R>): ObjectSchemaBuilder<{}, true, undefined>;
+    protected createFromProps<T extends Record<string, SchemaBuilder>, R extends boolean = true>(props: ObjectSchemaBuilderCreateProps<T, R>): this;
     private constructor();
-    static create<TCRequired extends boolean = true, TCNullable extends boolean = false, TCNoUnknownProperties extends boolean = false, TCProperties = {}, TMapToType = undefined>(obj?: {
-        isRequired: TCRequired;
-        isNullable: TCNullable;
-        properties: TCProperties;
-        noUnknownProperties: TCNoUnknownProperties;
-        validators?: Validator[];
-        preprocessor?: ((value: unknown) => unknown | Promise<unknown>) | string;
-        preprocessors?: {
-            [S in keyof TCProperties | '*']?: S extends keyof TCProperties ? ((value: any) => undefined | InferType<TCProperties[S]> | Promise<InferType<TCProperties[S]>>) | string : (value: InferType<TCProperties>) => void | Promise<void>;
-        };
-    }): IObjectSchemaBuilder<TCRequired, TCNullable, TCNoUnknownProperties, TCProperties, TMapToType>;
-    canHaveUnknownProps(): IObjectSchemaBuilder<TRequired, TNullable, false, TProperties, TMapToType>;
-    noUnknownProps(): IObjectSchemaBuilder<TRequired, TNullable, true, TProperties, TMapToType>;
-    optional(): IObjectSchemaBuilder<false, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    required(): IObjectSchemaBuilder<true, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    nullable(): IObjectSchemaBuilder<TRequired, true, TNoUnknownProperties, TProperties, TMapToType>;
-    notNullable(): IObjectSchemaBuilder<TRequired, false, TNoUnknownProperties, TProperties, TMapToType>;
-    addProps<T extends Record<string, any>>(val?: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties & T, TMapToType>;
-    removeProp<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T>, TMapToType>;
-    setPropPreprocessor<T extends keyof TProperties | '*', S = T extends keyof TProperties ? ((value: any) => undefined | InferType<TProperties[T]> | Promise<InferType<TProperties[T]>>) | string : (value: InferType<T>) => void | Promise<void>>(property: T, validator: S): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    unsetPropPreprocessor<T extends keyof TProperties | '*'>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    clearPropsPreprocessors(): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, TMapToType>;
-    mapToType<T>(): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, T>;
-    clearMapToType(): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, TProperties, undefined>;
-    makeAllPropsOptional<T extends keyof TProperties>(): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, {
-        [k in T]: MakeOptional<TProperties[k]>;
-    }, TMapToType>;
-    makePropOptional<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T> & {
-        [k in T]: MakeOptional<TProperties[k]>;
-    }, TMapToType>;
-    makePropRequired<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T> & {
-        [k in T]: MakeRequired<TProperties[k]>;
-    }, TMapToType>;
-    makePropNullable<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T> & {
-        [k in T]: MakeNullable<TProperties[k]>;
-    }, TMapToType>;
-    makePropNotNullable<T extends keyof TProperties>(property: T): IObjectSchemaBuilder<TRequired, TNullable, TNoUnknownProperties, Omit<TProperties, T> & {
-        [k in T]: MakeNotNullable<TProperties[k]>;
-    }, TMapToType>;
+    introspect(): {
+        /**
+         * Properties defined in schema
+         */
+        properties: TProperties;
+        /**
+         * If set to `true`, schema validation will not
+         * return errors if object contains fields which
+         * are not defined in the schema `properties`.
+         * Set to `false` by default
+         */
+        acceptUnknownProps: boolean;
+        type: string;
+        isRequired: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").Preprocessor<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType>[];
+        validators: readonly import("./SchemaBuilder.js").Validator<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType>[];
+    };
+    /**
+     * @hidden
+     */
+    required(): ObjectSchemaBuilder<TProperties, true, TExplicitType>;
+    /**
+     * @hidden
+     */
+    optional(): ObjectSchemaBuilder<TProperties, false, TExplicitType>;
+    /**
+     * Performs validion of object schema over the `object`.
+     * @param context Optional `ValidationContext` settings.
+     */
+    validate(object: undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType, context?: ValidationContext): Promise<ValidationResult<undefined extends TExplicitType ? RespectPropsOptionality<TProperties> : TExplicitType>>;
+    /**
+     * Fields not defined in `properties` will not be validated
+     * and will be passed through the validation.
+     */
+    acceptUnknownProps(): ObjectSchemaBuilder<TProperties, TRequired, TExplicitType>;
+    /**
+     * Fields not defined in `properties` will be considered
+     * as schema violation. This is the default behavior.
+     */
+    notAcceptUnknownProps(): ObjectSchemaBuilder<TProperties, TRequired, TExplicitType>;
+    /**
+     * @hidden
+     */
+    hasType<T>(notUsed?: T): ObjectSchemaBuilder<TProperties, TRequired, T>;
+    /**
+     * @hidden
+     */
+    clearHasType(): ObjectSchemaBuilder<TProperties, TRequired>;
+    /**
+     * Adds a new property to the object schema. The new property
+     * will be validated according to the provided schema.
+     * @param propName name of the new property
+     * @param schema schema builder of the new property
+     */
+    addProp<TType extends SchemaBuilder<any, any>, TName extends string>(propName: TName, schema: TType): ObjectSchemaBuilder<TProperties & {
+        [k in TName]: TType;
+    }, TRequired, TExplicitType>;
+    /**
+     * @hidden
+     * @deprecated this is for internal use, do not use if you are
+     * not sure you need it.
+     *
+     * TODO: This is used to avoid `&` in resulting types. For example,
+     * when you have a schema like `object({prop1: string()})` and then use `addProp({prop2: string()})` method,
+     * the resulting type without `optimize` will be something like `{prop1: string} & {prop2: string}`. Which
+     * is not we would like to have. Instead we want to have `{prop1: string, prop2: string}`. This is what
+     * `optimize` method does. However it is not always possible to do this optimization without losing
+     * JSDoc comments, which is sucks. For example, I had to disable optimization for UnionSchemas, because
+     * comments were lost. Hopefully it will be fixed in the future by Typescript team or somebody will
+     * find a workaround/fix and create a pull request.
+     */
+    optimize(): SchemaBuilder<undefined extends TExplicitType ? Id<RespectPropsOptionality<TProperties>> : TExplicitType>;
+    /**
+     * Adds new properties to the object schema. The same as `.addProp()` but
+     * allows to add multiple properties with one call. The new properties
+     * will be validated according to the provided schemas.
+     * @param props a key/schema object map.
+     */
+    addProps<TProps extends Record<string, SchemaBuilder<any, any>>>(props: TProps): ObjectSchemaBuilder<TProperties & TProps, true, undefined>;
+    /**
+     * Adds all properties from the `schema` object schema to the current schema.
+     * @param schema an instance of `ObjectSchemaBuilder`
+     */
+    addProps<K extends ObjectSchemaBuilder<any, any, any>>(schema: K): K extends ObjectSchemaBuilder<infer TProp, infer TReq, infer TExpType> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProp> & TProp, TRequired, TExplicitType> : never;
+    /**
+     * Omits properties listed in `properties` from the schema.
+     * Consider `Omit<Type, 'prop1'|'prop2'...>` as a good illustration
+     * from the TS world.
+     * @param properties - array of property names (strings) to remove from the schema.
+     */
+    omit<K extends keyof TProperties>(properties: K[]): ObjectSchemaBuilder<Omit<TProperties, K>, TRequired, TExplicitType>;
+    /**
+     * Removes `propName` from the list of properties.
+     * @param propName property name to remove. Schema should contain
+     * this property. An error will be thrown otherwise.
+     */
+    omit<TProperty extends keyof TProperties>(propName: TProperty): ObjectSchemaBuilder<Omit<TProperties, TProperty>, TRequired, TExplicitType>;
+    /**
+     * Removes all properties of `schema` from the current schema.
+     * `Omit<TSchema, keyof TAnotherSchema>` as a good illustration
+     * from the TS world.
+     * @param schema schema builder to take properties from.
+     */
+    omit<T>(schema: T): T extends ObjectSchemaBuilder<infer TProps, infer TRequired, infer TExplicitType> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProps>, TRequired, TExplicitType> : never;
+    /**
+     * Adds all properties from `schema` to the current schema.
+     * `TSchema & TAnotherSchema` is a good example of the similar concept
+     * in the TS type system.
+     * @param schema an object schema to take properties from
+     */
+    intersect<T extends ObjectSchemaBuilder<any, any, any>>(schema: T): T extends ObjectSchemaBuilder<infer TProps, infer TReq, infer TExplType> ? ObjectSchemaBuilder<Omit<TProperties, keyof TProps> & TProps, TRequired, TExplType> : never;
+    /**
+     * Marks all properties in the current schema as optional.
+     * It is the same as call `.optional('propname')` where `propname` is the name
+     * of every property in the schema.
+     */
+    partial(): ObjectSchemaBuilder<MakeChildrenOptional<TProperties>, TRequired, TExplicitType>;
+    /**
+     * Marks all properties from `properties` as optional in the schema.
+     * @param properties list of property names (string) to make optional
+     */
+    partial<K extends keyof TProperties>(properties: K[]): ObjectSchemaBuilder<Omit<TProperties, K> & Pick<MakeChildrenOptional<TProperties>, K>, TRequired, TExplicitType>;
+    /**
+     * Marks property `propName` as optional in the schema.
+     * @param propName the name of the property (string).
+     */
+    partial<TProperty extends keyof TProperties>(propName: TProperty): ObjectSchemaBuilder<Omit<TProperties, TProperty> & Pick<MakeChildrenOptional<TProperties>, TProperty>, TRequired, TExplicitType>;
+    /**
+     * Returns a new schema containing only properties listed in
+     * `properties` array.
+     * @param properties array of property names (strings)
+     */
+    pick<K extends keyof TProperties>(properties: K[]): ObjectSchemaBuilder<Pick<TProperties, K>, TRequired, undefined>;
+    /**
+     * Returns new schema based on the current schema. This new schema
+     * will consists only from properties which names are taken from the
+     * `schema` object schema.
+     * @param schema schema to take property names list from
+     */
+    pick<K extends ObjectSchemaBuilder<any, any, any>>(schema: K): K extends ObjectSchemaBuilder<infer TProps, infer T1, infer T2> ? ObjectSchemaBuilder<Omit<TProperties, keyof Omit<TProperties, keyof TProps>>, TRequired, undefined> : never;
+    /**
+     * Returns a new schema consisting of only one property
+     * (taken from the `property` property name). If the property
+     * does not exists in the current schema, an error will be thrown.
+     * @param property the name of the property (string).
+     */
+    pick<K extends keyof TProperties>(property: K): ObjectSchemaBuilder<Pick<TProperties, K>, TRequired, undefined>;
+    /**
+     * Modify schema for `propName` and return a new schema.
+     * Could be useful if you want to leave all schema intact, but
+     * change a type of one property.
+     * @param propName name of the property (string)
+     * @param callback callback function returning a new schema fo the `propName`. As a first parameter
+     * you will receive an old schema for `propName`.
+     * @returns
+     */
+    modifyPropSchema<K extends keyof TProperties, R extends SchemaBuilder<any, any>>(propName: K, callback: (builder: TProperties[K]) => R): ObjectSchemaBuilder<ModifyPropSchema<TProperties, K, R>, TRequired, TExplicitType>;
+    /**
+     * An alias for `.partial(prop: string)`
+     * @param prop name of the property
+     */
+    makePropOptional<K extends keyof TProperties>(prop: K): ObjectSchemaBuilder<MakeChildOptional<TProperties, K>, TRequired, TExplicitType>;
+    /**
+     * Marks `prop` as required property.
+     * If `prop` does not exists in the current schema,
+     * an error will be thrown.
+     * @param prop name of the property
+     */
+    makePropRequired<K extends keyof TProperties>(prop: K): ObjectSchemaBuilder<MakeChildRequired<TProperties, K>, TRequired, TExplicitType>;
+    /**
+     * `Partial<T>` would be a good example of the
+     * same operation in the TS world.
+     */
+    makeAllPropsOptional(): ObjectSchemaBuilder<MakeChildrenOptional<TProperties>, TRequired, TExplicitType>;
+    /**
+     * `Required<T>` would be a good example of the
+     * same operation in the TS world.
+     */
+    makeAllPropsRequired(): ObjectSchemaBuilder<MakeChildrenRequired<TProperties>, TRequired, TExplicitType>;
 }
-export declare const object: <T>(properties?: T) => IObjectSchemaBuilder<true, false, true, T extends undefined ? {} : T, undefined>;
+/**
+ * Defines a schema for empty object `{}`
+ */
+export declare function object(): ObjectSchemaBuilder<{}, true>;
+/**
+ * Defines an object schema, properties definitions are takens from `props`.
+ * @param props key/schema object map for schema's properties.
+ */
+export declare function object<TProps extends Record<string, SchemaBuilder<any, any>>>(props: TProps): ObjectSchemaBuilder<TProps, true>;
+type RequiredProps<T extends Record<string, SchemaBuilder<any, any>>> = keyof {
+    [k in keyof T as T[k] extends SchemaBuilder<infer TRes, infer TReq> ? TReq extends true ? k : never : never]: T[k];
+};
+type NotRequiredProps<T extends Record<string, SchemaBuilder<any, any>>> = keyof {
+    [k in keyof T as T[k] extends SchemaBuilder<infer TRes, infer TReq> ? TReq extends true ? never : k : never]: T[k];
+};
+export {};