@lakutata/core 1.0.60 → 3.0.0-beta.0

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

@@ -0,0 +1,97 @@
+import { ErrorFormattingOptions } from './ErrorFormattingOptions.js';
+import { PresenceMode } from '../types/PresenceMode.js';
+import { Context } from './Context.js';
+export interface BaseValidationOptions {
+    /**
+     * when true, stops validation on the first error, otherwise returns all the errors found.
+     *
+     * @default true
+     */
+    abortEarly?: boolean;
+    /**
+     * When true, the objects may contain unknown keys; when false, they are rejected, unless `stripUnknown` removes
+     * them. `ObjectSchema.unknown()` overrides it for an object.
+     *
+     * @default true (lakutata)
+     */
+    allowUnknown?: boolean;
+    /**
+     * when true, return artifacts alongside the value.
+     *
+     * @default false
+     */
+    artifacts?: boolean;
+    /**
+     * when true, schema caching is enabled (for schemas with explicit caching rules).
+     *
+     * @default false
+     */
+    cache?: boolean;
+    /**
+     * provides an external data set to be used in references
+     */
+    context?: Context;
+    /**
+     * when true, attempts to cast values to the required types (e.g. a string to a number).
+     *
+     * @default true
+     */
+    convert?: boolean;
+    /**
+     * sets the string format used when converting dates to strings in error messages and casting.
+     *
+     * @default 'iso'
+     */
+    dateFormat?: 'date' | 'iso' | 'string' | 'time' | 'utc';
+    /**
+     * when true, valid results and throw errors are decorated with a debug property which includes an array of the validation steps used to generate the returned result.
+     *
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * error formatting settings.
+     */
+    errors?: ErrorFormattingOptions;
+    /**
+     * if false, the external rules set with `any.external()` are ignored, which is required to ignore any external validations in synchronous mode (or an exception is thrown).
+     *
+     * @default true
+     */
+    externals?: boolean;
+    /**
+     * when true, do not apply default values.
+     *
+     * @default false
+     */
+    noDefaults?: boolean;
+    /**
+     * when true, inputs are shallow cloned to include non-enumerable properties.
+     *
+     * @default false
+     */
+    nonEnumerables?: boolean;
+    /**
+     * sets the default presence requirements. Supported modes: 'optional', 'required', and 'forbidden'.
+     *
+     * @default 'optional'
+     */
+    presence?: PresenceMode;
+    /**
+     * when true, ignores unknown keys with a function value.
+     *
+     * @default false
+     */
+    skipFunctions?: boolean;
+    /**
+     * Remove the unknown elements instead of rejecting them: true (or `{objects: true}`) removes the unknown keys of the
+     * objects, `{arrays: true}` the array items matching none of the item schemas. The keys an object allows with
+     * `unknown()` are kept.
+     *
+     * @default true (lakutata)
+     */
+    stripUnknown?: boolean | {
+        arrays?: boolean;
+        objects?: boolean;
+    };
+}

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

@@ -0,0 +1,67 @@
+import { AnySchema } from './AnySchema.js';
+import { Reference } from './Reference.js';
+/**
+ * A schema of bigints, built by `DTO.BigInt()`, for the integers beyond the safe integers of the numbers. With
+ * conversion enabled (`strict(false)`), the integer strings and the integer numbers are accepted and converted to
+ * bigints. Its limits and its base may be references to other values (`DTO.Ref('min')`), resolved when validating: a
+ * reference resolving to a value which is not a bigint fails the validation.
+ * @typeParam T The type of the bigints the schema validates.
+ */
+export interface BigIntSchema<T = bigint> extends AnySchema<T> {
+    /**
+     * Require the bigint to be greater than a limit.
+     * @param limit The limit (exclusive): a bigint, or a reference to one.
+     * @returns A new schema.
+     * @throws {SchemaDefinitionException} When it is neither a bigint nor a reference.
+     */
+    greater(limit: bigint | Reference): this;
+    /**
+     * Require the bigint to be less than a limit.
+     * @param limit The limit (exclusive): a bigint, or a reference to one.
+     * @returns A new schema.
+     * @throws {SchemaDefinitionException} When it is neither a bigint nor a reference.
+     */
+    less(limit: bigint | Reference): this;
+    /**
+     * Require the bigint to be at most a limit.
+     * @param limit The maximum (inclusive): a bigint, or a reference to one.
+     * @returns A new schema.
+     * @throws {SchemaDefinitionException} When it is neither a bigint nor a reference.
+     */
+    max(limit: bigint | Reference): this;
+    /**
+     * Require the bigint to be at least a limit.
+     * @param limit The minimum (inclusive): a bigint, or a reference to one.
+     * @returns A new schema.
+     * @throws {SchemaDefinitionException} When it is neither a bigint nor a reference.
+     */
+    min(limit: bigint | Reference): this;
+    /**
+     * Require the bigint to be a multiple of a base: 0 and the negative multiples included.
+     * @param base The base: a positive bigint, or a reference to one.
+     * @returns A new schema.
+     * @throws {SchemaDefinitionException} When it is neither a positive bigint nor a reference.
+     */
+    multiple(base: bigint | Reference): this;
+    /**
+     * Require the bigint to be negative (less than 0n).
+     * @returns A new schema.
+     */
+    negative(): this;
+    /**
+     * Require the bigint to be a TCP port: from 0n to 65535n.
+     * @returns A new schema.
+     */
+    port(): this;
+    /**
+     * Require the bigint to be positive (greater than 0n).
+     * @returns A new schema.
+     */
+    positive(): this;
+    /**
+     * Require the bigint to be negative or positive (0n is neither).
+     * @param sign The sign required.
+     * @returns A new schema.
+     */
+    sign(sign: 'positive' | 'negative'): this;
+}

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

@@ -0,0 +1,33 @@
+import { AnySchema } from './AnySchema.js';
+import { Reference } from './Reference.js';
+/**
+ * A schema of `Buffer`s, built by `DTO.Binary()`: their length in bytes. With conversion enabled (`strict(false)`),
+ * strings are accepted and converted to buffers (see `encoding()`).
+ * @typeParam TSchema The type of the buffers the schema validates.
+ */
+export interface BinarySchema<TSchema = Buffer> extends AnySchema<TSchema> {
+    /**
+     * Set the encoding of the strings converted to buffers, with conversion enabled (`strict(false)`).
+     * @param encoding A Node.js buffer encoding: `'base64'`, `'hex'`, `'utf8'`… Defaults to `utf8`.
+     * @returns A new schema.
+     */
+    encoding(encoding: string): this;
+    /**
+     * Require a minimum length.
+     * @param limit The minimum length (inclusive) in bytes, or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    min(limit: number | Reference): this;
+    /**
+     * Require a maximum length.
+     * @param limit The maximum length (inclusive) in bytes, or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    max(limit: number | Reference): this;
+    /**
+     * Require an exact length.
+     * @param limit The length in bytes, or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    length(limit: number | Reference): this;
+}

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

@@ -0,0 +1,29 @@
+import { AnySchema } from './AnySchema.js';
+/**
+ * A schema of booleans, built by `DTO.Boolean()`. With conversion enabled (`strict(false)`), the strings `'true'` and
+ * `'false'` (case-insensitively) and the values of `truthy()` and `falsy()` are accepted and converted to booleans.
+ * @typeParam TSchema The type of the booleans the schema validates.
+ */
+export interface BooleanSchema<TSchema = boolean> extends AnySchema<TSchema> {
+    /**
+     * Accept other values as false, with conversion enabled (`strict(false)`). The strings are compared
+     * case-insensitively unless `sensitive()` is called.
+     * @param values The values converted to false: strings, numbers or null.
+     * @returns A new schema.
+     */
+    falsy(...values: Array<string | number | null>): this;
+    /**
+     * Compare the strings converted to booleans (`'true'`, `'false'`, and the ones of `truthy()` and `falsy()`)
+     * case-sensitively.
+     * @param enabled Whether the comparison is case-sensitive. Defaults to true.
+     * @returns A new schema.
+     */
+    sensitive(enabled?: boolean): this;
+    /**
+     * Accept other values as true, with conversion enabled (`strict(false)`). The strings are compared
+     * case-insensitively unless `sensitive()` is called.
+     * @param values The values converted to true: strings, numbers or null.
+     * @returns A new schema.
+     */
+    truthy(...values: Array<string | number | null>): this;
+}

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

@@ -0,0 +1,14 @@
+export interface Cache {
+    /**
+     * Add an item to the cache.
+     *
+     * Note that key and value can be anything including objects, array, etc.
+     */
+    set(key: any, value: any): void;
+    /**
+     * Retrieve an item from the cache.
+     *
+     * Note that key and value can be anything including objects, array, etc.
+     */
+    get(key: any): any;
+}

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

@@ -0,0 +1,15 @@
+import { Cache } from './Cache.js';
+export interface CacheProvisionOptions {
+    /**
+     * number of items to store in the cache before the least used items are dropped.
+     *
+     * @default 1000
+     */
+    max: number;
+}
+export interface CacheConfiguration {
+    /**
+     * Provisions a simple LRU cache for caching simple inputs (`undefined`, `null`, strings, numbers, and booleans).
+     */
+    provision(options?: CacheProvisionOptions): Cache;
+}

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

@@ -0,0 +1,9 @@
+export interface CompileOptions {
+    /**
+     * If true and the provided schema is (or contains parts) using an older version of the validation engine, will
+     * return a compiled schema that is compatible with the older version.
+     * If false, the schema is always compiled using the current version and if older schema components are found, an
+     * error is thrown.
+     */
+    legacy: boolean;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * The local context of a validation error, available to its message template
+ */
+export interface Context {
+    [key: string]: any;
+    key?: string;
+    label?: string;
+    value?: any;
+}

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

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

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

@@ -0,0 +1,8 @@
+export interface DataUriOptions {
+    /**
+     * optional parameter defaulting to true which will require `=` padding if true or make padding optional if false
+     *
+     * @default true
+     */
+    paddingRequired?: boolean;
+}

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

@@ -0,0 +1,48 @@
+import { AnySchema } from './AnySchema.js';
+import { Reference } from './Reference.js';
+/**
+ * A schema of dates, built by `DTO.Date()`: `Date` objects, between limits. With conversion enabled
+ * (`strict(false)`), date strings and timestamps (milliseconds) are accepted and converted to `Date` objects.
+ * @typeParam TSchema The type of the dates the schema validates.
+ */
+export interface DateSchema<TSchema = Date> extends AnySchema<TSchema> {
+    /**
+     * Require the date to be after a date (exclusive).
+     * @param date The date: a `Date`, a timestamp in milliseconds, a date string, `'now'` (the time of the
+     * validation, to require a date in the past or the future), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    greater(date: 'now' | Date | number | string | Reference): this;
+    /**
+     * Require the date strings converted (with conversion enabled, `strict(false)`) to be in the ISO 8601 format.
+     * @returns A new schema.
+     */
+    iso(): this;
+    /**
+     * Require the date to be before a date (exclusive).
+     * @param date The date: a `Date`, a timestamp in milliseconds, a date string, `'now'` (the time of the
+     * validation, to require a date in the past or the future), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    less(date: 'now' | Date | number | string | Reference): this;
+    /**
+     * Require the date to be a date or later (inclusive).
+     * @param date The date: a `Date`, a timestamp in milliseconds, a date string, `'now'` (the time of the
+     * validation, to require a date in the past or the future), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    min(date: 'now' | Date | number | string | Reference): this;
+    /**
+     * Require the date to be a date or earlier (inclusive).
+     * @param date The date: a `Date`, a timestamp in milliseconds, a date string, `'now'` (the time of the
+     * validation, to require a date in the past or the future), or a reference to another value holding it.
+     * @returns A new schema.
+     */
+    max(date: 'now' | Date | number | string | Reference): this;
+    /**
+     * Require the dates converted (with conversion enabled, `strict(false)`) to be given as timestamps.
+     * @param type The unit of the timestamps: `javascript` (milliseconds, the default) or `unix` (seconds).
+     * @returns A new schema.
+     */
+    timestamp(type?: 'javascript' | 'unix'): this;
+}

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

@@ -0,0 +1,9 @@
+import { HierarchySeparatorOptions } from './HierarchySeparatorOptions.js';
+export interface DependencyOptions extends HierarchySeparatorOptions {
+    /**
+     * overrides the default check for a present value.
+     *
+     * @default (resolved) => resolved !== undefined
+     */
+    isPresent?: (resolved: any) => boolean;
+}

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

@@ -0,0 +1,20 @@
+import { Types } from '../types/Types.js';
+import { ValidationOptions } from './ValidationOptions.js';
+/**
+ * A schema description (describe())
+ */
+export interface Description {
+    type?: Types | string;
+    label?: string;
+    description?: string;
+    flags?: object;
+    notes?: string[];
+    tags?: string[];
+    metas?: any[];
+    example?: any[];
+    valids?: any[];
+    invalids?: any[];
+    unit?: string;
+    options?: ValidationOptions;
+    [key: string]: any;
+}

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

@@ -0,0 +1,33 @@
+import { TopLevelDomainOptions } from './TopLevelDomainOptions.js';
+export interface DomainOptions {
+    /**
+     * if `true`, domains ending with a `.` character are permitted
+     *
+     * @default false
+     */
+    allowFullyQualified?: boolean;
+    /**
+     * If `true`, Unicode characters are permitted
+     *
+     * @default true
+     */
+    allowUnicode?: boolean;
+    /**
+     * Options for TLD (top level domain) validation. By default, the TLD must be a valid name listed on the [IANA registry](http://data.iana.org/TLD/tlds-alpha-by-domain.txt)
+     *
+     * @default { allow: true }
+     */
+    tlds?: TopLevelDomainOptions | false;
+    /**
+     * Number of segments required for the domain.
+     *
+     * @default 2
+     */
+    minDomainSegments?: number;
+    /**
+     * The maximum number of domain segments (e.g. `x.y.z` has 3 segments) allowed. Defaults to no limit.
+     *
+     * @default Infinity
+     */
+    maxDomainSegments?: number;
+}

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

@@ -0,0 +1,51 @@
+import { TopLevelDomainOptions } from './TopLevelDomainOptions.js';
+export interface EmailOptions {
+    /**
+     * if `true`, domains ending with a `.` character are permitted
+     *
+     * @default false
+     */
+    allowFullyQualified?: boolean;
+    /**
+     * If `true`, Unicode characters are permitted
+     *
+     * @default true
+     */
+    allowUnicode?: boolean;
+    /**
+     * if `true`, ignore invalid email length errors.
+     *
+     * @default false
+     */
+    ignoreLength?: boolean;
+    /**
+     * if true, allows multiple email addresses in a single string, separated by , or the separator characters.
+     *
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * when multiple is true, overrides the default , separator. String can be a single character or multiple separator characters.
+     *
+     * @default ','
+     */
+    separator?: string | string[];
+    /**
+     * Options for TLD (top level domain) validation. By default, the TLD must be a valid name listed on the [IANA registry](http://data.iana.org/TLD/tlds-alpha-by-domain.txt)
+     *
+     * @default { allow: true }
+     */
+    tlds?: TopLevelDomainOptions | false;
+    /**
+     * Number of segments required for the domain. Be careful since some domains, such as `io`, directly allow email.
+     *
+     * @default 2
+     */
+    minDomainSegments?: number;
+    /**
+     * The maximum number of domain segments (e.g. `x.y.z` has 3 segments) allowed. Defaults to no limit.
+     *
+     * @default Infinity
+     */
+    maxDomainSegments?: number;
+}

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

@@ -0,0 +1,60 @@
+import { LanguageMessages } from '../types/LanguageMessages.js';
+export interface ErrorFormattingOptions {
+    /**
+     * when true, error message templates will escape special characters to HTML entities, for security purposes.
+     *
+     * @default false
+     */
+    escapeHtml?: boolean;
+    /**
+     * defines the value used to set the label context variable.
+     */
+    label?: 'path' | 'key' | false;
+    /**
+     * The preferred language code for error messages.
+     * The value is matched against keys at the root of the messages object, and then the error code as a child key of that.
+     * Can be a reference to the value, global context, or local context which is the root value passed to the validation function.
+     *
+     * Note that references to the value are usually not what you want as they move around the value structure relative to where the error happens.
+     * Instead, either use the global context, or the absolute value (e.g. `VLD.ref('/variable')`)
+     */
+    language?: keyof LanguageMessages;
+    /**
+     * when false, skips rendering error templates. Useful when error messages are generated elsewhere to save processing time.
+     *
+     * @default true
+     */
+    render?: boolean;
+    /**
+     * when true, the main error will possess a stack trace, otherwise it will be disabled.
+     * Defaults to false for performances reasons. Has no effect on platforms other than V8/node.js as it uses the Stack trace API.
+     *
+     * @default false
+     */
+    stack?: boolean;
+    /**
+     * overrides the way values are wrapped (e.g. `[]` around arrays, `""` around labels).
+     * Each key can be set to a string with one (same character before and after the value) or two characters (first character
+     * before and second character after), or `false` to disable wrapping.
+     */
+    wrap?: {
+        /**
+         * the characters used around `{#label}` references. Defaults to `'"'`.
+         *
+         * @default '"'
+         */
+        label?: string | false;
+        /**
+         * the characters used around array values. Defaults to `'[]'`
+         *
+         * @default '[]'
+         */
+        array?: string | false;
+        /**
+         * the characters used around array string values. Defaults to no wrapping.
+         *
+         * @default false
+         */
+        string?: string | false;
+    };
+}

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

@@ -0,0 +1,14 @@
+import { ErrorValidationOptions } from './ErrorValidationOptions.js';
+import { LanguageMessages } from '../types/LanguageMessages.js';
+import { State } from './State.js';
+import { ExtensionFlag } from './ExtensionFlag.js';
+export interface ErrorReport extends Error {
+    code: string;
+    flags: Record<string, ExtensionFlag>;
+    path: string[];
+    prefs: ErrorValidationOptions;
+    messages: LanguageMessages;
+    state: State;
+    value: any;
+    local: any;
+}

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

@@ -0,0 +1,5 @@
+import { BaseValidationOptions } from './BaseValidationOptions.js';
+import { LanguageMessageTemplate } from './LanguageMessageTemplate.js';
+export interface ErrorValidationOptions extends BaseValidationOptions {
+    messages?: Record<string, LanguageMessageTemplate>;
+}

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

@@ -0,0 +1,100 @@
+import { Schema } from '../types/Schema.js';
+import { SchemaLike } from '../types/SchemaLike.js';
+import { LanguageMessages } from '../types/LanguageMessages.js';
+import { ExtensionBoundSchema } from '../types/ExtensionBoundSchema.js';
+import { AnySchema } from './AnySchema.js';
+import { CustomHelpers } from './CustomHelpers.js';
+import { ErrorReport } from './ErrorReport.js';
+import { ExtensionFlag } from './ExtensionFlag.js';
+import { SchemaInternals } from './SchemaInternals.js';
+export interface RuleArgs {
+    name: string;
+    ref?: boolean;
+    assert?: ((value: any) => boolean) | AnySchema;
+    message?: string;
+    /**
+     * Undocumented properties
+     */
+    normalize?(value: any): any;
+}
+export type RuleMethod = (...args: any[]) => any;
+export interface ExtensionRule {
+    /**
+     * alternative name for this rule.
+     */
+    alias?: string;
+    /**
+     * whether rule supports multiple invocations.
+     */
+    multi?: boolean;
+    /**
+     * Dual rule: converts or validates.
+     */
+    convert?: boolean;
+    /**
+     * list of arguments accepted by `method`.
+     */
+    args?: Array<RuleArgs | string>;
+    /**
+     * rule body.
+     */
+    method?: RuleMethod | false;
+    /**
+     * validation function.
+     */
+    validate?(value: any, helpers: any, args: Record<string, any>, options: any): any;
+    /**
+     * undocumented flags.
+     */
+    priority?: boolean;
+    manifest?: boolean;
+}
+export interface CoerceResult {
+    errors?: ErrorReport[];
+    value?: any;
+}
+export type CoerceFunction = (value: any, helpers: CustomHelpers) => CoerceResult;
+export interface CoerceObject {
+    method: CoerceFunction;
+    from?: string | string[];
+}
+export interface ExtensionTermManifest {
+    mapped: {
+        from: string;
+        to: string;
+    };
+}
+export interface ExtensionTerm {
+    init: any[] | null;
+    register?: any;
+    manifest?: Record<string, 'schema' | 'single' | ExtensionTermManifest>;
+}
+/**
+ * A validation extension: a new type, or an existing type extended
+ */
+export interface Extension {
+    type: string | RegExp;
+    args?(...args: SchemaLike[]): Schema;
+    base?: Schema;
+    coerce?: CoerceFunction | CoerceObject;
+    flags?: Record<string, ExtensionFlag>;
+    manifest?: {
+        build?(obj: ExtensionBoundSchema, desc: Record<string, any>): any;
+    };
+    messages?: LanguageMessages | string;
+    modifiers?: Record<string, (rule: any, enabled?: boolean) => any>;
+    overrides?: Record<string, (value: any) => Schema>;
+    prepare?(value: any, helpers: CustomHelpers): any;
+    rebuild?(schema: ExtensionBoundSchema): void;
+    rules?: Record<string, ExtensionRule & ThisType<SchemaInternals>>;
+    terms?: Record<string, ExtensionTerm>;
+    validate?(value: any, helpers: CustomHelpers): any;
+    /**
+     * undocumented options
+     */
+    cast?: Record<string, {
+        from(value: any): any;
+        to(value: any, helpers: CustomHelpers): any;
+    }>;
+    properties?: Record<string, any>;
+}

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

@@ -0,0 +1,4 @@
+export interface ExtensionFlag {
+    setter?: string;
+    default?: any;
+}