@warlock.js/notifications 5.30.0 → 5.32.0

package/esm/packages/seal/src/validators/base-validator.mjs

@@ -1,720 +0,0 @@
-import { clone } from "../../../../node_modules/.pnpm/@mongez_reinforcements@4.0.2/node_modules/@mongez/reinforcements/esm/mixed/clone/clone.mjs";
-import "../../../../node_modules/.pnpm/@mongez_reinforcements@4.0.2/node_modules/@mongez/reinforcements/esm/index.mjs";
-import { validate } from "../factory/validate.mjs";
-import { VALID_RULE, invalidRule } from "../helpers/validation-helpers.mjs";
-import { isEmptyValue } from "../helpers/is-empty-value.mjs";
-import { requiredRule } from "../rules/core/required.mjs";
-import { mapToStandardResult } from "../standard-schema/map-result.mjs";
-
-//#region ../../packages/seal/src/validators/base-validator.ts
-/**
-* Base validator class - foundation for all validators
-*/
-var BaseValidator = class {
-	rules = [];
-	mutators = [];
-	defaultValue;
-	description;
-	shouldOmit = false;
-	isNullable = false;
-	isMutable = false;
-	/** Treat empty or whitespace-only form strings as an absent value. */
-	blankIsMissing = false;
-	/**
-	* Catch state — when `hasCatch` is true and validation fails, `catchValue`
-	* (or its callback result) substitutes for the failed value, and the public
-	* result reports `isValid: true` with no errors.
-	*
-	* See `.catch()` for semantics and the v1 scope (leaf-only).
-	*/
-	catchValue;
-	hasCatch = false;
-	/**
-	* Whether the field is optional.
-	* - false (default): field is required unless a requiredRule governs the condition.
-	* - true: field can be absent or empty — set by calling .optional().
-	*
-	* Also used as a TypeScript literal brand via the optional() return type.
-	*/
-	isOptional = false;
-	/**
-	* The single required-condition rule for this field.
-	* - null: field uses strict default (always required when not optional).
-	* - set: the rule governs when the field is required (e.g., requiredIf).
-	*
-	* Stored separately from rules[] and prepended at validate() time.
-	*/
-	requiredRule = this.createRule(requiredRule);
-	/**
-	* Pipeline to transform the mutated/original data before returning it
-	*/
-	dataTransformers = [];
-	/**
-	* Attributes text to be replaced on translations
-	* If the value is an object, it will be used as the attributes list for the rule
-	* If the value is a string, it will be used as the attributes list for the rule
-	*/
-	attributesText = {};
-	/**
-	* Attributed that will be always using the attribute translator
-	*/
-	translatedAttributes = {};
-	/**
-	* Mark the validator as mutable
-	*/
-	get mutable() {
-		this.isMutable = true;
-		return this;
-	}
-	/**
-	* Mark the validator as immutable
-	*/
-	get immutable() {
-		this.isMutable = false;
-		return this;
-	}
-	/**
-	* Get the instance to apply changes to.
-	* By default (immutable), returns a clone so the original is unchanged.
-	* When `.mutable` is set, returns `this` to mutate in place.
-	*/
-	get instance() {
-		return this.isMutable ? this : this.clone();
-	}
-	/**
-	* Get the default value
-	* Supports lazy evaluation via callbacks
-	*/
-	getDefaultValue() {
-		return typeof this.defaultValue === "function" ? this.defaultValue() : this.defaultValue;
-	}
-	/**
-	* Allow null as a valid value.
-	*
-	* Brands the return type with `{ isNullable: true }` so `Infer<>` widens
-	* the inferred output to include `| null`.
-	*/
-	nullable() {
-		const instance = this.instance;
-		instance.isNullable = true;
-		return instance;
-	}
-	/**
-	* Explicitly disallow null values after calling nullable.
-	*
-	* Brands the return type with `{ isNullable: false }` to cancel any prior
-	* `.nullable()` at the type level.
-	*/
-	notNullable() {
-		const instance = this.instance;
-		instance.isNullable = false;
-		return instance;
-	}
-	/**
-	* Add transformer with optional options
-	*
-	* @param transform - The transformer callback function
-	* @param options - Optional options to pass to the transformer
-	*
-	* @example
-	* ```ts
-	* // Without options
-	* v.date().addTransformer(data => data.toISOString())
-	*
-	* // With options
-	* v.date().addTransformer(
-	*   (data, { options }) => dayjs(data).format(options.format),
-	*   { format: 'YYYY-MM-DD' }
-	* )
-	* ```
-	*/
-	addTransformer(transform, options = {}) {
-		const instance = this.instance;
-		instance.addMutableTransformer(transform, options);
-		return instance;
-	}
-	/**
-	* Add transformer with optional options
-	*
-	* @param transform - The transformer callback function
-	* @param options - Optional options to pass to the transformer
-	*
-	* @example
-	* ```ts
-	* // Without options
-	* v.date().addTransformer(data => data.toISOString())
-	*
-	* // With options
-	* v.date().addTransformer(
-	*   (data, { options }) => dayjs(data).format(options.format),
-	*   { format: 'YYYY-MM-DD' }
-	* )
-	* ```
-	*/
-	addMutableTransformer(transform, options = {}) {
-		this.dataTransformers.push({
-			transform,
-			options
-		});
-	}
-	/**
-	* Transform the output value - simple one-time transformation
-	*
-	* @param callback - Simple callback receiving data and context
-	*
-	* @example
-	* ```ts
-	* // Simple transformation
-	* v.string().outputAs(data => data.toUpperCase())
-	*
-	* // With context
-	* v.string().outputAs((data, context) => {
-	*   console.log(`Transforming ${context.path}`);
-	*   return data.toLowerCase();
-	* })
-	* ```
-	*/
-	outputAs(callback) {
-		return this.addTransformer((data, { context }) => callback(data, context));
-	}
-	/**
-	* Transform output to JSON string
-	*
-	* Works with any validator type (string, number, date, object, array, etc.)
-	*
-	* @param indent - Optional indentation for pretty printing (default: 0 for compact)
-	*
-	* @example
-	* ```ts
-	* // Compact JSON
-	* v.object({ name: v.string() }).toJSON()
-	* // Output: '{"name":"John"}'
-	*
-	* // Pretty-printed JSON
-	* v.array(v.object({...})).toJSON(2)
-	* // Output:
-	* // [
-	* //   {
-	* //     "name": "John"
-	* //   }
-	* // ]
-	*
-	* // Works with any type
-	* v.string().toJSON()  // '"hello"'
-	* v.number().toJSON()  // '42'
-	* v.date().toJSON()    // '"2024-10-26T00:00:00.000Z"'
-	* ```
-	*
-	* @category Transformer
-	*/
-	toJSON(indent) {
-		return this.addTransformer((data, { options }) => JSON.stringify(data, null, options.indent), { indent: indent ?? 0 });
-	}
-	/**
-	* Start data transformation pipeline
-	* Context is passed at runtime, not stored
-	*/
-	async startTransformationPipeline(data, context) {
-		for (const transformer of this.dataTransformers) data = await transformer.transform(data, {
-			options: transformer.options,
-			context
-		});
-		return data;
-	}
-	/**
-	* Set attributes text to be replaced on translations
-	* If the value is an object, it will be used as the attributes list for the rule
-	* If the value is a string, it will be used as the attributes list for the rule
-	*
-	* @example
-	* v.string().attributes({
-	*   name: "Name",
-	*   email: "Email",
-	* });
-	* // Example 2: Add custom attributes for matches
-	* v.string().matches("confirmPassword").attributes({
-	*   matches: {
-	*     confirmPassword: "Confirm Password",
-	*   },
-	* });
-	*/
-	attributes(attributes) {
-		const instance = this.instance;
-		for (const [key, value] of Object.entries(attributes)) instance.attributesText[key] = value;
-		return instance;
-	}
-	/**
-	* Define a lazy getter property for each attribute in the given object and use the config attribute translator
-	*/
-	transAttributes(attributes) {
-		const instance = this.instance;
-		for (const [key, value] of Object.entries(attributes)) instance.translatedAttributes[key] = value;
-		return instance;
-	}
-	/**
-	* Add description to the validator
-	*/
-	describe(description) {
-		const instance = this.instance;
-		instance.description = description;
-		return instance;
-	}
-	/**
-	* Check if this validator can handle the given value's type
-	* Override this in specific validators to enable type-based routing in union validators
-	*
-	* Default: returns true (validator will attempt to validate any type)
-	*
-	* @param value - The value to check
-	* @returns True if this validator can handle this type
-	*
-	* @example
-	* ```ts
-	* // StringValidator
-	* public matchesType(value: any): boolean {
-	*   return typeof value === 'string';
-	* }
-	*
-	* // Custom FileValidator
-	* public matchesType(value: any): boolean {
-	*   return value instanceof UploadedFile;
-	* }
-	* ```
-	*/
-	matchesType(_value) {
-		return true;
-	}
-	/**
-	* Create a copy of this validator with the same configuration
-	* Copies all rules, mutators, transformers, default values, and settings
-	*
-	* @returns A new validator instance with copied configuration
-	*
-	* @example
-	* ```ts
-	* // Create reusable validator templates
-	* const baseString = v.string().required().trim().min(3);
-	* const emailField = baseString.clone().email();
-	* const usernameField = baseString.clone().alphanumeric().max(20);
-	*
-	* // Works with all validators
-	* const positiveInt = v.int().positive().required();
-	* const ageField = positiveInt.clone().min(18).max(120);
-	* ```
-	*/
-	clone() {
-		const Constructor = this.constructor;
-		const cloned = Object.create(Constructor.prototype);
-		cloned.rules = [...this.rules];
-		cloned.mutators = [...this.mutators];
-		cloned.dataTransformers = [...this.dataTransformers];
-		cloned.defaultValue = this.defaultValue;
-		cloned.shouldOmit = this.shouldOmit;
-		cloned.description = this.description;
-		cloned.attributesText = { ...this.attributesText };
-		cloned.translatedAttributes = { ...this.translatedAttributes };
-		cloned.isNullable = this.isNullable;
-		cloned.isOptional = this.isOptional;
-		cloned.blankIsMissing = this.blankIsMissing;
-		cloned.requiredRule = this.requiredRule;
-		cloned.catchValue = this.catchValue;
-		cloned.hasCatch = this.hasCatch;
-		return cloned;
-	}
-	/**
-	* @deprecated This method is no longer needed and does nothing.
-	* Empty values are now automatically skipped for validation rules by default.
-	* Only presence validators (required, present, etc.) will check empty values.
-	* You can safely remove this call from your code.
-	*/
-	ignoreEmptyValue(_ignoreEmptyValue = true) {
-		return this;
-	}
-	/**
-	* Omit this field from the validated data output
-	*
-	* Field will still be validated but not included in the final result.
-	* Useful for confirmation fields, captcha, terms acceptance, etc.
-	*
-	* @example
-	* ```ts
-	* v.object({
-	*   password: v.string().required(),
-	*   confirmPassword: v.string().required().sameAs("password").omit(),
-	*   acceptTerms: v.boolean().required().omit(),
-	* });
-	* // Output: { password: "..." }
-	* // confirmPassword and acceptTerms validated but omitted
-	* ```
-	*/
-	omit() {
-		const instance = this.instance;
-		instance.shouldOmit = true;
-		return instance;
-	}
-	/**
-	* @alias omit
-	*/
-	exclude() {
-		return this.omit();
-	}
-	/**
-	* Check if this field should be omitted from the output
-	*/
-	isOmitted() {
-		return this.shouldOmit;
-	}
-	/**
-	* Add rule to the validator
-	*/
-	addRule(rule, errorMessage, options = {}) {
-		const instance = this.instance;
-		instance.addMutableRule(rule, errorMessage, options);
-		return instance;
-	}
-	/**
-	* Set the required-condition rule for this field.
-	*
-	* Unlike addRule(), this does NOT push to rules[]. The rule is stored in the
-	* dedicated `requiredRule` slot and is prepended to the validation pipeline
-	* at runtime. Only one required rule can be active per field — this replaces
-	* any previously set required rule.
-	*
-	* Also marks the field as not optional (isOptional = false).
-	*
-	* @example
-	* ```ts
-	* // Used internally by required(), requiredIf(), requiredWith(), etc.
-	* BaseValidator.prototype.required = function(msg) {
-	*   return this.setRequiredRule(requiredRule, msg);
-	* };
-	* ```
-	*/
-	setRequiredRule(rule, errorMessage, options = {}) {
-		const instance = this.instance;
-		instance.isOptional = false;
-		instance.requiredRule = instance.createRule(rule, errorMessage, options);
-		return instance;
-	}
-	/**
-	* Add mutable rule
-	*/
-	addMutableRule(rule, errorMessage, options = {}) {
-		const newRule = this.createRule(rule, errorMessage, options);
-		this.rules.push(newRule);
-		return newRule;
-	}
-	/**
-	* Create new rule
-	*/
-	createRule(rule, errorMessage, options = {}) {
-		const newRule = {
-			...clone(rule),
-			context: {
-				errorMessage,
-				options,
-				attributesList: this.attributesText,
-				translatedAttributes: this.translatedAttributes,
-				translationParams: {},
-				translatableParams: {}
-			}
-		};
-		if (errorMessage) newRule.errorMessage = errorMessage;
-		if (rule.sortOrder === void 0) newRule.sortOrder = this.rules.length + 1;
-		return newRule;
-	}
-	/**
-	* Use a custom or pre-built validation rule
-	*
-	* @param rule - The validation rule to apply
-	* @param options - Rule options including errorMessage and any rule-specific options
-	*
-	* @example
-	* ```ts
-	* import { hexColorRule } from "@warlock.js/seal";
-	*
-	* v.string().useRule(hexColorRule, { errorMessage: "Invalid color" });
-	* ```
-	*
-	* @example
-	* ```ts
-	* // With rule options
-	* v.string().useRule(myCustomRule, {
-	*   customOption: true,
-	*   errorMessage: "Custom validation failed"
-	* });
-	* ```
-	*/
-	useRule(rule, options) {
-		const { errorMessage, ...ruleOptions } = options || {};
-		return this.addRule(rule, errorMessage, ruleOptions);
-	}
-	/**
-	* Define custom rule
-	*
-	* `value` is deliberately untyped: custom rules run in the rule pipeline,
-	* before a container validates its children (an object's fields are not yet
-	* validated or defaulted) and, when `firstErrorOnly` is `false` (the default
-	* is `true`), even after the type rule has failed. Typing it as the schema
-	* output would promise a shape the callback does not always receive.
-	*/
-	refine(callback) {
-		return this.addRule({
-			name: "custom",
-			async validate(value, context) {
-				const result = await callback(value, context);
-				if (result) {
-					this.context.errorMessage = result;
-					return invalidRule(this, context);
-				}
-				return VALID_RULE;
-			}
-		});
-	}
-	/**
-	* Add mutator to the validator
-	*/
-	addMutator(mutator, options = {}) {
-		const instance = this.instance;
-		instance.addMutableMutator(mutator, options);
-		return instance;
-	}
-	/**
-	* Add mutable mutator
-	*/
-	addMutableMutator(mutator, options = {}) {
-		this.mutators.push({
-			mutate: mutator,
-			context: {
-				options,
-				ctx: {}
-			}
-		});
-	}
-	/**
-	* Set default value for the field. The default is used when the input is
-	* absent (`undefined`); it then flows through the rule pipeline.
-	*
-	* Brands the return type with `{ hasDefault: true }` so `Infer<>` treats
-	* the field as guaranteed-present even when chained with `.optional()`.
-	*/
-	default(value) {
-		const instance = this.instance;
-		instance.defaultValue = value;
-		return instance;
-	}
-	/**
-	* Fallback to a value when validation fails.
-	*
-	* Complementary to `.default()`: `.default(x)` fires when input is **absent**,
-	* `.catch(y)` fires when input is **present but invalid**. Combine them when
-	* you want both behaviours: `.optional().default(x).catch(y)`.
-	*
-	* The fallback can be a value or a callback `(errors, originalInput) => fallback`.
-	* The callback variant is the only side-channel for the swallowed errors —
-	* use it to log/alert before the fallback substitutes.
-	*
-	* Brands the return type with `{ hasCatch: true }` so `Infer<>` treats the
-	* field as guaranteed-present (the catch ensures a value will always exist).
-	*
-	* **Scope (v1).** Catch is honoured for **leaf validators** (string, number,
-	* boolean, date, …) and for fields inside containers. It is a **no-op on
-	* container validators themselves** (`v.object`, `v.array`, `v.record`,
-	* `v.tuple`, `v.discriminatedUnion`) — those use their own iteration logic
-	* that bypasses the catch hook in `BaseValidator.validate()`.
-	*
-	* @example
-	* ```ts
-	* v.int().min(0).catch(3)                   // bad number → 3
-	* v.string().in(["us", "eu"]).catch("us")   // unknown enum → "us"
-	* v.string().catch((errors, input) => {
-	*   console.warn(`bad user value: ${JSON.stringify(input)}`, errors);
-	*   return "anonymous";
-	* })
-	* ```
-	*/
-	catch(fallback) {
-		const instance = this.instance;
-		instance.catchValue = fallback;
-		instance.hasCatch = true;
-		return instance;
-	}
-	/**
-	* Mutate the data
-	*/
-	async mutate(data, context) {
-		let mutatedData = data;
-		for (const mutator of this.mutators) {
-			mutator.context.ctx = context;
-			mutatedData = await mutator.mutate(mutatedData, mutator.context);
-		}
-		return mutatedData;
-	}
-	/**
-	* Set the label for the validator that will be matching the :input attribute
-	*/
-	label(label) {
-		const instance = this.instance;
-		instance.attributesText.input = label;
-		return instance;
-	}
-	/**
-	* Validate the data
-	*/
-	async validate(data, context) {
-		if (data === null && this.isNullable) return {
-			isValid: true,
-			errors: [],
-			data: null
-		};
-		const isBlank = this.blankIsMissing && typeof data === "string" && data.trim() === "";
-		if (isBlank && this.isNullable) return {
-			isValid: true,
-			errors: [],
-			data: null
-		};
-		const input = isBlank ? void 0 : data;
-		let valueForRules = input ?? this.getDefaultValue();
-		const parentFilledDefault = context?.valueIsDefault === true;
-		if (parentFilledDefault) context.valueIsDefault = false;
-		const isUsableDefault = (value) => value !== void 0 && (value !== null || this.isNullable);
-		let blankMatchesDefault = false;
-		if (typeof input === "string" && input.trim() === "" && this.defaultValue !== void 0) {
-			const fallback = this.getDefaultValue();
-			if (typeof fallback === "string" && fallback.trim() === "") {
-				valueForRules = fallback;
-				blankMatchesDefault = true;
-			}
-		}
-		const usedDefault = blankMatchesDefault || input == null && isUsableDefault(valueForRules) || parentFilledDefault && isUsableDefault(input);
-		const mutatedData = this.isOptional && valueForRules === void 0 ? void 0 : await this.mutate(valueForRules, context);
-		const errors = [];
-		let isValid = true;
-		const isFirstErrorOnly = context.configurations?.firstErrorOnly ?? true;
-		const isEmpty = isEmptyValue(valueForRules);
-		const skipEmptyRules = usedDefault && isEmpty && valueForRules !== null && !this.matchesType(valueForRules) ? false : this.isOptional ? valueForRules === void 0 : isEmpty;
-		const rulesToRun = this.requiredRule && !usedDefault ? [this.requiredRule, ...this.rules] : this.rules;
-		for (const rule of rulesToRun) {
-			if ((rule.requiresValue ?? true) && skipEmptyRules) continue;
-			this.setRuleAttributesList(rule);
-			const result = await rule.validate(mutatedData, context);
-			if (result.isValid === false) {
-				isValid = false;
-				errors.push({
-					type: rule.name,
-					error: result.error,
-					input: result.path ?? context.path
-				});
-				if (isFirstErrorOnly) break;
-			}
-		}
-		const result = {
-			isValid,
-			errors,
-			data: mutatedData !== void 0 ? await this.startTransformationPipeline(mutatedData, context) : void 0
-		};
-		if (result.isValid === false && this.hasCatch) return {
-			isValid: true,
-			errors: [],
-			data: typeof this.catchValue === "function" ? await this.catchValue(result.errors, data) : this.catchValue
-		};
-		return result;
-	}
-	/**
-	* Set rule attributes list
-	*/
-	setRuleAttributesList(rule) {
-		rule.context.attributesList = typeof this.attributesText[rule.name] === "object" ? this.attributesText[rule.name] : this.attributesText;
-		rule.context.translatedAttributes = this.translatedAttributes;
-	}
-	/**
-	* Standard Schema V1 compliance.
-	*
-	* Allows this validator to be used with any Standard Schema-aware library
-	* (OpenAI structured outputs, LangGraph, TanStack Form, Conform, Valibot adapters, etc.)
-	* without extra adapters.
-	*
-	* Delegates to the `validate()` factory so all `configureSeal()` options
-	* (translations, firstErrorOnly) are picked up automatically at call time.
-	*
-	* Includes Standard JSON Schema support via `jsonSchema.input()` / `jsonSchema.output()`.
-	*
-	* ## How Standard Schema libraries consume this
-	*
-	* You pass the **schema object itself** to the library — they internally read
-	* `schema["~standard"]`. Do NOT pass `schema["~standard"]` directly.
-	*
-	* @example
-	* ```ts
-	* const schema = v.object({ name: v.string().required() });
-	*
-	* // TanStack Form — pass schema, library reads ["~standard"] internally
-	* const form = useForm({ validators: { onChange: schema } });
-	*
-	* // Conform (Remix) — same pattern
-	* const [form] = useForm({ onValidate({ formData }) {
-	*   return parseWithStandardSchema(formData, { schema });
-	* }});
-	*
-	* // Direct validation (lower level — most apps don't need this)
-	* const result = await schema["~standard"].validate({ name: "Hasan" });
-	* // → { value: { name: "Hasan" } }  on success
-	* // → { issues: [{ message: "...", path: [{ key: "name" }] }] }  on failure
-	*
-	* // JSON Schema for OpenAI / LangChain tool calling
-	* const parameters = schema["~standard"].jsonSchema.input({ target: "openai-strict" });
-	* // → { type: "object", properties: {...}, required: [...], additionalProperties: false }
-	* ```
-	*
-	* @note Cross-field rules (sameAs, requiredIf, requiredWith) rely on sibling values
-	* available in the full validation context. When called on a standalone scalar validator,
-	* sibling data is absent and those rules will not evaluate correctly.
-	* Always call on the parent ObjectValidator for full-payload validation.
-	*/
-	get ["~standard"]() {
-		return {
-			version: 1,
-			vendor: "seal",
-			types: void 0,
-			validate: async (value) => {
-				return mapToStandardResult(await validate(this, value));
-			},
-			jsonSchema: {
-				input: (options) => this.toJsonSchema(options.target),
-				output: (options) => this.toJsonSchema(options.target)
-			}
-		};
-	}
-	/**
-	* Generate a JSON Schema representation of this validator.
-	*
-	* Supports targets: `"draft-2020-12"` (default), `"draft-07"`, `"openapi-3.0"`.
-	*
-	* Subclasses override this to describe their specific constraints.
-	* The base implementation returns `{}` (permissive — accepts anything),
-	* which is correct for validators with no representable JSON Schema constraints.
-	*
-	* @note Rules that cannot be expressed in JSON Schema are silently omitted:
-	* - Cross-field rules: sameAs, requiredIf, requiredWith, requiredWithout
-	* - Custom callbacks: refine()
-	* - Framework-specific runtime rules (core/cascade plugins)
-	* These rules still run normally at validation time — only absent from JSON Schema.
-	*
-	* @example
-	* ```ts
-	* v.string().min(3).max(50).toJsonSchema("draft-2020-12")
-	* // → { type: "string", minLength: 3, maxLength: 50 }
-	*
-	* v.object({ name: v.string().required(), age: v.int().optional() })
-	*   .toJsonSchema("draft-07")
-	* // → { type: "object", properties: { name: { type: "string" }, age: { type: "integer" } }, required: ["name"] }
-	* ```
-	*/
-	toJsonSchema(_target = "draft-2020-12") {
-		return {};
-	}
-};
-
-//#endregion
-export { BaseValidator };
-//# sourceMappingURL=base-validator.mjs.map