@lakutata/core 1.0.59 → 3.0.0-beta.0

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

@@ -0,0 +1,72 @@
+import { type ExpressionFunction, Parser } from '../expression/index.js';
+import type { ErrorPreferences, Preferences, StateLike } from './model.js';
+import * as Ref from './ref.js';
+import type { Messages } from './messages.js';
+/**
+ * Options of a template: reference options, and functions callable from the template expressions
+ */
+export interface TemplateOptions extends Ref.RefOptions {
+    functions?: Record<string, ExpressionFunction>;
+}
+export interface TemplateDescription {
+    template: string;
+    options?: Ref.RefOptions;
+    functions?: Record<string, ExpressionFunction>;
+}
+/**
+ * Options of a template rendering
+ */
+export interface RenderOptions extends Ref.ResolveOptions {
+    errors?: ErrorPreferences;
+    messages?: (Messages | null | undefined)[];
+    arrayItems?: boolean;
+}
+/**
+ * The arguments a template resolves with, also the `this` of its expression functions
+ */
+type RenderContext = [value: unknown, state: StateLike, prefs: Preferences, local: unknown, options: RenderOptions];
+interface RefPart {
+    ref: Ref.Ref;
+    raw: boolean;
+    refs: Ref.Ref[];
+    wrapped: boolean;
+}
+interface ExpressionPart {
+    expression: Parser;
+    raw: boolean;
+    refs: Ref.Ref[];
+    wrapped?: undefined;
+    ref?: undefined;
+}
+type DynamicPart = RefPart | ExpressionPart;
+type TemplatePart = string | DynamicPart;
+/**
+ * A message template: text with {references} and {{escaped references}}, which may be expressions
+ */
+export declare class Template {
+    isImmutable: true;
+    source: string;
+    rendered: string;
+    protected _template: TemplatePart[] | null;
+    protected _settings: Ref.RefOptions | undefined;
+    protected _functions: Record<string, ExpressionFunction> | undefined;
+    constructor(source: string, options?: TemplateOptions);
+    protected _parse(): void;
+    static date(date: Date, prefs: Preferences): string;
+    describe(options?: {
+        compact?: boolean;
+    }): string | TemplateDescription;
+    static build(desc: TemplateDescription): Template;
+    isDynamic(): boolean;
+    static isTemplate(template: unknown): template is Template;
+    refs(): Ref.Ref[] | undefined;
+    resolve(value: unknown, state: StateLike, prefs: Preferences, local: unknown): unknown;
+    protected _part(part: DynamicPart, context: RenderContext): unknown;
+    render(value: unknown, state: StateLike, prefs: Preferences, local: unknown, options?: RenderOptions): string;
+    protected _ref(content: string, { raw, wrapped }: {
+        raw: boolean;
+        wrapped: boolean;
+    }): string | DynamicPart;
+    toString(): string;
+}
+export {};

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

@@ -0,0 +1,121 @@
+import type { MainstayLike, PathKey, SchemaInternals, StateLike } from './model.js';
+import type { ResolvableValue } from './values.js';
+type TraceResult = 'error' | 'pass' | 'full';
+/**
+ * A segment of a sub schema path: an id or key, or a [@term, position] pair
+ */
+type TracePathSegment = string | [string, PathKey];
+type TracePath = TracePathSegment[];
+/**
+ * A debug event of a validation
+ */
+export interface DebugEvent {
+    type: string;
+    path?: unknown[];
+    [name: string]: unknown;
+}
+/**
+ * The state parts the tracer reads
+ */
+export interface TraceState extends StateLike {
+    debug?: unknown;
+    mainstay: MainstayLike & {
+        debug?: DebugEvent[] | null;
+    };
+}
+/**
+ * A resolvable value, as the tracer displays it
+ */
+interface DisplayedResolvable extends ResolvableValue {
+    display?: string;
+}
+/**
+ * A matched value of a values set
+ */
+interface ValuesFilter {
+    value: unknown;
+    ref?: DisplayedResolvable;
+}
+/**
+ * The coverage log of one (sub) schema
+ */
+interface SourceLog {
+    paths: Set<TracePath>;
+    entry: boolean;
+    rule: Record<string, number>;
+    valid: Set<ValuesFilter>;
+    invalid: Set<ValuesFilter>;
+}
+/**
+ * A missing coverage item
+ */
+interface MissingItem {
+    status: string | unknown[];
+    paths?: TracePath[];
+    rule?: string;
+}
+/**
+ * The coverage report of one registered schema
+ */
+export interface CoverageReport {
+    filename: string;
+    line: number;
+    missing: MissingItem[];
+    severity: 'error';
+    message: string;
+}
+interface RegisteredSchema {
+    filename: string;
+    line: number;
+    store: Store;
+}
+/**
+ * The root object parts set by setup()
+ */
+export interface TraceRoot {
+    _tracer?: Tracer | null;
+    trace?: () => Tracer;
+    untrace?: () => void;
+}
+/**
+ * Add trace() and untrace() to the root object
+ * @param root
+ */
+export declare function setup(root: TraceRoot): void;
+/**
+ * Record the location of the caller of schema.tracer()
+ * @param schema
+ */
+export declare function location<T extends SchemaInternals>(schema: T): T;
+/**
+ * Collects the coverage of the traced schemas
+ */
+export declare class Tracer {
+    name: string;
+    protected _schemas: Map<SchemaInternals, RegisteredSchema>;
+    constructor();
+    _register(schema: SchemaInternals): Store;
+    _combine(merged: SchemaInternals, sources: SchemaInternals[]): void;
+    report(file?: string): CoverageReport[] | null;
+}
+/**
+ * The coverage store of a registered schema, recording the validations of its sub schemas
+ */
+export declare class Store {
+    active: boolean;
+    _sources: Map<SchemaInternals, SourceLog>;
+    protected _combos: Map<SchemaInternals, SchemaInternals[]>;
+    constructor(schema: SchemaInternals);
+    debug(state: TraceState, source: string, name: string, result: unknown): void;
+    entry(schema: SchemaInternals, state: TraceState): void;
+    filter(schema: SchemaInternals, state: TraceState, source: 'valid' | 'invalid', value: ValuesFilter): void;
+    log(schema: SchemaInternals, state: TraceState, source: 'rule', name: string, result: TraceResult): void;
+    resolve(state: TraceState, ref: {
+        display?: string;
+    }, to: unknown): void;
+    value(state: TraceState, by: string, from: unknown, to: unknown, name?: string): void;
+    _record(schema: SchemaInternals, each: (log: SourceLog) => void): void;
+    _scan(schema: SchemaInternals, _path?: TracePath): void;
+    _combine(merged: SchemaInternals, sources: SchemaInternals[]): void;
+}
+export {};

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

@@ -0,0 +1,36 @@
+import type { Base, SchemaTerms } from '../base.js';
+import * as Compile from '../compile.js';
+import * as Ref from '../ref.js';
+import { type AnySchema, type AnyTerms } from './any.js';
+/**
+ * The match modes of an alternatives schema
+ */
+export type AlternativesMatchMode = 'any' | 'one' | 'all' | 'none';
+/**
+ * An item of the matches term: an alternative schema, a condition, or a switch statement
+ */
+export interface AlternativesMatch {
+    schema?: Base;
+    ref?: Ref.Ref;
+    is?: Base;
+    then?: Base;
+    otherwise?: Base;
+    switch?: Compile.WhenCase[];
+}
+/**
+ * The terms of an alternatives schema
+ */
+export interface AlternativesTerms {
+    matches: AlternativesMatch[];
+}
+/**
+ * The alternatives schema: matches any (or one, or all) of the alternative schemas, or the conditions
+ */
+export interface AlternativesSchema extends AnySchema {
+    $_terms: SchemaTerms & AnyTerms & AlternativesTerms;
+    conditional(condition: unknown, options: Compile.WhenOptions | Compile.WhenSwitchCase[]): this;
+    match(mode: AlternativesMatchMode): this;
+    try(...schemas: unknown[]): this;
+}
+declare const Alternatives: AlternativesSchema;
+export default Alternatives;

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

@@ -0,0 +1,37 @@
+import { type AlterationTerm, type Base, type SchemaTerms, type WhenTerm } from '../base.js';
+import type { ReportLocal } from '../errors.js';
+import * as Messages from '../messages.js';
+import type { ValidationHelpers } from '../model.js';
+/**
+ * A custom rule method: the validated (or converted) value, or an error
+ */
+export type CustomMethod = (value: unknown, helpers: ValidationHelpers) => unknown;
+/**
+ * The terms of any schema
+ */
+export interface AnyTerms {
+    alterations: AlterationTerm[] | null;
+    examples: unknown[] | null;
+    externals: unknown[] | null;
+    metas: unknown[];
+    notes: string[];
+    shared: Base[] | null;
+    tags: string[];
+    whens: WhenTerm[] | null;
+}
+/**
+ * The any schema: Base with the rules and modifiers shared by all the types
+ */
+export interface AnySchema extends Base {
+    $_terms: SchemaTerms & AnyTerms;
+    allOf(...schemas: unknown[]): this;
+    custom(method: CustomMethod, description?: string): this;
+    messages(messages: Messages.MessagesInput): this;
+    shared(schema: Base): this;
+    warning(code: string, local?: ReportLocal): this;
+    keep(enabled?: boolean): this;
+    message(message: Messages.MessagesInput): this;
+    warn(enabled?: boolean): this;
+}
+declare const Any: AnySchema;
+export default Any;

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

@@ -0,0 +1,46 @@
+import type { Base, SchemaTerms } from '../base.js';
+import { type AnySchema, type AnyTerms } from './any.js';
+/**
+ * A custom unique comparator: truthy when both values are duplicates
+ */
+export type UniqueComparator = (a: unknown, b: unknown) => unknown;
+export interface UniqueOptions {
+    ignoreUndefined?: boolean;
+    separator?: string | false;
+}
+export interface SortOptions {
+    by?: unknown;
+    order?: 'ascending' | 'descending';
+}
+/**
+ * The terms of array schemas
+ */
+export interface ArrayTerms {
+    items: Base[];
+    ordered: Base[];
+    _exclusions: Base[];
+    _inclusions: Base[];
+    _requireds: Base[];
+}
+/**
+ * The array schema
+ */
+export interface HasOptions {
+    min?: number;
+    max?: number;
+}
+export interface ArraySchema extends AnySchema {
+    $_terms: SchemaTerms & AnyTerms & ArrayTerms;
+    has(schema: unknown, options?: HasOptions): this;
+    items(...schemas: unknown[]): this;
+    length(limit: unknown): this;
+    max(limit: unknown): this;
+    min(limit: unknown): this;
+    ordered(...schemas: unknown[]): this;
+    single(enabled?: unknown): this;
+    sort(options?: SortOptions): this;
+    sparse(enabled?: unknown): this;
+    unique(comparator?: string | UniqueComparator, options?: UniqueOptions): this;
+}
+declare const ArrayType: ArraySchema;
+export default ArrayType;

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

@@ -0,0 +1,20 @@
+import { type AnySchema } from './any.js';
+import type { SchemaFlags } from '../model.js';
+/**
+ * The flags of binary schemas
+ */
+export interface BinaryFlags extends SchemaFlags {
+    encoding?: BufferEncoding;
+}
+/**
+ * The binary schema
+ */
+export interface BinarySchema extends AnySchema {
+    _flags: BinaryFlags;
+    encoding(encoding: BufferEncoding): this;
+    length(limit: unknown): this;
+    max(limit: unknown): this;
+    min(limit: unknown): this;
+}
+declare const BinaryType: BinarySchema;
+export default BinaryType;

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

@@ -0,0 +1,29 @@
+import { type AnySchema, type AnyTerms } from './any.js';
+import type { SchemaTerms } from '../base.js';
+import type { SchemaFlags } from '../model.js';
+import { Values } from '../values.js';
+/**
+ * The flags of boolean schemas
+ */
+export interface BooleanFlags extends SchemaFlags {
+    sensitive?: boolean;
+}
+/**
+ * The terms of boolean schemas
+ */
+export interface BooleanTerms {
+    falsy: Values | null;
+    truthy: Values | null;
+}
+/**
+ * The boolean schema
+ */
+export interface BooleanSchema extends AnySchema {
+    _flags: BooleanFlags;
+    $_terms: SchemaTerms & AnyTerms & BooleanTerms;
+    falsy(...values: unknown[]): this;
+    sensitive(enabled?: boolean): this;
+    truthy(...values: unknown[]): this;
+}
+declare const BooleanType: BooleanSchema;
+export default BooleanType;

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

@@ -0,0 +1,27 @@
+import { type AnySchema } from './any.js';
+import type { SchemaFlags } from '../model.js';
+/**
+ * The date formats
+ */
+export type DateFormat = 'iso' | 'javascript' | 'unix';
+/**
+ * The flags of date schemas
+ */
+export interface DateFlags extends SchemaFlags {
+    format?: DateFormat;
+}
+/**
+ * The date schema
+ */
+export interface DateSchema extends AnySchema {
+    _flags: DateFlags;
+    format(format: DateFormat): this;
+    greater(date: unknown): this;
+    iso(): this;
+    less(date: unknown): this;
+    max(date: unknown): this;
+    min(date: unknown): this;
+    timestamp(type?: 'javascript' | 'unix'): this;
+}
+declare const DateType: DateSchema;
+export default DateType;

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

@@ -0,0 +1,12 @@
+import { type KeysSchema } from './keys.js';
+/**
+ * The function schema: keys (of the function object), and arity rules
+ */
+export interface FunctionSchema extends KeysSchema {
+    arity(n: number): this;
+    class(): this;
+    minArity(n: number): this;
+    maxArity(n: number): this;
+}
+declare const FunctionType: FunctionSchema;
+export default FunctionType;

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

@@ -0,0 +1,119 @@
+import type { Base, SchemaTerms } from '../base.js';
+import * as Ref from '../ref.js';
+import { Template } from '../template.js';
+import { type AnySchema, type AnyTerms } from './any.js';
+/**
+ * The relation of a dependency between keys
+ */
+export type DependencyRel = 'and' | 'nand' | 'or' | 'oxor' | 'with' | 'without' | 'xor';
+/**
+ * The options of a dependency (the optional last peer of and(), nand(), or(), oxor() and xor())
+ */
+export interface DependencyOptions {
+    separator?: string | false;
+    isPresent?: (resolved: unknown) => unknown;
+}
+/**
+ * A peer of a dependency (or its options, when last)
+ */
+export type DependencyPeer = string | DependencyOptions;
+/**
+ * The description of a dependency
+ */
+export interface DependencyDescription {
+    rel: DependencyRel;
+    peers: string[];
+    key?: string | null;
+    options?: DependencyOptions;
+}
+/**
+ * A child key of an object schema
+ */
+export interface KeysChild {
+    key: string;
+    schema: Base;
+}
+/**
+ * An item of the patterns term
+ */
+export interface PatternTerm {
+    regex?: RegExp;
+    schema?: Base;
+    rule: Base;
+    matches?: Base;
+    fallthrough?: boolean;
+}
+export interface PatternOptions {
+    fallthrough?: boolean;
+    matches?: unknown;
+}
+export interface RenameOptions {
+    alias?: boolean;
+    ignoreUndefined?: boolean;
+    multiple?: boolean;
+    override?: boolean;
+}
+/**
+ * An item of the renames term
+ */
+export interface RenameTerm {
+    from: string | RegExp;
+    to: string | Template;
+    options: RenameOptions;
+}
+/**
+ * The terms of the object-like schemas
+ */
+export interface KeysTerms {
+    dependencies: Dependency[] | null;
+    keys: Keys | null;
+    patterns: PatternTerm[] | null;
+    renames: RenameTerm[] | null;
+}
+/**
+ * The base schema of the object and function types
+ */
+export interface KeysSchema extends AnySchema {
+    $_terms: SchemaTerms & AnyTerms & KeysTerms;
+    and(...peers: DependencyPeer[]): this;
+    append(schema?: Record<string, unknown> | null): this;
+    assert(subject: unknown, schema: unknown, message?: string): this;
+    instance(constructor: Function, name?: string): this;
+    keyNames(schema: unknown): this;
+    keys(schema?: Record<string, unknown> | null): this;
+    length(limit: unknown): this;
+    max(limit: unknown): this;
+    min(limit: unknown): this;
+    nand(...peers: DependencyPeer[]): this;
+    or(...peers: DependencyPeer[]): this;
+    oxor(...peers: DependencyPeer[]): this;
+    pattern(pattern: unknown, schema: unknown, options?: PatternOptions): this;
+    ref(): this;
+    regex(): this;
+    rename(from: string | RegExp, to: string | Template, options?: RenameOptions): this;
+    schema(type?: string): this;
+    unknown(allow?: boolean | unknown): this;
+    with(key: string, peers: string | string[], options?: DependencyOptions): this;
+    without(key: string, peers: string | string[], options?: DependencyOptions): this;
+    xor(...peers: DependencyPeer[]): this;
+}
+declare const KeysType: KeysSchema;
+export default KeysType;
+/**
+ * An item of the dependencies term
+ */
+declare class Dependency {
+    rel: DependencyRel;
+    key: Ref.Ref | null;
+    peers: Ref.Ref[];
+    paths: string[];
+    options: DependencyOptions;
+    constructor(rel: DependencyRel, key: Ref.Ref | null, peers: Ref.Ref[], paths: string[], options: DependencyOptions);
+    describe(): DependencyDescription;
+}
+/**
+ * The keys term: an array of children which concatenates by key
+ */
+declare class Keys extends Array<KeysChild> {
+    concat(source: KeysChild[]): KeysChild[];
+}

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

@@ -0,0 +1,21 @@
+import type { SchemaTerms } from '../base.js';
+import type * as Ref from '../ref.js';
+import { type AnySchema, type AnyTerms } from './any.js';
+/**
+ * The terms of a link schema
+ */
+export interface LinkTerms {
+    link: {
+        ref: Ref.Ref;
+    }[] | null;
+}
+/**
+ * The link schema: validates with the schema a reference points to
+ */
+export interface LinkSchema extends AnySchema {
+    $_terms: SchemaTerms & AnyTerms & LinkTerms;
+    ref(ref: unknown): this;
+    relative(enabled?: boolean): this;
+}
+declare const Link: LinkSchema;
+export default Link;

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

@@ -0,0 +1,46 @@
+import { type AnySchema } from './any.js';
+import type { SchemaFlags } from '../model.js';
+/**
+ * The flags of number schemas
+ */
+export interface NumberFlags extends SchemaFlags {
+    unsafe?: boolean;
+}
+/**
+ * The number schema
+ */
+export interface NumberSchema extends AnySchema {
+    _flags: NumberFlags;
+    double(): this;
+    float(): this;
+    greater(limit: unknown): this;
+    int8(): this;
+    int16(): this;
+    int32(): this;
+    int64(): this;
+    integer(): this;
+    less(limit: unknown): this;
+    max(limit: unknown): this;
+    min(limit: unknown): this;
+    multiple(base: unknown): this;
+    negative(): this;
+    port(): this;
+    positive(): this;
+    precision(limit: number): this;
+    sign(sign: 'negative' | 'positive'): this;
+    uint8(): this;
+    uint16(): this;
+    uint32(): this;
+    uint64(): this;
+    unsafe(enabled?: boolean): this;
+}
+/**
+ * The ranges of the integer types (the 64-bit types are limited to the safe integers of JavaScript)
+ */
+export declare const integerTypes: Readonly<Record<string, readonly [number, number]>>;
+/**
+ * The largest finite 32-bit floating point number
+ */
+export declare const FLOAT_MAX: number;
+declare const NumberType: NumberSchema;
+export default NumberType;

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

@@ -0,0 +1,10 @@
+/**
+ * Derived from the upstream lib/types/object.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+import { type KeysSchema } from './keys.js';
+/**
+ * The object schema: keys, cast to a map
+ */
+export type ObjectSchema = KeysSchema;
+declare const ObjectType: ObjectSchema;
+export default ObjectType;