@cleverbrush/schema 1.1.11 → 2.0.0

package/dist/builders/ObjectSchemaBuilder.js

@@ -1,589 +1,2 @@
-import { SchemaBuilder } from './SchemaBuilder.js';
-/**
- * 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 class ObjectSchemaBuilder extends SchemaBuilder {
-    #properties = {};
-    #acceptUnknownProps = false;
-    static create(props) {
-        return new ObjectSchemaBuilder({
-            type: 'object',
-            ...props
-        });
-    }
-    createFromProps(props) {
-        return ObjectSchemaBuilder.create(props);
-    }
-    constructor(props) {
-        super(props);
-        if (typeof props.properties === 'object' && props.properties) {
-            this.#properties = props.properties;
-        }
-        if (typeof props.acceptUnknownProps === 'boolean') {
-            this.#acceptUnknownProps = props.acceptUnknownProps;
-        }
-    }
-    introspect() {
-        return {
-            ...super.introspect(),
-            /**
-             * Properties defined in schema
-             */
-            properties: { ...this.#properties },
-            /**
-             * 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: this.#acceptUnknownProps
-        };
-    }
-    /**
-     * @hidden
-     */
-    required() {
-        return super.required();
-    }
-    /**
-     * @hidden
-     */
-    optional() {
-        return super.optional();
-    }
-    /**
-     * Performs validion of object schema over the `object`.
-     * @param context Optional `ValidationContext` settings.
-     */
-    async validate(object, context) {
-        const prevalidatedResult = await super.preValidate(object, context);
-        const { valid, context: prevalidationContext, transaction: validationTransaction, errors: preValidationErrors } = prevalidatedResult;
-        const { path, doNotStopOnFirstError } = prevalidationContext;
-        let errors = prevalidatedResult.errors || [];
-        if (!valid && !doNotStopOnFirstError) {
-            return {
-                valid,
-                errors: preValidationErrors
-            };
-        }
-        const { object: { validatedObject: objToValidate } } = validationTransaction;
-        if (!this.isRequired &&
-            (typeof objToValidate === 'undefined' || objToValidate === null)) {
-            return {
-                valid: true,
-                object: validationTransaction.commit().validatedObject
-            };
-        }
-        if (typeof objToValidate !== 'object') {
-            errors.push({
-                message: 'must be an object',
-                path: path
-            });
-            if (!doNotStopOnFirstError) {
-                if (validationTransaction) {
-                    validationTransaction.rollback();
-                }
-                return {
-                    valid: false,
-                    errors: [errors[0]]
-                };
-            }
-        }
-        const propKeys = Object.keys(this.#properties);
-        const objKeys = Object.keys(objToValidate);
-        if (propKeys.length === 0) {
-            if (objKeys.length === 0) {
-                if (doNotStopOnFirstError && errors.length > 0) {
-                    return {
-                        valid: false,
-                        errors
-                    };
-                }
-                if (validationTransaction) {
-                    validationTransaction.commit().validatedObject;
-                }
-                return {
-                    valid: true,
-                    object: {}
-                };
-            }
-        }
-        const validationResults = await Promise.all(propKeys.map(async (key) => ({
-            key,
-            result: await this.#properties[key].validate(objToValidate[key], {
-                ...context,
-                path: `${path}.${key}`
-            })
-        })));
-        const notValidResults = validationResults.filter((res) => !res.result.valid);
-        validationResults
-            .filter((res) => res.result.valid)
-            .forEach(({ key, result }) => {
-            objToValidate[key] = result.object;
-        });
-        errors = [
-            ...errors,
-            ...notValidResults.reduce((acc, val) => [...acc, ...(val?.result?.errors || [])], [])
-        ];
-        for (let i = 0; i < objKeys.length; i++) {
-            const key = objKeys[i];
-            if (!(key in this.#properties) && !this.#acceptUnknownProps) {
-                errors.push({
-                    message: `unknown property '${key}'`,
-                    path: path
-                });
-                if (!doNotStopOnFirstError) {
-                    if (validationTransaction) {
-                        validationTransaction.rollback();
-                    }
-                    return {
-                        valid: false,
-                        errors: [errors[0]]
-                    };
-                }
-            }
-        }
-        if (notValidResults.length === 0 && errors.length === 0) {
-            const commited = validationTransaction.commit();
-            return {
-                valid: true,
-                object: commited.validatedObject
-            };
-        }
-        validationTransaction.rollback();
-        return {
-            valid: false,
-            errors: doNotStopOnFirstError
-                ? errors
-                : errors[0]
-                    ? [errors[0]]
-                    : []
-        };
-    }
-    /**
-     * Fields not defined in `properties` will not be validated
-     * and will be passed through the validation.
-     */
-    acceptUnknownProps() {
-        return this.createFromProps({
-            ...this.introspect(),
-            acceptUnknownProps: true
-        });
-    }
-    /**
-     * Fields not defined in `properties` will be considered
-     * as schema violation. This is the default behavior.
-     */
-    notAcceptUnknownProps() {
-        return this.createFromProps({
-            ...this.introspect(),
-            acceptUnknownProps: false
-        });
-    }
-    /**
-     * @hidden
-     */
-    hasType(
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    notUsed) {
-        return this.createFromProps({
-            ...this.introspect()
-        });
-    }
-    /**
-     * @hidden
-     */
-    clearHasType() {
-        return this.createFromProps({
-            ...this.introspect()
-        });
-    }
-    /**
-     * 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(propName, schema) {
-        if (typeof propName !== 'string' || !propName) {
-            throw new Error('propName must be a non empty string');
-        }
-        if (propName in this.#properties) {
-            throw new Error(`Property ${propName} already exists`);
-        }
-        if (!(schema instanceof SchemaBuilder)) {
-            throw new Error('schema must be an instance of the SchemaBuilder class');
-        }
-        return this.createFromProps({
-            ...this.introspect(),
-            properties: {
-                ...this.introspect().properties,
-                [propName]: schema
-            }
-        });
-    }
-    /**
-     * @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() {
-        return this.createFromProps({
-            ...this.introspect()
-        });
-    }
-    addProps(props) {
-        if (props instanceof ObjectSchemaBuilder) {
-            return this.addProps(props.introspect().properties);
-        }
-        if (typeof props !== 'object') {
-            throw new Error('props should be an object');
-        }
-        if (props === null) {
-            throw new Error('props should not be null');
-        }
-        const newProps = { ...this.#properties };
-        for (const key in props) {
-            if (key in this.#properties) {
-                throw new Error(`property '${key}' already exists`);
-            }
-            if (!(props[key] instanceof SchemaBuilder)) {
-                throw new Error(`${key} is not a SchemaBuilder`);
-            }
-            newProps[key] = props[key];
-        }
-        return this.createFromProps({
-            ...this.introspect(),
-            properties: newProps
-        });
-    }
-    omit(propNameOrArrayOrPropsOrBuilder) {
-        if (typeof propNameOrArrayOrPropsOrBuilder === 'string') {
-            // remove one field
-            const propName = propNameOrArrayOrPropsOrBuilder;
-            if (!propName || !(propName in this.#properties)) {
-                throw new Error(`property ${propName.toString()} does not exists in the schema`);
-            }
-            return this.createFromProps({
-                ...this.introspect(),
-                properties: (() => {
-                    const result = { ...this.#properties };
-                    delete result[propName];
-                    return result;
-                })()
-            });
-        }
-        else if (Array.isArray(propNameOrArrayOrPropsOrBuilder)) {
-            const propsArray = propNameOrArrayOrPropsOrBuilder;
-            const distinctKeys = new Map();
-            propsArray.forEach((key) => {
-                if (typeof key !== 'string' || !key) {
-                    throw new Error('property name must be a string');
-                }
-                if (!(key in this.#properties)) {
-                    throw new Error(`property ${key.toString()} does not exists in the schema`);
-                }
-                distinctKeys.set(key.toString(), true);
-            });
-            if (distinctKeys.size === 0) {
-                throw new Error('please provide at least one property to omit');
-            }
-            const props = {
-                ...this.introspect()
-            };
-            for (const key of distinctKeys.keys()) {
-                delete props.properties[key];
-            }
-            return this.createFromProps(props);
-        }
-        else if (propNameOrArrayOrPropsOrBuilder instanceof ObjectSchemaBuilder) {
-            const propsToOmit = {
-                ...propNameOrArrayOrPropsOrBuilder.introspect().properties
-            };
-            const props = {
-                ...this.introspect()
-            };
-            for (const key in propsToOmit) {
-                if (key in props.properties) {
-                    delete props.properties[key];
-                }
-            }
-            return this.createFromProps(props);
-        }
-        throw new Error('this parameter type is not supported');
-    }
-    /**
-     * 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(schema) {
-        if (!(schema instanceof ObjectSchemaBuilder)) {
-            throw new Error('schema must be an instance of the ObjectSchemaBuilder class');
-        }
-        const remoteProps = schema.introspect().properties;
-        const localProps = this.introspect();
-        const newProps = Object.keys(localProps.properties).reduce((acc, curr) => {
-            acc[curr] =
-                curr in remoteProps ? remoteProps[curr] : localProps[curr];
-            return acc;
-        }, {});
-        return this.createFromProps({
-            ...this.introspect(),
-            properties: newProps
-        });
-    }
-    partial(propNameOrArray) {
-        if (typeof propNameOrArray === 'undefined' ||
-            propNameOrArray === null) {
-            return this.createFromProps({
-                ...this.introspect(),
-                properties: Object.keys(this.#properties).reduce((acc, key) => {
-                    acc[key] = this.#properties[key].optional();
-                    return acc;
-                }, {})
-            });
-        }
-        if (Array.isArray(propNameOrArray)) {
-            const propsArray = propNameOrArray;
-            if (propsArray.length === 0) {
-                throw new Error('properties cannot be empty');
-            }
-            const newProps = {
-                ...this.introspect()
-            };
-            propsArray.forEach((key) => {
-                if (typeof key !== 'string') {
-                    throw new Error('each propery in property list must be as string value');
-                }
-                if (!(key in newProps.properties)) {
-                    throw new Error(`property ${key} does not exists`);
-                }
-                newProps.properties[key] =
-                    newProps.properties[key].optional();
-            });
-            return this.createFromProps(newProps);
-        }
-        if (typeof propNameOrArray === 'string') {
-            return this.modifyPropSchema(propNameOrArray, (schema) => schema.optional());
-        }
-        throw new Error('expecting string or string[] parameter');
-    }
-    pick(properties) {
-        if (typeof properties === 'string') {
-            const property = properties;
-            if (!property) {
-                throw new Error('property cannot be empty');
-            }
-            if (!(property in this.#properties)) {
-                throw new Error(`property ${property} does not exists`);
-            }
-            return this.createFromProps({
-                ...this.introspect(),
-                properties: {
-                    [property]: this.#properties[property]
-                }
-            });
-        }
-        if (Array.isArray(properties)) {
-            if (properties.length === 0) {
-                throw new Error('properties must be a non empty erray');
-            }
-            const newProperties = properties.reduce((acc, curr) => {
-                if (typeof curr !== 'string' || !curr) {
-                    throw new Error('each property name must be a non empty string');
-                }
-                if (!(curr in this.#properties)) {
-                    throw new Error(`property ${curr} does not exists`);
-                }
-                acc[curr] = this.#properties[curr];
-                return acc;
-            }, {});
-            return this.createFromProps({
-                ...this.introspect(),
-                properties: newProperties
-            });
-        }
-        if (properties instanceof ObjectSchemaBuilder) {
-            const externalSchema = properties;
-            const props = Object.keys(externalSchema.introspect().properties).filter((p) => typeof this.#properties[p] !== 'undefined');
-            if (props.length === 0) {
-                throw new Error('there are no common properties in provided schemas');
-            }
-            return this.pick(props);
-        }
-        throw new Error('string, array or ObjectSchemaBuilder is expected');
-    }
-    /**
-     * 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(propName, callback) {
-        if (typeof propName !== 'string' || !propName) {
-            throw new Error('propName must be a non empty string');
-        }
-        if (!(propName in this.#properties)) {
-            throw new Error(`property ${propName} does not exists in the schema`);
-        }
-        if (typeof callback !== 'function') {
-            throw new Error('callback must be a function');
-        }
-        const callbackResult = callback(this.#properties[propName]);
-        if (!(callbackResult instanceof SchemaBuilder)) {
-            throw new Error('callback must return a SchemaBuilder object');
-        }
-        const props = {
-            ...this.introspect()
-        };
-        props.properties = {
-            ...props.properties,
-            [propName]: callbackResult
-        };
-        return this.createFromProps(props);
-    }
-    /**
-     * An alias for `.partial(prop: string)`
-     * @param prop name of the property
-     */
-    makePropOptional(prop) {
-        return this.modifyPropSchema(prop, (builder) => builder.optional());
-    }
-    /**
-     * 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(prop) {
-        return this.modifyPropSchema(prop, (builder) => builder.required());
-    }
-    /**
-     * `Partial<T>` would be a good example of the
-     * same operation in the TS world.
-     */
-    makeAllPropsOptional() {
-        return this.createFromProps({
-            ...this.introspect(),
-            properties: Object.keys(this.#properties).reduce((acc, curr) => {
-                acc[curr] = this.#properties[curr].optional();
-                return acc;
-            }, {})
-        });
-    }
-    /**
-     * `Required<T>` would be a good example of the
-     * same operation in the TS world.
-     */
-    makeAllPropsRequired() {
-        return this.createFromProps({
-            ...this.introspect(),
-            properties: Object.keys(this.#properties).reduce((acc, curr) => {
-                acc[curr] = this.#properties[curr].required();
-                return acc;
-            }, {})
-        });
-    }
-}
-export function object(props) {
-    return ObjectSchemaBuilder.create({
-        isRequired: true,
-        properties: props
-    });
-}
+import{a,b}from"../chunk-NXPH3ZUW.js";import"../chunk-CTP4RHDG.js";export{a as ObjectSchemaBuilder,b as object};
+//# sourceMappingURL=ObjectSchemaBuilder.js.map

package/dist/builders/ObjectSchemaBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/builders/PropertyValidationResult.d.ts

@@ -0,0 +1,68 @@
+import { ObjectSchemaBuilder } from './ObjectSchemaBuilder.js';
+import { type InferType, type NestedValidationResult, type PropertyDescriptorInner, type PropertyDescriptorTree } from './SchemaBuilder.js';
+/**
+ * Mutable container for nested validation results associated with a specific
+ * property descriptor. Implements {@link NestedValidationResult} and tracks
+ * the seen value, accumulated error messages, and child results for
+ * nested object properties.
+ *
+ * Used internally by `ObjectSchemaBuilder` during validation to build up
+ * a tree of per-property validation results.
+ */
+export declare class PropertyValidationResult<TSchema extends ObjectSchemaBuilder<any, any, any, any, any> = ObjectSchemaBuilder<any, any, any, any, any>, TRootSchema extends ObjectSchemaBuilder<any, any, any, any, any> = ObjectSchemaBuilder<any, any, any, any, any>, TParentPropertyDescriptor = any> implements NestedValidationResult<TSchema, TRootSchema, TParentPropertyDescriptor> {
+    #private;
+    /**
+     * The value that was seen at the property location described by the descriptor.
+     * Retrieves the value from the root object using the property descriptor's `getValue` method.
+     * Returns `undefined` if the property is not found.
+     */
+    get seenValue(): InferType<TSchema> | undefined;
+    /**
+     * The list of validation error messages accumulated for this property.
+     */
+    get errors(): ReadonlyArray<string>;
+    /**
+     * Whether validation passed for this property and all of its children.
+     * Returns `true` only when there are no errors and no child errors.
+     */
+    get isValid(): boolean;
+    /**
+     * Returns the list of child `NestedValidationResult` instances
+     * representing validation results for nested properties.
+     */
+    getChildErrors(): ReadonlyArray<NestedValidationResult<any, any, any>>;
+    /**
+     * The inner property descriptor providing `getValue`, `setValue`, and `getSchema`
+     * operations for the property this error relates to.
+     */
+    get descriptor(): PropertyDescriptorInner<TRootSchema, TSchema, TParentPropertyDescriptor>;
+    /**
+     * Creates a new `PropertyValidationResult`.
+     *
+     * @param descriptor - the property descriptor tree node this error is associated with;
+     *   must be a valid descriptor (checked via `ObjectSchemaBuilder.isValidPropertyDescriptor`)
+     * @param rootObjectValue - the root object being validated, used to resolve property values
+     * @param errors - optional initial list of error message strings
+     * @throws if `descriptor` is not a valid property descriptor
+     */
+    constructor(descriptor: PropertyDescriptorTree<TSchema, TRootSchema, any, TParentPropertyDescriptor>, rootObjectValue: InferType<TRootSchema> | undefined, errors?: string[]);
+    /**
+     * Appends a validation error message to this property's error list.
+     * @param error - the error message string to add
+     */
+    addError(error: string): void;
+    /**
+     * Appends a child `NestedValidationResult` for a nested property.
+     * @param childError - the child validation result to add
+     */
+    addChildError(childError: NestedValidationResult<any, any, any>): void;
+    /**
+     * Returns a JSON-serializable representation of this validation result.
+     * This ensures `JSON.stringify` includes `isValid` and `errors`,
+     * which are otherwise non-enumerable prototype getters.
+     */
+    toJSON(): {
+        isValid: boolean;
+        errors: ReadonlyArray<string>;
+    };
+}