@lakutata/core 1.0.60 → 3.0.0-beta.0

package/dist/types/lib/validation/engine/json-schema/model.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Types of the JSON Schema conversion (derived from the upstream index.d.ts, see UPSTREAM.md; MIT, see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * The output format of a conversion
+ */
+export type Mode = 'json' | 'open-api' | 'open-api-3.1' | 'json-2020-12' | 'json-draft-2019-09' | 'json-draft-04';
+/**
+ * A JSON schema (or OpenAPI schema object) produced by a parser
+ */
+export interface JsonSchema {
+    type?: string | string[];
+    $ref?: string;
+    $schema?: string;
+    properties?: Record<string, JsonSchema>;
+    patternProperties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: unknown;
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    not?: JsonSchema;
+    if?: JsonSchema;
+    then?: JsonSchema | false;
+    else?: JsonSchema;
+    items?: JsonSchema | JsonSchema[] | false;
+    prefixItems?: JsonSchema[];
+    contains?: JsonSchema;
+    enum?: unknown[];
+    const?: unknown;
+    examples?: unknown[];
+    example?: unknown;
+    dependentRequired?: Record<string, string[]>;
+    dependencies?: Record<string, string[]>;
+    nullable?: boolean;
+    [keyword: string]: unknown;
+}
+/**
+ * A key dependency of an object schema (and, or, with...), as described by the schema
+ */
+export interface SpecDependency {
+    rel: string;
+    key: string | null;
+    peers: string[];
+    [option: string]: unknown;
+}
+/**
+ * A condition (when() or alternatives conditional()), or an alternatives try() match, as described by the schema
+ */
+export interface SpecCondition {
+    schema?: SchemaSpec;
+    ref?: unknown;
+    is?: SchemaSpec;
+    then?: SchemaSpec;
+    otherwise?: SchemaSpec;
+    switch?: SpecCondition[];
+    [option: string]: unknown;
+}
+/**
+ * A rule, as described by the schema
+ */
+export interface SpecRule {
+    name: string;
+    args?: Record<string, unknown>;
+    [modifier: string]: unknown;
+}
+/**
+ * A schema description (describe() output), as far as the parsers read it
+ */
+export interface SchemaSpec {
+    type: string;
+    flags?: Record<string, unknown>;
+    preferences?: Record<string, unknown>;
+    allow?: unknown[];
+    invalid?: unknown[];
+    rules?: SpecRule[];
+    keys?: Record<string, SchemaSpec>;
+    patterns?: {
+        regex?: string;
+        rule?: SchemaSpec;
+        schema?: SchemaSpec;
+    }[];
+    dependencies?: SpecDependency[];
+    matches?: SpecCondition[];
+    whens?: SpecCondition[];
+    items?: SchemaSpec[];
+    metas?: Record<string, unknown>[];
+    shared?: SchemaSpec[];
+    link?: {
+        ref?: {
+            type?: string;
+            path: string[];
+        };
+    };
+    examples?: unknown[];
+    [term: string]: unknown;
+}
+/**
+ * A parser of a key dependency: sets the matching keywords of the schema (in place)
+ */
+export type LogicalOpParserFn = (schema: JsonSchema, dependency: SpecDependency) => void;
+export interface LogicalOpParserOpts {
+    and?: LogicalOpParserFn | null;
+    nand?: LogicalOpParserFn | null;
+    or?: LogicalOpParserFn | null;
+    xor?: LogicalOpParserFn | null;
+    oxor?: LogicalOpParserFn | null;
+    with?: LogicalOpParserFn | null;
+    without?: LogicalOpParserFn | null;
+}
+/**
+ * The options of a parser (false: the defaults)
+ */
+export interface ParserSettings {
+    $schema?: string;
+    includeSchemaDialect?: boolean;
+    logicalOpParser?: LogicalOpParserOpts | false;
+    preferences?: Record<string, unknown>;
+}
+export type ParserOptions = false | ParserSettings;
+/**
+ * The shared schemas collected by a conversion, by id
+ */
+export type Definitions = Record<string, JsonSchema>;

package/dist/types/lib/validation/engine/json-schema/parsers/json-2020-12.d.ts

@@ -0,0 +1,9 @@
+import type { JsonSchema, ParserOptions } from '../model.js';
+import { JsonDraft201909SchemaParser } from './json-draft-2019-09.js';
+/**
+ * Converts schema descriptions into JSON schemas (draft 2020-12)
+ */
+export declare class JsonDraft202012SchemaParser extends JsonDraft201909SchemaParser {
+    constructor(opts?: ParserOptions);
+    protected _setTuple(schema: JsonSchema, ordered: JsonSchema[], rest: JsonSchema | undefined): void;
+}

package/dist/types/lib/validation/engine/json-schema/parsers/json-draft-04.d.ts

@@ -0,0 +1,17 @@
+import type { SchemaSpec, JsonSchema, ParserOptions } from '../model.js';
+import { JsonSchemaParser } from './json.js';
+/**
+ * Converts schema descriptions into JSON schemas (draft 04)
+ */
+export declare class JsonDraft04SchemaParser extends JsonSchemaParser {
+    constructor(opts?: ParserOptions);
+    protected _isIfThenElseSupported(): boolean;
+    protected _setNumberFieldProperties(fieldSchema: JsonSchema, fieldDefn: SchemaSpec): void;
+    protected _getLocalSchemaBasePath(): string;
+    protected _setContains(_schema: JsonSchema, _contains: JsonSchema, _options: {
+        min?: number;
+        max?: number;
+    }): void;
+    protected _setPropertyNames(_schema: JsonSchema, _names: JsonSchema): void;
+    protected _getValuesSchema(values: unknown[]): JsonSchema;
+}

package/dist/types/lib/validation/engine/json-schema/parsers/json-draft-2019-09.d.ts

@@ -0,0 +1,13 @@
+import type { JsonSchema, ParserOptions } from '../model.js';
+import { JsonSchemaParser } from './json.js';
+/**
+ * Converts schema descriptions into JSON schemas (draft 2019-09)
+ */
+export declare class JsonDraft201909SchemaParser extends JsonSchemaParser {
+    constructor(opts?: ParserOptions);
+    protected _setContains(schema: JsonSchema, contains: JsonSchema, options: {
+        min?: number;
+        max?: number;
+    }): void;
+    protected _isKnownMetaKey(key: string): boolean;
+}

package/dist/types/lib/validation/engine/json-schema/parsers/json.d.ts

@@ -0,0 +1,245 @@
+import type { Definitions, SpecCondition, SpecDependency, SpecRule, SchemaSpec, JsonSchema, LogicalOpParserFn, ParserOptions } from '../model.js';
+/**
+ * A numeric bound
+ */
+interface Bound {
+    value: number;
+    exclusive: boolean;
+}
+/**
+ * Converts schema descriptions into JSON schemas (draft 07)
+ */
+export declare class JsonSchemaParser {
+    $schema: string | undefined;
+    includeSchemaDialect: boolean;
+    childrenFieldName: string;
+    optionsFieldName: string;
+    ruleArgFieldName: string;
+    enumFieldName: string;
+    allowUnknownFlagName: string;
+    inheritedPreferences: Record<string, unknown>[];
+    logicalOpParser: Record<string, LogicalOpParserFn | null | undefined>;
+    knownKeys: string[] | undefined;
+    protected _exact: boolean;
+    protected readonly _inexactSchemas: WeakSet<JsonSchema>;
+    constructor(opts?: ParserOptions);
+    parse(spec: SchemaSpec, definitions?: Definitions, level?: number): JsonSchema;
+    /**
+     * Whether a converted schema is exact: it accepts the values the schema accepts (without conversion), and only
+     * them (lakutata's own). Formats are named after the rules, and the numbers beyond the safe integers are accepted.
+     * @param schema
+     */
+    isExact(schema: JsonSchema): boolean;
+    /**
+     * Marks the schema being converted as not exact: something of it has no JSON Schema equivalent and is dropped
+     */
+    protected _inexact(): void;
+    protected _parse(spec: SchemaSpec, definitions: Definitions, level: number): JsonSchema;
+    protected _retainKnownKeys(schema: JsonSchema): JsonSchema;
+    /**
+     * Marks the schemas with constructs JSON Schema cannot express as not exact (the constructs the type setters do
+     * not convert)
+     * @param spec
+     */
+    protected _checkRules(spec: SchemaSpec): void;
+    protected _pushInheritiedPreferences(spec: SchemaSpec): boolean;
+    protected _popInheritiedPreferences(): void;
+    protected _getInheritedPreferences(): Record<string, unknown>;
+    /**
+     * The preferences of a schema: its preferences merged with the inherited ones (upstream uses its preferences
+     * instead of the inherited ones)
+     * @param spec
+     */
+    protected _getPreferences(spec: SchemaSpec): Record<string, unknown>;
+    protected _isIfThenElseSupported(): boolean;
+    protected _getChildrenFieldName(): string;
+    protected _getOptionsFieldName(): string;
+    protected _getRuleArgFieldName(): string;
+    protected _getEnumFieldName(): string;
+    protected _getAllowUnknownFlagName(): string;
+    protected _getLocalSchemaBasePath(): string;
+    protected _getFieldDescription(fieldDefn: SchemaSpec): unknown;
+    protected _getFieldType(fieldDefn: SchemaSpec): string | undefined;
+    /**
+     * Makes a schema with a null type nullable (OpenAPI 3.0), and replaces the type lists where types are lists
+     * @param _fieldSchema
+     * @param _fieldDefn
+     */
+    protected _addNullTypeIfNullable(_fieldSchema: JsonSchema, _fieldDefn: SchemaSpec): void;
+    protected _getFieldExample(fieldDefn: SchemaSpec): unknown;
+    protected _getPresence(fieldDefn: SchemaSpec): unknown;
+    protected _isRequired(fieldDefn: SchemaSpec): boolean;
+    protected _getDefaultValue(fieldDefn: SchemaSpec): unknown;
+    /**
+     * Whether the unknown keys of an object are accepted (true), rejected (false), or must match a schema
+     * @param spec
+     */
+    protected _getUnknown(spec: SchemaSpec): boolean | SchemaSpec;
+    /**
+     * Whether the unknown keys of an object are stripped before its rules
+     * @param spec
+     */
+    protected _stripsUnknown(spec: SchemaSpec): boolean;
+    /**
+     * Whether the items of arrays which match no item schema are stripped
+     * @param spec
+     */
+    protected _stripsArrayItems(spec: SchemaSpec): boolean;
+    protected _setIfNotEmpty(schema: JsonSchema, field: string, value: unknown): void;
+    /**
+     * The tighter of a bound and a limit (a reference limit is dropped)
+     * @param bound
+     * @param limit
+     * @param exclusive
+     * @param lower
+     */
+    protected _bound(bound: Bound | undefined, limit: unknown, exclusive: boolean, lower: boolean): Bound | undefined;
+    /**
+     * Adds a keyword, or a subschema of the keyword to allOf when the schema has the keyword (lakutata)
+     * @param schema
+     * @param keyword
+     * @param value
+     */
+    protected _addKeyword(schema: JsonSchema, keyword: string, value: unknown): void;
+    /**
+     * Merges the keywords of a subschema, or adds the subschema to allOf when the keywords conflict (lakutata)
+     * @param schema
+     * @param part
+     */
+    protected _mergeKeywords(schema: JsonSchema, part: JsonSchema): void;
+    protected _setBasicProperties(fieldSchema: JsonSchema, fieldDefn: SchemaSpec): void;
+    /**
+     * The schema of a values list (only these values)
+     * @param values
+     */
+    protected _getValuesSchema(values: unknown[]): JsonSchema;
+    /**
+     * Applies the valid and invalid values of a schema description (lakutata's own; upstream sets the enum of the
+     * valid values, and adds null to the type): the valid values of `valid()` are the only accepted values, the
+     * values of `allow()` are accepted besides the values of the schema, and the invalid values are rejected
+     * @param schema
+     * @param spec
+     */
+    protected _setValues(schema: JsonSchema, spec: SchemaSpec): JsonSchema;
+    /**
+     * Arrays accepting single values also accept a value their items accept (lakutata's own)
+     * @param schema
+     * @param spec
+     */
+    protected _setSingle(schema: JsonSchema, spec: SchemaSpec): JsonSchema;
+    /**
+     * Whether a string schema certainly accepts the empty string
+     * @param schema
+     */
+    protected _acceptsEmpty(schema: JsonSchema): boolean;
+    /**
+     * Whether a string schema certainly rejects the empty string
+     * @param schema
+     */
+    protected _rejectsEmpty(schema: JsonSchema): boolean;
+    /**
+     * Whether null can be accepted by adding it to the type of a schema: its keywords apply to other types
+     * @param schema
+     */
+    protected _canAddType(schema: JsonSchema): boolean;
+    protected _setBinaryFieldProperties(fieldSchema: JsonSchema, fieldDefn: SchemaSpec): void;
+    /**
+     * The format of binary strings (JSON Schema has none: upstream sets binary)
+     */
+    protected _getBinaryFormat(): string | undefined;
+    protected _setObjectProperties(schema: JsonSchema, spec: SchemaSpec, definitions: Definitions, level: number): void;
+    /**
+     * Sets the schema of the key names
+     * @param schema
+     * @param names
+     */
+    protected _setPropertyNames(schema: JsonSchema, names: JsonSchema): void;
+    /**
+     * Sets the patternProperties of the patterns of an object (lakutata's own; upstream also adds each pattern as a
+     * property): like the engine, a pattern applies to the keys which are not defined keys and which no previous
+     * pattern (without fallthrough) matched. Returns false when a pattern is not expressible.
+     * @param schema
+     * @param spec
+     * @param definedKeys
+     * @param definitions
+     * @param level
+     */
+    protected _setPatternProperties(schema: JsonSchema, spec: SchemaSpec, definedKeys: string[], definitions: Definitions, level: number): boolean;
+    /**
+     * The schema of the key names an object processes (its defined keys and the keys its patterns match)
+     * @param spec
+     */
+    protected _knownKeys(spec: SchemaSpec): JsonSchema;
+    /**
+     * Whether a key is processed by an object (not stripped as an unknown key)
+     * @param spec
+     * @param key
+     */
+    protected _isKnownKey(spec: SchemaSpec, key: string): boolean;
+    protected _setObjectDependencies(schema: JsonSchema, spec: SchemaSpec): void;
+    protected _setDependencySubSchema(schema: JsonSchema, dependency: SpecDependency): JsonSchema;
+    /**
+     * The format of a number schema (JSON Schema has no number formats)
+     * @param _rules
+     */
+    protected _getNumberFormat(_rules: SpecRule[]): string | undefined;
+    protected _setNumberFieldProperties(fieldSchema: JsonSchema, fieldDefn: SchemaSpec): void;
+    protected _setStringFieldProperties(fieldSchema: JsonSchema, fieldDefn: SchemaSpec): void;
+    /**
+     * Sets the schema the items of an array contain
+     * @param schema
+     * @param contains
+     * @param options
+     */
+    protected _setContains(schema: JsonSchema, contains: JsonSchema, options: {
+        min?: number;
+        max?: number;
+    }): void;
+    /**
+     * Sets the items of an array with ordered items
+     * @param schema
+     * @param ordered
+     * @param rest the schema of the other items (undefined: no other items)
+     */
+    protected _setTuple(schema: JsonSchema, ordered: JsonSchema[], rest: JsonSchema | undefined): void;
+    protected _setArrayFieldProperties(fieldSchema: JsonSchema, fieldDefn: SchemaSpec, definitions: Definitions, level: number): void;
+    protected _setDateFieldProperties(fieldSchema: JsonSchema, fieldDefn: SchemaSpec): void;
+    protected _setAlternativesProperties(schema: JsonSchema, spec: SchemaSpec, definitions: Definitions, level: number): void;
+    protected _setConditionProperties(schema: JsonSchema, spec: SchemaSpec, definitions: Definitions, level: number, conditionFieldName: string, logicKeyword?: string): void;
+    protected _setConditionSchema(ifThenStyle: boolean, schema: JsonSchema, conditionSpec: SpecCondition, definitions: Definitions, level: number): JsonSchema | undefined;
+    protected _parseIfThenElseCondition(schema: JsonSchema, conditionSpec: SpecCondition, definitions: Definitions, level: number): JsonSchema;
+    /**
+     * Sets the branches of a condition which cannot be converted: a value matches one of them (lakutata's own)
+     * @param schema
+     * @param conditionSpec
+     * @param definitions
+     * @param level
+     */
+    protected _setBranches(schema: JsonSchema, conditionSpec: SpecCondition, definitions: Definitions, level: number): JsonSchema;
+    protected _parseSwitchCondition(ifThenStyle: boolean, schema: JsonSchema, condition: SpecCondition, definitions: Definitions, level: number): void;
+    protected _setConditionCompositionStyle(schema: JsonSchema, condition: SpecCondition, definitions: Definitions, level: number): JsonSchema;
+    protected _setAnyProperties(schema: JsonSchema): void;
+    /**
+     * The schemas the value must also match (lakutata)
+     * @param schema
+     * @param spec
+     * @param definitions
+     * @param level
+     */
+    protected _setAllOf(schema: JsonSchema, spec: SchemaSpec, definitions: Definitions, level: number): void;
+    /**
+     * No JSON value is a function or a symbol (lakutata)
+     * @param schema
+     * @param spec
+     */
+    protected _setNonJsonProperties(schema: JsonSchema, spec: SchemaSpec): void;
+    protected _setMetaProperties(schema: JsonSchema, spec: SchemaSpec): void;
+    protected _setLinkFieldProperties(schema: JsonSchema, spec: SchemaSpec): void;
+    protected _copyMetasToSchema(spec: SchemaSpec, schema: JsonSchema): void;
+    /**
+     * Intended to be overridden by child parsers. By default no meta key will be is considered "known".
+     * @param _key
+     */
+    protected _isKnownMetaKey(_key: string): boolean;
+}
+export {};

package/dist/types/lib/validation/engine/json-schema/parsers/open-api-3.1.d.ts

@@ -0,0 +1,13 @@
+import type { Definitions, SchemaSpec, JsonSchema, ParserOptions, SpecRule } from '../model.js';
+import { JsonDraft202012SchemaParser } from './json-2020-12.js';
+/**
+ * Converts schema descriptions into OpenAPI 3.1 schema objects
+ */
+export declare class OpenApi31SchemaParser extends JsonDraft202012SchemaParser {
+    constructor(opts?: ParserOptions);
+    parse(spec: SchemaSpec, definitions?: Definitions, level?: number): JsonSchema;
+    protected _getNumberFormat(rules: SpecRule[]): string | undefined;
+    protected _getBinaryFormat(): string | undefined;
+    protected _getLocalSchemaBasePath(): string;
+    protected _isKnownMetaKey(key: string): boolean;
+}

package/dist/types/lib/validation/engine/json-schema/parsers/open-api.d.ts

@@ -0,0 +1,24 @@
+import type { Definitions, SchemaSpec, JsonSchema, ParserOptions, SpecRule } from '../model.js';
+import { JsonDraft04SchemaParser } from './json-draft-04.js';
+/**
+ * The OpenAPI format of a number schema: the formats of the integer and floating point types (lakutata's own)
+ * @param rules
+ */
+export declare function openApiNumberFormat(rules: SpecRule[]): string | undefined;
+/**
+ * Converts schema descriptions into OpenAPI 3.0 schema objects
+ */
+export declare class OpenApiSchemaParser extends JsonDraft04SchemaParser {
+    constructor(opts?: ParserOptions);
+    parse(spec: SchemaSpec, definitions?: Definitions, level?: number): JsonSchema;
+    protected _isIfThenElseSupported(): boolean;
+    protected _getNumberFormat(rules: SpecRule[]): string | undefined;
+    protected _setAnyProperties(schema: JsonSchema): void;
+    protected _getBinaryFormat(): string | undefined;
+    protected _setTuple(schema: JsonSchema, ordered: JsonSchema[], rest: JsonSchema | undefined): void;
+    protected _setObjectProperties(schema: JsonSchema, spec: SchemaSpec, definitions: Definitions, level: number): void;
+    protected _getLocalSchemaBasePath(): string;
+    protected _setBasicProperties(fieldSchema: JsonSchema, fieldDefn: SchemaSpec): void;
+    protected _addNullTypeIfNullable(fieldSchema: JsonSchema, fieldDefn: SchemaSpec): void;
+    protected _isKnownMetaKey(key: string): boolean;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Derived from the upstream lib/index.js (see UPSTREAM.md; BSD-3-Clause, see THIRD_PARTY_NOTICES.md)
+ */
+export interface Location {
+    /**
+     * The fully qualified filename
+     */
+    readonly filename: string;
+    /**
+     * The file line number
+     */
+    readonly line: number;
+}
+/**
+ * Get the filename and line number of a caller in the call stack
+ * @param depth distance from the location function in the call stack, defaults to 0 (location's caller)
+ */
+export declare function location(depth?: number): Location;

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

@@ -0,0 +1,13 @@
+import type { ErrorDetail } from './model.js';
+/**
+ * The validation error annotate() is called on
+ */
+export interface AnnotatedError {
+    _original: unknown;
+    details: ErrorDetail[];
+}
+/**
+ * Render the validated value with the errors marked in place (SchemaValidationException.annotate())
+ * @param stripColorCodes
+ */
+export declare function error(this: AnnotatedError, stripColorCodes?: boolean): string;

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

@@ -0,0 +1,25 @@
+import { SchemaDefinitionException } from '../../exceptions/SchemaDefinitionException.js';
+/**
+ * A definition exception, with the stack from the caller of the given function
+ * @param message
+ * @param caller
+ * @param cause
+ */
+export declare function definitionException(message: string, caller: Function, cause?: unknown): SchemaDefinitionException;
+/**
+ * Set the message of an error (lakutata: a framework exception keeps its message in errMsg too)
+ * @param err
+ * @param message
+ */
+export declare function setMessage(err: Error, message: string): void;
+/**
+ * Assert a condition of a schema definition
+ * @param condition
+ * @param args the message parts (an Error alone is thrown as is)
+ */
+export declare function assert(condition: unknown, ...args: unknown[]): asserts condition;
+/**
+ * Call a utility (utils, sorter, address) with definition inputs: its assertion errors become definition exceptions
+ * @param fn
+ */
+export declare function definition<T>(fn: () => T): T;