kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/api/request/kuzzleRequest.js

@@ -90,9 +90,13 @@ class KuzzleRequest {
         // @deprecated - Backward compatibility with the RequestInput.headers
         // property
         this[_input].headers = this[_context].connection.misc.headers;
-        this.id = data.requestId
+        // Through a local: `assertString` answers `string | null` and the ternary
+        // is what proves it non-null here, which the declaration of `id` cannot
+        // see. `?? uuid.v4()` keeps the falsy-requestId path exactly as it was.
+        const requestId = data.requestId
             ? assert.assertString("requestId", data.requestId)
-            : uuid.v4();
+            : null;
+        this.id = requestId ?? uuid.v4();
         this[_timestamp] = data.timestamp || Date.now();
         // handling provided options
         if (options !== undefined && options !== null) {
@@ -118,9 +122,10 @@ class KuzzleRequest {
                 }
                 else {
                     const error = new errors_1.KuzzleError(options.error.message, options.error.status || 500);
-                    for (const prop of Object.keys(options.error).filter((key) => key !== "message" && key !== "status")) {
-                        error[prop] = options.error[prop];
-                    }
+                    // `Object.assign` rather than an indexed write: a KuzzleError has no
+                    // index signature, and these are arbitrary extra properties carried
+                    // over from a plain object.
+                    Object.assign(error, Object.fromEntries(Object.entries(options.error).filter(([key]) => key !== "message" && key !== "status")));
                     this.setError(error);
                 }
             }
@@ -142,6 +147,15 @@ class KuzzleRequest {
     get deprecations() {
         return this[_deprecations];
     }
+    /**
+     * The setter `RequestResponse.deprecations` has always assigned through to
+     * here, and there was no setter to assign to: in a module — which is strict
+     * mode — writing to an accessor-only property throws a TypeError. Nothing in
+     * the tree exercised it, so the throw was never seen.
+     */
+    set deprecations(deprecations) {
+        this[_deprecations] = deprecations;
+    }
     /**
      * Request timestamp (in Epoch-micro)
      */
@@ -211,7 +225,7 @@ class KuzzleRequest {
     /**
      * Sets the request result and status
      *
-     * @deprecated Use request.response.configure instead
+     * @deprecated Use `request.response.configure({ result, status, headers, format })`
      *
      * @param result Request result. Will be converted to JSON unless `raw` option is set to `true`
      * @param options Additional options
@@ -220,13 +234,7 @@ class KuzzleRequest {
      *    - `raw` (boolean): instead of a Kuzzle response, forward the result directly (default: false)
      */
     setResult(result, options = {}) {
-        if (result instanceof Error) {
-            throw new errors_1.InternalError("cannot set an error as a request's response");
-        }
-        if (this.context.connection.protocol !== "http" &&
-            result instanceof types_1.HttpStream) {
-            throw kerror.get("api", "assert", "forbidden_stream");
-        }
+        this.assertResultAllowed(result);
         this.status = options.status || 200;
         if (options.headers) {
             this.response.configure({
@@ -238,6 +246,29 @@ class KuzzleRequest {
         }
         this[_result] = result;
     }
+    /**
+     * Sets the result and nothing else, after the checks every result goes
+     * through. What `response.configure({ result })` calls; plugins use that.
+     *
+     * @internal
+     */
+    assignResult(result) {
+        this.assertResultAllowed(result);
+        this[_result] = result;
+    }
+    /**
+     * @throws {InternalError} if the result is an Error
+     * @throws {api.assert.forbidden_stream} for an HttpStream outside HTTP
+     */
+    assertResultAllowed(result) {
+        if (result instanceof Error) {
+            throw new errors_1.InternalError("cannot set an error as a request's response");
+        }
+        if (this.context.connection.protocol !== "http" &&
+            result instanceof types_1.HttpStream) {
+            throw kerror.get("api", "assert", "forbidden_stream");
+        }
+    }
     /**
      * Add a deprecation for a used component, this can be action/controller/parameters...
      *
@@ -295,6 +326,10 @@ class KuzzleRequest {
      *
      * This can be used to match Koncorde filter rather than the Request object
      * because it has properties defined with invisible unicode characters.
+     *
+     * The `!`s are not claims: each of these may be `null`, as on the request
+     * itself. The copy is typed as v2.56.0 typed it, non-nullable, because
+     * nullable members broke code compiled against that.
      */
     pojo() {
         return {
@@ -326,12 +361,19 @@ class KuzzleRequest {
     }
     /**
      * Return the requested controller
+     *
+     * `null` on a request built without one. Declared `string` all the same,
+     * as v2.56.0 declared it: a `string | null` return broke code compiled
+     * against it. `input.controller` is the nullable form.
      */
     getController() {
         return this[_input].controller;
     }
     /**
      * Returns the requested controller's action
+     *
+     * `null` and declared `string` as {@link getController} is;
+     * `input.action` is the nullable form.
      */
     getAction() {
         return this[_input].action;
@@ -538,13 +580,15 @@ class KuzzleRequest {
         return this._getArray(this.input.args, name, name, def, true);
     }
     /**
-     * @deprecated do not use, Use getArray instead
-     *
-     * Gets a parameter from a request arguments and checks that it is an array
-     *
-     * If the request argument is a String instead of an array, it will be JSON parsed
-     * and returned if it is a valid JSON array, otherwise it will return the string splitted on `,`.
+     * Gets a parameter from a request arguments as an array, also accepting a
+     * **comma-separated string** — the form the API documents for `ids` on
+     * `document:mGet`, `document:mExists` and `security:mGetUsers`, and the only
+     * form it documents for `server:healthCheck`'s `services`.
      *
+     * An array is returned as is. A string is, over HTTP only, first parsed as a
+     * JSON array — the one way to pass an element that contains a comma — and
+     * otherwise split on `,`, on every protocol. Unlike `getArray`, a single
+     * query-string value (`?ids=a`) is therefore a one-element array.
      *
      * @param name parameter name
      * @param def default value to return if the parameter is not set
@@ -553,7 +597,7 @@ class KuzzleRequest {
      *                                       value provided
      * @throws {api.assert.invalid_type} If the fetched parameter is not an array or a string
      */
-    getArrayLegacy(name, def = undefined) {
+    getArrayOrCsv(name, def = undefined) {
         const value = (0, lodash_1.get)(this.input.args, name, def);
         if (value === undefined) {
             throw assertionError.get("missing_argument", name);
@@ -573,12 +617,20 @@ class KuzzleRequest {
                     return parsedValue;
                 }
             }
-            catch (e) {
+            catch {
                 // Do nothing, let the code continue
             }
         }
         return value.split(",");
     }
+    /**
+     * @deprecated Use {@link getArrayOrCsv}, which it is an alias of: same
+     * behaviour, named after what it does. Kept because `KuzzleRequest` is part
+     * of the public plugin API.
+     */
+    getArrayLegacy(name, def = undefined) {
+        return this.getArrayOrCsv(name, def);
+    }
     /**
      * Gets a parameter from a request arguments and checks that it is an object
      *
@@ -639,6 +691,11 @@ class KuzzleRequest {
     }
     /**
      * Returns the index specified in the request
+     *
+     * With `{ required: false }` and no index, this returns `null`. It is
+     * declared `string` all the same: that is what v2.56.0 declared, and a
+     * `string | null` overload broke code compiled against it — so Kuzzle's own
+     * callers of the optional form annotate the result `string | null`.
      */
     getIndex({ required = true } = {}) {
         const index = this.input.args.index;
@@ -647,6 +704,9 @@ class KuzzleRequest {
     }
     /**
      * Returns the collection specified in the request
+     *
+     * `null` under the same conditions as {@link getIndex}, and declared
+     * `string` for the same reason.
      */
     getCollection({ required = true } = {}) {
         const collection = this.input.args.collection;
@@ -692,6 +752,8 @@ class KuzzleRequest {
      *    - `ifMissing`: method behavior if the ID is missing (default: 'error')
      *    - `generator`: function used to generate an ID (default: 'uuid.v4')
      *
+     * With `ifMissing: 'ignore'` and no ID, this returns `null`. It is declared
+     * `string` all the same, for the reason given on {@link getIndex}.
      */
     getId(options = { generator: uuid.v4, ifMissing: "error" }) {
         const id = this.input.args._id;
@@ -721,6 +783,9 @@ class KuzzleRequest {
     }
     /**
      * Returns the current user
+     *
+     * `null` when the request carries none. Declared `User`, as v2.56.0
+     * declared it; `context.user` is the nullable form.
      */
     getUser() {
         if (this.context?.user) {
@@ -928,7 +993,7 @@ class KuzzleRequest {
                         return parsedValue;
                     }
                 }
-                catch (e) {
+                catch {
                     // Do nothing, let the error be thrown below
                 }
             }
@@ -965,7 +1030,7 @@ class KuzzleRequest {
                         return parsedValue;
                     }
                 }
-                catch (e) {
+                catch {
                     // Do nothing, let the error be thrown below
                 }
             }

package/dist/lib/api/request/requestContext.d.ts

@@ -1,6 +1,13 @@
-import { JSONObject } from "kuzzle-sdk";
-import { Token } from "../../model/security/token";
-import { User } from "../../model/security/user";
+import type { JSONObject } from "../../types/JSONObject";
+import type { Token } from "../../model/security/token";
+import type { User } from "../../model/security/user";
+declare const _token = "token\u200B";
+declare const _user = "user\u200B";
+declare const _connection = "connection\u200B";
+declare const _c_id = "id\u200B";
+declare const _c_protocol = "protocol\u200B";
+declare const _c_ips = "ips\u200B";
+declare const _c_misc = "misc\u200B";
 export type ContextMisc = {
     /**
      * HTTP url
@@ -25,16 +32,20 @@ export type ContextMisc = {
  * Information about the connection at the origin of the request.
  */
 export declare class Connection {
+    [_c_id]: string | null;
+    [_c_protocol]: string | null;
+    [_c_ips]: string[];
+    [_c_misc]: ContextMisc;
     constructor(connection: any);
     /**
      * Unique identifier of the user connection
      */
-    set id(str: string);
+    set id(str: string | null);
     get id(): string | null;
     /**
      * Network protocol name
      */
-    set protocol(str: string);
+    set protocol(str: string | null);
     get protocol(): string | null;
     /**
      * Chain of IP addresses, starting from the client
@@ -57,6 +68,9 @@ export declare class Connection {
  * and origin (connection, protocol).
  */
 export declare class RequestContext {
+    [_token]: Token | null;
+    [_user]: User | null;
+    [_connection]: Connection;
     constructor(options?: any);
     /**
      * Serializes the RequestContext object
@@ -88,3 +102,4 @@ export declare class RequestContext {
     get user(): User | null;
     set user(obj: User | null);
 }
+export {};

package/dist/lib/api/request/requestContext.js

@@ -68,12 +68,22 @@ class Connection {
         if (typeof connection !== "object" || connection === null) {
             return;
         }
-        for (const prop of Object.keys(connection)) {
-            if (["id", "protocol", "ips"].includes(prop)) {
-                this[prop] = connection[prop];
+        // Assigned by name rather than through a dynamic index, and straight to the
+        // backing fields: the value read out of an arbitrary object is `unknown`,
+        // and asserting it here is the same single check the matching setter would
+        // have run.
+        for (const [prop, value] of Object.entries(connection)) {
+            if (prop === "id") {
+                this[_c_id] = assert.assertString("connection.id", value);
+            }
+            else if (prop === "protocol") {
+                this[_c_protocol] = assert.assertString("connection.protocol", value);
+            }
+            else if (prop === "ips") {
+                this[_c_ips] = assert.assertArray("connection.ips", value, "string");
             }
             else {
-                this.misc[prop] = connection[prop];
+                this.misc[prop] = value;
             }
         }
     }

package/dist/lib/api/request/requestInput.d.ts

@@ -1,4 +1,11 @@
-import { JSONObject } from "kuzzle-sdk";
+import type { JSONObject } from "../../types/JSONObject";
+declare const _jwt = "jwt\u200B";
+declare const _volatile = "volatile\u200B";
+declare const _body = "body\u200B";
+declare const _headers = "headers\u200B";
+declare const _controller = "controller\u200B";
+declare const _action = "action\u200B";
+declare const _triggerEvents = "triggerEvents\u200B";
 /**
  * @deprecated
  */
@@ -69,6 +76,13 @@ export declare class RequestInput {
      *  }
      */
     resource: RequestResource;
+    [_jwt]: string | null;
+    [_volatile]: JSONObject | null;
+    [_body]: JSONObject | null;
+    [_headers]: JSONObject | null;
+    [_controller]: string | null;
+    [_action]: string | null;
+    [_triggerEvents]: boolean | undefined;
     /**
      * Builds a Kuzzle normalized request input object
      *
@@ -76,8 +90,11 @@ export declare class RequestInput {
      * format as the one used, for instance, for the Websocket protocol
      *
      * Any undefined option is set to null
+     *
+     * @param data - a non-null object; anything else throws. Declared
+     * `unknown`, as v2.56.0's `any` accepted anything.
      */
-    constructor(data: any);
+    constructor(data: unknown);
     /**
      * Authentication token.
      * @example
@@ -96,7 +113,7 @@ export declare class RequestInput {
      *  }
      */
     get jwt(): string | null;
-    set jwt(str: string);
+    set jwt(str: string | null);
     /**
      * API controller name.
      * @example
@@ -156,14 +173,27 @@ export declare class RequestInput {
      *  }
      */
     get body(): JSONObject | null;
-    set body(obj: JSONObject | Array<any>);
+    /**
+     * `null` is accepted, and was already the only way to *clear* a body:
+     * `assertArrayOrObject` answers `null` for both `null` and `undefined`, the
+     * constructor initialises the field to `null`, and the getter above declares
+     * it. The parameter type excluded the one value the implementation handles
+     * first — the same asymmetry `headers` documents just below.
+     */
+    set body(obj: JSONObject | Array<any> | null);
     /**
      * Request headers (Http only).
      *
      * @deprecated Use RequestContext.connection.misc.headers instead
      */
     get headers(): JSONObject | null;
-    set headers(obj: JSONObject);
+    /**
+     * `undefined` is accepted because `KuzzleRequest`'s constructor assigns
+     * `context.connection.misc.headers`, which a connection without headers does
+     * not have. `assertObject` answers null for it, which is what the getter has
+     * always reported.
+     */
+    set headers(obj: JSONObject | undefined);
     /**
      * Volatile object.
      * @example
@@ -182,5 +212,6 @@ export declare class RequestInput {
      *  }
      */
     get volatile(): JSONObject | null;
-    set volatile(obj: JSONObject);
+    set volatile(obj: JSONObject | null);
 }
+export {};

package/dist/lib/api/request/requestInput.js

@@ -110,14 +110,6 @@ exports.RequestResource = RequestResource;
  * "_id", "index", "collection", "refresh", "onExistingUser", "foobar", etc.
  */
 class RequestInput {
-    /**
-     * Builds a Kuzzle normalized request input object
-     *
-     * The 'data' object accepts a request content using the same
-     * format as the one used, for instance, for the Websocket protocol
-     *
-     * Any undefined option is set to null
-     */
     constructor(data) {
         if (!data || typeof data !== "object" || Array.isArray(data)) {
             throw new internalError_1.InternalError("Input request data must be a non-null object");
@@ -127,7 +119,11 @@ class RequestInput {
         this[_body] = null;
         this[_controller] = null;
         this[_action] = null;
-        this[_triggerEvents] = null;
+        // `undefined`, not `null`: the setter already normalises "not asked for"
+        // to undefined, and the getter has always declared `boolean | undefined`.
+        // The only reader is a truthiness test in funnel.ts, so this is the same
+        // value said honestly.
+        this[_triggerEvents] = undefined;
         // default value to null for former "resources" to avoid breaking
         this.args = {};
         this.resource = new RequestResource(this.args);
@@ -171,6 +167,9 @@ class RequestInput {
     get jwt() {
         return this[_jwt];
     }
+    // `| null` for the same reason as `body` below: `assertString` answers
+    // `null` for `null` and `undefined` in its first branch, and the getter
+    // above declares it. See docs/adr-001/steps/14-test-program-strict.md (M5).
     set jwt(str) {
         this[_jwt] = assert.assertString("jwt", str);
     }
@@ -253,6 +252,13 @@ class RequestInput {
     get body() {
         return this[_body];
     }
+    /**
+     * `null` is accepted, and was already the only way to *clear* a body:
+     * `assertArrayOrObject` answers `null` for both `null` and `undefined`, the
+     * constructor initialises the field to `null`, and the getter above declares
+     * it. The parameter type excluded the one value the implementation handles
+     * first — the same asymmetry `headers` documents just below.
+     */
     set body(obj) {
         this[_body] = assert.assertArrayOrObject("body", obj);
     }
@@ -264,6 +270,12 @@ class RequestInput {
     get headers() {
         return this[_headers];
     }
+    /**
+     * `undefined` is accepted because `KuzzleRequest`'s constructor assigns
+     * `context.connection.misc.headers`, which a connection without headers does
+     * not have. `assertObject` answers null for it, which is what the getter has
+     * always reported.
+     */
     set headers(obj) {
         this[_headers] = assert.assertObject("headers", obj);
     }
@@ -287,6 +299,7 @@ class RequestInput {
     get volatile() {
         return this[_volatile];
     }
+    // `| null`, as `assertObject` and the getter above both allow.
     set volatile(obj) {
         this[_volatile] = assert.assertObject("volatile", obj);
     }

package/dist/lib/api/request/requestResponse.d.ts

@@ -1,17 +1,21 @@
-import { JSONObject } from "kuzzle-sdk";
-import { Deprecation } from "../../types";
-import { KuzzleError } from "../../kerror/errors/kuzzleError";
+import type { JSONObject } from "../../types/JSONObject";
+import type { KuzzleRequest } from "./kuzzleRequest";
+import type { Deprecation } from "../../types";
+import type { KuzzleError } from "../../kerror/errors/kuzzleError";
+declare const _request = "request\u200B";
+declare const _headers = "headers\u200B";
+declare const _userHeaders = "userHeaders\u200B";
 export declare class Headers {
     headers: JSONObject;
     private namesMap;
-    private proxy;
+    proxy: any;
     constructor();
     /**
      * Gets a header value
      *
      * @param name Header name. Could be a string (case-insensitive) or a symbol
      */
-    getHeader(name: any): string | void;
+    getHeader(name: any): string | undefined;
     removeHeader(name: string): boolean;
     setHeader(name: string, value: string): boolean;
 }
@@ -23,7 +27,14 @@ export declare class RequestResponse {
      * If sets to true, "result" content will not be wrapped in a Kuzzle response
      */
     raw: boolean;
-    constructor(request: any);
+    [_request]: KuzzleRequest;
+    [_headers]: Headers;
+    [_userHeaders]: Set<string>;
+    /**
+     * @param request - the request this is the response of. Declared
+     * `unknown`, as v2.56.0's `any` accepted anything.
+     */
+    constructor(request: unknown);
     /**
      * Get the parent request deprecations
      */
@@ -32,7 +43,7 @@ export declare class RequestResponse {
      * Set the parent request deprecations
      * @param {Object[]} deprecations
      */
-    set deprecations(deprecations: Array<Deprecation> | void);
+    set deprecations(deprecations: Array<Deprecation> | undefined);
     /**
      * Get the parent request status
      * @returns {number}
@@ -43,7 +54,12 @@ export declare class RequestResponse {
      * Request error
      */
     get error(): KuzzleError | null;
-    set error(e: KuzzleError | null);
+    /**
+     * Narrower than the getter on purpose: `setError` throws an InternalError on
+     * anything that is not an Error, so assigning null here has never cleared the
+     * error — `KuzzleRequest.clearError()` is what does that.
+     */
+    set error(e: KuzzleError);
     /**
      * Request external ID
      */
@@ -85,28 +101,47 @@ export declare class RequestResponse {
      * Configure the response
      *
      * @param [options]
+     * @param [options.result] - Response result. Set only when the key is
+     *   present, so `{ result: null }` clears it; the status is left to the
+     *   `status` option, unlike the `result` setter, which resets it to 200
      * @param [options.headers] - Additional protocol headers
-     * @param [options.status=200] - HTTP status code
+     * @param [options.status] - HTTP status code. When absent, a pending 102
+     *   becomes 200 and any other status is kept
      * @param [options.format] - Response format, standard or raw
      *
+     * @throws {InternalError} if the result is an Error
+     * @throws {api.assert.forbidden_stream} if the result is an HttpStream and
+     *   the protocol is not HTTP
+     *
      * @returns void
      */
     configure(options?: {
         headers?: JSONObject;
         status?: number;
         format?: "standard" | "raw";
+        result?: unknown;
     }): void;
     /**
      * Gets a header value (case-insensitive)
+     *
+     * A missing header gives `undefined`, as it always has. The declared
+     * `string | null` is v2.56.0's, which code compiled against it assigns to
+     * a `string | null` — so test a result with `== null`, which covers both.
      */
     getHeader(name: string): string | null;
     /**
      * Deletes a header (case-insensitive)
+     *
+     * Answers `true`. Declared `any`, as v2.56.0 declared it: a `boolean`
+     * breaks code compiled against that, e.g. `return` of it from a function
+     * declared `void`.
      */
     removeHeader(name: string): any;
     /**
      * Sets a new array. Behaves the same as Node.js' HTTP response.setHeader
      * method (@see https://nodejs.org/api/http.html#http_response_setheader_name_value)
+     *
+     * Answers `true`, declared `any` for the reason given on `removeHeader`.
      */
     setHeader(name: string, value: string): any;
     /**
@@ -118,3 +153,4 @@ export declare class RequestResponse {
      */
     toJSON(): JSONObject;
 }
+export {};