@lakutata/core 1.0.59 → 3.0.0-beta.0

package/dist/types/lib/validation/interfaces/ExternalHelpers.d.ts

@@ -0,0 +1,16 @@
+import { ExtensionBoundSchema } from '../types/ExtensionBoundSchema.js';
+import { State } from './State.js';
+import { ValidationOptions } from './ValidationOptions.js';
+import { ErrorReport } from './ErrorReport.js';
+import { LanguageMessages } from '../types/LanguageMessages.js';
+import { Context } from './Context.js';
+export interface ExternalHelpers<V = any> {
+    schema: ExtensionBoundSchema;
+    linked: ExtensionBoundSchema | null;
+    state: State;
+    prefs: ValidationOptions;
+    original: V;
+    warn: (code: string, local?: Context) => void;
+    error: (code: string, local?: Context) => ErrorReport;
+    message: (messages: LanguageMessages, local?: Context) => ErrorReport;
+}

package/dist/types/lib/validation/interfaces/FunctionSchema.d.ts

@@ -0,0 +1,31 @@
+import { AnySchema } from './AnySchema.js';
+/**
+ * A schema of functions, built by `DTO.Function()` (and `DTO.AsyncFunction()`, `DTO.Class()`): their number of
+ * declared parameters (`length`), or whether they are classes.
+ * @typeParam TSchema The type of the functions the schema validates.
+ */
+export interface FunctionSchema<TSchema = Function> extends AnySchema<TSchema> {
+    /**
+     * Require an exact number of declared parameters (the `length` of the function).
+     * @param n The number of parameters, a non-negative integer.
+     * @returns A new schema.
+     */
+    arity(n: number): this;
+    /**
+     * Require the function to be a class (declared with `class`).
+     * @returns A new schema.
+     */
+    class(): this;
+    /**
+     * Require a minimum number of declared parameters (the `length` of the function).
+     * @param n The minimum number of parameters (inclusive), an integer greater than 0.
+     * @returns A new schema.
+     */
+    minArity(n: number): this;
+    /**
+     * Require a maximum number of declared parameters (the `length` of the function).
+     * @param n The maximum number of parameters (inclusive), a non-negative integer.
+     * @returns A new schema.
+     */
+    maxArity(n: number): this;
+}

package/dist/types/lib/validation/interfaces/GuidOptions.d.ts

@@ -0,0 +1,6 @@
+type GuidVersions = 'uuidv1' | 'uuidv2' | 'uuidv3' | 'uuidv4' | 'uuidv5' | 'uuidv6' | 'uuidv7' | 'uuidv8';
+export interface GuidOptions {
+    version?: GuidVersions[] | GuidVersions;
+    separator?: boolean | '-' | ':';
+}
+export {};

package/dist/types/lib/validation/interfaces/HexOptions.d.ts

@@ -0,0 +1,16 @@
+export interface HexOptions {
+    /**
+     * hex decoded representation must be byte aligned.
+     * @default false
+     */
+    byteAligned?: boolean;
+    /**
+     * controls whether the prefix `0x` or `0X` is allowed (or required) on hex strings.
+     * When `true`, the prefix must be provided.
+     * When `false`, the prefix is forbidden.
+     * When `optional`, the prefix is allowed but not required.
+     *
+     * @default false
+     */
+    prefix?: boolean | 'optional';
+}

package/dist/types/lib/validation/interfaces/HierarchySeparatorOptions.d.ts

@@ -0,0 +1,7 @@
+export interface HierarchySeparatorOptions {
+    /**
+     * The separator of the keys in a path, or false to read the whole path as a single key.
+     * @default '.'
+     */
+    separator?: string | false;
+}

package/dist/types/lib/validation/interfaces/IpOptions.d.ts

@@ -0,0 +1,11 @@
+import { PresenceMode } from '../types/PresenceMode.js';
+export interface IpOptions {
+    /**
+     * One or more IP address versions to validate against. Valid values: ipv4, ipv6, ipvfuture
+     */
+    version?: string | string[];
+    /**
+     * Used to determine if a CIDR is allowed or not. Valid values: optional, required, forbidden
+     */
+    cidr?: PresenceMode;
+}

package/dist/types/lib/validation/interfaces/LanguageMessageTemplate.d.ts

@@ -0,0 +1,4 @@
+export interface LanguageMessageTemplate {
+    source: string;
+    rendered: string;
+}

package/dist/types/lib/validation/interfaces/LinkSchema.d.ts

@@ -0,0 +1,26 @@
+import { AnySchema } from './AnySchema.js';
+import { Schema } from '../types/Schema.js';
+/**
+ * A schema validating with another schema of the same schema tree, reached by its id or its path: built by
+ * `DTO.Link(ref)`, for recursive schemas (a tree of categories).
+ * @typeParam TSchema The type of the values the schema validates.
+ */
+export interface LinkSchema<TSchema = any> extends AnySchema<TSchema> {
+    /**
+     * Merge a schema into the linked schema, once the link is resolved during the validation (unlike `concat()` on the
+     * link itself, it may add the rules of the linked type).
+     * @param schema The schema to merge, of the type of the linked schema.
+     * @returns A new schema.
+     * @throws {SchemaDefinitionException} When the link has no linked schema yet or the schema is a link; during the
+     * validation, when the types cannot be merged.
+     */
+    concat(schema: Schema): this;
+    /**
+     * Set the schema linked to, when the link is built without it; a link must have one before it validates.
+     * @param ref The linked schema: an id (`'#node'`, set by `id()`), a path from the root of the schema (`'/a'`), or
+     * a relative path (`'...'`); not the link itself, its children or another link.
+     * @returns A new schema.
+     * @throws {SchemaDefinitionException} When the link already has a schema.
+     */
+    ref(ref: string): this;
+}

package/dist/types/lib/validation/interfaces/NumberSchema.d.ts

@@ -0,0 +1,134 @@
+import { AnySchema } from './AnySchema.js';
+import { Reference } from './Reference.js';
+/**
+ * A schema of numbers, built by `DTO.Number()`: limits, integers and their sizes, precision. `NaN`, the infinities and
+ * the numbers beyond the safe integers (`Number.MAX_SAFE_INTEGER`) are rejected unless `unsafe()` is called. With
+ * conversion enabled (`strict(false)`), numeric strings are accepted as numbers.
+ * @typeParam TSchema The type of the numbers the schema validates.
+ */
+export interface NumberSchema<TSchema = number> extends AnySchema<TSchema> {
+    /**
+     * Require the number to be greater than a limit.
+     * @param limit The limit (exclusive), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    greater(limit: number | Reference): this;
+    /**
+     * Require the number to be an integer.
+     * @returns A new schema.
+     */
+    integer(): this;
+    /**
+     * Require the number to be an 8-bit signed integer: from -128 to 127.
+     * @returns A new schema.
+     */
+    int8(): this;
+    /**
+     * Require the number to be an 8-bit unsigned integer: from 0 to 255.
+     * @returns A new schema.
+     */
+    uint8(): this;
+    /**
+     * Require the number to be a 16-bit signed integer: from -32768 to 32767.
+     * @returns A new schema.
+     */
+    int16(): this;
+    /**
+     * Require the number to be a 16-bit unsigned integer: from 0 to 65535.
+     * @returns A new schema.
+     */
+    uint16(): this;
+    /**
+     * Require the number to be a 32-bit signed integer: from -2147483648 to 2147483647.
+     * @returns A new schema.
+     */
+    int32(): this;
+    /**
+     * Require the number to be a 32-bit unsigned integer: from 0 to 4294967295.
+     * @returns A new schema.
+     */
+    uint32(): this;
+    /**
+     * Require the number to be a 64-bit signed integer, limited to the safe integers of JavaScript
+     * (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`): the larger ones are imprecise as numbers (use
+     * `DTO.BigInt()` for them).
+     * @returns A new schema.
+     */
+    int64(): this;
+    /**
+     * Require the number to be a 64-bit unsigned integer, limited to the safe integers of JavaScript (0 to
+     * `Number.MAX_SAFE_INTEGER`): the larger ones are imprecise as numbers (use `DTO.BigInt()` for them).
+     * @returns A new schema.
+     */
+    uint64(): this;
+    /**
+     * Require the number to be in the range of the 32-bit floating point numbers (about ±3.4e38).
+     * @returns A new schema.
+     */
+    float(): this;
+    /**
+     * Declare the number as a 64-bit floating point number (the `double` format of the JSON Schemas): every finite
+     * number, those beyond the safe integers included (it calls `unsafe()`).
+     * @returns A new schema.
+     */
+    double(): this;
+    /**
+     * Require the number to be less than a limit.
+     * @param limit The limit (exclusive), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    less(limit: number | Reference): this;
+    /**
+     * Require the number to be at most a limit.
+     * @param limit The maximum (inclusive), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    max(limit: number | Reference): this;
+    /**
+     * Require the number to be at least a limit.
+     * @param limit The minimum (inclusive), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    min(limit: number | Reference): this;
+    /**
+     * Require the number to be a multiple of a base.
+     * @param base The base, a positive number, or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    multiple(base: number | Reference): this;
+    /**
+     * Require the number to be negative (less than 0).
+     * @returns A new schema.
+     */
+    negative(): this;
+    /**
+     * Require the number to be a TCP port: an integer from 0 to 65535.
+     * @returns A new schema.
+     */
+    port(): this;
+    /**
+     * Require the number to be positive (greater than 0).
+     * @returns A new schema.
+     */
+    positive(): this;
+    /**
+     * Require at most a number of decimal places; with conversion enabled (`strict(false)`), the number is rounded to
+     * them instead.
+     * @param limit The maximum number of decimal places.
+     * @returns A new schema.
+     */
+    precision(limit: number): this;
+    /**
+     * Require the number to be negative or positive (0 is neither).
+     * @param sign The sign required.
+     * @returns A new schema.
+     */
+    sign(sign: 'positive' | 'negative'): this;
+    /**
+     * Allow the numbers beyond the safe integers (`Number.MIN_SAFE_INTEGER` to `Number.MAX_SAFE_INTEGER`), which lose
+     * precision; rejected by default.
+     * @param enabled Whether they are allowed: a falsy value restores the default. Defaults to true.
+     * @returns A new schema.
+     */
+    unsafe(enabled?: any): this;
+}

package/dist/types/lib/validation/interfaces/ObjectPatternOptions.d.ts

@@ -0,0 +1,6 @@
+import { SchemaLike } from '../types/SchemaLike.js';
+import { Reference } from './Reference.js';
+export interface ObjectPatternOptions {
+    fallthrough?: boolean;
+    matches: SchemaLike | Reference;
+}

package/dist/types/lib/validation/interfaces/ObjectSchema.d.ts

@@ -0,0 +1,173 @@
+import { AnySchema } from './AnySchema.js';
+import { SchemaMap } from '../types/SchemaMap.js';
+import { SchemaLike } from '../types/SchemaLike.js';
+import { ObjectPatternOptions } from './ObjectPatternOptions.js';
+import { DependencyOptions } from './DependencyOptions.js';
+import { Reference } from './Reference.js';
+import { RenameOptions } from './RenameOptions.js';
+/**
+ * A schema of objects, built by `DTO.Object(keys)` (and returned by `DTO.Schema()` for a DTO class): the schemas of
+ * its keys, the unknown keys, and the dependencies between keys.
+ *
+ * The validations of lakutata allow the unknown keys and remove them from the validated object (the `allowUnknown` and
+ * `stripUnknown` options); `unknown(false)` rejects them instead.
+ * @typeParam TSchema The type of the objects the schema validates.
+ */
+export interface ObjectSchema<TSchema = any> extends AnySchema<TSchema> {
+    /**
+     * Require all the keys together: when one of them is present, all of them must be.
+     * @param peers The key names (dotted paths reach nested keys), optionally followed by the options: `separator`
+     * of the paths (default `.`), `isPresent` (what counts as present, by default not undefined).
+     * @returns A new schema.
+     */
+    and(...peers: Array<string | DependencyOptions>): this;
+    /**
+     * Add keys to the schema, replacing the schemas of the keys already present. Unlike `keys()`, an empty or missing
+     * argument changes nothing.
+     * @param schema The schemas of the keys to add, by key.
+     * @returns A new schema.
+     */
+    append(schema?: SchemaMap<TSchema>): this;
+    append<TSchemaExtended = any, T = TSchemaExtended>(schema?: SchemaMap<T>): ObjectSchema<T>;
+    /**
+     * Require a value of the object to match a schema (the object itself fails, with the message).
+     * @param ref The value tested: a key path relative to the object, which starts with `.` (`'.a.b'`), or a
+     * reference.
+     * @param schema The schema the value must match, like `DTO.Ref('b')` to require it to equal another key.
+     * @param message The reason shown in the error message (`… failed to <message>`).
+     * @returns A new schema.
+     */
+    assert(ref: string | Reference, schema: SchemaLike, message?: string): this;
+    /**
+     * Require the object to be an instance of a class.
+     *
+     * @param constructor The class the object must be an instance of.
+     * @param name The name of the class in the error messages, for a class without a name. Defaults to its name.
+     * @returns A new schema.
+     */
+    instance(constructor: Function, name?: string): this;
+    /**
+     * Require every key name of the object to match a schema.
+     * @param schema The schema of the key names, like `DTO.String().pattern(/^[a-z]+$/)`.
+     * @returns A new schema.
+     */
+    keyNames(schema: SchemaLike): this;
+    /**
+     * Set the keys of the schema, adding to the keys already set (a key given again replaces its schema). Without an
+     * argument, any key is allowed; with `{}`, no key is.
+     * @param schema The schemas of the keys, by key.
+     * @returns A new schema.
+     */
+    keys(schema?: SchemaMap<TSchema>): this;
+    /**
+     * Require an exact number of keys.
+     * @param limit The number of keys.
+     * @returns A new schema.
+     */
+    length(limit: number): this;
+    /**
+     * Require at most a number of keys.
+     * @param limit The maximum number of keys (inclusive), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    max(limit: number | Reference): this;
+    /**
+     * Require at least a number of keys.
+     * @param limit The minimum number of keys (inclusive), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    min(limit: number | Reference): this;
+    /**
+     * Forbid all the keys together: some of them may be present, not all of them.
+     * @param peers The key names (dotted paths reach nested keys), optionally followed by the options: `separator`
+     * of the paths (default `.`), `isPresent` (what counts as present, by default not undefined).
+     * @returns A new schema.
+     */
+    nand(...peers: Array<string | DependencyOptions>): this;
+    /**
+     * Require at least one of the keys (several are allowed).
+     * @param peers The key names (dotted paths reach nested keys), optionally followed by the options: `separator`
+     * of the paths (default `.`), `isPresent` (what counts as present, by default not undefined).
+     * @returns A new schema.
+     */
+    or(...peers: Array<string | DependencyOptions>): this;
+    /**
+     * Allow at most one of the keys: none or one of them.
+     * @param peers The key names (dotted paths reach nested keys), optionally followed by the options: `separator`
+     * of the paths (default `.`), `isPresent` (what counts as present, by default not undefined).
+     * @returns A new schema.
+     */
+    oxor(...peers: Array<string | DependencyOptions>): this;
+    /**
+     * Specify validation rules for unknown keys matching a pattern.
+     *
+     * @param pattern A regular expression, or a schema, the unknown key names are tested against.
+     * @param schema The schema of the values of the matching keys.
+     * @param options `fallthrough`: whether a key matching this pattern is also tested against the following patterns
+     * (default false); `matches`: a schema the array of the matching key names must match (like
+     * `DTO.Array().max(3)`).
+     * @returns A new schema.
+     */
+    pattern(pattern: RegExp | SchemaLike, schema: SchemaLike, options?: ObjectPatternOptions): this;
+    /**
+     * Require the value to be a reference (created by `DTO.Ref()`).
+     * @returns A new schema.
+     */
+    ref(): this;
+    /**
+     * Require the value to be a `RegExp` object.
+     * @returns A new schema.
+     */
+    regex(): this;
+    /**
+     * Rename a key of the validated object, before its keys are validated: the old key is removed unless the `alias`
+     * option is set.
+     * @param from The key to rename, or a regular expression matching the keys to rename.
+     * @param to The new key name.
+     * @param options `alias` (keep the old key too), `multiple` (allow several keys renamed to the same one, the last
+     * wins), `override` (allow replacing an existing key), `ignoreUndefined` (skip an undefined value); all false by
+     * default.
+     * @returns A new schema.
+     * @throws {SchemaDefinitionException} When the key is already renamed by the schema, or renamed to itself.
+     */
+    rename(from: string | RegExp, to: string, options?: RenameOptions): this;
+    /**
+     * Require the value to be a schema (built by `DTO`).
+     * @param type The type the schema must have (`'number'`). Defaults to `any`, which accepts every schema.
+     * @returns A new schema.
+     */
+    schema(type?: SchemaLike): this;
+    /**
+     * Set whether the unknown keys are allowed, for this object only (not its children), overriding the `allowUnknown`
+     * validation option. Allowed unknown keys are kept in the validated object.
+     * @param allow True (the default) to allow and keep them, false to reject them, or a schema their values must
+     * match.
+     * @returns A new schema.
+     */
+    unknown(allow?: boolean | SchemaLike): this;
+    /**
+     * Require other keys whenever a key is present.
+     * @param key The key (a dotted path reaches a nested key).
+     * @param peers The keys required with it.
+     * @param options `separator` of the paths (default `.`), `isPresent` (what counts as present, by default not
+     * undefined).
+     * @returns A new schema.
+     */
+    with(key: string, peers: string | string[], options?: DependencyOptions): this;
+    /**
+     * Forbid other keys whenever a key is present.
+     * @param key The key (a dotted path reaches a nested key).
+     * @param peers The keys forbidden with it.
+     * @param options `separator` of the paths (default `.`), `isPresent` (what counts as present, by default not
+     * undefined).
+     * @returns A new schema.
+     */
+    without(key: string, peers: string | string[], options?: DependencyOptions): this;
+    /**
+     * Require exactly one of the keys.
+     * @param peers The key names (dotted paths reach nested keys), optionally followed by the options: `separator`
+     * of the paths (default `.`), `isPresent` (what counts as present, by default not undefined).
+     * @returns A new schema.
+     */
+    xor(...peers: Array<string | DependencyOptions>): this;
+}

package/dist/types/lib/validation/interfaces/Reference.d.ts

@@ -0,0 +1,38 @@
+import { ReferenceOptions } from './ReferenceOptions.js';
+/**
+ * A reference to another value, resolved during the validation: a sibling key (`'b'`), a key of an ancestor
+ * (`'...b'`, `'/root.key'`), or a value of the global context (`'$key'`). Created by `DTO.Ref(key)` (`DTO.In(key)` for
+ * a list of values), and given in place of a value to the rules accepting one (`min()`, `valid()`, `default()`…).
+ */
+export interface Reference extends Exclude<ReferenceOptions, 'prefix'> {
+    /**
+     * The number of keys in the path.
+     */
+    depth: number;
+    /**
+     * What the reference reaches: `value` (the validated value), `global` (the `context` validation option) or `local`
+     * (the context of an error message).
+     */
+    type: string;
+    /**
+     * The path joined by the separator (`'a.b'`), or null for the reference to the value itself.
+     */
+    key: string;
+    /**
+     * The first key of the path.
+     */
+    root: string;
+    /**
+     * The keys of the path, from the starting point of the reference.
+     */
+    path: string[];
+    /**
+     * The text of the reference in the descriptions and the error messages, like `ref:a.b` or `ref:global:key`.
+     */
+    display: string;
+    /**
+     * The text of the reference (`display`).
+     * @returns The text, like `ref:a.b`.
+     */
+    toString(): string;
+}

package/dist/types/lib/validation/interfaces/ReferenceOptions.d.ts

@@ -0,0 +1,59 @@
+import { HierarchySeparatorOptions } from './HierarchySeparatorOptions.js';
+/**
+ * The options of a reference created by `DTO.Ref()` or `DTO.In()`: how its key is read and how the value it resolves to
+ * is adjusted.
+ */
+export interface ReferenceOptions extends HierarchySeparatorOptions {
+    /**
+     * A function adjusting the resolved value, like `(value) => value + 5`. The adjusted value is not validated: it
+     * must be what the rule using the reference expects. Cannot be combined with `map`.
+     */
+    adjust?: (value: any) => any;
+    /**
+     * Pairs `[[from, to], …]` mapping the resolved value to another one; a value not in the map is used as is. Cannot
+     * be combined with `adjust`.
+     */
+    map?: Array<[any, any]>;
+    /**
+     * The characters marking the kind of a reference at the start of its key.
+     */
+    prefix?: {
+        /**
+         * The prefix of the references to the `context` validation option.
+         * @default '$'
+         */
+        global?: string;
+        /**
+         * The prefix of the references to the context of an error message or a rule.
+         * @default '#'
+         */
+        local?: string;
+        /**
+         * The prefix of the references to the root value being validated.
+         * @default '/'
+         */
+        root?: string;
+    };
+    /**
+     * The starting point of the reference: 0 for the value itself, 1 for its parent (the object holding it), 2 for the
+     * grandparent… Cannot be combined with a key starting with separators (`'...a'`).
+     * @default the number of leading separators of the key, else 1
+     */
+    ancestor?: number;
+    /**
+     * Whether the reference resolves to an array of values the value must be one of (what `DTO.In()` creates), in
+     * `valid()` and `invalid()`.
+     * @default false
+     */
+    in?: boolean;
+    /**
+     * Whether the path reaches into the `Map` and `Set` objects.
+     * @default false
+     */
+    iterables?: boolean;
+    /**
+     * Whether the error messages show the resolved value instead of the name of the reference.
+     * @default false
+     */
+    render?: boolean;
+}

package/dist/types/lib/validation/interfaces/RenameOptions.d.ts

@@ -0,0 +1,26 @@
+export interface RenameOptions {
+    /**
+     * if true, does not delete the old key name, keeping both the new and old keys in place.
+     *
+     * @default false
+     */
+    alias?: boolean;
+    /**
+     * if true, allows renaming multiple keys to the same destination where the last rename wins.
+     *
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * if true, allows renaming a key over an existing key.
+     *
+     * @default false
+     */
+    override?: boolean;
+    /**
+     * if true, skip renaming of a key if it's undefined.
+     *
+     * @default false
+     */
+    ignoreUndefined?: boolean;
+}

package/dist/types/lib/validation/interfaces/RuleOptions.d.ts

@@ -0,0 +1,22 @@
+import { LanguageMessages } from '../types/LanguageMessages.js';
+export interface RuleOptions {
+    /**
+     * if true, the rules will not be replaced by the same unique rule later.
+     *
+     * For example, `VLD.number().min(1).rule({ keep: true }).min(2)` will keep both `min()` rules instead of the later rule overriding the first.
+     *
+     * @default false
+     */
+    keep?: boolean;
+    /**
+     * a single message string or a messages object where each key is an error code and corresponding message string as value.
+     *
+     * The object is the same as the messages used as an option in `any.validate()`.
+     * The strings can be plain messages or a message template.
+     */
+    message?: string | LanguageMessages;
+    /**
+     * if true, turns any error generated by the ruleset to warnings.
+     */
+    warn?: boolean;
+}