@podium/client 5.1.0-beta.1 → 5.1.0

package/CHANGELOG.md

@@ -1,10 +1,199 @@
-# [5.1.0-beta.1](https://github.com/podium-lib/client/compare/v5.0.7...v5.1.0-beta.1) (2024-03-20)
+# [5.1.0](https://github.com/podium-lib/client/compare/v5.0.34...v5.1.0) (2024-07-02)
 
 
 ### Features
 
-* add new options to register and use them in fetch ([5aed9d6](https://github.com/podium-lib/client/commit/5aed9d6303681910fc95413535345643bbfa8d62))
-* add support for includeBy and excludeBy options in Resource ([51eb442](https://github.com/podium-lib/client/commit/51eb442398a15b487970ebabe51a5c33f3aede29))
+* conditional fetch by deviceType header ([de4e9c4](https://github.com/podium-lib/client/commit/de4e9c47eea6baf07f2dc72465699a080b6aace1))
+
+## [5.0.34](https://github.com/podium-lib/client/compare/v5.0.33...v5.0.34) (2024-06-18)
+
+
+### Bug Fixes
+
+* **deps:** update dependency undici to v6.19.2 ([ac66051](https://github.com/podium-lib/client/commit/ac66051d0600273f5d3e7c0b57be6fccf222cb83))
+
+## [5.0.33](https://github.com/podium-lib/client/compare/v5.0.32...v5.0.33) (2024-06-17)
+
+
+### Bug Fixes
+
+* **deps:** update dependency undici to v6.19.1 ([c64b634](https://github.com/podium-lib/client/commit/c64b6343c87630fc88a2dbf37ca26044c6a81c75))
+
+## [5.0.32](https://github.com/podium-lib/client/compare/v5.0.31...v5.0.32) (2024-06-14)
+
+
+### Bug Fixes
+
+* **deps:** update dependency undici to v6.19.0 ([ae67694](https://github.com/podium-lib/client/commit/ae6769416e368071a7a7ff8776856cf2307877c0))
+
+## [5.0.31](https://github.com/podium-lib/client/compare/v5.0.30...v5.0.31) (2024-06-05)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/schemas to v5.0.5 ([1fd5c68](https://github.com/podium-lib/client/commit/1fd5c68bf97de53cdffdb26f3510f569fd8a110f))
+
+## [5.0.30](https://github.com/podium-lib/client/compare/v5.0.29...v5.0.30) (2024-06-04)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/schemas to v5.0.4 ([d3574df](https://github.com/podium-lib/client/commit/d3574dfa36e0aa0838ed1410e8b7c0cf15559c0b))
+
+## [5.0.29](https://github.com/podium-lib/client/compare/v5.0.28...v5.0.29) (2024-05-29)
+
+
+### Bug Fixes
+
+* **deps:** update dependency undici to v6.18.2 ([68b44d0](https://github.com/podium-lib/client/commit/68b44d06037a5e8323ff2b7c913838b55e44f59e))
+
+## [5.0.28](https://github.com/podium-lib/client/compare/v5.0.27...v5.0.28) (2024-05-26)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/schemas to v5.0.3 ([089f50a](https://github.com/podium-lib/client/commit/089f50ad1bf06c7bf6ae16fcb24cec3d243dd271))
+
+## [5.0.27](https://github.com/podium-lib/client/compare/v5.0.26...v5.0.27) (2024-05-22)
+
+
+### Bug Fixes
+
+* **deps:** update dependency undici to v6.18.1 ([f1d0705](https://github.com/podium-lib/client/commit/f1d0705a269aee4ddb92b75ff4d791ba02e305e9))
+
+## [5.0.26](https://github.com/podium-lib/client/compare/v5.0.25...v5.0.26) (2024-05-20)
+
+
+### Bug Fixes
+
+* **deps:** update dependency undici to v6.18.0 ([3c6585f](https://github.com/podium-lib/client/commit/3c6585f0d4ce5289f63034384243892557ec67c3))
+
+## [5.0.25](https://github.com/podium-lib/client/compare/v5.0.24...v5.0.25) (2024-05-17)
+
+
+### Bug Fixes
+
+* **deps:** update dependency undici to v6.17.0 ([83f8fba](https://github.com/podium-lib/client/commit/83f8fbaa6c1c417f29f76152510d14cba673abe3))
+
+## [5.0.24](https://github.com/podium-lib/client/compare/v5.0.23...v5.0.24) (2024-05-15)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/utils to v5.0.7 ([ee4ee5b](https://github.com/podium-lib/client/commit/ee4ee5b160ff2aab130e17a3e86abdfec08d1864))
+
+## [5.0.23](https://github.com/podium-lib/client/compare/v5.0.22...v5.0.23) (2024-05-15)
+
+
+### Bug Fixes
+
+* make response toJSON return type serializable ([026a723](https://github.com/podium-lib/client/commit/026a723b545c6b3b0c622851b7d164be2674e8a2))
+
+## [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)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/schemas to v5.0.2 ([e8e2fb4](https://github.com/podium-lib/client/commit/e8e2fb45e00be74222fa19e1faba1f29829976e8))
+
+## [5.0.19](https://github.com/podium-lib/client/compare/v5.0.18...v5.0.19) (2024-05-13)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/utils to v5.0.6 ([fb1e29f](https://github.com/podium-lib/client/commit/fb1e29f6734fc04f907c64904c535bb02faca334))
+
+## [5.0.18](https://github.com/podium-lib/client/compare/v5.0.17...v5.0.18) (2024-05-10)
+
+
+### Bug Fixes
+
+* **deps:** update dependency undici to v6.16.1 ([16edd1c](https://github.com/podium-lib/client/commit/16edd1c20a34686182868f0432e3280952805450))
+
+## [5.0.17](https://github.com/podium-lib/client/compare/v5.0.16...v5.0.17) (2024-05-07)
+
+
+### Bug Fixes
+
+* **deps:** update dependency undici to v6.16.0 ([8884811](https://github.com/podium-lib/client/commit/88848113650e00183f0368aa7c8642a33aaae3ec))
+
+## [5.0.16](https://github.com/podium-lib/client/compare/v5.0.15...v5.0.16) (2024-05-07)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/utils to v5.0.5 ([4059526](https://github.com/podium-lib/client/commit/40595261f2d5b644e7cda15e7d1998cdbbb8b3c3))
+
+## [5.0.15](https://github.com/podium-lib/client/compare/v5.0.14...v5.0.15) (2024-05-07)
+
+
+### Bug Fixes
+
+* Requests hang on http errors ([a9c82b6](https://github.com/podium-lib/client/commit/a9c82b6a931d92540c69c2cbf911184710dc54ee))
+
+## [5.0.14](https://github.com/podium-lib/client/compare/v5.0.13...v5.0.14) (2024-05-02)
+
+
+### Bug Fixes
+
+* **deps:** update dependency abslog to v2.4.4 ([0e21e41](https://github.com/podium-lib/client/commit/0e21e41d2503387dc1d796f857a41048f5222209))
+
+## [5.0.13](https://github.com/podium-lib/client/compare/v5.0.12...v5.0.13) (2024-04-30)
+
+
+### Bug Fixes
+
+* **deps:** update dependency abslog to v2.4.3 ([ea2a8ff](https://github.com/podium-lib/client/commit/ea2a8ff0cc43c97cdd853551959928d4fcc53992))
+
+## [5.0.12](https://github.com/podium-lib/client/compare/v5.0.11...v5.0.12) (2024-04-30)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/schemas to v5.0.1 ([f6b3f56](https://github.com/podium-lib/client/commit/f6b3f56e1be12b2e5a3d5296a00488e61d354662))
+
+## [5.0.11](https://github.com/podium-lib/client/compare/v5.0.10...v5.0.11) (2024-04-23)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/utils to v5.0.4 ([b622774](https://github.com/podium-lib/client/commit/b62277448a0fe326fdd11504a0d7787132911908))
+
+## [5.0.10](https://github.com/podium-lib/client/compare/v5.0.9...v5.0.10) (2024-04-12)
+
+
+### Bug Fixes
+
+* **deps:** update dependency abslog to v2.4.2 ([f36069e](https://github.com/podium-lib/client/commit/f36069ecc3022b3e02a7b4630511fee8b8c8e21d))
+
+## [5.0.9](https://github.com/podium-lib/client/compare/v5.0.8...v5.0.9) (2024-04-12)
+
+
+### Bug Fixes
+
+* **deps:** update dependency @podium/utils to v5.0.3 ([9412fa6](https://github.com/podium-lib/client/commit/9412fa6d3dd847f595fc8818a2f74374f047feeb))
+
+## [5.0.8](https://github.com/podium-lib/client/compare/v5.0.7...v5.0.8) (2024-04-10)
+
+
+### Bug Fixes
+
+* **deps:** update dependency abslog to v2.4.1 ([105a16c](https://github.com/podium-lib/client/commit/105a16c0ff0215cd68984d7aad7351b4b5b623b2))
 
 ## [5.0.7](https://github.com/podium-lib/client/compare/v5.0.6...v5.0.7) (2024-02-01)
 

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.
     },
 });
 ```
@@ -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';
     }
-};
+}