@podium/client 5.1.0-beta.1 → 5.1.1

package/lib/resolver.content.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-param-reassign */
 import { pipeline } from 'stream';
 import Metrics from '@metrics/client';
 import abslog from 'abslog';
@@ -21,11 +20,24 @@ const pkg = JSON.parse(pkgJson);
 
 const UA_STRING = `${pkg.name} ${pkg.version}`;
 
+/**
+ * @typedef {object} PodletClientContentResolverOptions
+ * @property {string} clientName
+ * @property {import('./http.js').default} [http]
+ * @property {import('abslog').AbstractLoggerOptions} [logger]
+ */
+
 export default class PodletClientContentResolver {
     #log;
     #metrics;
     #histogram;
     #http;
+
+    /**
+     * @constructor
+     * @param {PodletClientContentResolverOptions} options
+     */
+    // @ts-expect-error Deliberate default empty options for better error messages
     constructor(options = {}) {
         this.#http = options.http || new HTTP();
         const name = options.clientName;
@@ -54,6 +66,12 @@ export default class PodletClientContentResolver {
         return this.#metrics;
     }
 
+    /**
+     * Resolves/fetches the podlet's content.
+     *
+     * @param {import('./http-outgoing.js').default} outgoing
+     * @returns {Promise<import('./http-outgoing.js').default>}
+     */
     async resolve(outgoing) {
         if (outgoing.kill && outgoing.throwable) {
             this.#log.warn(
@@ -71,12 +89,12 @@ export default class PodletClientContentResolver {
             outgoing.success = true;
             outgoing.pushFallback();
             outgoing.emit(
-              'beforeStream',
-              new Response({
-                  js: utils.filterAssets("fallback", outgoing.manifest.js),
-                  css: utils.filterAssets("fallback", outgoing.manifest.css),
-              }),
-          );
+                'beforeStream',
+                new Response({
+                    js: utils.filterAssets('fallback', outgoing.manifest.js),
+                    css: utils.filterAssets('fallback', outgoing.manifest.css),
+                }),
+            );
             return outgoing;
         }
 
@@ -94,12 +112,12 @@ export default class PodletClientContentResolver {
             outgoing.success = true;
             outgoing.pushFallback();
             outgoing.emit(
-              'beforeStream',
-              new Response({
-                  js: utils.filterAssets("fallback", outgoing.manifest.js),
-                  css: utils.filterAssets("fallback", outgoing.manifest.css),
-              }),
-          );
+                'beforeStream',
+                new Response({
+                    js: utils.filterAssets('fallback', outgoing.manifest.js),
+                    css: utils.filterAssets('fallback', outgoing.manifest.css),
+                }),
+            );
             return outgoing;
         }
 
@@ -113,8 +131,9 @@ export default class PodletClientContentResolver {
         const uri = putils.uriBuilder(
             outgoing.reqOptions.pathname,
             outgoing.contentUri,
-        )
+        );
 
+        /** @type {import('./http.js').PodiumHttpClientRequestOptions} */
         const reqOptions = {
             rejectUnauthorized: outgoing.rejectUnauthorized,
             bodyTimeout: outgoing.timeout,
@@ -183,11 +202,17 @@ export default class PodletClientContentResolver {
                 outgoing.success = true;
                 outgoing.pushFallback();
                 outgoing.emit(
-                  'beforeStream',
-                  new Response({
-                      js: utils.filterAssets("fallback", outgoing.manifest.js),
-                      css: utils.filterAssets("fallback", outgoing.manifest.css),
-                  }),
+                    'beforeStream',
+                    new Response({
+                        js: utils.filterAssets(
+                            'fallback',
+                            outgoing.manifest.js,
+                        ),
+                        css: utils.filterAssets(
+                            'fallback',
+                            outgoing.manifest.css,
+                        ),
+                    }),
                 );
 
                 // Body must be consumed; https://github.com/nodejs/undici/issues/583#issuecomment-855384858
@@ -227,6 +252,7 @@ export default class PodletClientContentResolver {
             if (outgoing.redirectable && statusCode >= 300) {
                 outgoing.redirect = {
                     statusCode,
+                    // @ts-expect-error TODO: look into what happens if the podlet returns more than one location header
                     location: hdrs && hdrs.location,
                 };
             }
@@ -235,8 +261,8 @@ export default class PodletClientContentResolver {
                 'beforeStream',
                 new Response({
                     headers: outgoing.headers,
-                    js: utils.filterAssets("content", outgoing.manifest.js),
-                    css: utils.filterAssets("content", outgoing.manifest.css),
+                    js: utils.filterAssets('content', outgoing.manifest.js),
+                    css: utils.filterAssets('content', outgoing.manifest.css),
                     redirect: outgoing.redirect,
                 }),
             );
@@ -260,10 +286,7 @@ export default class PodletClientContentResolver {
                 this.#log.warn(
                     `could not create network connection to remote resource when trying to request content - resource: ${outgoing.name} - url: ${uri}`,
                 );
-                throw badGateway(
-                    `Error reading content at ${uri}`,
-                    error,
-                );
+                throw badGateway(`Error reading content at ${uri}`, error);
             }
 
             timer({
@@ -280,12 +303,12 @@ export default class PodletClientContentResolver {
 
             outgoing.pushFallback();
             outgoing.emit(
-              'beforeStream',
-              new Response({
-                  js: utils.filterAssets("fallback", outgoing.manifest.js),
-                  css: utils.filterAssets("fallback", outgoing.manifest.css),
-              }),
-          );
+                'beforeStream',
+                new Response({
+                    js: utils.filterAssets('fallback', outgoing.manifest.js),
+                    css: utils.filterAssets('fallback', outgoing.manifest.css),
+                }),
+            );
 
             return outgoing;
         }

package/lib/resolver.fallback.js

@@ -1,5 +1,3 @@
-/* eslint-disable no-param-reassign */
-
 import abslog from 'abslog';
 import Metrics from '@metrics/client';
 import { join, dirname } from 'path';
@@ -17,11 +15,24 @@ const pkg = JSON.parse(pkgJson);
 
 const UA_STRING = `${pkg.name} ${pkg.version}`;
 
+/**
+ * @typedef {object} PodletClientFallbackResolverOptions
+ * @property {string} clientName
+ * @property {import('./http.js').default} [http]
+ * @property {import('abslog').AbstractLoggerOptions} [logger]
+ */
+
 export default class PodletClientFallbackResolver {
     #log;
     #metrics;
     #histogram;
     #http;
+
+    /**
+     * @constructor
+     * @param {PodletClientFallbackResolverOptions} options
+     */
+    // @ts-expect-error Deliberate default empty options for better error messages
     constructor(options = {}) {
         this.#http = options.http || new HTTP();
         const name = options.clientName;
@@ -50,6 +61,12 @@ export default class PodletClientFallbackResolver {
         return this.#metrics;
     }
 
+    /**
+     * Resolves/fetches the podlet's fallback.
+     *
+     * @param {import('./http-outgoing.js').default} outgoing
+     * @returns {Promise<import('./http-outgoing.js').default>}
+     */
     async resolve(outgoing) {
         if (outgoing.status === 'cached') {
             return outgoing;
@@ -77,6 +94,7 @@ export default class PodletClientFallbackResolver {
             'User-Agent': UA_STRING,
         };
 
+        /** @type {import('./http.js').PodiumHttpClientRequestOptions} */
         const reqOptions = {
             rejectUnauthorized: outgoing.rejectUnauthorized,
             timeout: outgoing.timeout,
@@ -133,6 +151,7 @@ export default class PodletClientFallbackResolver {
                 `successfully read fallback from remote resource - resource: ${outgoing.name} - url: ${outgoing.fallbackUri}`,
             );
             return outgoing;
+            // eslint-disable-next-line no-unused-vars
         } catch (error) {
             timer({
                 labels: {

package/lib/resolver.js

@@ -7,12 +7,25 @@ import Fallback from './resolver.fallback.js';
 import Content from './resolver.content.js';
 import Cache from './resolver.cache.js';
 
+/**
+ * @typedef {object} PodletClientResolverOptions
+ * @property {string} clientName
+ * @property {import('abslog').AbstractLoggerOptions} [logger]
+ */
+
 export default class PodletClientResolver {
     #cache;
     #manifest;
     #fallback;
     #content;
     #metrics;
+
+    /**
+     * @constructor
+     * @param {import('ttl-mem-cache').default} registry
+     * @param {PodletClientResolverOptions} options
+     */
+    // @ts-expect-error Deliberate default empty options for better error messages
     constructor(registry, options = {}) {
         assert(
             registry,
@@ -22,12 +35,16 @@ export default class PodletClientResolver {
         const log = abslog(options.logger);
         const http = new HTTP();
         this.#cache = new Cache(registry, options);
-        this.#manifest = new Manifest({ ...options, http });
+        this.#manifest = new Manifest({
+            clientName: options.clientName,
+            logger: options.logger,
+            http,
+        });
         this.#fallback = new Fallback({ ...options, http });
         this.#content = new Content({ ...options, http });
         this.#metrics = new Metrics();
 
-        this.#metrics.on('error', error => {
+        this.#metrics.on('error', (error) => {
             log.error(
                 'Error emitted by metric stream in @podium/client module',
                 error,
@@ -43,14 +60,20 @@ export default class PodletClientResolver {
         return this.#metrics;
     }
 
+    /**
+     * Resolve the podlet's manifest, fallback and content
+     *
+     * @param {import('./http-outgoing.js').default} outgoing
+     * @returns {Promise<import('./http-outgoing.js').default>}
+     */
     resolve(outgoing) {
         return this.#cache
             .load(outgoing)
-            .then(obj => this.#manifest.resolve(obj))
-            .then(obj => this.#fallback.resolve(obj))
-            .then(obj => this.#content.resolve(obj))
-            .then(obj => this.#cache.save(obj))
-            .then(obj => {
+            .then((obj) => this.#manifest.resolve(obj))
+            .then((obj) => this.#fallback.resolve(obj))
+            .then((obj) => this.#content.resolve(obj))
+            .then((obj) => this.#cache.save(obj))
+            .then((obj) => {
                 if (obj.success) {
                     return obj;
                 }
@@ -58,15 +81,21 @@ export default class PodletClientResolver {
             });
     }
 
+    /**
+     * Refresh the podlet's cached manifest and fallback
+     *
+     * @param {import('./http-outgoing.js').default} outgoing
+     * @returns {Promise<boolean>} `true` if successful
+     */
     refresh(outgoing) {
         return this.#manifest
             .resolve(outgoing)
-            .then(obj => this.#fallback.resolve(obj))
-            .then(obj => this.#cache.save(obj))
-            .then(obj => !!obj.manifest.name);
+            .then((obj) => this.#fallback.resolve(obj))
+            .then((obj) => this.#cache.save(obj))
+            .then((obj) => !!obj.manifest.name);
     }
 
     get [Symbol.toStringTag]() {
         return 'PodletClientResolver';
     }
-};
+}

package/lib/resolver.manifest.js

@@ -1,5 +1,3 @@
-/* eslint-disable no-param-reassign */
-
 import CachePolicy from 'http-cache-semantics';
 import { manifest as validateManifest } from '@podium/schemas';
 import Metrics from '@metrics/client';
@@ -20,11 +18,24 @@ const pkg = JSON.parse(pkgJson);
 
 const UA_STRING = `${pkg.name} ${pkg.version}`;
 
+/**
+ * @typedef {object} PodletClientManifestResolverOptions
+ * @property {string} clientName
+ * @property {import('abslog').AbstractLoggerOptions} [logger]
+ * @property {import('./http.js').default} [http]
+ */
+
 export default class PodletClientManifestResolver {
     #log;
     #metrics;
     #histogram;
     #http;
+
+    /**
+     * @constructor
+     * @param {PodletClientManifestResolverOptions} options
+     */
+    // @ts-expect-error Deliberate default empty options for better error messages
     constructor(options = {}) {
         this.#http = options.http || new HTTP();
         const name = options.clientName;
@@ -53,6 +64,10 @@ export default class PodletClientManifestResolver {
         return this.#metrics;
     }
 
+    /**
+     * @param {import('./http-outgoing.js').default} outgoing
+     * @returns {Promise<import('./http-outgoing.js').default>}
+     */
     async resolve(outgoing) {
         if (outgoing.status === 'cached') {
             return outgoing;
@@ -62,6 +77,7 @@ export default class PodletClientManifestResolver {
             'User-Agent': UA_STRING,
         };
 
+        /** @type {import('./http.js').PodiumHttpClientRequestOptions} */
         const reqOptions = {
             rejectUnauthorized: outgoing.rejectUnauthorized,
             timeout: outgoing.timeout,
@@ -81,11 +97,11 @@ export default class PodletClientManifestResolver {
         );
 
         try {
-            const {
-                statusCode,
-                headers: hdrs,
-                body,
-            } = await this.#http.request(outgoing.manifestUri, reqOptions);
+            const response = await this.#http.request(
+                outgoing.manifestUri,
+                reqOptions,
+            );
+            const { statusCode, headers: hdrs, body } = response;
 
             // Remote responds but with an http error code
             const resError = statusCode !== 200;
@@ -105,7 +121,11 @@ export default class PodletClientManifestResolver {
                 return outgoing;
             }
 
-            const manifest = validateManifest(await body.json());
+            const manifest = validateManifest(
+                /** @type {import("@podium/schemas").PodletManifestSchema} */ (
+                    await body.json()
+                ),
+            );
 
             // Manifest validation error
             if (manifest.error) {
@@ -158,6 +178,7 @@ export default class PodletClientManifestResolver {
             );
 
             // Construct css and js objects with absolute URIs
+            // @ts-expect-error We assign here what will end up as PodletManifest as defined in http-outgoing.js
             manifest.value.css = manifest.value.css.map((obj) => {
                 obj.value = utils.uriRelativeToAbsolute(
                     obj.value,
@@ -166,6 +187,7 @@ export default class PodletClientManifestResolver {
                 return new utils.AssetCss(obj);
             });
 
+            // @ts-expect-error We assign here what will end up as PodletManifest as defined in http-outgoing.js
             manifest.value.js = manifest.value.js.map((obj) => {
                 obj.value = utils.uriRelativeToAbsolute(
                     obj.value,
@@ -179,9 +201,9 @@ export default class PodletClientManifestResolver {
 
                 If .proxy is and Array, the podlet are of version 6 or newer. The Array is then an
                 Array of proxy Objects ({ name: 'foo', target: '/' }) which is the new structure
-                wanted from version 6 and onwards so leave this structure untouched. 
+                wanted from version 6 and onwards so leave this structure untouched.
 
-                If .proxy is an Object, the podlet are of version 5 or older where the key of the 
+                If .proxy is an Object, the podlet are of version 5 or older where the key of the
                 Object is the key of the target. If so, convert the structure to the new structure
                 consisting of an Array of proxy Objects.
 
@@ -191,12 +213,12 @@ export default class PodletClientManifestResolver {
             if (Array.isArray(manifest.value.proxy)) {
                 // Build absolute proxy URIs
                 manifest.value.proxy = manifest.value.proxy.map((item) => ({
-                        target: utils.uriRelativeToAbsolute(
-                            item.target,
-                            outgoing.manifestUri,
-                        ),
-                        name: item.name,
-                    }));
+                    target: utils.uriRelativeToAbsolute(
+                        item.target,
+                        outgoing.manifestUri,
+                    ),
+                    name: item.name,
+                }));
             } else {
                 const proxies = [];
                 // Build absolute proxy URIs
@@ -216,6 +238,7 @@ export default class PodletClientManifestResolver {
                 END: Proxy backwards compabillity check and handling
             */
 
+            // @ts-expect-error We map to AssetCss and AssetJs above
             outgoing.manifest = manifest.value;
             outgoing.status = 'fresh';
 
@@ -223,6 +246,7 @@ export default class PodletClientManifestResolver {
                 `successfully read manifest from remote resource - resource: ${outgoing.name} - url: ${outgoing.manifestUri}`,
             );
             return outgoing;
+            // eslint-disable-next-line no-unused-vars
         } catch (error) {
             timer({
                 labels: {

package/lib/resource.js

@@ -1,5 +1,3 @@
-/* eslint-disable no-param-reassign */
-
 import Metrics from '@metrics/client';
 import abslog from 'abslog';
 import assert from 'assert';
@@ -11,11 +9,42 @@ import * as utils from './utils.js';
 
 const inspect = Symbol.for('nodejs.util.inspect.custom');
 
+/**
+ * @typedef {object} RequestFilterOptions
+ * @property {string[]} [deviceType] List of values for the `x-podium-device-type` HTTP request header.
+ */
+
+/**
+ * @typedef {object} PodiumClientResourceOptions
+ * @property {import('abslog').AbstractLoggerOptions} [logger]
+ * @property {string} clientName
+ * @property {string} name
+ * @property {string} uri To the podlet's `manifest.json`
+ * @property {number} timeout In milliseconds
+ * @property {number} maxAge
+ * @property {number} [retries]
+ * @property {boolean} [throwable]
+ * @property {boolean} [redirectable]
+ * @property {boolean} [rejectUnauthorized]
+ * @property {import('http').Agent} [httpAgent]
+ * @property {import('https').Agent} [httpsAgent]
+ * @property {RequestFilterOptions} [excludeBy] Used by `fetch` to conditionally skip fetching the podlet content based on values on the request.
+ * @property {RequestFilterOptions} [includeBy] Used by `fetch` to conditionally skip fetching the podlet content based on values on the request.
+ */
+
 export default class PodiumClientResource {
     #resolver;
     #options;
     #metrics;
     #state;
+
+    /**
+     * @constructor
+     * @param {import('ttl-mem-cache').default} registry
+     * @param {import('./state.js').default} state
+     * @param {PodiumClientResourceOptions} options
+     */
+    // @ts-expect-error Deliberate for better error messages
     constructor(registry, state, options = {}) {
         assert(
             registry,
@@ -56,7 +85,22 @@ export default class PodiumClientResource {
         return this.#options.uri;
     }
 
-    async fetch(incoming = {}, reqOptions = {}) {
+    /**
+     * Fetch the podlet's content, or fallback if the podlet is unavailable.
+     * The podlet response includes references to its CSS and JS assets which should be included in the final HTML document.
+     *
+     * @param {import('@podium/utils').HttpIncoming} incoming Instance of HttpIncoming
+     * @param {import('./http-outgoing.js').PodiumClientResourceOptions} [reqOptions={}] Optional parameters to the HTTP request, such as query parameters or HTTP request headers.
+     * @returns {Promise<import('./response.js').default>}
+     *
+     * @example
+     * ```js
+     * const incoming = res.locals.podium; // Express server example
+     * const header = await headerPodlet.fetch(incoming);
+     * incoming.podlets = [header]; // Register the podlet's JS and CSS assets with the layout's HTML template
+     * ```
+     */
+    async fetch(incoming, reqOptions = {}) {
         if (!utils.validateIncoming(incoming))
             throw new TypeError(
                 'you must pass an instance of "HttpIncoming" as the first argument to the .fetch() method',
@@ -67,21 +111,21 @@ export default class PodiumClientResource {
             /**
              * @type {string[] | undefined}
              */
-            const exclucedDeviceTypes = this.#options.excludeBy.deviceType;
-            if (Array.isArray(exclucedDeviceTypes)) {
+            const excludedDeviceTypes = this.#options.excludeBy.deviceType;
+            if (Array.isArray(excludedDeviceTypes)) {
                 const deviceTypeHeader =
                     incoming.request.headers['x-podium-device-type'];
 
-                for (let i = 0; i < exclucedDeviceTypes.length; i += 1) {
+                for (let i = 0; i < excludedDeviceTypes.length; i += 1) {
                     const shouldSkip =
-                        exclucedDeviceTypes[i] === deviceTypeHeader;
+                        excludedDeviceTypes[i] === deviceTypeHeader;
                     if (shouldSkip) {
                         return new Response({
                             headers: {},
                             content: '',
                             css: [],
                             js: [],
-                            redirect: '',
+                            redirect: null,
                         });
                     }
                 }
@@ -107,7 +151,7 @@ export default class PodiumClientResource {
                         content: '',
                         css: [],
                         js: [],
-                        redirect: '',
+                        redirect: null,
                     });
                 }
             }
@@ -119,7 +163,7 @@ export default class PodiumClientResource {
             await this.#resolver.resolve(outgoing);
 
         const chunks = [];
-        // eslint-disable-next-line no-restricted-syntax
+
         for await (const chunk of outgoing) {
             chunks.push(chunk);
         }
@@ -143,7 +187,14 @@ export default class PodiumClientResource {
         });
     }
 
-    stream(incoming = {}, reqOptions = {}) {
+    /**
+     * Stream the podlet's content, or fallback if the podlet is unavailable.
+     *
+     * @param {import('@podium/utils').HttpIncoming} incoming
+     * @param {import('./http-outgoing.js').PodiumClientResourceOptions} [reqOptions={}]
+     * @returns {import('./http-outgoing.js').default}
+     */
+    stream(incoming, reqOptions = {}) {
         if (!utils.validateIncoming(incoming))
             throw new TypeError(
                 'you must pass an instance of "HttpIncoming" as the first argument to the .stream() method',
@@ -154,7 +205,14 @@ export default class PodiumClientResource {
         return outgoing;
     }
 
-    refresh(incoming = {}, reqOptions = {}) {
+    /**
+     * Refresh the podlet's manifest and fallback in the cache.
+     *
+     * @param {import('@podium/utils').HttpIncoming} [incoming]
+     * @param {import('./http-outgoing.js').PodiumClientResourceOptions} [reqOptions={}]
+     * @returns {Promise<boolean>} `true` if succesful
+     */
+    refresh(incoming, reqOptions = {}) {
         const outgoing = new HttpOutgoing(this.#options, reqOptions, incoming);
         this.#state.setInitializingState();
         return this.#resolver.refresh(outgoing).then((obj) => obj);

package/lib/response.js

@@ -1,11 +1,25 @@
 const inspect = Symbol.for('nodejs.util.inspect.custom');
 
+/**
+ * @typedef {object} PodiumClientResponseOptions
+ * @property {string} [content]
+ * @property {object} [headers]
+ * @property {Array<import('@podium/utils').AssetJs>} [js]
+ * @property {Array<import('@podium/utils').AssetCss>} [css]
+ * @property {import('./http-outgoing.js').PodiumRedirect | null} [redirect]
+ */
+
 export default class PodiumClientResponse {
     #redirect;
     #content;
     #headers;
     #css;
     #js;
+
+    /**
+     * @constructor
+     * @param {PodiumClientResponseOptions} options
+     */
     constructor({
         content = '',
         headers = {},
@@ -45,8 +59,8 @@ export default class PodiumClientResponse {
             redirect: this.redirect,
             content: this.content,
             headers: this.headers,
-            css: this.css,
-            js: this.js,
+            css: this.css.map((a) => a.toJSON()),
+            js: this.js.map((a) => a.toJSON()),
         };
     }
 
@@ -71,4 +85,4 @@ export default class PodiumClientResponse {
     get [Symbol.toStringTag]() {
         return 'PodiumClientResponse';
     }
-};
+}

package/lib/state.js

@@ -2,12 +2,25 @@ import EventEmitter from 'events';
 
 const inspect = Symbol.for('nodejs.util.inspect.custom');
 
+/**
+ * @typedef {object} PodiumClientStateOptions
+ * @property {number} [resolveThreshold=10000]
+ * @property {number} [resolveMax=240000]
+ */
+
 export default class PodiumClientState extends EventEmitter {
+    /** @type {NodeJS.Timeout | undefined} */
     #thresholdTimer;
     #threshold;
+    /** @type {NodeJS.Timeout | undefined} */
     #maxTimer;
+    /** @type {"instantiated" | "stable" | "initializing" | "unhealthy" | "unstable"} */
     #state;
     #max;
+
+    /**
+     * @param {PodiumClientStateOptions} [options]
+     */
     constructor({
         resolveThreshold = 10 * 1000,
         resolveMax = 4 * 60 * 1000,
@@ -113,4 +126,4 @@ export default class PodiumClientState extends EventEmitter {
     get [Symbol.toStringTag]() {
         return 'PodiumClientState';
     }
-};
+}