@podium/client 5.1.0-beta.1 → 5.1.1

package/README.md

@@ -150,18 +150,16 @@ The following values can be provided:
 -   `retries` - {Number} - The number of times the client should retry to settle a version number conflict before terminating. See the section "[on retrying](#on-retrying)" for more information. Default: 4 - Optional.
 -   `timeout` - {Number} - Defines how long, in milliseconds, a request should wait before the connection is terminated. Overrides the global default. Default: 1000 - Optional.
 -   `throwable` - {Boolean} - Defines whether an error should be thrown if a failure occurs during the process of fetching a podium component. Defaults to `false` - Optional.
--   `resolveJs` - {Boolean} - Defines whether to resolve a relative JS uri for a component to be an absolute uri. Defaults to `false` - Optional.
--   `resolveCss` - {Boolean} - Defines whether to resolve a relative CSS uri for a component to be an absolute uri. Defaults to `false` - Optional.
 -   `excludeBy` - {Object} - Lets you define a set of rules where a `fetch` call will not be resolved if it matches. - Optional.
--   `includeBy` - {Object} - Inverse of `excludeBy`. - Optional.
+-   `includeBy` - {Object} - Inverse of `excludeBy`. Setting both at the same time will throw. - Optional.
 
 ##### `excludeBy` and `includeBy`
 
-These options are used by `fetch` to conditionally skip fetching the podlet content based on values on the request. It's an alternative to conditionally fetching podlets in your request handler.
+These options are used by `fetch` to conditionally skip fetching the podlet content based on values on the request. It's an alternative to conditionally fetching podlets in your request handler. Setting both at the same time will throw.
 
 Allowed options:
 
-- `deviceType` - {Array<String>} - List of values for the `x-podium-device-type` header. - Optional.
+-   `deviceType` - {Array<String>} - List of values for the `x-podium-device-type` header. - Optional.
 
 Example: exclude a header and footer in a hybrid web view.
 
@@ -173,7 +171,7 @@ const footer = client.register({
     uri: 'http://footer.site.com/manifest.json',
     name: 'footer',
     excludeBy: {
-        deviceType: ["hybrid-ios", "hybrid-android"], // when footer.fetch(incoming) is called, if the incoming request has the header `x-podium-device-type: hybrid-ios`, `fetch` will return an empty response.
+        deviceType: ['hybrid-ios', 'hybrid-android'], // when footer.fetch(incoming) is called, if the incoming request has the header `x-podium-device-type: hybrid-ios`, `fetch` will return an empty response.
     },
 });
 ```
@@ -382,7 +380,7 @@ Response object containing the keys `content`, `headers`, `css` and `js`.
 
 #### incoming (required)
 
-A HttpIncoming object. See https://github.com/podium-lib/utils/blob/master/lib/http-incoming.js
+A HttpIncoming object. See https://github.com/podium-lib/utils/blob/main/lib/http-incoming.js
 
 #### options (optional)
 
@@ -413,7 +411,7 @@ emitted.
 
 #### incoming (required)
 
-A HttpIncoming object. See https://github.com/podium-lib/utils/blob/master/lib/http-incoming.js
+A HttpIncoming object. See https://github.com/podium-lib/utils/blob/main/lib/http-incoming.js
 
 #### options (optional)
 
@@ -462,15 +460,19 @@ stream.once('beforeStream', (data) => {
 Both the .fetch() method and the .stream() method give you access to podlet asset objects and these CSS and JS asset objects will be filtered if the asset objects contain a `scope` property and that `scope` property matches the current response type (either content or fallback).
 
 For example, if the podlet manifest contains a JavaScript asset definition of the form:
+
 ```
 {
 	js: [{ value: "https://assets.com/path/to/file.js", scope: "content" }],
 }
 ```
+
 And the client performs a fetch like so:
+
 ```js
 const result = await component.fetch();
 ```
+
 Then, if the podlet successfully responds from its content route, the `result.js` property will contain the asset defined above. If, however, the podlet's content route errors and the client is forced to use the podlet's fallback content, then `result.js` property will be an empty array.
 
 Possible `scope` values are `content`, `fallback` and `all`. For backwards compatibility reasons, when assets do not provide a `scope` property, they will always be included in both `content` and `fallback` responses.

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,51 @@ 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.
+ * @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 {
     #resources;
     #registry;
@@ -43,6 +71,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);
@@ -71,7 +105,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);
         });
 
@@ -81,7 +115,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,
@@ -93,7 +127,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,
@@ -101,7 +135,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,
@@ -130,7 +164,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.`,
@@ -147,6 +195,12 @@ export default class PodiumClient extends EventEmitter {
             );
         }
 
+        if (options.includeBy && options.excludeBy) {
+            throw new Error(
+                'A podlet can only be registered with either includeBy or excludeBy, not both.',
+            );
+        }
+
         const resourceOptions = {
             rejectUnauthorized: this.#options.rejectUnauthorized,
             clientName: this.#options.name,
@@ -154,12 +208,13 @@ export default class PodiumClient extends EventEmitter {
             timeout: this.#options.timeout,
             logger: this.#options.logger,
             maxAge: this.#options.maxAge,
-            includeBy: this.#options.includeBy,
-            excludeBy: this.#options.excludeBy,
             httpsAgent: this.#options.httpsAgent,
             httpAgent: this.#options.httpAgent,
+            includeBy: this.#options.includeBy,
+            excludeBy: this.#options.excludeBy,
             ...options,
         };
+
         const resource = new Resource(
             this.#registry,
             this.#state,
@@ -187,12 +242,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();
@@ -208,4 +268,4 @@ export default class PodiumClient extends EventEmitter {
     get [Symbol.toStringTag]() {
         return 'PodiumClient';
     }
-};
+}

package/lib/http-outgoing.js

@@ -1,28 +1,84 @@
-/* eslint-disable no-underscore-dangle */
-
 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 +87,7 @@ export default class PodletClientHttpOutgoing extends PassThrough {
             maxAge,
             name = '',
             uri,
-        } = {},
-        reqOptions,
-        incoming,
-    ) {
-        super();
+        } = options;
 
         assert(
             uri,
@@ -45,7 +97,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 +118,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 +134,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 +144,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 +167,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 +208,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 +242,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 +277,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 +291,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 +315,4 @@ export default class PodletClientHttpOutgoing extends PassThrough {
     get [Symbol.toStringTag]() {
         return 'PodletClientHttpOutgoing';
     }
-};
+}

package/lib/http.js

@@ -1,23 +1,28 @@
-import { Client } from 'undici';
+import { request } from 'undici';
 
-export default class HTTP {
-    // #client;
-
-    // constructor() {
-    //     // this.#client = { request };
-    // }
+/**
+ * @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 u = new URL(url);
-        const client = new Client(u.origin, {
-            ...options,
-            connect: { rejectUnauthorized: options.rejectUnauthorized },
-        });
-
-        const { statusCode, headers, body } = await client.request({
-            ...options,
-            path: u.pathname,
-        });
+        const { statusCode, headers, body } = await request(
+            new URL(url),
+            options,
+        );
         return { statusCode, headers, body };
     }
 }

package/lib/resolver.cache.js

@@ -1,13 +1,21 @@
-/* eslint-disable no-plusplus */
-/* eslint-disable no-param-reassign */
-
 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 +25,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 +47,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 +75,4 @@ export default class PodletClientCacheResolver {
     get [Symbol.toStringTag]() {
         return 'PodletClientCacheResolver';
     }
-};
+}