kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/core/validation/baseType.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,36 +19,25 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
 /**
- * @class BaseType
+ * Base class of every validation type, and the contract `Validation.addType`
+ * checks a plugin-provided type against.
+ *
+ * @typeParam TOptions - the `typeOptions` shape this type accepts, once
+ *   `validateFieldSpecification` has run
+ * @typeParam TSpecification - the `typeOptions` shape a user writes, which
+ *   `validateFieldSpecification` checks and normalises into `TOptions`; the
+ *   same shape unless the type converts something
  */
 class BaseType {
-    /**
-     * Validate a document against a registered field type validator
-     *
-     * @param {TypeOptions} typeOptions
-     * @param {*} fieldValue
-     * @param {string[]} errorMessages
-     * @returns {boolean}
-     */
     validate() {
         return true;
     }
-    /**
-     * Validate a field specification itself
-     *
-     * @param {TypeOptions} typeOptions
-     * @returns {TypeOptions}
-     * @throws {KuzzleError}
-     */
     validateFieldSpecification(opts) {
         return opts;
     }
     /**
-     * @param {*} object
-     * @param {string[]} allowedProperties
-     * @returns {boolean}
+     * Narrows `object` to a plain object holding none but the allowed properties.
      */
     checkAllowedProperties(object, allowedProperties) {
         if (typeof object !== "object" ||
@@ -55,13 +45,8 @@ class BaseType {
             object === null) {
             return false;
         }
-        return !Object.keys(object).some((propertyName) => allowedProperties.indexOf(propertyName) === -1);
+        return !Object.keys(object).some((propertyName) => !allowedProperties.includes(propertyName));
     }
-    /**
-     * @param {StructuredFieldSpecification} fieldSpec
-     * @param {boolean} parentStrictness
-     * @returns {boolean}
-     */
     getStrictness(fieldSpec, parentStrictness) {
         return parentStrictness;
     }

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

@@ -0,0 +1,148 @@
+import type { JSONObject } from "../../types/JSONObject";
+import type { TypeOptions } from "./typeOptions";
+/**
+ * The shapes a collection validation specification passes through.
+ *
+ * Like `typeOptions` before it ([step 09](../../../docs/adr-001/steps/09-sprint-6-core-ii.md)),
+ * every name here existed only as a JSDoc `@typedef` that was never declared:
+ * `FieldSpecification`, `StructuredFieldSpecification`, `CollectionSpecification`
+ * and `DocumentSpecification` were written in annotations across
+ * `validation.js` and `default.config.ts` and resolved to nothing.
+ *
+ * The distinction the JSDoc could not draw, and which is the whole reason this
+ * file has four types rather than one, is **before and after curation**. What a
+ * user submits is a flat map of path-keyed fields with almost everything
+ * optional; what the validator walks at runtime is a tree, with defaults filled
+ * in and `path`/`depth`/`children` added. `curateCollectionSpecification` is
+ * the boundary between the two.
+ */
+/** A field's multivalued constraints, as submitted. */
+export interface MultivaluedSpecification {
+    value: boolean;
+    minCount?: number;
+    maxCount?: number;
+}
+/**
+ * One field of a collection specification, as submitted. Keys of the enclosing
+ * map are `/`-separated paths (`"address/city"`), which is what gives the tree
+ * its shape once curated.
+ */
+export interface FieldSpecification {
+    type: string;
+    mandatory?: boolean;
+    defaultValue?: unknown;
+    description?: string;
+    multivalued?: MultivaluedSpecification;
+    typeOptions?: TypeOptions;
+}
+/**
+ * A field once curated, as it sits in the tree `curateStructuredFields` builds.
+ *
+ * The tree's **root** is the single node carrying `root: true` and no `type`:
+ * it holds children and nothing else. Every other node is a curated field, so
+ * the properties `curateFieldSpecification` guarantees (`mandatory`,
+ * `multivalued`, `typeOptions`) are optional here only because the root does
+ * not have them.
+ */
+export interface StructuredFieldSpecification {
+    /** Set on the tree root, and only there. */
+    root?: boolean;
+    type?: string;
+    /** The field's key split on `/` — `["address", "city"]`. */
+    path?: string[];
+    /** `path.length`; the depth counting starts at 1. */
+    depth?: number;
+    mandatory?: boolean;
+    defaultValue?: unknown;
+    description?: string;
+    multivalued?: MultivaluedSpecification;
+    typeOptions?: TypeOptions;
+    children?: Record<string, CuratedFieldSpecification>;
+}
+/**
+ * A node hanging off some `children` map: always a curated field, never the
+ * root. Everything the root is missing is present here, because it is
+ * `curateFieldSpecification` that puts it there —
+ *
+ * - `type` is checked by `curateFieldSpecificationFormat` before anything else;
+ * - `mandatory` and `multivalued.value` are filled by its `defaultsDeep`;
+ * - `typeOptions` defaults to `{}` and is then replaced by whatever the owning
+ *   type's `validateFieldSpecification` answers;
+ * - `path` and `depth` are set by `curateCollectionSpecification` on the way
+ *   into the tree.
+ *
+ * Splitting this out is what lets the walkers stop asking whether each of them
+ * is there: they only ever receive children, and a child is always curated.
+ */
+export interface CuratedFieldSpecification extends StructuredFieldSpecification {
+    root?: false;
+    type: string;
+    path: string[];
+    depth: number;
+    mandatory: boolean;
+    multivalued: MultivaluedSpecification;
+    typeOptions: TypeOptions;
+    children?: Record<string, CuratedFieldSpecification>;
+}
+/**
+ * A field once `curateFieldSpecification` is done with it, and before the tree
+ * gives it its place: everything a curated field carries except `path` and
+ * `depth`, which `structureCollectionValidation` assigns from the field's key.
+ */
+export type UnplacedCuratedField = Omit<CuratedFieldSpecification, "path" | "depth"> & {
+    path?: string[];
+    depth?: number;
+};
+/** A collection's specification, as submitted. */
+export interface CollectionSpecification {
+    strict?: boolean;
+    fields?: Record<string, FieldSpecification>;
+    validators?: JSONObject[];
+}
+/**
+ * A collection's specification once curated: the fields are a tree, and
+ * `validators` has been replaced by the Koncorde filter id registered for it
+ * (or `null` on a dry run, and when the collection declares no validator).
+ */
+export interface CuratedCollectionSpecification {
+    strict: boolean;
+    fields: StructuredFieldSpecification;
+    validators: string | null;
+}
+/** Curated specifications, by index then collection. */
+export type DocumentSpecification = Record<string, Record<string, CuratedCollectionSpecification>>;
+/** Raw specifications as they are stored, by index then collection. */
+export type RawSpecification = Record<string, Record<string, CollectionSpecification>>;
+/**
+ * The configuration's startup specifications (`validation`), read as what
+ * they are. The configuration's type declares them `Record<string, unknown>`
+ * — it is public, and that is what v2.56.0 declared — and what they hold is
+ * checked specification by specification when it is curated.
+ */
+export declare function configuredSpecifications(): RawSpecification;
+/**
+ * What the curation methods answer when asked not to fail fast. `errors` is
+ * present exactly when `isValid` is false.
+ */
+export interface SpecificationValidationResult {
+    isValid: boolean;
+    errors?: string[];
+}
+/**
+ * Verbose validation errors, keyed by where they happened. A field's messages
+ * hang off the tree at its own path, so a caller can report them in place.
+ */
+export interface FieldErrorScope {
+    children?: Record<string, FieldErrorScope>;
+    messages?: string[];
+}
+export interface VerboseErrorMessages {
+    documentScope?: string[];
+    fieldScope?: FieldErrorScope;
+}
+/**
+ * Where validation errors are collected. A flat list when `verbose` is false —
+ * in which case nothing is ever pushed to it, because the first failure throws
+ * — and the structured holder above when it is true.
+ */
+export type ErrorMessages = string[] | VerboseErrorMessages;

package/dist/lib/core/validation/specification.js

@@ -0,0 +1,34 @@
+"use strict";
+/*
+ * Kuzzle, a backend software, self-hostable and ready to use
+ * to power modern apps
+ *
+ * Copyright 2015-2022 Kuzzle
+ * mailto: support AT kuzzle.io
+ * website: http://kuzzle.io
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configuredSpecifications = void 0;
+/**
+ * The configuration's startup specifications (`validation`), read as what
+ * they are. The configuration's type declares them `Record<string, unknown>`
+ * — it is public, and that is what v2.56.0 declared — and what they hold is
+ * checked specification by specification when it is curated.
+ */
+function configuredSpecifications() {
+    return global.kuzzle.config.validation;
+}
+exports.configuredSpecifications = configuredSpecifications;
+//# sourceMappingURL=specification.js.map

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

@@ -0,0 +1,62 @@
+import type { Moment } from "moment";
+/**
+ * A field's `typeOptions`: an arbitrary, user-provided object, narrowed by each
+ * validation type into the shape that type actually accepts.
+ *
+ * The narrowed shapes below describe the options **after**
+ * `validateFieldSpecification` has run: that method is what rejects the invalid
+ * ones and fills the defaults in, so `validate` may rely on them.
+ */
+export type TypeOptions = Record<string, unknown>;
+/**
+ * Bounds of a `date` range, as `validateFieldSpecification` leaves them: either
+ * a parsed moment, or the `NOW` literal kept verbatim so that it is resolved at
+ * validation time rather than at specification time.
+ */
+export type DateRangeBound = Moment | "NOW";
+export interface DateTypeOptions extends TypeOptions {
+    formats?: string[];
+    range?: {
+        min?: DateRangeBound;
+        max?: DateRangeBound;
+    };
+}
+/**
+ * Bounds of a `date` range as a user writes them, before
+ * `validateFieldSpecification` converts them into {@link DateRangeBound}s: an
+ * ISO 8601 string, an epoch number, or `NOW`.
+ */
+export type DateSpecificationBound = string | number;
+/** The `date` type's `typeOptions` as a user writes them. */
+export interface DateSpecification extends TypeOptions {
+    formats?: string[];
+    range?: {
+        min?: DateSpecificationBound;
+        max?: DateSpecificationBound;
+    };
+}
+export interface EnumTypeOptions extends TypeOptions {
+    values?: string[];
+}
+export interface GeoShapeTypeOptions extends TypeOptions {
+    shapeTypes?: string[];
+}
+/** Shared by the `email`, `ip_address` and `url` types. */
+export interface NotEmptyTypeOptions extends TypeOptions {
+    notEmpty?: boolean;
+}
+export interface NumericTypeOptions extends TypeOptions {
+    range?: {
+        min?: number;
+        max?: number;
+    };
+}
+export interface ObjectTypeOptions extends TypeOptions {
+    strict?: boolean;
+}
+export interface StringTypeOptions extends TypeOptions {
+    length?: {
+        min?: number;
+        max?: number;
+    };
+}

package/dist/lib/core/validation/typeOptions.js

@@ -0,0 +1,23 @@
+"use strict";
+/*
+ * Kuzzle, a backend software, self-hostable and ready to use
+ * to power modern apps
+ *
+ * Copyright 2015-2022 Kuzzle
+ * mailto: support AT kuzzle.io
+ * website: http://kuzzle.io
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=typeOptions.js.map

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

@@ -1,10 +1,7 @@
-export = AnythingType;
-/**
- * @class AnythingType
- */
+import BaseType from "../baseType";
 declare class AnythingType extends BaseType {
     typeName: string;
     allowChildren: boolean;
-    allowedTypeOptions: any[];
+    allowedTypeOptions: string[];
 }
-import BaseType = require("../baseType");
+export = AnythingType;

package/dist/lib/core/validation/types/anything.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,14 +19,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
-const BaseType = require("../baseType");
-/**
- * @class AnythingType
- */
-class AnythingType extends BaseType {
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const baseType_1 = __importDefault(require("../baseType"));
+class AnythingType extends baseType_1.default {
     constructor() {
-        super();
+        super(...arguments);
         this.typeName = "anything";
         this.allowChildren = false;
         this.allowedTypeOptions = [];

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

@@ -1,16 +1,9 @@
-export = BooleanType;
-/**
- * @class BooleanType
- */
+import BaseType from "../baseType";
+import type { TypeOptions } from "../typeOptions";
 declare class BooleanType extends BaseType {
     typeName: string;
     allowChildren: boolean;
-    allowedTypeOptions: any[];
-    /**
-     * @param {TypeOptions} typeOptions
-     * @param {*} fieldValue
-     * @param {string[]} errorMessages
-     */
-    validate(typeOptions: TypeOptions, fieldValue: any, errorMessages: string[]): boolean;
+    allowedTypeOptions: string[];
+    validate(typeOptions: TypeOptions, fieldValue: unknown, errorMessages: string[]): boolean;
 }
-import BaseType = require("../baseType");
+export = BooleanType;

package/dist/lib/core/validation/types/boolean.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,23 +19,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
-const BaseType = require("../baseType");
-/**
- * @class BooleanType
- */
-class BooleanType extends BaseType {
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const baseType_1 = __importDefault(require("../baseType"));
+class BooleanType extends baseType_1.default {
     constructor() {
-        super();
+        super(...arguments);
         this.typeName = "boolean";
         this.allowChildren = false;
         this.allowedTypeOptions = [];
     }
-    /**
-     * @param {TypeOptions} typeOptions
-     * @param {*} fieldValue
-     * @param {string[]} errorMessages
-     */
     validate(typeOptions, fieldValue, errorMessages) {
         if (typeof fieldValue !== "boolean") {
             errorMessages.push("The field must be of type boolean.");

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

@@ -1,17 +1,25 @@
-export = DateType;
-/**
- * @class DateType
- */
-declare class DateType extends BaseType {
+import BaseType from "../baseType";
+import type { DateSpecification, DateTypeOptions } from "../typeOptions";
+declare class DateType extends BaseType<DateTypeOptions, DateSpecification> {
     typeName: string;
     allowChildren: boolean;
     allowedTypeOptions: string[];
+    validate(typeOptions: DateTypeOptions, fieldValue: unknown, errorMessages: string[]): boolean;
+    /**
+     * Normalises the specification **in place**, as it always has — the caller's
+     * object is the one it answers — which is why the result is `Object.assign`ed
+     * onto it rather than built beside it.
+     *
+     * @throws {PreconditionError}
+     */
+    validateFieldSpecification(specification: DateSpecification): DateTypeOptions;
     /**
-     * @param {TypeOptions} typeOptions
-     * @param {*} fieldValue
-     * @param {string[]} errorMessages
-     * @returns {boolean}
+     * Converts `range`'s bounds, in place: each becomes a moment, except `NOW`,
+     * which is kept verbatim so that it resolves at validation time rather than
+     * at specification time.
+     *
+     * @throws {PreconditionError}
      */
-    validate(typeOptions: TypeOptions, fieldValue: any, errorMessages: string[]): boolean;
+    private validateRange;
 }
-import BaseType = require("../baseType");
+export = DateType;