@podium/client 5.0.34 → 5.1.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [5.1.0](https://github.com/podium-lib/client/compare/v5.0.34...v5.1.0) (2024-07-02)
+
+
+### Features
+
+* 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)
 
 

package/README.md

@@ -150,8 +150,31 @@ 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`. 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. Setting both at the same time will throw.
+
+Allowed options:
+
+-   `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.
+
+```js
+import Client from '@podium/client';
+const client = new Client();
+
+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.
+    },
+});
+```
 
 ### .js()
 
@@ -437,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

@@ -60,6 +60,8 @@ const MAX_AGE = Infinity;
  * @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 {
@@ -94,6 +96,8 @@ export default class PodiumClient extends EventEmitter {
             rejectUnauthorized: REJECT_UNAUTHORIZED,
             httpAgent: HTTP_AGENT,
             httpsAgent: HTTPS_AGENT,
+            includeBy: undefined,
+            excludeBy: undefined,
             ...options,
         };
 
@@ -191,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,
@@ -200,8 +210,11 @@ export default class PodiumClient extends EventEmitter {
             maxAge: this.#options.maxAge,
             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,

package/lib/resource.js

@@ -11,6 +11,11 @@ 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]
@@ -25,6 +30,8 @@ const inspect = Symbol.for('nodejs.util.inspect.custom');
  * @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 {
@@ -102,6 +109,56 @@ export default class PodiumClientResource {
             );
         const outgoing = new HttpOutgoing(this.#options, reqOptions, incoming);
 
+        if (this.#options.excludeBy) {
+            /**
+             * @type {string[] | undefined}
+             */
+            const excludedDeviceTypes = this.#options.excludeBy.deviceType;
+            if (Array.isArray(excludedDeviceTypes)) {
+                const deviceTypeHeader =
+                    incoming.request.headers['x-podium-device-type'];
+
+                for (let i = 0; i < excludedDeviceTypes.length; i += 1) {
+                    const shouldSkip =
+                        excludedDeviceTypes[i] === deviceTypeHeader;
+                    if (shouldSkip) {
+                        return new Response({
+                            headers: {},
+                            content: '',
+                            css: [],
+                            js: [],
+                            redirect: null,
+                        });
+                    }
+                }
+            }
+        }
+
+        if (this.#options.includeBy) {
+            /**
+             * @type {string[] | undefined}
+             */
+            const includeDeviceTypes = this.#options.includeBy.deviceType;
+            if (Array.isArray(includeDeviceTypes)) {
+                const deviceTypeHeader =
+                    incoming.request.headers['x-podium-device-type'];
+
+                const shouldRequest =
+                    !deviceTypeHeader ||
+                    includeDeviceTypes.includes(deviceTypeHeader);
+
+                if (!shouldRequest) {
+                    return new Response({
+                        headers: {},
+                        content: '',
+                        css: [],
+                        js: [],
+                        redirect: null,
+                    });
+                }
+            }
+        }
+
         this.#state.setInitializingState();
 
         const { manifest, headers, redirect, isFallback } =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podium/client",
-  "version": "5.0.34",
+  "version": "5.1.0",
   "type": "module",
   "license": "MIT",
   "keywords": [
@@ -46,11 +46,11 @@
     "undici": "6.19.2"
   },
   "devDependencies": {
-    "@babel/eslint-parser": "7.24.6",
+    "@babel/eslint-parser": "7.24.7",
     "@podium/test-utils": "2.5.2",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
-    "@semantic-release/github": "10.0.5",
+    "@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",
@@ -65,7 +65,7 @@
     "get-stream": "9.0.1",
     "http-proxy": "1.18.1",
     "is-stream": "4.0.1",
-    "prettier": "3.3.0",
+    "prettier": "3.3.2",
     "semantic-release": "23.1.1",
     "tap": "18.7.2",
     "typescript": "5.4.5"

package/types/client.d.ts

@@ -27,6 +27,8 @@
  * @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]> {
     /**
@@ -105,6 +107,14 @@ export type RegisterOptions = {
      * 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';

package/types/resource.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @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]
@@ -12,6 +16,8 @@
  * @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 {
     /**
@@ -64,6 +70,12 @@ export default class PodiumClientResource {
     get [Symbol.toStringTag](): string;
     #private;
 }
+export type RequestFilterOptions = {
+    /**
+     * List of values for the `x-podium-device-type` HTTP request header.
+     */
+    deviceType?: string[];
+};
 export type PodiumClientResourceOptions = {
     logger?: import('abslog').AbstractLoggerOptions;
     clientName: string;
@@ -83,6 +95,14 @@ export type PodiumClientResourceOptions = {
     rejectUnauthorized?: boolean;
     httpAgent?: import('http').Agent;
     httpsAgent?: import('https').Agent;
+    /**
+     * Used by `fetch` to conditionally skip fetching the podlet content based on values on the request.
+     */
+    excludeBy?: RequestFilterOptions;
+    /**
+     * Used by `fetch` to conditionally skip fetching the podlet content based on values on the request.
+     */
+    includeBy?: RequestFilterOptions;
 };
 import Metrics from '@metrics/client';
 declare const inspect: unique symbol;