@podium/client 5.0.20 → 5.0.22

package/lib/resolver.fallback.js

@@ -17,11 +17,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 +63,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 +96,7 @@ export default class PodletClientFallbackResolver {
             'User-Agent': UA_STRING,
         };
 
+        /** @type {import('./http.js').PodiumHttpClientRequestOptions} */
         const reqOptions = {
             rejectUnauthorized: outgoing.rejectUnauthorized,
             timeout: outgoing.timeout,

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

@@ -20,11 +20,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 +66,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 +79,7 @@ export default class PodletClientManifestResolver {
             'User-Agent': UA_STRING,
         };
 
+        /** @type {import('./http.js').PodiumHttpClientRequestOptions} */
         const reqOptions = {
             rejectUnauthorized: outgoing.rejectUnauthorized,
             timeout: outgoing.timeout,
@@ -81,11 +99,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 +123,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 +180,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 +189,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 +203,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 +215,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 +240,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';
 

package/lib/resource.js

@@ -11,11 +11,35 @@ import * as utils from './utils.js';
 
 const inspect = Symbol.for('nodejs.util.inspect.custom');
 
+/**
+ * @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]
+ */
+
 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,
@@ -34,7 +58,7 @@ export default class PodiumClientResource {
         this.#metrics = new Metrics();
         this.#state = state;
 
-        this.#metrics.on('error', error => {
+        this.#metrics.on('error', (error) => {
             log.error(
                 'Error emitted by metric stream in @podium/client module',
                 error,
@@ -56,20 +80,37 @@ export default class PodiumClientResource {
         return this.#options.uri;
     }
 
-    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');
+    /**
+     * 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',
+            );
         const outgoing = new HttpOutgoing(this.#options, reqOptions, incoming);
 
         this.#state.setInitializingState();
 
-        const { manifest, headers, redirect, isFallback } = await this.#resolver.resolve(
-            outgoing,
-        );
+        const { manifest, headers, redirect, isFallback } =
+            await this.#resolver.resolve(outgoing);
 
         const chunks = [];
         // eslint-disable-next-line no-restricted-syntax
         for await (const chunk of outgoing) {
-            chunks.push(chunk)
+            chunks.push(chunk);
         }
 
         const content = !outgoing.redirect
@@ -79,24 +120,47 @@ export default class PodiumClientResource {
         return new Response({
             headers,
             content,
-            css: utils.filterAssets(isFallback ? "fallback" : "content", manifest.css),
-            js: utils.filterAssets(isFallback ? "fallback" : "content", manifest.js),
+            css: utils.filterAssets(
+                isFallback ? 'fallback' : 'content',
+                manifest.css,
+            ),
+            js: utils.filterAssets(
+                isFallback ? 'fallback' : 'content',
+                manifest.js,
+            ),
             redirect,
         });
     }
 
-    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');
+    /**
+     * 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',
+            );
         const outgoing = new HttpOutgoing(this.#options, reqOptions, incoming);
         this.#state.setInitializingState();
         this.#resolver.resolve(outgoing);
         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);
+        return this.#resolver.refresh(outgoing).then((obj) => obj);
     }
 
     [inspect]() {
@@ -110,4 +174,4 @@ export default class PodiumClientResource {
     get [Symbol.toStringTag]() {
         return 'PodiumClientResource';
     }
-};
+}

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 = {},
@@ -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';
     }
-};
+}

package/lib/utils.js

@@ -1,14 +1,12 @@
 /**
- * Checks if a header Oject has a header.
- * Will return true if the header exist and are not an empty
- * String or a String of whitespace.
+ * Checks if a header object has a header.
+ * Will return true if the header exist and is not an empty
+ * string or a string of whitespace.
  *
- * @param {Object} headers A headers object
- * @param {String} header A header value
- *
- * @returns {Boolean}
+ * @param {object} headers
+ * @param {string} header
+ * @returns {boolean}
  */
-
 export const isHeaderDefined = (headers, header) => {
     if (headers[header] === undefined || headers[header].trim() === '') {
         return false;
@@ -21,31 +19,24 @@ export const isHeaderDefined = (headers, header) => {
  * the changelog event object emitted from the internal
  * cache registry.
  *
- * @param {Object} item A changelog event object
- *
- * @returns {Boolean}
+ * @param {object} item A changelog event object
+ * @returns {boolean}
  */
-
-export const hasManifestChange = item => {
+export const hasManifestChange = (item) => {
     const oldVersion = item.oldVal ? item.oldVal.version : '';
     const newVersion = item.newVal ? item.newVal.version : '';
     return oldVersion !== newVersion;
 };
 
-
 /**
- * Check if a value is a HttpIncoming object or not. If not, it
+ * Check if a value is a Podium HttpIncoming object or not. If not, it
  * assume the incoming value is a context
  *
- * @param {Object} incoming A object
- *
- * @returns {HttpIncoming}
- */
-export const validateIncoming = (incoming = {}) => (Object.prototype.toString.call(incoming) === '[object PodiumHttpIncoming]');
-
-/**
- * @typedef {import("@podium/utils").AssetCss | import("@podium/utils").AssetJs} Asset
+ * @param {object} incoming
+ * @returns {boolean}
  */
+export const validateIncoming = (incoming = {}) =>
+    Object.prototype.toString.call(incoming) === '[object PodiumHttpIncoming]';
 
 /**
  * Filter assets array based on scope.
@@ -53,9 +44,10 @@ export const validateIncoming = (incoming = {}) => (Object.prototype.toString.ca
  * If scope property is set to "all", asset will be included.
  * If scope is set to "content" and asset scope property is set to "fallback", asset will not be included
  * If scope is set to "fallback" and asset scope property is set to "content", asset will not be included
+ * @template {import("@podium/utils").AssetCss | import("@podium/utils").AssetJs} T[]
  * @param {"content" | "fallback" | "all"} scope
- * @param {Asset[]} assets
- * @returns {Asset[]}
+ * @param {T[]} assets
+ * @returns {T[]}
  *
  * @example
  * ```
@@ -69,7 +61,13 @@ export const filterAssets = (scope, assets) => {
     // if undefined or null, passthrough
     if (!assets) return assets;
     // if a non array value is given, throw
-    if (!Array.isArray(assets)) throw new TypeError(`Asset definition must be of type array. Got ${typeof assets}`);
+    if (!Array.isArray(assets))
+        throw new TypeError(
+            `Asset definition must be of type array. Got ${typeof assets}`,
+        );
     // filter the array of asset definitions to matchin scope or anything with all. Treat no scope the same as "all" for backwards compatibility.
-    return assets.filter(asset => !asset.scope || asset.scope === scope || asset.scope === "all");
+    return assets.filter(
+        (asset) =>
+            !asset.scope || asset.scope === scope || asset.scope === 'all',
+    );
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podium/client",
-  "version": "5.0.20",
+  "version": "5.0.22",
   "type": "module",
   "license": "MIT",
   "keywords": [
@@ -21,18 +21,18 @@
   "files": [
     "package.json",
     "CHANGELOG.md",
-    "client.d.ts",
     "README.md",
     "LICENSE",
-    "dist",
-    "lib"
+    "lib",
+    "types"
   ],
   "main": "./lib/client.js",
-  "types": "client.d.ts",
+  "types": "./types/client.d.ts",
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "test": "tap --disable-coverage --allow-empty-coverage"
+    "test": "tap tests/*.js --disable-coverage --allow-empty-coverage && tsc --project tsconfig.test.json",
+    "types": "tsc --declaration --emitDeclarationOnly"
   },
   "dependencies": {
     "@hapi/boom": "10.0.1",
@@ -46,14 +46,15 @@
     "undici": "6.16.1"
   },
   "devDependencies": {
+    "@babel/eslint-parser": "7.24.5",
     "@podium/test-utils": "2.5.2",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
-    "@babel/eslint-parser": "7.24.5",
     "@semantic-release/github": "10.0.3",
     "@semantic-release/npm": "12.0.0",
     "@semantic-release/release-notes-generator": "13.0.0",
     "@sinonjs/fake-timers": "11.2.2",
+    "@types/readable-stream": "4.0.14",
     "benchmark": "2.1.4",
     "eslint": "8.57.0",
     "eslint-config-airbnb-base": "15.0.0",
@@ -66,6 +67,7 @@
     "is-stream": "4.0.1",
     "prettier": "3.2.5",
     "semantic-release": "23.0.8",
-    "tap": "18.7.2"
+    "tap": "18.7.2",
+    "typescript": "5.4.5"
   }
 }