kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/core/validation/validation.d.ts

@@ -1,113 +1,152 @@
-export = Validation;
-/**
- * @class Validation
- */
+import { Koncorde } from "koncorde";
+import type { JSONObject } from "../../types/JSONObject";
+import type { KuzzleRequest } from "../../api/request";
+import type BaseType from "./baseType";
+import type { CollectionSpecification, CuratedCollectionSpecification, DocumentSpecification, ErrorMessages, FieldSpecification, RawSpecification, SpecificationValidationResult, CuratedFieldSpecification, StructuredFieldSpecification, UnplacedCuratedField, VerboseErrorMessages } from "./specification";
 declare class Validation {
-    /** @type {...ValidationType} */
-    types: ValidationType;
-    /** @type {string[]} */
+    types: Record<string, BaseType>;
     typeAllowsChildren: string[];
-    /** @type {DocumentSpecification} */
     specification: DocumentSpecification;
-    /** @type {Koncorde} */
     koncorde: Koncorde;
-    rawConfiguration: {};
-    logger: import("../../kuzzle/Logger").Logger;
+    rawConfiguration: RawSpecification;
+    logger: ReturnType<typeof global.kuzzle.log.child>;
+    constructor();
     /**
-     * Walks through all types in "defaultTypesFiles" initializes all types
+     * Registers every built-in validation type.
      */
     init(): void;
     /**
-     * Validates a document against its collection specifications
+     * Validates a document against its collection specifications.
      *
-     * @param {Request} request
-     * @param {boolean} [verbose]
-     * @returns {Promise.<{documentBody: *, errorMessages:string[], valid: boolean}|KuzzleRequest>}
+     * Answers the request itself when `verbose` is false — the caller's document
+     * has had its defaults applied in place — and a report when it is true.
      */
-    validate(request: Request, verbose?: boolean): Promise<{
-        documentBody: any;
-        errorMessages: string[];
+    validate(request: KuzzleRequest, verbose?: false): Promise<KuzzleRequest>;
+    validate(request: KuzzleRequest, verbose: true): Promise<{
+        errorMessages: VerboseErrorMessages;
         valid: boolean;
-    } | KuzzleRequest>;
+    }>;
     /**
-     * @param {boolean} isUpdate
-     * @param {*} documentSubset
-     * @param {...StructuredFieldSpecification} collectionSpecSubset
+     * The body validation runs against: the request's own, or — on an update —
+     * a copy merged over the stored document, so that a partial update is
+     * validated as the document it will produce.
      */
-    recurseApplyDefault(isUpdate: boolean, documentSubset: any, collectionSpecSubset: StructuredFieldSpecification): any;
+    private resolveValidationBody;
     /**
-     * @param {*} documentSubset
-     * @param {StructuredFieldSpecification} collectionSpecSubset
-     * @param {boolean} strictness
-     * @param {string[]} errorMessages
-     * @param {boolean} verbose
+     * Walks the document against the collection's field tree, turning a
+     * root-level strictness breach into a message rather than an exception.
      */
-    recurseFieldValidation(documentSubset: any, collectionSpecSubset: StructuredFieldSpecification, strictness: boolean, errorMessages: string[], verbose: boolean): boolean;
+    private checkDocumentFields;
     /**
-     * @param {string} fieldName
-     * @param {*} documentSubset
-     * @param {StructuredFieldSpecification} collectionSpecSubset
-     * @param {boolean} strictness
-     * @param {string[]} errorMessages
-     * @param {boolean} verbose
-     * @returns {boolean}
+     * Checks the document against the collection's Koncorde validator filter.
      */
-    isValidField(fieldName: string, documentSubset: any, collectionSpecSubset: StructuredFieldSpecification, strictness: boolean, errorMessages: string[], verbose: boolean): boolean;
+    private checkValidators;
     /**
-     * @returns {Promise.<T>}
+     * Fills a document subset in with the default values its specification
+     * declares, recursing through the fields that allow children.
+     */
+    recurseApplyDefault(isUpdate: boolean, documentSubset: JSONObject, collectionSpecSubset: Record<string, CuratedFieldSpecification>): JSONObject;
+    /**
+     * Validates every field of a document subset against its specification.
+     *
+     * @throws {StrictnessError} when `strictness` holds and the subset declares a
+     * field the specification does not — caught by the two callers, which turn it
+     * into a message naming the field.
      */
-    curateSpecification(): Promise<T>;
+    recurseFieldValidation(documentSubset: JSONObject | null, collectionSpecSubset: Record<string, CuratedFieldSpecification>, strictness: boolean, errorMessages: ErrorMessages, verbose: boolean): boolean;
     /**
-     * @param {string} indexName
-     * @param {string} collectionName
-     * @param {CollectionSpecification} collectionSpec
-     * @param {boolean} [verboseErrors]
-     * @returns {Promise<object>}
+     * Validates one field of a document subset against its specification.
      */
-    validateFormat(indexName: string, collectionName: string, collectionSpec: CollectionSpecification, verboseErrors?: boolean): Promise<object>;
+    isValidField(fieldName: string, documentSubset: JSONObject, collectionSpecSubset: Record<string, CuratedFieldSpecification>, strictness: boolean, errorMessages: ErrorMessages, verbose: boolean): boolean;
     /**
-     * @param {string} index
-     * @param {string} collection
-     * @param {CollectionSpecification} spec
-     * @param {boolean} [dryRun]
-     * @param {boolean} [verbose]
-     * @returns {Promise<CollectionSpecification>}
-     * @rejects PreconditionError
+     * Answers the values to validate — the array itself for a multivalued field,
+     * a single-element list otherwise — or `null` once it has filed the reason
+     * the field's arity is wrong.
      */
-    curateCollectionSpecification(index: string, collection: string, spec: CollectionSpecification, dryRun?: boolean, verbose?: boolean): Promise<CollectionSpecification>;
-    structureCollectionValidation(collectionSpec: any, indexName: any, collectionName: any, verboseErrors?: boolean): any;
+    private resolveFieldValues;
     /**
-     * @param {FieldSpecification} fieldSpec
-     * @param {string} indexName
-     * @param {string} collectionName
-     * @param {string} fieldName
-     * @param {boolean} [verboseErrors]
-     * @returns {object}
-     * @throws PreconditionError
+     * Hands one value to the field's registered type.
      */
-    curateFieldSpecification(fieldSpec: FieldSpecification, indexName: string, collectionName: string, fieldName: string, verboseErrors?: boolean): object;
+    private validateFieldValue;
     /**
-     * @param {FieldSpecification} fieldSpec
-     * @param {string} indexName
-     * @param {string} collectionName
-     * @param {string} fieldName
-     * @param {boolean} [verboseErrors]
-     * @returns {object}
-     * @throws PreconditionError
+     * Recurses into a value's children, turning this field's strictness breach
+     * into a message rather than an exception.
+     */
+    private validateFieldChildren;
+    /**
+     * Loads every stored specification, curates it, and swaps the result in.
+     *
+     * A collection whose specification does not curate is logged and skipped, so
+     * one bad specification cannot keep the others from being applied.
+     */
+    curateSpecification(): Promise<void>;
+    /**
+     * Reports whether a specification would curate, without registering it.
+     */
+    validateFormat(indexName: string, collectionName: string, collectionSpec: CollectionSpecification, verboseErrors?: boolean): Promise<SpecificationValidationResult>;
+    /**
+     * Turns a submitted specification into the tree the validator walks.
+     *
+     * Answers a {@link SpecificationValidationResult} instead of throwing when
+     * `verbose` holds, which is what lets `validateFormat` collect every problem
+     * rather than the first one.
+     *
+     * @throws {PreconditionError}
+     */
+    curateCollectionSpecification(index: string, collection: string, spec: CollectionSpecification, dryRun?: boolean, verbose?: false): Promise<CuratedCollectionSpecification>;
+    curateCollectionSpecification(index: string, collection: string, spec: CollectionSpecification, dryRun: boolean, verbose: boolean): Promise<CuratedCollectionSpecification | SpecificationValidationResult>;
+    /**
+     * Registers a specification's validator filter and answers its id.
+     *
+     * The wrapping is what `curateCollectionSpecification` did inline: a filter
+     * Koncorde refuses is an `invalid_filters` assertion, logged on the way
+     * past.
      */
-    curateFieldSpecificationFormat(fieldSpec: FieldSpecification, indexName: string, collectionName: string, fieldName: string, verboseErrors?: boolean): object;
+    private curateValidators;
     /**
-     * @param {string} indexName
-     * @param {string} collectionName
-     * @param {*} validatorFilter
-     * @param {boolean} dryRun
-     * @returns {string}
+     * Curates every field of a specification, then assembles them into a tree.
      */
-    curateValidatorFilter(indexName: string, collectionName: string, validatorFilter: any, dryRun: boolean): string;
+    structureCollectionValidation(collectionSpec: CollectionSpecification, indexName: string, collectionName: string, verboseErrors?: boolean): StructuredFieldSpecification | SpecificationValidationResult;
     /**
-     * @param {ValidationType} validationType
+     * Fills a field specification's defaults in and hands its `typeOptions` to
+     * the type that owns them.
+     *
+     * @throws {PreconditionError}
+     */
+    curateFieldSpecification(fieldSpec: FieldSpecification, indexName: string, collectionName: string, fieldName: string, verboseErrors?: boolean): SpecificationValidationResult & {
+        fieldSpec?: UnplacedCuratedField;
+    };
+    /**
+     * Checks a field specification's shape, before any type is consulted.
+     *
+     * @throws {PreconditionError}
+     */
+    curateFieldSpecificationFormat(fieldSpec: FieldSpecification, indexName: string, collectionName: string, fieldName: string, verboseErrors?: boolean): SpecificationValidationResult;
+    /**
+     * Registers a collection's validators as a Koncorde filter and answers its
+     * id — or validates it and answers `null`, on a dry run.
+     */
+    curateValidatorFilter(indexName: string, collectionName: string, validatorFilter: JSONObject[], dryRun: boolean): string | null;
+    /**
+     * Registers a validation type, built-in or plugin-provided.
+     *
+     * This is public API: `pluginContext` hands it to every plugin, so the
+     * runtime assertions below are the contract and stay exactly as they were —
+     * a plugin's type is not checked by the compiler.
+     *
      * @throws {PluginImplementationError}
      */
-    addType(validationType: ValidationType): void;
+    addType(validationType: BaseType): void;
+    /**
+     * The validation type a curated field declares.
+     *
+     * Every caller reaches this through a field that `curateFieldSpecification`
+     * has been through, and that method refuses a `type` the map does not hold —
+     * so the throw here is the invariant restated where the compiler can see it,
+     * not a new failure mode.
+     *
+     * @throws {PreconditionError} when the type is not registered
+     */
+    private typeOf;
 }
-import { Koncorde } from "koncorde";
+export = Validation;