@podium/client 5.1.0-beta.1 → 5.1.0

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,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 +87,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 +113,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 +153,7 @@ export default class PodiumClientResource {
                         content: '',
                         css: [],
                         js: [],
-                        redirect: '',
+                        redirect: null,
                     });
                 }
             }
@@ -143,7 +189,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 +207,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';
     }
-};
+}

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.1.0-beta.1",
+  "version": "5.1.0",
   "type": "module",
   "license": "MIT",
   "keywords": [
@@ -21,51 +21,53 @@
   "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.0",
+    "@hapi/boom": "10.0.1",
     "@metrics/client": "2.5.2",
-    "@podium/schemas": "5.0.0",
-    "@podium/utils": "5.0.2",
-    "abslog": "2.4.0",
+    "@podium/schemas": "5.0.5",
+    "@podium/utils": "5.0.7",
+    "abslog": "2.4.4",
     "http-cache-semantics": "^4.0.3",
     "lodash.clonedeep": "^4.5.0",
     "ttl-mem-cache": "4.1.0",
-    "undici": "^6.0.0"
+    "undici": "6.19.2"
   },
   "devDependencies": {
+    "@babel/eslint-parser": "7.24.7",
     "@podium/test-utils": "2.5.2",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
-    "@babel/eslint-parser": "7.23.10",
-    "@semantic-release/github": "9.2.6",
-    "@semantic-release/npm": "11.0.2",
-    "@semantic-release/release-notes-generator": "12.1.0",
+    "@semantic-release/github": "10.0.6",
+    "@semantic-release/npm": "12.0.1",
+    "@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",
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-import": "2.29.1",
     "eslint-plugin-prettier": "5.1.3",
-    "express": "4.18.3",
-    "get-stream": "8.0.1",
+    "express": "4.19.2",
+    "get-stream": "9.0.1",
     "http-proxy": "1.18.1",
-    "is-stream": "3.0.0",
-    "prettier": "3.2.5",
-    "semantic-release": "23.0.2",
-    "tap": "18.7.0"
+    "is-stream": "4.0.1",
+    "prettier": "3.3.2",
+    "semantic-release": "23.1.1",
+    "tap": "18.7.2",
+    "typescript": "5.4.5"
   }
 }

package/types/client.d.ts

@@ -0,0 +1,120 @@
+/// <reference types="node" resolution-mode="require"/>
+/**
+ * @typedef {import('./resource.js').default} PodiumClientResource
+ * @typedef {import('./resource.js').PodiumClientResourceOptions} PodiumClientResourceOptions
+ * @typedef {import('./response.js').default} PodiumClientResponse
+ * @typedef {import('./http-outgoing.js').PodiumRedirect} PodiumRedirect
+ * @typedef {import('@podium/schemas').PodletManifestSchema} PodletManifest
+ */
+/**
+ * @typedef {object} PodiumClientOptions
+ * @property {string} name
+ * @property {import('abslog').AbstractLoggerOptions} [logger]
+ * @property {number} [retries=4]
+ * @property {number} [timeout=1000] In milliseconds
+ * @property {number} [maxAge=Infinity]
+ * @property {boolean} [rejectUnauthorized=true]
+ * @property {number} [resolveThreshold]
+ * @property {number} [resolveMax]
+ * @property {import('http').Agent} [httpAgent]
+ * @property {import('https').Agent} [httpsAgent]
+ */
+/**
+ * @typedef {object} RegisterOptions
+ * @property {string} name A unique name for the podlet
+ * @property {string} uri URL to the podlet's `manifest.json`
+ * @property {number} [retries=4] Number of retries before serving fallback
+ * @property {number} [timeout=1000] In milliseconds, the amount of time to wait before serving fallback.
+ * @property {boolean} [throwable=false] Set to `true` and surround `fetch` in `try/catch` to serve different content in case podlet is unavailable. Will not server fallback content.
+ * @property {boolean} [redirectable=false] Set to `true` to allow podlet to respond with a redirect. You need to look for the redirect response from the podlet and return a redirect response to the browser yourself.
+ * @property {import('./resource.js').RequestFilterOptions} [excludeBy] Used by `fetch` to conditionally skip fetching the podlet content based on values on the request.
+ * @property {import('./resource.js').RequestFilterOptions} [includeBy] Used by `fetch` to conditionally skip fetching the podlet content based on values on the request.
+ */
+export default class PodiumClient extends EventEmitter<[never]> {
+    /**
+     * @constructor
+     * @param {PodiumClientOptions} options
+     */
+    constructor(options?: PodiumClientOptions);
+    get registry(): any;
+    get metrics(): Metrics;
+    get state(): "instantiated" | "stable" | "initializing" | "unhealthy" | "unstable";
+    /**
+     * Register a podlet so you can fetch its contents later with {@link PodiumClientResource.fetch}.
+     *
+     * @param {RegisterOptions} options
+     * @returns {PodiumClientResource}
+     *
+     * @example
+     * ```js
+     * const headerPodlet = layout.client.register({
+     *   name: 'header',
+     *   uri: 'http://header/manifest.json',
+     * });
+     * ```
+     */
+    register(options: RegisterOptions): PodiumClientResource;
+    dump(): any;
+    load(dump: any): any;
+    /**
+     * Refreshes the cached podlet manifest for all {@link register}ed podlets.
+     */
+    refreshManifests(): Promise<void>;
+    #private;
+}
+export type PodiumClientResource = import('./resource.js').default;
+export type PodiumClientResourceOptions = import('./resource.js').PodiumClientResourceOptions;
+export type PodiumClientResponse = import('./response.js').default;
+export type PodiumRedirect = import('./http-outgoing.js').PodiumRedirect;
+export type PodletManifest = import('@podium/schemas').PodletManifestSchema;
+export type PodiumClientOptions = {
+    name: string;
+    logger?: import('abslog').AbstractLoggerOptions;
+    retries?: number;
+    /**
+     * In milliseconds
+     */
+    timeout?: number;
+    maxAge?: number;
+    rejectUnauthorized?: boolean;
+    resolveThreshold?: number;
+    resolveMax?: number;
+    httpAgent?: import('http').Agent;
+    httpsAgent?: import('https').Agent;
+};
+export type RegisterOptions = {
+    /**
+     * A unique name for the podlet
+     */
+    name: string;
+    /**
+     * URL to the podlet's `manifest.json`
+     */
+    uri: string;
+    /**
+     * Number of retries before serving fallback
+     */
+    retries?: number;
+    /**
+     * In milliseconds, the amount of time to wait before serving fallback.
+     */
+    timeout?: number;
+    /**
+     * Set to `true` and surround `fetch` in `try/catch` to serve different content in case podlet is unavailable. Will not server fallback content.
+     */
+    throwable?: boolean;
+    /**
+     * Set to `true` to allow podlet to respond with a redirect. You need to look for the redirect response from the podlet and return a redirect response to the browser yourself.
+     */
+    redirectable?: boolean;
+    /**
+     * Used by `fetch` to conditionally skip fetching the podlet content based on values on the request.
+     */
+    excludeBy?: import('./resource.js').RequestFilterOptions;
+    /**
+     * Used by `fetch` to conditionally skip fetching the podlet content based on values on the request.
+     */
+    includeBy?: import('./resource.js').RequestFilterOptions;
+};
+import EventEmitter from 'events';
+import Metrics from '@metrics/client';