kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/kuzzle/event/KuzzleEventEmitter.d.ts

@@ -1,13 +1,22 @@
 import EventEmitter from "eventemitter3";
-import { AskEventDefinition, AskEventHandler, CallEventHandler, EventDefinition, HookEventHandler, PipeEventHandler } from "../../types/EventHandler";
+import type { AskEventDefinition, AskEventHandler, CallEventHandler, EventDefinition, HookEventHandler, PipeEventHandler, RegisteredPipeHandler } from "../../types/EventHandler";
 declare class KuzzleEventEmitter extends EventEmitter {
-    private coreAnswerers;
+    /**
+     * The ask answerers, whatever event each was registered for.
+     *
+     * `onAsk` is generic over its event, and a handler's parameters are
+     * contravariant: a handler for one event is not assignable to the handler
+     * type of another, so the only thing the map can say about all of them
+     * together is that they are callable. `ask()` dispatches through
+     * `Reflect.apply`, which is what that costs.
+     */
+    private readonly coreAnswerers;
     private coreSyncedAnswerers;
-    private corePipes;
-    private pipeRunner;
-    private pluginPipes;
-    private pluginPipeDefinitions;
-    private superEmit;
+    private readonly corePipes;
+    private readonly pipeRunner;
+    private readonly pluginPipes;
+    private readonly pluginPipeDefinitions;
+    private readonly superEmit;
     constructor(maxConcurrentPipes: number, pipesBufferSize: number);
     /**
      * Registers a core method on a pipe
@@ -59,8 +68,8 @@ declare class KuzzleEventEmitter extends EventEmitter {
      * Registers a plugin hook.
      * Catch any error in the handler and emit the hook:onError event.
      */
-    registerPluginHook<TEventDefinition extends EventDefinition = EventDefinition>(pluginName: string, event: TEventDefinition["name"], fn: HookEventHandler<TEventDefinition>): void;
-    registerPluginPipe<TEventDefinition extends EventDefinition = EventDefinition>(event: TEventDefinition["name"], handler: PipeEventHandler<TEventDefinition>): string;
+    registerPluginHook<TEventDefinition extends EventDefinition = EventDefinition>(pluginName: string, event: TEventDefinition["name"], fn: HookEventHandler<TEventDefinition> | ((...args: unknown[]) => unknown)): void;
+    registerPluginPipe<TEventDefinition extends EventDefinition = EventDefinition>(event: TEventDefinition["name"], handler: RegisteredPipeHandler<TEventDefinition>): string;
     unregisterPluginPipe(pipeId: string): void;
     /**
      * Checks if an ask event has an answerer

package/dist/lib/kuzzle/event/KuzzleEventEmitter.js

@@ -89,10 +89,9 @@ class KuzzleEventEmitter extends eventemitter3_1.default {
      */
     onPipe(event, fn) {
         (0, assert_1.default)(typeof fn === "function", `Cannot listen to pipe event ${event}: "${fn}" is not a function`);
-        if (!this.corePipes.has(event)) {
-            this.corePipes.set(event, []);
-        }
-        this.corePipes.get(event).push(fn);
+        const registered = this.corePipes.get(event) ?? [];
+        registered.push(fn);
+        this.corePipes.set(event, registered);
     }
     /**
      * Registers a core 'ask' event answerer
@@ -101,6 +100,9 @@ class KuzzleEventEmitter extends eventemitter3_1.default {
     onAsk(event, fn) {
         (0, assert_1.default)(typeof fn === "function", `Cannot listen to ask event "${event}": "${fn}" is not a function`);
         (0, assert_1.default)(!this.coreAnswerers.has(event), `Cannot add a listener to the ask event "${event}": event has already an answerer`);
+        // The map holds the un-parameterised handler: `onAsk` is generic over the
+        // event it registers, and what the map can say about all of them together
+        // is the base signature.
         this.coreAnswerers.set(event, fn);
     }
     /**
@@ -152,7 +154,10 @@ class KuzzleEventEmitter extends eventemitter3_1.default {
             typeof payload[payload.length - 1] === "function") {
             callback = payload.pop();
         }
-        const events = getWildcardEvents(event);
+        // Named once: the event is the pipe's target and the seed of its
+        // wildcard list, and the callback context carries it too.
+        const eventName = event;
+        const events = getWildcardEvents(eventName);
         const funcs = [];
         for (const element of events) {
             const targets = this.pluginPipes.get(element);
@@ -164,11 +169,18 @@ class KuzzleEventEmitter extends eventemitter3_1.default {
         }
         // Create a context for the emitPluginPipe callback
         const promback = new promback_1.default(callback);
+        // What the callback needs, rather than the whole emitter: it is invoked
+        // with this object as its receiver, from `pipeRunner`, and reaching back
+        // into two private members through it was the only thing that asked for
+        // `instance`.
         const callbackContext = {
+            corePipes: this.corePipes,
             events,
-            instance: this,
             promback,
-            targetEvent: event,
+            superEmit: (ev, ...a) => {
+                this.superEmit(ev, ...a);
+            },
+            targetEvent: eventName,
         };
         if (funcs.length === 0) {
             pipeCallback.call(callbackContext, null, ...payload);
@@ -187,7 +199,10 @@ class KuzzleEventEmitter extends eventemitter3_1.default {
         if (!fn) {
             throw kerror.get("core", "fatal", "assertion_failed", `the requested ask event '${event}' doesn't have an answerer`);
         }
-        const response = await fn(...args);
+        // `undefined` as the receiver, which is what `fn(...args)` passed: an
+        // answerer is registered as a bound function or an arrow, and handing it
+        // the emitter would be a new claim rather than a preserved one.
+        const response = await Reflect.apply(fn, undefined, args);
         for (const ev of getWildcardEvents(event)) {
             super.emit(ev, {
                 args,
@@ -218,11 +233,17 @@ class KuzzleEventEmitter extends eventemitter3_1.default {
      * Registers a plugin hook.
      * Catch any error in the handler and emit the hook:onError event.
      */
-    registerPluginHook(pluginName, event, fn) {
+    registerPluginHook(pluginName, event, 
+    // Same as `registerPluginPipe`: a hook resolved from a plugin member is a
+    // function of unknown return, not necessarily `void | Promise<void>`.
+    fn) {
         this.on(event, (...args) => {
             try {
                 const ret = fn(...args, event);
-                if (typeof ret === "object" && typeof ret.catch === "function") {
+                if (typeof ret === "object" &&
+                    ret !== null &&
+                    "catch" in ret &&
+                    typeof ret.catch === "function") {
                     ret.catch((error) => {
                         if (event !== "hook:onError") {
                             this.emit("hook:onError", { error, event, pluginName });
@@ -243,11 +264,14 @@ class KuzzleEventEmitter extends eventemitter3_1.default {
             }
         });
     }
-    registerPluginPipe(event, handler) {
-        if (!this.pluginPipes.has(event)) {
-            this.pluginPipes.set(event, []);
-        }
-        this.pluginPipes.get(event).push(handler);
+    registerPluginPipe(event, 
+    // A plugin pipe may answer a promise OR take a trailing callback — the
+    // runner supports both, and `PluginsManager.registerPipe` hands it the
+    // callback form. The promise-only type described half of what is accepted.
+    handler) {
+        const registered = this.pluginPipes.get(event) ?? [];
+        registered.push(handler);
+        this.pluginPipes.set(event, registered);
         const definition = new PluginPipeDefinition(event, handler);
         this.pluginPipeDefinitions.set(definition.pipeId, definition);
         return definition.pipeId;
@@ -257,7 +281,7 @@ class KuzzleEventEmitter extends eventemitter3_1.default {
         if (!definition) {
             throw kerror.get("plugin", "runtime", "unknown_pipe", pipeId);
         }
-        const handlers = this.pluginPipes.get(definition.event);
+        const handlers = this.pluginPipes.get(definition.event) ?? [];
         handlers.splice(handlers.indexOf(definition.handler), 1);
         if (handlers.length > 0) {
             this.pluginPipes.set(definition.event, handlers);
@@ -281,6 +305,9 @@ class KuzzleEventEmitter extends eventemitter3_1.default {
  * The context of this callback must be bound to this following object:
  * { instance: (kuzzle instance), promback, events }
  *
+ * Declared as `this`, rather than left implicit: the function is never called
+ * as a method, so the compiler has nothing else to read the receiver from.
+ *
  * @warning Critical section of code
  */
 async function pipeCallback(error, ...updated) {
@@ -289,12 +316,12 @@ async function pipeCallback(error, ...updated) {
         this.promback.reject(error);
         return;
     }
-    const corePipes = this.instance.corePipes.get(this.targetEvent);
+    const corePipes = this.corePipes.get(this.targetEvent);
     if (corePipes) {
         await bluebird_1.default.map(corePipes, (fn) => fn(...updated));
     }
     for (const element of this.events) {
-        this.instance.superEmit(element, ...updated);
+        this.superEmit(element, ...updated);
     }
     this.promback.resolve(updated[0]);
     /* eslint-enable no-invalid-this */

package/dist/lib/kuzzle/event/pipeRunner.d.ts

@@ -1,30 +1,51 @@
-export = PipeRunner;
+import Denque from "denque";
+/** A pipe in a chain: the payload, then the callback the pipe must call. */
+type Pipe = (...args: unknown[]) => void;
+/**
+ * How a pipe chain reports back to whoever asked for it to be run.
+ *
+ * The error is `unknown` for the same reason it is in `waterfall`: a pipe is
+ * plugin code and can call its callback with anything.
+ */
+type PipeCallback = (error?: unknown, ...results: unknown[]) => void;
+/**
+ * @private
+ */
+declare class PipeChain {
+    readonly chain: Pipe[];
+    readonly args: unknown[];
+    readonly callback: PipeCallback;
+    readonly callbackContext: unknown;
+    constructor(chain: Pipe[], args: unknown[], callback: PipeCallback, callbackContext: unknown);
+}
 /**
- * @class PipeRunner
  * Runs pipe chains if the number of already running concurrent pipes allows it.
  * Otherwise, delays the pipe chain until a slot is freed. If the storage
  * buffer is full, rejects the provided callback and discard the pipe chain.
- *
- * @param {Number} concurrent - max number of concurrent pipes
- * @param {Number} bufferSize - max number of delayed pipe chains
  */
 declare class PipeRunner {
-    constructor(concurrent: any, bufferSize: any);
-    maxConcurrent: number;
+    readonly maxConcurrent: number;
+    readonly maxBufferSize: number;
+    readonly buffer: Denque<PipeChain>;
+    /** Read and written by `waterfallCallback`, which runs outside the class. */
     running: number;
-    maxBufferSize: number;
-    buffer: Denque<any>;
-    _boundRunNext: any;
+    /** Same: `waterfallCallback` schedules it, so it cannot be private. */
+    readonly _boundRunNext: () => void;
+    /**
+     * @param concurrent - max number of concurrent pipes
+     * @param bufferSize - max number of delayed pipe chains
+     */
+    constructor(concurrent: number, bufferSize: number);
     /**
      * @warning Critical code section
      *
      * Pipes can be run thousands of times per seconds
-     * @param {Array} chain - functions chain
-     * @param {Array} args  - functions arguments
-     * @param {Function} callback - end-of-chain callback
-     * @param {Object} callbackContext - functions/callback context
+     * @param chain           - functions chain
+     * @param args            - functions arguments
+     * @param callback        - end-of-chain callback
+     * @param callbackContext - functions/callback context
      */
-    run(chain: any[], args: any[], callback: Function, callbackContext: any): void;
+    run(chain: Pipe[], args: unknown[], callback: PipeCallback, callbackContext: unknown): void;
     _runNext(): void;
 }
-import Denque = require("denque");
+export = PipeRunner;

package/dist/lib/kuzzle/event/pipeRunner.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,18 +19,48 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
-const assert = require("assert");
-const Denque = require("denque");
-const { KuzzleError } = require("../../kerror/errors");
-const waterfall = require("./waterfall");
-const kerror = require("../../kerror").wrap("plugin", "runtime");
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_assert_1 = __importDefault(require("node:assert"));
+const denque_1 = __importDefault(require("denque"));
+const kerrorLib = __importStar(require("../../kerror"));
+const errors_1 = require("../../kerror/errors");
+const thrown_1 = require("../../util/thrown");
+const waterfall_1 = __importDefault(require("./waterfall"));
+const kerror = kerrorLib.wrap("plugin", "runtime");
 /**
  * We declare the callback used by waterfall one time instead
  * of redeclaring a closure each time we want to run the pipes.
  *
- * This callback must be called with the following object as context:
- * { instance: (pipeRunner instance), callback: (callback after pipes execution) }
+ * The declared `this` is what makes the accesses below check: the context is
+ * the object `run` builds.
+ *
+ * The suppression stays because it is ESLint's *core* `no-invalid-this`, which
+ * predates `this` parameters and cannot see the declaration.
  */
 /* eslint-disable no-invalid-this */
 function waterfallCallback(error, ...result) {
@@ -38,19 +69,28 @@ function waterfallCallback(error, ...result) {
         setImmediate(this.instance._boundRunNext);
     }
     if (error) {
-        const cbError = error instanceof KuzzleError
-            ? error
-            : kerror.getFrom(error, "unexpected_error", error.message);
-        this.callback.call(this.callbackContext, cbError);
+        this.callback.call(this.callbackContext, toKuzzleError(error));
     }
     else {
         this.callback.call(this.callbackContext, null, ...result);
     }
 }
 /* eslint-enable no-invalid-this */
+/**
+ * Wraps whatever a pipe rejected with into a `KuzzleError`.
+ *
+ * The message is the rejected value's own `message`, as the JavaScript read
+ * it: a plugin rejecting with `{ message: "oops" }` says "oops", and one
+ * calling `cb("oops")` still says "undefined".
+ */
+function toKuzzleError(error) {
+    if (error instanceof errors_1.KuzzleError) {
+        return error;
+    }
+    return kerror.getFrom(error, "unexpected_error", (0, thrown_1.causeOf)(error).message);
+}
 /**
  * @private
- * @class PipeChain
  */
 class PipeChain {
     constructor(chain, args, callback, callbackContext) {
@@ -61,32 +101,32 @@ class PipeChain {
     }
 }
 /**
- * @class PipeRunner
  * Runs pipe chains if the number of already running concurrent pipes allows it.
  * Otherwise, delays the pipe chain until a slot is freed. If the storage
  * buffer is full, rejects the provided callback and discard the pipe chain.
- *
- * @param {Number} concurrent - max number of concurrent pipes
- * @param {Number} bufferSize - max number of delayed pipe chains
  */
 class PipeRunner {
+    /**
+     * @param concurrent - max number of concurrent pipes
+     * @param bufferSize - max number of delayed pipe chains
+     */
     constructor(concurrent, bufferSize) {
-        assert(typeof concurrent === "number" && concurrent > 0, "Cannot instantiate pipes executor: invalid maxConcurrentPipes parameter value");
-        assert(typeof bufferSize === "number" && bufferSize > 0, "Cannot instantiate pipes executor: invalid pipesBufferSize parameter value");
+        (0, node_assert_1.default)(typeof concurrent === "number" && concurrent > 0, "Cannot instantiate pipes executor: invalid maxConcurrentPipes parameter value");
+        (0, node_assert_1.default)(typeof bufferSize === "number" && bufferSize > 0, "Cannot instantiate pipes executor: invalid pipesBufferSize parameter value");
         this.maxConcurrent = concurrent;
         this.running = 0;
         this.maxBufferSize = bufferSize;
-        this.buffer = new Denque();
+        this.buffer = new denque_1.default();
         this._boundRunNext = this._runNext.bind(this);
     }
     /**
      * @warning Critical code section
      *
      * Pipes can be run thousands of times per seconds
-     * @param {Array} chain - functions chain
-     * @param {Array} args  - functions arguments
-     * @param {Function} callback - end-of-chain callback
-     * @param {Object} callbackContext - functions/callback context
+     * @param chain           - functions chain
+     * @param args            - functions arguments
+     * @param callback        - end-of-chain callback
+     * @param callbackContext - functions/callback context
      */
     run(chain, args, callback, callbackContext) {
         if (this.running >= this.maxConcurrent) {
@@ -105,13 +145,20 @@ class PipeRunner {
             callbackContext,
             instance: this,
         };
-        waterfall(chain, args, waterfallCallback, waterfallCallbackCtx);
+        (0, waterfall_1.default)(chain, args, waterfallCallback, waterfallCallbackCtx);
     }
     _runNext() {
-        if (this.buffer.isEmpty() || this.running >= this.maxConcurrent) {
+        if (this.running >= this.maxConcurrent) {
             return;
         }
+        // One lookup rather than `isEmpty()` and then `shift()`: `shift()` on an
+        // empty Denque returns `undefined` and mutates nothing, so the two forms
+        // agree, and this one leaves no invariant for the compiler to take on
+        // trust.
         const pipe = this.buffer.shift();
+        if (!pipe) {
+            return;
+        }
         this.run(pipe.chain, pipe.args, pipe.callback, pipe.callbackContext);
     }
 }

package/dist/lib/kuzzle/event/waterfall.d.ts

@@ -1,2 +1,12 @@
+/** A step in the chain: the payload, then the callback the step must call. */
+type WaterfallStep = (...args: unknown[]) => void;
+/**
+ * How a step — and the waterfall itself — reports back.
+ *
+ * The error is `unknown`, not `Error`: a step is arbitrary plugin code and can
+ * call its callback with anything at all. `pipeRunner` is what turns whatever
+ * arrives into a `KuzzleError`.
+ */
+type WaterfallCallback = (error?: unknown, ...results: unknown[]) => void;
+declare function waterfall(chain: WaterfallStep[], args: unknown[], cb: WaterfallCallback, context?: unknown): void;
 export = waterfall;
-declare function waterfall(chain: any, args: any, cb: any, context: any): void;

package/dist/lib/kuzzle/event/waterfall.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,13 +19,12 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
 class WaterfallContext {
     /**
-     * @param  {Array}    chain  - list of functions to call
-     * @param  {Array}    args   - function arguments
-     * @param  {Function} cb     - end of waterfall callback
-     * @param  {Object}   cbCtx  - functions context
+     * @param chain - list of functions to call
+     * @param args  - function arguments
+     * @param cb    - end of waterfall callback
+     * @param cbCtx - functions context
      */
     constructor(chain, args, cb, cbCtx) {
         this.chain = chain;
@@ -37,9 +37,6 @@ class WaterfallContext {
         // sure that all pipe methods receive the same payload
         this.args = args.length ? args : [null];
     }
-    hasNext() {
-        return this.index < this.chain.length;
-    }
     /**
      * Each function in the waterfall chain returns a result. This result should
      * always be the 1st payload argument (updated or left intact, it matters not)
@@ -47,9 +44,30 @@ class WaterfallContext {
     set result(result) {
         this.args[0] = result;
     }
-    next(cb) {
-        this.index++;
-        this.chain[this.index - 1](...this.args, cb);
+    /** Whether every step of the chain has been run. */
+    get exhausted() {
+        return this.index >= this.chain.length;
+    }
+    /**
+     * Runs the next step against the current payload and advances.
+     *
+     * The two questions this file asks are about different things: `exhausted`
+     * is about the *chain*, this is about the *value*. Collapsing them into one
+     * truthiness test — which is what the first conversion did — resolves the
+     * waterfall early on a chain entry that is not callable, silently skipping
+     * every remaining step (TD-55, #2758). A pipe chain is where a plugin denies
+     * a request, so the one outcome it must not have is a silent success.
+     *
+     * The JavaScript called `undefined(...)` and let the `TypeError` reach
+     * `waterfallNext`'s `try`. The throw below is that, spelled, because
+     * `noUncheckedIndexedAccess` does not let the call be written directly.
+     */
+    invokeNext(cb) {
+        const step = this.chain[this.index++];
+        if (step === undefined) {
+            throw new TypeError(`waterfall: chain step ${this.index - 1} is not a function`);
+        }
+        step(...this.args, cb);
     }
     reject(error) {
         this.cb.call(this.cbCtx, error);
@@ -59,6 +77,13 @@ class WaterfallContext {
         this.cb.call(this.cbCtx, null, ...this.args);
     }
 }
+/**
+ * The declared `this` is what makes the accesses below check: the context is
+ * always the `WaterfallContext` bound at the call site.
+ *
+ * The suppression stays because it is ESLint's *core* `no-invalid-this`, which
+ * predates `this` parameters and cannot see the declaration.
+ */
 /* eslint-disable no-invalid-this */
 function waterfallCB(err, res) {
     if (err) {
@@ -71,12 +96,12 @@ function waterfallCB(err, res) {
 }
 /* eslint-enable no-invalid-this */
 function waterfallNext(ctx) {
-    if (!ctx.hasNext()) {
+    if (ctx.exhausted) {
         ctx.resolve();
         return;
     }
     try {
-        ctx.next(waterfallCB.bind(ctx));
+        ctx.invokeNext(waterfallCB.bind(ctx));
     }
     catch (error) {
         ctx.reject(error);