@cleverbrush/schema 1.1.10 → 2.0.0

package/dist/builders/StringSchemaBuilder.d.ts

@@ -1,4 +1,4 @@
-import { Preprocessor, SchemaBuilder, ValidationResult, ValidationContext, Validator } from './SchemaBuilder.js';
+import { type BRAND, type PreprocessorEntry, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult, type ValidatorEntry } from './SchemaBuilder.js';
 type StringSchemaBuilderCreateProps<T = string, R extends boolean = true> = Partial<ReturnType<StringSchemaBuilder<T, R>['introspect']>>;
 /**
  * Allows to define a schema for a string. It can be: required or optional,
@@ -12,165 +12,280 @@ type StringSchemaBuilderCreateProps<T = string, R extends boolean = true> = Part
  *
  * @example ```ts
  * const schema = string().equals('hello');
- * const result = await schema.validate('hello');
+ * const result = schema.validate('hello');
  * // result.valid === true
  * // result.object === 'hello'
  * ```
  *
  * @example ```ts
  * const schema = string().equals('hello');
- * const result = await schema.validate('world');
+ * const result = schema.validate('world');
  * // result.valid === false
  * // result.errors[0].message === "is expected to be equal to 'hello'"
  * ```
  *
  * @example ```ts
  * const schema = string().minLength(5);
- * const result = await schema.validate('hello');
+ * const result = schema.validate('hello');
  * // result.valid === true
  * // result.object === 'hello'
  * ```
  *
  * @example ```ts
  * const schema = string().minLength(5);
- * const result = await schema.validate('hi');
+ * const result = schema.validate('hi');
  * // result.valid === false
  * // result.errors[0].message === 'is expected to have a length of at least 5'
  * ```
  *
  * @example ```ts
  * const schema = string().minLength(2).maxLength(5);
- * const result = await schema.validate('yes');
+ * const result = schema.validate('yes');
  * // result.valid === true
  * // result.object === 'yes'
  * ```
  *
  * @example ```ts
  * const schema = string('no');
- * const result = await schema.validate('yes');
+ * const result = schema.validate('yes');
  * // result.valid === false
  * // result.errors[0].message === "is expected to be equal to 'no'"
  * ```
  *
  * @see {@link string}
  */
-export declare class StringSchemaBuilder<TResult = string, TRequired extends boolean = true> extends SchemaBuilder<TResult, TRequired> {
+export declare class StringSchemaBuilder<TResult = string, TRequired extends boolean = true, TNullable extends boolean = false, THasDefault extends boolean = false, TExtensions = {}> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
     #private;
-    static create(props: StringSchemaBuilderCreateProps): StringSchemaBuilder<string, true>;
-    private constructor();
+    /**
+     * @hidden
+     */
+    static create(props: StringSchemaBuilderCreateProps): StringSchemaBuilder<string, true, false, false, {}>;
+    protected constructor(props: StringSchemaBuilderCreateProps);
     introspect(): {
         /**
          * Min length of the string (if defined).
          */
         minLength: number | undefined;
+        /**
+         * Min length validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        minLengthValidationErrorMessageProvider: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired, false, false, {}>>;
         /**
          * Max length of the string (if defined).
          */
         maxLength: number | undefined;
+        /**
+         * Max length validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        maxLengthValidationErrorMessageProvider: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired, false, false, {}>>;
         /**
          * If set, restrict object to be equal to a certain value.
          */
         equalsTo: string | undefined;
+        /**
+         * Equals validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        equalsToValidationErrorMessageProvider: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired, false, false, {}>>;
         /**
          * If set, restrict string to start with a certain value.
          */
         startsWith: string | undefined;
+        /**
+         * Starts with validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        startsWithValidationErrorMessageProvider: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired, false, false, {}>>;
         /**
          * If set, restrict string to end with a certain value.
          */
         endsWith: string | undefined;
+        /**
+         * Ends with validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        endsWithValidationErrorMessageProvider: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired, false, false, {}>>;
         /**
          * If set, restrict string to match a certain regular expression.
          */
         matches: RegExp | undefined;
+        /**
+         * Matches validation error message provider.
+         * If not provided, default error message will be used.
+         */
+        matchesValidationErrorMessageProvider: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired, false, false, {}>>;
         /**
          * Array of preprocessor functions
          */
-        preprocessors: Preprocessor<TResult>[];
+        preprocessors: PreprocessorEntry<TResult>[];
         /**
          * Array of validator functions
          */
-        validators: Validator<TResult>[];
+        validators: ValidatorEntry<TResult>[];
         type: string;
         isRequired: boolean;
+        isNullable: boolean;
+        isReadonly: boolean;
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: TResult | (() => TResult) | undefined;
+        description: string | undefined;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
     };
     /**
-     * @hidden
+     * @inheritdoc
      */
-    hasType<T>(notUsed?: T): StringSchemaBuilder<T, true>;
+    hasType<T>(_notUsed?: T): StringSchemaBuilder<T, true, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
-     * @hidden
+     * @inheritdoc
+     */
+    clearHasType(): StringSchemaBuilder<string, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /** {@inheritDoc SchemaBuilder.validate} */
+    validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /** {@inheritDoc SchemaBuilder.validateAsync} */
+    validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    /**
+     * Performs synchronous validation of string schema over `object`.
+     * Throws if any preprocessor, validator, or error message provider returns a Promise.
+     * @param context Optional `ValidationContext` settings.
      */
-    clearHasType(): StringSchemaBuilder<string, TRequired>;
+    protected _validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
     /**
-     * Performs validion of string schema over `object`.
+     * Performs async validation of string schema over `object`.
+     * Supports async preprocessors, validators, and error message providers.
      * @param context Optional `ValidationContext` settings.
      */
-    validate(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    protected _validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
     protected createFromProps<T, TReq extends boolean>(props: StringSchemaBuilderCreateProps<T, TReq>): this;
     /**
-     * Restricts object to be equal to `value`.
+     * Restricts string to be equal to `value`.
      */
-    equals<T extends string>(value: T): StringSchemaBuilder<T, TRequired>;
+    equals<T extends string>(value: T, 
+    /**
+     * Custom error message provider.
+     */
+    errorMessage?: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired>>): StringSchemaBuilder<T, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Cancels `equals()` call.
      */
-    clearEquals(): StringSchemaBuilder<string, TRequired>;
+    clearEquals(): StringSchemaBuilder<string, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): StringSchemaBuilder<TResult, TRequired, true, THasDefault, TExtensions> & TExtensions;
     /**
      * @hidden
      */
-    required(): StringSchemaBuilder<TResult, true>;
+    notNullable(): StringSchemaBuilder<TResult, TRequired, false, THasDefault, TExtensions> & TExtensions;
     /**
      * @hidden
      */
-    optional(): StringSchemaBuilder<TResult, false>;
+    required(errorMessage?: ValidationErrorMessageProvider): StringSchemaBuilder<TResult, true, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): StringSchemaBuilder<TResult, false, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): StringSchemaBuilder<TResult, true, TNullable, true, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): StringSchemaBuilder<TResult, TRequired, TNullable, false, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): StringSchemaBuilder<TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Marks the inferred type as `Readonly<string>`. Since strings are
+     * already immutable this is an identity operation, but it sets the
+     * `isReadonly` introspection flag for tooling consistency.
+     *
+     * @see {@link SchemaBuilder.readonly}
+     */
+    readonly(): StringSchemaBuilder<Readonly<TResult>, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Set minimal length of the valid value for schema.
-     * @param {number} length
+     * @param length minimum string length
      */
-    minLength(length: number): StringSchemaBuilder<TResult, TRequired>;
+    minLength(length: number, 
+    /**
+     * Custom error message provider.
+     */
+    errorMessage?: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired>>): StringSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Cancel `minLength()` call.
      */
-    clearMinLength(): StringSchemaBuilder<TResult, TRequired>;
+    clearMinLength(): StringSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Set maximal length of the valid value for schema.
-     * @length {number} length
+     * @param length maximum string length
+     */
+    maxLength(length: number, 
+    /**
+     * Custom error message provider.
      */
-    maxLength(length: number): StringSchemaBuilder<TResult, TRequired>;
+    errorMessage?: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired>>): StringSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
-     * cancel `maxLength()` call.
+     * Cancel `maxLength()` call.
      */
-    clearMaxLength(): StringSchemaBuilder<TResult, TRequired>;
+    clearMaxLength(): StringSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Restricts string to start with `val`.
      */
-    startsWith(val: string): StringSchemaBuilder<TResult, TRequired>;
+    startsWith<T extends string>(val: T, 
+    /**
+     * Custom error message provider.
+     */
+    errorMessage?: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired>>): StringSchemaBuilder<TResult extends string ? `${T}${TResult}` : TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Cancels `startsWith()` call.
      */
-    clearStartsWith(): StringSchemaBuilder<TResult, TRequired>;
+    clearStartsWith(): StringSchemaBuilder<string, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Restricts string to end with `val`.
      */
-    endsWith(val: string): StringSchemaBuilder<TResult, TRequired>;
+    endsWith<T extends string>(val: T, 
+    /**
+     * Custom error message provider.
+     */
+    errorMessage?: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired>>): StringSchemaBuilder<TResult extends string ? `${TResult}${T}` : TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Cancels `endsWith()` call.
      */
-    clearEndsWith(): StringSchemaBuilder<TResult, TRequired>;
+    clearEndsWith(): StringSchemaBuilder<string, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Restricts string to match `regexp`.
+     * @param regexp regular expression pattern to match against
+     */
+    matches(regexp: RegExp, 
+    /**
+     * Custom error message provider.
      */
-    matches(regexp: RegExp): StringSchemaBuilder<TResult, TRequired>;
+    errorMessage?: ValidationErrorMessageProvider<StringSchemaBuilder<TResult, TRequired>>): StringSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
     /**
      * Cancels `matches()` call.
      */
-    clearMatches(): StringSchemaBuilder<TResult, TRequired>;
+    clearMatches(): StringSchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
 }
 /**
  * Creates a string schema restricted to be equal to `equals`.
- * @param equals number value
+ * @param equals string value the schema is restricted to
  */
 export declare function string<T extends string>(equals: T): StringSchemaBuilder<T, true>;
+/**
+ * Creates a string schema restricted to be equal to `equals` with a custom error message.
+ * @param equals string value the schema is restricted to
+ */
+export declare function string<T extends string>(equals: T, errorMessage: ValidationErrorMessageProvider<StringSchemaBuilder<T, true>>): StringSchemaBuilder<T, true>;
 export declare function string(): StringSchemaBuilder<string, true>;
 export {};