@lakutata/core 1.0.59 → 3.0.0-beta.0

package/dist/types/lib/validation/engine/schema/types/string.d.ts

@@ -0,0 +1,115 @@
+import { type AnySchema, type AnyTerms } from './any.js';
+import type { SchemaTerms } from '../base.js';
+/**
+ * A replacement applied to the value before validation (see string.replace())
+ */
+export interface StringReplacement {
+    pattern: RegExp;
+    replacement: string;
+}
+/**
+ * The terms of string schemas
+ */
+export interface StringTerms {
+    replacements: StringReplacement[] | null;
+}
+/**
+ * The top level domain options of the domain, email and uri rules
+ */
+export interface TldsOptions {
+    allow?: Set<string> | string[] | boolean;
+    deny?: Set<string> | string[] | null;
+}
+/**
+ * The options of the domain rule (and of the domain option of the uri rule)
+ */
+export interface DomainOptions {
+    allowFullyQualified?: boolean;
+    allowUnicode?: boolean;
+    allowUnderscore?: boolean;
+    maxDomainSegments?: number;
+    minDomainSegments?: number;
+    tlds?: TldsOptions | boolean;
+}
+/**
+ * The options of the email rule
+ */
+export interface EmailOptions extends DomainOptions {
+    ignoreLength?: boolean;
+    multiple?: boolean;
+    separator?: string;
+}
+export interface Base64Options {
+    paddingRequired?: boolean;
+    urlSafe?: boolean;
+}
+export interface DataUriOptions {
+    paddingRequired?: boolean;
+}
+export interface GuidOptions {
+    version?: string | string[];
+    separator?: boolean | '-' | ':';
+    wrapper?: boolean | string;
+}
+export interface HexOptions {
+    byteAligned?: boolean;
+    prefix?: boolean | 'optional';
+}
+export interface IpOptions {
+    cidr?: 'optional' | 'required' | 'forbidden';
+    version?: string | string[];
+}
+export interface PatternOptions {
+    invert?: boolean;
+    name?: string;
+}
+export interface UriOptions {
+    allowRelative?: boolean;
+    allowQuerySquareBrackets?: boolean;
+    domain?: DomainOptions;
+    relativeOnly?: boolean;
+    scheme?: string | RegExp | (string | RegExp)[];
+    encodeUri?: boolean;
+}
+/**
+ * The string schema
+ */
+export interface StringSchema extends AnySchema {
+    $_terms: SchemaTerms & AnyTerms & StringTerms;
+    alphanum(): this;
+    base64(options?: Base64Options): this;
+    case(direction: 'lower' | 'upper'): this;
+    creditCard(): this;
+    dataUri(options?: DataUriOptions): this;
+    domain(options?: DomainOptions): this;
+    email(options?: EmailOptions): this;
+    format(name: string): this;
+    guid(options?: GuidOptions): this;
+    uuid(options?: GuidOptions): this;
+    hex(options?: HexOptions): this;
+    hostname(): this;
+    insensitive(): this;
+    ip(options?: IpOptions): this;
+    isoDate(): this;
+    isoDuration(): this;
+    length(limit: unknown, encoding?: string): this;
+    lowercase(): this;
+    max(limit: unknown, encoding?: string): this;
+    min(limit: unknown, encoding?: string): this;
+    normalize(form?: string): this;
+    pattern(regex: RegExp, options?: PatternOptions | string): this;
+    regex(regex: RegExp, options?: PatternOptions | string): this;
+    replace(pattern: RegExp | string, replacement: string): this;
+    token(): this;
+    trim(enabled?: boolean): this;
+    truncate(enabled?: boolean): this;
+    uppercase(): this;
+    uri(options?: UriOptions): this;
+}
+declare const StringType: StringSchema;
+export default StringType;
+/**
+ * The length of a string in Unicode code points (a surrogate pair is one character, a lone surrogate too)
+ * @param value
+ */
+export declare function codePointLength(value: string): number;

package/dist/types/lib/validation/engine/schema/types/symbol.d.ts

@@ -0,0 +1,23 @@
+import { type AnySchema, type AnyTerms } from './any.js';
+import type { SchemaTerms } from '../base.js';
+/**
+ * A map of keys to symbols, sliced (copied) when the schema is cloned
+ */
+declare class SymbolMap extends Map<unknown, symbol> {
+    slice(): SymbolMap;
+}
+/**
+ * The terms of symbol schemas
+ */
+export interface SymbolTerms {
+    map: SymbolMap;
+}
+/**
+ * The symbol schema
+ */
+export interface SymbolSchema extends AnySchema {
+    $_terms: SchemaTerms & AnyTerms & SymbolTerms;
+    map(iterable: Iterable<unknown> | Record<string, symbol>): this;
+}
+declare const SymbolType: SymbolSchema;
+export default SymbolType;

package/dist/types/lib/validation/engine/schema/validator.d.ts

@@ -0,0 +1,114 @@
+import * as Errors from './errors.js';
+import type { MessagesInput } from './messages.js';
+import type { PathKey, Preferences, SchemaInternals } from './model.js';
+import { type Shadow, State } from './state.js';
+import type { DebugEvent, Store } from './trace.js';
+/**
+ * The tracer parts a validation uses (a coverage store, or a no-op tracer)
+ */
+export type ValidationTracer = Pick<Store, 'active' | 'debug' | 'entry' | 'filter' | 'log' | 'resolve' | 'value'>;
+/**
+ * The helpers passed to an external rule
+ */
+export interface ExternalHelpers {
+    schema: SchemaInternals;
+    linked: SchemaInternals | null;
+    state: State;
+    prefs: Preferences | undefined;
+    original: unknown;
+    error(code: string, local?: Errors.ReportLocal | null): Errors.Report;
+    errorsArray(): Errors.ErrorItem[];
+    warn(code: string, local?: Errors.ReportLocal | null): void;
+    message(messages: MessagesInput, local?: Errors.ReportLocal | null): Errors.Report;
+}
+export type ExternalMethod = (value: unknown, helpers: ExternalHelpers) => unknown;
+/**
+ * An external rule, queued to run after the validation (by validateAsync())
+ */
+export interface External {
+    method: ExternalMethod;
+    schema: SchemaInternals;
+    state: State;
+    label: unknown;
+}
+/**
+ * The outcome of a (synchronous) validation
+ */
+export interface ValidationResult {
+    value: unknown;
+    error?: Error;
+    warning?: Errors.ErrorsDetails;
+    debug?: DebugEvent[];
+    artifacts?: Map<unknown, PathKey[][]>;
+}
+/**
+ * The value and errors of the validation of a schema
+ */
+export interface SchemaResult {
+    value: unknown;
+    errors: Errors.ErrorItem[] | null;
+}
+type Presence = Preferences['presence'] | null;
+interface Snapshot {
+    externals: External[];
+    warnings: Errors.ErrorItem[];
+}
+/**
+ * Validation-wide state shared by all the states of one validation
+ */
+export declare class Mainstay {
+    externals: External[];
+    warnings: Errors.ErrorItem[];
+    tracer: ValidationTracer;
+    debug: DebugEvent[] | null;
+    links: Map<SchemaInternals, SchemaInternals> | null;
+    shadow: Shadow | null;
+    artifacts: Map<unknown, PathKey[][]> | null;
+    protected _snapshots: Snapshot[];
+    constructor(tracer: ValidationTracer, debug: DebugEvent[] | null, links: Map<SchemaInternals, SchemaInternals> | null);
+    snapshot(): void;
+    restore(): void;
+    commit(): void;
+}
+/**
+ * Validate a value (synchronously)
+ * @param value
+ * @param schema
+ * @param prefs
+ */
+export declare function entry(value: unknown, schema: SchemaInternals, prefs?: Preferences): ValidationResult;
+/**
+ * Validate a value, running the external rules; throws the validation error
+ * @param value
+ * @param schema
+ * @param prefs
+ */
+export declare function entryAsync(value: unknown, schema: SchemaInternals, prefs?: Preferences): Promise<unknown>;
+/**
+ * Validate a value, asynchronously when the schema is asynchronous (Standard Schema)
+ * @param value
+ * @param schema
+ */
+export declare function standard(value: unknown, schema: SchemaInternals): ValidationResult | Promise<unknown>;
+/**
+ * Validate a value against a schema, in the state of a validation
+ * @param value
+ * @param schema
+ * @param state
+ * @param prefs
+ * @param overrides
+ */
+export declare function validate(value: unknown, schema: SchemaInternals, state: State, prefs: Preferences, overrides?: {
+    presence?: Presence;
+}): SchemaResult;
+/**
+ * The mode of the validation fast path (fastpath.ts): 'on' (the default), 'off' (interpreter only), or 'verify' (both
+ * run, for any settings, and a different result throws: for tests)
+ */
+export type FastPathMode = 'on' | 'off' | 'verify';
+/**
+ * Set the mode of the validation fast path
+ * @param mode
+ */
+export declare function setFastPathMode(mode: FastPathMode): void;
+export {};

package/dist/types/lib/validation/engine/schema/values.d.ts

@@ -0,0 +1,51 @@
+import type { Preferences, StateLike } from './model.js';
+import type { Manager } from './ref.js';
+/**
+ * A resolvable value (reference or template) of a values set
+ */
+export interface ResolvableValue {
+    in?: boolean;
+    resolve(value: unknown, state: StateLike, prefs: Preferences, local: unknown, options?: {
+        in?: boolean;
+    }): unknown;
+    describe(): unknown;
+}
+/**
+ * A match of a values set: the matched value, and the reference it came from
+ */
+export interface ValuesMatch {
+    value: unknown;
+    ref?: ResolvableValue;
+}
+export type ValuesDescription = ({
+    override: true;
+} | {
+    value: unknown;
+} | unknown)[];
+/**
+ * A set of allowed (valid) or forbidden (invalid) values and references
+ */
+export declare class Values {
+    _values: Set<unknown>;
+    _refs: Set<ResolvableValue>;
+    protected _lowercase: Map<string, string>;
+    protected _override: boolean;
+    constructor(values?: Iterable<unknown>, refs?: Iterable<ResolvableValue>);
+    get length(): number;
+    add(value: unknown, refs?: Manager): void;
+    static merge(target: Values | null | undefined, source: Values | null | undefined, remove?: Values | null): Values | null;
+    remove(value: unknown): void;
+    has(value: unknown, state: StateLike | null, prefs: Preferences | null, insensitive?: boolean): boolean;
+    get(value: unknown, state: StateLike | null, prefs: Preferences | null, insensitive?: boolean): ValuesMatch | false;
+    override(): void;
+    values(options?: {
+        display?: boolean;
+    }): unknown[];
+    clone(): Values;
+    /**
+     * Alias of clone()
+     */
+    slice(): Values;
+    concat(source: Values): Values;
+    describe(): ValuesDescription;
+}

package/dist/types/lib/validation/engine/sorter/index.d.ts

@@ -0,0 +1,54 @@
+export interface SorterOptions {
+    /**
+     * The group name of the added nodes, defaults to '?'
+     */
+    readonly group?: string;
+    /**
+     * Groups the nodes must come before
+     */
+    readonly before?: string | string[];
+    /**
+     * Groups the nodes must come after
+     */
+    readonly after?: string | string[];
+    /**
+     * Sort order used when merging sorters, defaults to 0
+     */
+    readonly sort?: number;
+    /**
+     * Skip sorting (call sort() manually), defaults to false
+     */
+    readonly manual?: boolean;
+}
+interface SorterItem<T> {
+    seq: number;
+    sort: number;
+    before: string[];
+    after: string[];
+    group: string;
+    node: T;
+}
+/**
+ * Topological sorter of nodes with group dependencies
+ */
+export declare class Sorter<T> {
+    nodes: T[];
+    protected _items: SorterItem<T>[];
+    /**
+     * Add nodes, returning the sorted nodes
+     * @param nodes
+     * @param options
+     */
+    add(nodes: T | T[], options?: SorterOptions): T[];
+    /**
+     * Merge other sorters into this one, returning the sorted nodes
+     * @param others
+     */
+    merge(others: Sorter<T> | Sorter<T>[] | null | undefined): T[];
+    /**
+     * Sort the nodes (when added with manual), returning the sorted nodes
+     */
+    sort(): T[];
+    protected _sort(): boolean;
+}
+export {};

package/dist/types/lib/validation/engine/tlds/index.d.ts

@@ -0,0 +1 @@
+export declare const tlds: Set<string>;

package/dist/types/lib/validation/engine/tlds/tlds.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Derived from the upstream src/tlds.ts (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+export declare const TLDS: string[];

package/dist/types/lib/validation/engine/utils/applyToDefaults.d.ts

@@ -0,0 +1,17 @@
+export interface ApplyToDefaultsOptions {
+    /**
+     * Override the default value with null source values, defaults to false
+     */
+    readonly nullOverride?: boolean;
+    /**
+     * Keys (paths) whose values are copied by reference
+     */
+    readonly shallow?: string[] | string[][];
+}
+/**
+ * Apply source to a copy of the defaults
+ * @param defaults
+ * @param source true to return a copy of the defaults, a falsy value to return null
+ * @param options
+ */
+export declare function applyToDefaults<T extends object>(defaults: T, source: Partial<T> | object | boolean | null | undefined, options?: ApplyToDefaultsOptions): T | null;

package/dist/types/lib/validation/engine/utils/assert.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Throw an AssertError (or the given error) when the condition is falsy
+ * @param condition
+ * @param args message parts (strings, errors or values to stringify), or a single error to throw
+ */
+export declare function assert(condition: unknown, ...args: unknown[]): asserts condition;

package/dist/types/lib/validation/engine/utils/assertError.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Derived from the upstream lib/assertError.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * Error thrown by assert()
+ */
+export declare class AssertError extends Error {
+    name: "AssertError";
+    constructor(message?: string, ctor?: Function);
+}

package/dist/types/lib/validation/engine/utils/clone.d.ts

@@ -0,0 +1,25 @@
+export interface CloneOptions {
+    /**
+     * Clone the object's prototype, defaults to true
+     */
+    readonly prototype?: boolean;
+    /**
+     * Include symbol properties, defaults to true
+     */
+    readonly symbols?: boolean;
+    /**
+     * Shallow clone the specified keys (paths), or the whole object when true
+     */
+    readonly shallow?: string[] | string[][] | boolean;
+}
+/**
+ * Map of already cloned objects to their clones
+ */
+export type CloneSeen = Map<unknown, unknown>;
+/**
+ * Deep clone an object or array
+ * @param obj
+ * @param options
+ * @param _seen already cloned objects, internal
+ */
+export declare function clone<T>(obj: T, options?: CloneOptions, _seen?: CloneSeen | null): T;

package/dist/types/lib/validation/engine/utils/deepEqual.d.ts

@@ -0,0 +1,29 @@
+export interface DeepEqualOptions {
+    /**
+     * Compare functions by their source code, defaults to false
+     */
+    readonly deepFunction?: boolean;
+    /**
+     * Allow a partial match, defaults to false
+     */
+    readonly part?: boolean;
+    /**
+     * Compare the objects' prototypes, defaults to true
+     */
+    readonly prototype?: boolean;
+    /**
+     * Property keys to skip
+     */
+    readonly skip?: (string | symbol)[];
+    /**
+     * Compare symbol properties, defaults to true
+     */
+    readonly symbols?: boolean;
+}
+/**
+ * Perform a deep comparison of the two values including support for circular dependencies, prototype, and enumerable properties
+ * @param obj
+ * @param ref
+ * @param options
+ */
+export declare function deepEqual(obj: unknown, ref: unknown, options?: DeepEqualOptions): boolean;

package/dist/types/lib/validation/engine/utils/escapeHtml.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Derived from the upstream lib/escapeHtml.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * Escape a string for HTML
+ * @param input
+ */
+export declare function escapeHtml(input: string): string;

package/dist/types/lib/validation/engine/utils/escapeRegex.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Derived from the upstream lib/escapeRegex.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * Escape a string for use in a regular expression: ^$.*+-?=!:|\/()[]{},
+ * @param string
+ */
+export declare function escapeRegex(string: string): string;

package/dist/types/lib/validation/engine/utils/ignore.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Derived from the upstream lib/ignore.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * A no-op function
+ * @param _args
+ */
+export declare function ignore(..._args: unknown[]): void;

package/dist/types/lib/validation/engine/utils/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Subset of the upstream used by the validation engine (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+export { applyToDefaults, type ApplyToDefaultsOptions } from './applyToDefaults.js';
+export { assert } from './assert.js';
+export { AssertError } from './assertError.js';
+export { clone, type CloneOptions, type CloneSeen } from './clone.js';
+export { deepEqual, type DeepEqualOptions } from './deepEqual.js';
+export { escapeHtml } from './escapeHtml.js';
+export { escapeRegex } from './escapeRegex.js';
+export { ignore } from './ignore.js';
+export { merge, type MergeOptions } from './merge.js';
+export { reach, type ReachChain, type ReachOptions } from './reach.js';
+export { stringify } from './stringify.js';
+export { getInternalProto, type InternalProto, Types } from './types.js';
+export { type Indexable, isArray, keys, type KeysOptions } from './utils.js';

package/dist/types/lib/validation/engine/utils/merge.d.ts

@@ -0,0 +1,21 @@
+export interface MergeOptions {
+    /**
+     * Override the target value with null or undefined source values, defaults to true
+     */
+    readonly nullOverride?: boolean;
+    /**
+     * Append array source values to the target array instead of replacing them, defaults to true
+     */
+    readonly mergeArrays?: boolean;
+    /**
+     * Include symbol properties, defaults to true
+     */
+    readonly symbols?: boolean;
+}
+/**
+ * Merge all the properties of source into target (target is modified)
+ * @param target
+ * @param source
+ * @param options
+ */
+export declare function merge<T1 extends object, T2 extends object>(target: T1, source: T2 | null | undefined, options?: MergeOptions): T1 & T2;

package/dist/types/lib/validation/engine/utils/reach.d.ts

@@ -0,0 +1,30 @@
+export interface ReachOptions {
+    /**
+     * String to split chain path on, defaults to '.'
+     */
+    readonly separator?: string;
+    /**
+     * Value to return if the path or value is not present, defaults to undefined
+     */
+    readonly default?: unknown;
+    /**
+     * Throw an error on missing member, defaults to false
+     */
+    readonly strict?: boolean;
+    /**
+     * Allow traversing functions for properties, defaults to true (false for a missing segment)
+     */
+    readonly functions?: boolean;
+    /**
+     * Traverse Set and Map objects, defaults to false
+     */
+    readonly iterables?: boolean;
+}
+export type ReachChain = string | (string | number)[] | false | null | undefined;
+/**
+ * Convert an object to a list of properties at the given path
+ * @param obj
+ * @param chain
+ * @param options
+ */
+export declare function reach(obj: unknown, chain: ReachChain, options?: ReachOptions | string): unknown;

package/dist/types/lib/validation/engine/utils/stringify.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Derived from the upstream lib/stringify.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * JSON.stringify() which never throws
+ * @param args
+ */
+export declare function stringify(...args: Parameters<typeof JSON.stringify>): string;

package/dist/types/lib/validation/engine/utils/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Derived from the upstream lib/types.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * Prototypes of the built-in object types handled by clone() and deepEqual()
+ */
+export declare const Types: {
+    readonly array: any[];
+    readonly buffer: any;
+    readonly date: Date;
+    readonly error: Error;
+    readonly generic: Object;
+    readonly map: Map<any, any>;
+    readonly promise: Promise<any>;
+    readonly regex: RegExp;
+    readonly set: Set<any>;
+    readonly url: import("url").URL;
+    readonly weakMap: WeakMap<object, any>;
+    readonly weakSet: WeakSet<object>;
+};
+export type InternalProto = (typeof Types)[keyof typeof Types];
+/**
+ * Get the built-in prototype an object is based on
+ * @param obj
+ */
+export declare function getInternalProto(obj: object): InternalProto;

package/dist/types/lib/validation/engine/utils/utils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Derived from the upstream lib/utils.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * An object whose properties are accessed by key
+ */
+export type Indexable = Record<PropertyKey, unknown>;
+export interface KeysOptions {
+    /**
+     * Include symbol keys, defaults to true
+     */
+    readonly symbols?: boolean;
+}
+/**
+ * Get the own keys of an object
+ * @param obj
+ * @param options
+ */
+export declare function keys(obj: object, options?: KeysOptions): (string | symbol)[];
+/**
+ * Array.isArray() narrowing to unknown[] (the built-in narrows to any[])
+ * @param value
+ */
+export declare function isArray(value: unknown): value is unknown[];

package/dist/types/lib/validation/exceptions/SchemaConversionException.d.ts

@@ -0,0 +1,7 @@
+import { SchemaException } from './SchemaException.js';
+/**
+ * A schema which cannot be converted (to a JSON schema or an OpenAPI schema object)
+ */
+export declare class SchemaConversionException extends SchemaException {
+    errno: string | number;
+}

package/dist/types/lib/validation/exceptions/SchemaDefinitionException.d.ts

@@ -0,0 +1,7 @@
+import { SchemaException } from './SchemaException.js';
+/**
+ * An invalid schema definition: invalid rule arguments, options, templates, references or key dependencies
+ */
+export declare class SchemaDefinitionException extends SchemaException {
+    errno: string | number;
+}

package/dist/types/lib/validation/exceptions/SchemaException.d.ts

@@ -0,0 +1,6 @@
+import { Exception } from '../../foundation/Exception.js';
+/**
+ * Base class of the errors of the validation engine
+ */
+export declare abstract class SchemaException extends Exception {
+}