@podium/client 5.2.0-next.2 → 5.2.0-next.4

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [5.2.0-next.4](https://github.com/podium-lib/client/compare/v5.2.0-next.3...v5.2.0-next.4) (2024-09-24)
+
+
+### Bug Fixes
+
+* update @podium/utils to support hints asset collection ([fe97c44](https://github.com/podium-lib/client/commit/fe97c44bc6d29d1e45d335235cd3b1ef6eeafeaa))
+
+
+### Features
+
+* keep track of which resources have emitted early hints and emit complete event once all resources have emitted ([7cf916a](https://github.com/podium-lib/client/commit/7cf916ab286a3c6cb8fbfdae46634b58f2be256f))
+
+# [5.2.0-next.3](https://github.com/podium-lib/client/compare/v5.2.0-next.2...v5.2.0-next.3) (2024-09-20)
+
+
+### Features
+
+* write early hints to browser ([42513a3](https://github.com/podium-lib/client/commit/42513a38f5304648f7b2fb915995c66dc1dd3594))
+
 # [5.2.0-next.2](https://github.com/podium-lib/client/compare/v5.2.0-next.1...v5.2.0-next.2) (2024-09-16)
 
 

package/README.md

@@ -152,6 +152,7 @@ The following values can be provided:
 -   `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.
 -   `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.
+-   `earlyHints` - {boolean} - Can be used to disable early hints from being sent to the browser for this resource, see [HTTP Status 103 Early Hints](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103).
 
 ##### `excludeBy` and `includeBy`
 

package/lib/client.js

@@ -62,6 +62,7 @@ const MAX_AGE = Infinity;
  * @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.
+ * @property {boolean} [earlyHints=true]
  */
 
 export default class PodiumClient extends EventEmitter {
@@ -212,6 +213,7 @@ export default class PodiumClient extends EventEmitter {
             httpAgent: this.#options.httpAgent,
             includeBy: this.#options.includeBy,
             excludeBy: this.#options.excludeBy,
+            earlyHints: true,
             ...options,
         };
 

package/lib/http-outgoing.js

@@ -1,5 +1,6 @@
 import { PassThrough } from 'stream';
 import assert from 'assert';
+import { toPreloadAssetObjects } from './utils.js';
 
 /**
  * @typedef {object} PodiumClientHttpOutgoingOptions
@@ -69,6 +70,7 @@ export default class PodletClientHttpOutgoing extends PassThrough {
     #uri;
     #js;
     #css;
+    #hintsReceived = false;
 
     /**
      * @constructor
@@ -299,6 +301,20 @@ export default class PodletClientHttpOutgoing extends PassThrough {
         this.#redirect = value;
     }
 
+    get hintsReceived() {
+        return this.#hintsReceived;
+    }
+
+    set hintsReceived(value) {
+        this.#hintsReceived = value;
+        if (this.#hintsReceived) {
+            this.#incoming?.hints?.addReceivedHint(this.#name, {
+                js: this.js,
+                css: this.css,
+            });
+        }
+    }
+
     /**
      * Whether the podlet can signal redirects to the layout.
      *
@@ -336,6 +352,21 @@ export default class PodletClientHttpOutgoing extends PassThrough {
         this.css = this.#manifest._css;
         this.push(null);
         this.#isFallback = true;
+        // assume the hints from the podlet have failed and fallback assets will be used
+        this.hintsReceived = true;
+    }
+
+    writeEarlyHints(cb = () => {}) {
+        if (this.#incoming.response.writeEarlyHints) {
+            const preloads = toPreloadAssetObjects([
+                ...(this.js || []),
+                ...(this.css || []),
+            ]);
+            const link = preloads.map((preload) => preload.toHeader());
+            if (link.length) {
+                this.#incoming.response.writeEarlyHints({ link }, cb);
+            }
+        }
     }
 
     get [Symbol.toStringTag]() {

package/lib/resolver.content.js

@@ -27,6 +27,7 @@ const UA_STRING = `${pkg.name} ${pkg.version}`;
  * @property {string} clientName
  * @property {import('./http.js').default} [http]
  * @property {import('abslog').AbstractLoggerOptions} [logger]
+ * @property {boolean} [earlyHints]
  */
 
 export default class PodletClientContentResolver {
@@ -34,6 +35,7 @@ export default class PodletClientContentResolver {
     #metrics;
     #histogram;
     #http;
+    #earlyHints;
 
     /**
      * @constructor
@@ -44,6 +46,8 @@ export default class PodletClientContentResolver {
         this.#http = options.http || new HTTP();
         const name = options.clientName;
         this.#log = abslog(options.logger);
+        this.#earlyHints =
+            typeof options.earlyHints === 'boolean' ? options.earlyHints : true;
         this.#metrics = new Metrics();
         this.#histogram = this.#metrics.histogram({
             name: 'podium_client_resolver_content_resolve',
@@ -135,8 +139,6 @@ export default class PodletClientContentResolver {
             outgoing.contentUri,
         );
 
-        let hintsReceived = false;
-
         /** @type {import('./http.js').PodiumHttpClientRequestOptions} */
         const reqOptions = {
             rejectUnauthorized: outgoing.rejectUnauthorized,
@@ -144,8 +146,8 @@ export default class PodletClientContentResolver {
             method: 'GET',
             query: outgoing.reqOptions.query,
             headers,
-            onInfo({ statusCode, headers }) {
-                if (statusCode === 103 && !hintsReceived) {
+            onInfo: ({ statusCode, headers }) => {
+                if (statusCode === 103 && !outgoing.hintsReceived) {
                     const parsedAssetObjects = parseLinkHeaders(headers.link);
 
                     const scriptObjects = parsedAssetObjects.filter(
@@ -158,8 +160,10 @@ export default class PodletClientContentResolver {
                     outgoing.js = filterAssets('content', scriptObjects);
                     // set the content css asset objects
                     outgoing.css = filterAssets('content', styleObjects);
+                    // write the early hints to the browser
+                    if (this.#earlyHints) outgoing.writeEarlyHints();
 
-                    hintsReceived = true;
+                    outgoing.hintsReceived = true;
                 }
             },
         };

package/lib/resolver.js

@@ -11,6 +11,7 @@ import Cache from './resolver.cache.js';
  * @typedef {object} PodletClientResolverOptions
  * @property {string} clientName
  * @property {import('abslog').AbstractLoggerOptions} [logger]
+ * @property {boolean} [earlyHints]
  */
 
 export default class PodletClientResolver {
@@ -41,7 +42,10 @@ export default class PodletClientResolver {
             http,
         });
         this.#fallback = new Fallback({ ...options, http });
-        this.#content = new Content({ ...options, http });
+        this.#content = new Content({
+            ...options,
+            http,
+        });
         this.#metrics = new Metrics();
 
         this.#metrics.on('error', (error) => {

package/lib/resource.js

@@ -105,6 +105,10 @@ export default class PodiumClientResource {
             throw new TypeError(
                 'you must pass an instance of "HttpIncoming" as the first argument to the .fetch() method',
             );
+        // add the name of this resource as expecting a hint to be received
+        // we use this to track across resources and emit a hint completion event once
+        // all hints from all resources have been received.
+        incoming.hints.addExpectedHint(this.#options.name);
         const outgoing = new HttpOutgoing(this.#options, reqOptions, incoming);
 
         if (this.#options.excludeBy) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@podium/client",
-  "version": "5.2.0-next.2",
+  "version": "5.2.0-next.4",
   "type": "module",
   "license": "MIT",
   "keywords": [
@@ -40,7 +40,7 @@
     "@hapi/boom": "10.0.1",
     "@metrics/client": "2.5.3",
     "@podium/schemas": "5.0.6",
-    "@podium/utils": "5.2.0",
+    "@podium/utils": "5.3.1",
     "abslog": "2.4.4",
     "http-cache-semantics": "^4.0.3",
     "lodash.clonedeep": "^4.5.0",

package/types/client.d.ts

@@ -29,6 +29,7 @@
  * @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.
+ * @property {boolean} [earlyHints=true]
  */
 export default class PodiumClient extends EventEmitter<[never]> {
     /**
@@ -115,6 +116,7 @@ export type RegisterOptions = {
      * Used by `fetch` to conditionally skip fetching the podlet content based on values on the request.
      */
     includeBy?: import('./resource.js').RequestFilterOptions;
+    earlyHints?: boolean;
 };
 import EventEmitter from 'events';
 import Metrics from '@metrics/client';

package/types/http-outgoing.d.ts

@@ -105,6 +105,8 @@ export default class PodletClientHttpOutgoing extends PassThrough {
      * @see https://podium-lib.io/docs/layout/handling_redirects
      */
     get redirect(): PodiumRedirect;
+    set hintsReceived(value: boolean);
+    get hintsReceived(): boolean;
     set redirectable(value: boolean);
     /**
      * Whether the podlet can signal redirects to the layout.
@@ -125,6 +127,7 @@ export default class PodletClientHttpOutgoing extends PassThrough {
      */
     get isFallback(): boolean;
     pushFallback(): void;
+    writeEarlyHints(cb?: () => void): void;
     get [Symbol.toStringTag](): string;
     #private;
 }

package/types/resolver.content.d.ts

@@ -3,6 +3,7 @@
  * @property {string} clientName
  * @property {import('./http.js').default} [http]
  * @property {import('abslog').AbstractLoggerOptions} [logger]
+ * @property {boolean} [earlyHints]
  */
 export default class PodletClientContentResolver {
     /**
@@ -25,5 +26,6 @@ export type PodletClientContentResolverOptions = {
     clientName: string;
     http?: import('./http.js').default;
     logger?: import('abslog').AbstractLoggerOptions;
+    earlyHints?: boolean;
 };
 import Metrics from '@metrics/client';

package/types/resolver.d.ts

@@ -2,6 +2,7 @@
  * @typedef {object} PodletClientResolverOptions
  * @property {string} clientName
  * @property {import('abslog').AbstractLoggerOptions} [logger]
+ * @property {boolean} [earlyHints]
  */
 export default class PodletClientResolver {
     /**
@@ -31,5 +32,6 @@ export default class PodletClientResolver {
 export type PodletClientResolverOptions = {
     clientName: string;
     logger?: import('abslog').AbstractLoggerOptions;
+    earlyHints?: boolean;
 };
 import Metrics from '@metrics/client';

package/types/utils.d.ts

@@ -1,8 +1,8 @@
 export function isHeaderDefined(headers: object, header: string): boolean;
 export function hasManifestChange(item: object): boolean;
 export function validateIncoming(incoming?: object): boolean;
-export function filterAssets<T extends AssetJs | AssetCss>(scope: "content" | "fallback" | "all", assets: T[]): T[];
+export function filterAssets<T extends AssetCss | AssetJs>(scope: "content" | "fallback" | "all", assets: T[]): T[];
 export function parseLinkHeaders(headers: any): any[];
 export function toPreloadAssetObjects(assetObjects: any): any;
-import { AssetJs } from '@podium/utils';
 import { AssetCss } from '@podium/utils';
+import { AssetJs } from '@podium/utils';