@podium/client 5.0.20 → 5.0.22

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [5.0.22](https://github.com/podium-lib/client/compare/v5.0.21...v5.0.22) (2024-05-15)
+
+
+### Bug Fixes
+
+* generate type definitions before publish ([8189b01](https://github.com/podium-lib/client/commit/8189b01c54c733c760b02f2138803f9b64a6fee5))
+
+## [5.0.21](https://github.com/podium-lib/client/compare/v5.0.20...v5.0.21) (2024-05-14)
+
+
+### Bug Fixes
+
+* export same types as before ([0e3c65a](https://github.com/podium-lib/client/commit/0e3c65afc0fef7e6c53ad544dc80cb7f8dc8596b))
+* generate types from JSDoc ([32cac7e](https://github.com/podium-lib/client/commit/32cac7e10a76494c0d2df602f41d42a67e8e7b6c))
+
 ## [5.0.20](https://github.com/podium-lib/client/compare/v5.0.19...v5.0.20) (2024-05-14)
 
 

package/lib/client.js

@@ -1,16 +1,17 @@
 import EventEmitter from 'events';
-import {uriStrict as validateUriStrict, name as validateName } from'@podium/schemas';
+import {
+    uriStrict as validateUriStrict,
+    name as validateName,
+} from '@podium/schemas';
 import Metrics from '@metrics/client';
 import abslog from 'abslog';
 import Cache from 'ttl-mem-cache';
 import http from 'http';
 import https from 'https';
-
 import Resource from './resource.js';
 import State from './state.js';
 
 const inspect = Symbol.for('nodejs.util.inspect.custom');
-
 const HTTP_AGENT_OPTIONS = {
     keepAlive: true,
     maxSockets: 10,
@@ -18,24 +19,49 @@ const HTTP_AGENT_OPTIONS = {
     timeout: 60000,
     keepAliveMsecs: 30000,
 };
-
 const HTTPS_AGENT_OPTIONS = {
     ...HTTP_AGENT_OPTIONS,
     maxCachedSessions: 10,
 };
-
 const REJECT_UNAUTHORIZED = true;
-
 const HTTP_AGENT = new http.Agent(HTTP_AGENT_OPTIONS);
-
 const HTTPS_AGENT = new https.Agent(HTTPS_AGENT_OPTIONS);
-
 const RETRIES = 4;
-
 const TIMEOUT = 1000; // 1 seconds
-
 const MAX_AGE = Infinity;
 
+/**
+ * @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.
+ */
+
 export default class PodiumClient extends EventEmitter {
     #resources;
     #registry;
@@ -43,6 +69,12 @@ export default class PodiumClient extends EventEmitter {
     #histogram;
     #options;
     #state;
+
+    /**
+     * @constructor
+     * @param {PodiumClientOptions} options
+     */
+    // @ts-expect-error Deliberate default empty options for better error messages
     constructor(options = {}) {
         super();
         const log = abslog(options.logger);
@@ -69,7 +101,7 @@ export default class PodiumClient extends EventEmitter {
             resolveThreshold: options.resolveThreshold,
             resolveMax: options.resolveMax,
         });
-        this.#state.on('state', state => {
+        this.#state.on('state', (state) => {
             this.emit('state', state);
         });
 
@@ -79,7 +111,7 @@ export default class PodiumClient extends EventEmitter {
             changefeed: true,
             ttl: options.maxAge,
         });
-        this.#registry.on('error', error => {
+        this.#registry.on('error', (error) => {
             log.error(
                 'Error emitted by the registry in @podium/client module',
                 error,
@@ -91,7 +123,7 @@ export default class PodiumClient extends EventEmitter {
         });
 
         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,
@@ -99,7 +131,7 @@ export default class PodiumClient extends EventEmitter {
         });
 
         this[Symbol.iterator] = () => ({
-            items: Array.from(this.#resources).map(item => item[1]),
+            items: Array.from(this.#resources).map((item) => item[1]),
             next: function next() {
                 return {
                     done: this.items.length === 0,
@@ -128,7 +160,21 @@ export default class PodiumClient extends EventEmitter {
         return this.#state.status;
     }
 
-    register(options = {}) {
+    /**
+     * 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) {
         if (validateName(options.name).error)
             throw new Error(
                 `The value, "${options.name}", for the required argument "name" on the .register() method is not defined or not valid.`,
@@ -183,12 +229,17 @@ export default class PodiumClient extends EventEmitter {
         return this.#registry.load(dump);
     }
 
+    /**
+     * Refreshes the cached podlet manifest for all {@link register}ed podlets.
+     */
     async refreshManifests() {
         const end = this.#histogram.timer();
 
         // Don't return this
         await Promise.all(
-            Array.from(this.#resources).map(resource => resource[1].refresh()),
+            Array.from(this.#resources).map((resource) =>
+                resource[1].refresh(),
+            ),
         );
 
         end();
@@ -204,4 +255,4 @@ export default class PodiumClient extends EventEmitter {
     get [Symbol.toStringTag]() {
         return 'PodiumClient';
     }
-};
+}

package/lib/http-outgoing.js

@@ -3,26 +3,84 @@
 import { PassThrough } from 'stream';
 import assert from 'assert';
 
+/**
+ * @typedef {object} PodiumClientHttpOutgoingOptions
+ * @property {string} name
+ * @property {string} uri To the podlet's `manifest.json`
+ * @property {number} timeout In milliseconds
+ * @property {number} maxAge
+ * @property {number} [retries=4]
+ * @property {boolean} [throwable=false]
+ * @property {boolean} [redirectable=false]
+ * @property {boolean} [rejectUnauthorized=true]
+ * @property {import('http').Agent} [httpAgent]
+ * @property {import('https').Agent} [httpsAgent]
+ */
+
+/**
+ * @typedef {object} PodiumClientResourceOptions
+ * @property {string} [pathname]
+ * @property {import('http').IncomingHttpHeaders} [headers]
+ * @property {object} [query]
+ */
+
+/**
+ * @typedef {object} PodiumRedirect
+ * @property {number} statusCode;
+ * @property {string} location;
+ */
+
+/**
+ * @typedef {object} PodletProxySchema
+ * @property {string} target
+ * @property {string} name
+ */
+
+/**
+ * @typedef {object} PodletManifest Similar to the schema's manifest, but with instances of AssetCss and AssetJs from `@podium/utils` and default values.
+ * @property {string} name
+ * @property {string} version
+ * @property {string} content
+ * @property {string} fallback
+ * @property {Array<import('@podium/utils').AssetJs>} js
+ * @property {Array<import('@podium/utils').AssetCss>} css
+ * @property {Record<string, string> | Array<PodletProxySchema>} proxy
+ * @property {string} team
+ */
+
 export default class PodletClientHttpOutgoing extends PassThrough {
     #rejectUnauthorized;
     #killRecursions;
     #killThreshold;
     #redirectable;
     #reqOptions;
-    #isFallback;
+    #isFallback = false;
     #throwable;
+    /** @type {PodletManifest} */
     #manifest;
     #incoming;
-    #redirect;
+    /** @type {null | PodiumRedirect} */
+    #redirect = null;
     #timeout;
     #success;
     #headers;
     #maxAge;
+    /** @type {'empty' | 'fresh' | 'cached' | 'stale'} */
     #status;
     #name;
-    #uri;    
-    constructor(
-        {
+    #uri;
+
+    /**
+     * @constructor
+     * @param {PodiumClientHttpOutgoingOptions} options
+     * @param {PodiumClientResourceOptions} [reqOptions]
+     * @param {import('@podium/utils').HttpIncoming} [incoming]
+     */
+    // @ts-expect-error Deliberate default empty options for better error messages
+    constructor(options = {}, reqOptions, incoming) {
+        super();
+
+        const {
             rejectUnauthorized = true,
             throwable = false,
             redirectable = false,
@@ -31,11 +89,7 @@ export default class PodletClientHttpOutgoing extends PassThrough {
             maxAge,
             name = '',
             uri,
-        } = {},
-        reqOptions,
-        incoming,
-    ) {
-        super();
+        } = options;
 
         assert(
             uri,
@@ -45,7 +99,6 @@ export default class PodletClientHttpOutgoing extends PassThrough {
         // If requests to https sites should reject on unsigned sertificates
         this.#rejectUnauthorized = rejectUnauthorized;
 
-        // A HttpIncoming object
         this.#incoming = incoming;
 
         // Kill switch for breaking the recursive promise chain
@@ -67,6 +120,7 @@ export default class PodletClientHttpOutgoing extends PassThrough {
         // Manifest which is either retrieved from the registry or
         // remote podlet (in other words its not saved in registry yet)
         this.#manifest = {
+            // @ts-expect-error Internal property
             _fallback: '',
         };
 
@@ -82,14 +136,6 @@ export default class PodletClientHttpOutgoing extends PassThrough {
         // How long the manifest should be cached before refetched
         this.#maxAge = maxAge;
 
-        // What status the manifest is in. This is used to tell what actions need to
-        // be performed throughout the resolving process to complete a request.
-        //
-        // The different statuses can be:
-        // "empty" - there is no manifest available - we are in process of fetching it
-        // "fresh" - the manifest has been fetched but is not stored in cache yet
-        // "cached" - the manifest was retrieved from cache
-        // "stale" - the manifest is outdated, a new manifest needs to be fetched
         this.#status = 'empty';
 
         // Name of the resource (name given to client)
@@ -100,13 +146,6 @@ export default class PodletClientHttpOutgoing extends PassThrough {
 
         // Whether the user can handle redirects manually.
         this.#redirectable = redirectable;
-
-        // When redirectable is true, this object should be populated with redirect information
-        // such that a user can perform manual redirection
-        this.#redirect = null;
-
-        // When isfallback is true, content fetch has failed and fallback will be served instead
-        this.#isFallback = false;
     }
 
     get rejectUnauthorized() {
@@ -130,10 +169,12 @@ export default class PodletClientHttpOutgoing extends PassThrough {
     }
 
     get fallback() {
+        // @ts-expect-error Internal property
         return this.#manifest._fallback;
     }
 
     set fallback(value) {
+        // @ts-expect-error Internal property
         this.#manifest._fallback = value;
     }
 
@@ -169,6 +210,16 @@ export default class PodletClientHttpOutgoing extends PassThrough {
         this.#maxAge = value;
     }
 
+    /**
+     * What status the manifest is in. This is used to tell what actions need to
+     * be performed throughout the resolving process to complete a request.
+     *
+     * The different statuses can be:
+     *  - `"empty"` - there is no manifest available - we are in process of fetching it
+     *  - `"fresh"` - the manifest has been fetched but is not stored in cache yet
+     *  - `"cached"` - the manifest was retrieved from cache
+     *  - `"stale"` - the manifest is outdated, a new manifest needs to be fetched
+     */
     get status() {
         return this.#status;
     }
@@ -193,18 +244,33 @@ export default class PodletClientHttpOutgoing extends PassThrough {
         return this.#manifest.content;
     }
 
+    /**
+     * Kill switch for breaking the recursive promise chain in case it is never able to completely resolve.
+     * This is true if the number of recursions matches the threshold.
+     */
     get kill() {
         return this.#killRecursions === this.#killThreshold;
     }
 
+    /**
+     * The number of recursions before the request should be {@link kill}ed
+     */
     get recursions() {
         return this.#killRecursions;
     }
 
+    /**
+     * Set the number of recursions before the request should be {@link kill}ed
+     */
     set recursions(value) {
         this.#killRecursions = value;
     }
 
+    /**
+     * When {@link redirectable} is `true` this is populated with redirect information so you can send a redirect response to the browser from your layout.
+     *
+     * @see https://podium-lib.io/docs/layout/handling_redirects
+     */
     get redirect() {
         return this.#redirect;
     }
@@ -213,6 +279,11 @@ export default class PodletClientHttpOutgoing extends PassThrough {
         this.#redirect = value;
     }
 
+    /**
+     * Whether the podlet can signal redirects to the layout.
+     *
+     * @see https://podium-lib.io/docs/layout/handling_redirects
+     */
     get redirectable() {
         return this.#redirectable;
     }
@@ -222,17 +293,22 @@ export default class PodletClientHttpOutgoing extends PassThrough {
     }
 
     /**
-     * Boolean getter that indicates whether the client is responding with a content or fallback payload.
+     * True if the client has returned the podlet's fallback.
+     *
      * @example
-     * ```
+     *
+     * ```js
      * if (outgoing.isFallback) console.log("Fallback!");
      * ```
+     *
+     * @see https://podium-lib.io/docs/podlet/fallbacks
      */
     get isFallback() {
-      return this.#isFallback;
+        return this.#isFallback;
     }
 
     pushFallback() {
+        // @ts-expect-error Internal property
         this.push(this.#manifest._fallback);
         this.push(null);
         this.#isFallback = true;
@@ -241,4 +317,4 @@ export default class PodletClientHttpOutgoing extends PassThrough {
     get [Symbol.toStringTag]() {
         return 'PodletClientHttpOutgoing';
     }
-};
+}

package/lib/http.js

@@ -1,8 +1,28 @@
 import { request } from 'undici';
 
+/**
+ * @typedef {object} PodiumHttpClientRequestOptions
+ * @property {'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH'} method
+ * @property {boolean} [json]
+ * @property {boolean} [rejectUnauthorized]
+ * @property {boolean} [follow]
+ * @property {number} [timeout]
+ * @property {number} [bodyTimeout]
+ * @property {object} [query]
+ * @property {import('http').IncomingHttpHeaders} [headers]
+ */
+
 export default class HTTP {
+    /**
+     * @param {string} url
+     * @param {PodiumHttpClientRequestOptions} options
+     * @returns {Promise<Pick<import('undici').Dispatcher.ResponseData, 'statusCode' | 'headers' | 'body'>>}
+     */
     async request(url, options) {
-        const { statusCode, headers, body } = await request(new URL(url), options);
+        const { statusCode, headers, body } = await request(
+            new URL(url),
+            options,
+        );
         return { statusCode, headers, body };
     }
 }

package/lib/resolver.cache.js

@@ -5,9 +5,20 @@ import clonedeep from 'lodash.clonedeep';
 import abslog from 'abslog';
 import assert from 'assert';
 
+/**
+ * @typedef {object} PodletClientCacheResolverOptions
+ * @property {import('abslog').AbstractLoggerOptions} [logger]
+ */
+
 export default class PodletClientCacheResolver {
     #registry;
     #log;
+
+    /**
+     * @constructor
+     * @param {import('ttl-mem-cache').default} registry
+     * @param {PodletClientCacheResolverOptions} options
+     */
     constructor(registry, options = {}) {
         assert(
             registry,
@@ -17,8 +28,14 @@ export default class PodletClientCacheResolver {
         this.#log = abslog(options.logger);
     }
 
+    /**
+     * Loads the podlet's manifest from cache if not stale
+     *
+     * @param {import('./http-outgoing.js').default} outgoing
+     * @returns {Promise<import('./http-outgoing.js').default>}
+     */
     load(outgoing) {
-        return new Promise(resolve => {
+        return new Promise((resolve) => {
             if (outgoing.status !== 'stale') {
                 const cached = this.#registry.get(outgoing.name);
                 if (cached) {
@@ -33,8 +50,14 @@ export default class PodletClientCacheResolver {
         });
     }
 
+    /**
+     * Saves the podlet's manifest to the cache
+     *
+     * @param {import('./http-outgoing.js').default} outgoing
+     * @returns {Promise<import('./http-outgoing.js').default>}
+     */
     save(outgoing) {
-        return new Promise(resolve => {
+        return new Promise((resolve) => {
             if (outgoing.status === 'fresh') {
                 this.#registry.set(
                     outgoing.name,
@@ -55,4 +78,4 @@ export default class PodletClientCacheResolver {
     get [Symbol.toStringTag]() {
         return 'PodletClientCacheResolver';
     }
-};
+}

package/lib/resolver.content.js

@@ -21,11 +21,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 +67,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 +90,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 +113,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 +132,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 +203,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 +253,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 +262,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 +287,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 +304,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;
         }