@warlock.js/notifications 4.16.0 → 5.0.0

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

@@ -0,0 +1,691 @@
+import { clone } from "../../../node_modules/@mongez/reinforcements/esm/mixed/clone/clone.mjs";
+import "../../../node_modules/@mongez/reinforcements/esm/index.mjs";
+import { validate } from "../factory/validate.mjs";
+import { VALID_RULE, invalidRule } from "../helpers/validation-helpers.mjs";
+import "../helpers/index.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 ../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;
+	/**
+	* 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 in attributes) instance.attributesText[key] = attributes[key];
+		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 in attributes) instance.translatedAttributes[key] = attributes[key];
+		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.isNullable = this.isNullable;
+		cloned.isOptional = this.isOptional;
+		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
+	*/
+	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 valueForRules = data ?? this.getDefaultValue();
+		const mutatedData = await this.mutate(valueForRules, context);
+		const errors = [];
+		let isValid = true;
+		const isFirstErrorOnly = context.configurations?.firstErrorOnly ?? true;
+		const isEmpty = isEmptyValue(valueForRules);
+		const skipEmptyRules = this.isOptional ? valueForRules === void 0 : isEmpty;
+		const rulesToRun = this.requiredRule ? [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;
+	}
+	/**
+	* 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