@komaci/prefetch 240.1.3

package/build/__mocks__/@lwrjs/router.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="jest" />
+import type { PageReference, Router } from 'lwr/router';
+export declare const createRouter: jest.Mock<any, any>;
+export type { PageReference, Router };
+//# sourceMappingURL=router.d.ts.map

package/build/__mocks__/lwr/router.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="jest" />
+import type { PageReference, Router } from 'lwr/router';
+export declare const createRouter: jest.Mock<any, any>;
+export type { PageReference, Router };
+//# sourceMappingURL=router.d.ts.map

package/build/__mocks__/mockAdgModule.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("packages/@komaci/resolver/src/modules/komaci/resolverTypes/resolverTypes").AdgModuleHandle | undefined;
+export default _default;
+//# sourceMappingURL=mockAdgModule.d.ts.map

package/build/__mocks__/o11y/client.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="jest" />
+export declare const getInstrumentation: jest.Mock<any, any>;
+//# sourceMappingURL=client.d.ts.map

package/build/__mocks__/o11y_schema/sf_komaci.d.ts

@@ -0,0 +1,5 @@
+export declare const wireContextSchema: any;
+export declare const batchSchema: any;
+export declare const bulkResolveSchema: any;
+export declare const prefetchSchema: any;
+//# sourceMappingURL=sf_komaci.d.ts.map

package/build/modules/komaci/prefetch/prefetch.d.ts

@@ -0,0 +1,5 @@
+import type { Router, PageReference, RouteDefinition } from 'lwr/router';
+import type { IPrefetchService, PrefetchConfig, AddressStatus } from 'komaci/prefetchTypes';
+export declare function prefetch(routes?: RouteDefinition[], pageReferences?: PageReference[], config?: PrefetchConfig): Promise<AddressStatus[]>;
+export declare function getPrefetchService<TAddress = PageReference>(router: Router<TAddress>, addresses: TAddress[], config?: PrefetchConfig<TAddress>): IPrefetchService;
+//# sourceMappingURL=prefetch.d.ts.map

package/build/modules/komaci/prefetch/prefetch.js

@@ -0,0 +1,53 @@
+/* eslint-disable no-console */
+import { PrefetchService } from 'komaci/prefetchService';
+import { createRouter } from 'lwr/router';
+// NOTE: Backward compatible prefetch until primer is updated to handle this.
+// TODO W-9690128 - Let's potentially remove this prefetch method and update lsdk code to call `getPrefetchState` directly.
+export function prefetch(routes = [], pageReferences = [], config) {
+  if (!routes?.length || !pageReferences?.length) {
+    return Promise.resolve([]);
+  }
+
+  const router = createRouter({
+    routes
+  });
+  return new Promise((resolve, reject) => {
+    let currentState;
+    const addressesProcessed = [];
+    const wrappedConfig = {
+      maxConcurrent: config?.maxConcurrent,
+      onAddressProcessed: status => {
+        addressesProcessed.push(status);
+        if (config && config.onAddressProcessed) config.onAddressProcessed(status);
+      },
+      onStateChanged: status => {
+        const {
+          state
+        } = status;
+
+        if (state === 'running') {
+          if (!currentState) {
+            currentState = state;
+          } else {
+            reject(new Error(`Unexpected state transition. ${currentState} -> ${state}`));
+          }
+        } else if (state === 'done') {
+          if (addressesProcessed.length !== pageReferences.length) {
+            reject(new Error(`Prefetch error, expected ${pageReferences.length} addresses processed, but only got ${addressesProcessed.length}`));
+          }
+
+          resolve(addressesProcessed);
+        } else if (state === 'error') {
+          reject(new Error(`Prefetch error: ${status.message}`));
+        }
+
+        if (config && config.onStateChanged) config.onStateChanged(status);
+      },
+      instrumentationContext: config?.instrumentationContext
+    };
+    getPrefetchService(router, pageReferences, wrappedConfig);
+  });
+}
+export function getPrefetchService(router, addresses, config) {
+  return new PrefetchService(router, addresses, config);
+}

package/build/modules/komaci/prefetchService/prefetchService.d.ts

@@ -0,0 +1,114 @@
+import type { Router, PageReference } from 'lwr/router';
+import { PrefetchState } from 'komaci/prefetchTypes';
+import type { IPrefetchService, PrefetchConfig, AdgRoutingResult, AdgResolutionGroup } from 'komaci/prefetchTypes';
+import type { BulkResolutionStatus } from '@komaci/resolver';
+export declare class PrefetchService<TAddress = PageReference> implements IPrefetchService {
+    private readonly config;
+    private router;
+    private adgMap;
+    private resolutionGroups;
+    private state;
+    private apiOptions;
+    private _instrumentation;
+    private _activity;
+    private readonly _startTime;
+    private readonly _size;
+    constructor(router: Router<TAddress>, addresses: TAddress[], config?: PrefetchConfig<TAddress>);
+    /**
+     * Processes the given address through the router, retrieving the AdgFunction if
+     * available.
+     * @param address to process
+     * @returns AdgRoutingResult encapsulating the status, original address, and adgFn
+     */
+    private processAddress;
+    private getErrorAddress;
+    /**
+     * Determine if the router has an adg for the given address. For each result
+     * with an adg, group the address with other addresses that resolve to the same
+     * adg.
+     *
+     * @param address that resolves to this routingResult
+     * @param routingResult provided by the router for this address
+     * @returns adgRoutingResult
+     */
+    private onRoutingResult;
+    /**
+     * Updates the adgMap with the given adgFn, creating the entry if needed
+     * and updating the pageReference array for the given address.
+     *
+     * @param adgModule adgModule that will act as a key in the map
+     * @param address address associated with this adgFn
+     */
+    private updateAdgMap;
+    /**
+     * Initiates the prefetch process for the given array of addresses.
+     * - Addresses are ran through the router to resolve their associated AdgModule, if any
+     * - Addresses that resolve to AdgModule are grouped together in order to be resolved in a batch
+     * - Addresses that do no resolve to an AdgModule are rejected
+     *
+     * @param addresses
+     */
+    private prefetch;
+    /**
+     * Processes a list of addresses through the router in series
+     * @param addresses to process
+     * @returns { AdgRoutingResult[] } a list of AdgRoutingResult
+     */
+    processAllAddresses(addresses: TAddress[]): Promise<AdgRoutingResult<TAddress>[]>;
+    /**
+     * Split all the addresses based on the maxConcurrent configuration
+     * bulkResolve them in iterations
+     */
+    private bulkResolveGuard;
+    /**
+     * Resolves the given adgFunction with the given resolutionGroup
+     * @param adgFn to resolve for the inputs provided in the resolutionContext
+     * @param addresses the list of addresses to be placed into a new BulkResolver
+     */
+    private bulkResolve;
+    /**
+     * StatusCallback to BulkResolver, invoked when resolver emits a new status.
+     * Updates the prefetchService's status if applicable.
+     * @param bulkResolutionGroup
+     * @param action InstrumentationContext
+     * @param status
+     */
+    private onBulkResolutionStatus;
+    /**
+     * Stops all bulkResolvers
+     */
+    stop(): void;
+    /**
+     * Called upon unexpected conditions that may indicate to the consumer that
+     * the prefetchService or its associated resolver is in an invalid state
+     * @param message
+     */
+    private onUnexpectedCondition;
+    /**
+     * Called when resolution for a given address has completed, or was otherwise
+     * rejected.
+     * @param address that is done
+     * @param state completed when resolved, or rejected when either no ADG exists, or resolver emitted an error with the given address
+     * @param reasons reasons for rejected status, if any
+     */
+    private onAddressDone;
+    /**
+     * Updates the current PrefetchState to done if every bulkResolver has emitted
+     * a non-running status for all inputs.
+     */
+    updateStateIfAllDone(bulkResolutionContext: AdgResolutionGroup<TAddress>, status: BulkResolutionStatus): void;
+    /**
+     * Called when resolver emits a "sink" state for an address or all addresses
+     * @param status
+     * @param bulkResolutionContext
+     */
+    private onResolutionDone;
+    /**
+     * Updates PrefetchState and notifies consumer via config.onStateChanged callback
+     * @param newState the new state
+     * @param [message] state message, if any
+     */
+    private updateState;
+    getState(): PrefetchState;
+}
+//# sourceMappingURL=prefetchService.d.ts.map

package/build/modules/komaci/prefetchService/prefetchService.js

@@ -0,0 +1,509 @@
+import { ERROR_PREFIX, PrefetchStatusStates as STATE } from 'komaci/prefetchTypes';
+import { getInstrumentation } from 'o11y/client';
+import { getBulkAdgResolver } from 'komaci/resolver';
+import ResolverConfig from 'komaci/resolverConfig';
+import { InstrumentedAction } from 'komaci/instrumentedAction';
+import { bulkResolveSchema, prefetchSchema, prefetchServiceSchema, totalRoutingSchema } from 'o11y_schema/sf_komaci';
+const NO_ADG_MODULE_FOUND = 'No ADG module found for given address.';
+const ValidStatusTransitions = {
+  [STATE.init]: [STATE.running, STATE.stopped, STATE.error],
+  [STATE.running]: [STATE.done, STATE.error, STATE.stopped],
+  [STATE.error]: [STATE.stopped, STATE.done],
+  [STATE.done]: [STATE.stopped],
+  [STATE.stopped]: [],
+
+  isValid(oldState, newState) {
+    return this[oldState].includes(newState);
+  }
+
+};
+export class PrefetchService {
+  config = {};
+  state = STATE.init;
+  apiOptions = {};
+
+  constructor(router, addresses, config = {}) {
+    if (!router) {
+      throw new TypeError(`${ERROR_PREFIX} Must provide Router.`);
+    }
+
+    this.config = config;
+    this.apiOptions.instrumentationContext = this.config.instrumentationContext ? this.config.instrumentationContext : undefined;
+    this.router = router;
+    this.adgMap = new Map();
+    this.resolutionGroups = [];
+    this._instrumentation = getInstrumentation('komaci');
+    this._activity = this._instrumentation.startActivity('prefetch', this.apiOptions);
+    this._size = addresses.length; //FIXME: to use o11y.startActivity() when o11y available
+
+    this._startTime = Date.now(); // setting Instrumentation into ResolverConfig singleton so that the Resolver can
+    // access the rootActivityId to enable multiple root activity instrumentation
+
+    if (this.config?.instrumentationContext && ResolverConfig) {
+      ResolverConfig.InstrumentationContext = this.config.instrumentationContext;
+    }
+
+    if (this.config?.downloadImage && ResolverConfig) {
+      ResolverConfig.DownloadImage = this.config.downloadImage;
+    }
+
+    this.prefetch(addresses);
+  }
+  /**
+   * Processes the given address through the router, retrieving the AdgFunction if
+   * available.
+   * @param address to process
+   * @returns AdgRoutingResult encapsulating the status, original address, and adgFn
+   */
+
+
+  processAddress(address) {
+    const userSchemaData = {
+      page: JSON.stringify(address)
+    };
+    let resolveViewResult;
+
+    try {
+      resolveViewResult = this.router.resolveView(address);
+    } catch (err) {
+      this._instrumentation.error(err, prefetchSchema, userSchemaData, this.apiOptions);
+
+      return Promise.resolve(this.getErrorAddress(address, 'Unexpected exception during routing: ' + err?.message));
+    }
+
+    return resolveViewResult.then(destination => {
+      return this.onRoutingResult(address, destination);
+    }).then(value => {
+      this._instrumentation.log(prefetchSchema, userSchemaData, this.apiOptions);
+
+      return value;
+    }).catch(err => {
+      this._instrumentation.error(err, prefetchSchema, userSchemaData, this.apiOptions);
+
+      return this.getErrorAddress(address, err?.message ? 'Unexpected exception processing routing result: ' + err?.message : 'Unknown exception processing routing result.');
+    });
+  }
+
+  getErrorAddress(address, reason) {
+    return {
+      address,
+      success: false,
+      reason: reason
+    };
+  }
+  /**
+   * Determine if the router has an adg for the given address. For each result
+   * with an adg, group the address with other addresses that resolve to the same
+   * adg.
+   *
+   * @param address that resolves to this routingResult
+   * @param routingResult provided by the router for this address
+   * @returns adgRoutingResult
+   */
+
+
+  async onRoutingResult(address, routingResult) {
+    const adg = 'komaci';
+    const {
+      viewset = {}
+    } = routingResult;
+    let adgModuleImporter; // if routing handler only provides komaci view, use komaci module importer
+
+    if (viewset[adg]) {
+      adgModuleImporter = viewset[adg];
+    } else if (viewset['default']) {
+      // calculate komaci specifier using generic default viewset
+      const viewInfo = viewset['default'];
+
+      if (viewInfo) {
+        if (viewInfo.specifier) {
+          const komaciSpecifier = '@salesforce/komaci/' + viewInfo.specifier.replace('/', '__'); // create adgModuleImporter using komaciSpecifier
+
+          adgModuleImporter = () => import(komaciSpecifier);
+        }
+      }
+    }
+
+    const adgModuleImport = await adgModuleImporter?.();
+    const adgRoutingResult = {
+      address,
+      success: false // assume the worst
+
+    };
+
+    if (adgModuleImport?.default) {
+      const adgModule = adgModuleImport.default;
+      adgRoutingResult.success = true;
+      adgRoutingResult.adgModule = adgModule;
+      this.updateAdgMap(adgModule, address);
+    } else {
+      adgRoutingResult.reason = NO_ADG_MODULE_FOUND;
+    }
+
+    return adgRoutingResult;
+  }
+  /**
+   * Updates the adgMap with the given adgFn, creating the entry if needed
+   * and updating the pageReference array for the given address.
+   *
+   * @param adgModule adgModule that will act as a key in the map
+   * @param address address associated with this adgFn
+   */
+
+
+  updateAdgMap(adgModule, address) {
+    const addresses = this.adgMap.get(adgModule); // check to see if adg has already been added, and append address to the list
+
+    if (addresses) {
+      // if highVolumePriming is enabled, we only wish to resolve each unique module once, so don't add additional addresses to the list for resolution
+      if (!this.config.highVolumePriming) {
+        addresses.push(address);
+      }
+    } else {
+      // adg hasn't been added, create entry.
+      this.adgMap.set(adgModule, [address]);
+    }
+  }
+  /**
+   * Initiates the prefetch process for the given array of addresses.
+   * - Addresses are ran through the router to resolve their associated AdgModule, if any
+   * - Addresses that resolve to AdgModule are grouped together in order to be resolved in a batch
+   * - Addresses that do no resolve to an AdgModule are rejected
+   *
+   * @param addresses
+   */
+
+
+  prefetch(addresses) {
+    this.updateState(STATE.running);
+    this.processAllAddresses(addresses).then(adgRoutingResults => {
+      const rejected = adgRoutingResults.filter(({
+        success
+      }) => !success);
+      rejected.forEach(({
+        address: rejectedAddress,
+        reason
+      }) => {
+        const message = reason || `${ERROR_PREFIX} Unknown exception processing routing result.`;
+        this.onAddressDone(rejectedAddress, 'rejected', [message]);
+      }); // if prefetch exclusively consists of unprocessable addresses, update state to done
+
+      if (rejected.length === adgRoutingResults.length) {
+        this.updateState(STATE.done, 'no processable addresses, do not bulkResolve and set state to "done"');
+      }
+
+      this.bulkResolveGuard();
+    });
+  }
+  /**
+   * Processes a list of addresses through the router in series
+   * @param addresses to process
+   * @returns { AdgRoutingResult[] } a list of AdgRoutingResult
+   */
+
+
+  async processAllAddresses(addresses) {
+    // add instrumentation to get total duration to process all addresses
+    const action = InstrumentedAction.startAction('komaci.router', totalRoutingSchema, {
+      instrumentWithoutLog: false,
+      postTimeInLog: true,
+      apiOptions: this.apiOptions
+    });
+    const results = [];
+    const maxConcurrent = this.config.maxConcurrent || Number.MAX_SAFE_INTEGER;
+
+    for (let i = 0; i < addresses.length; i += maxConcurrent) {
+      const processList = addresses.slice(i, Math.min(addresses.length, i + maxConcurrent));
+      results.push(...(await Promise.all(processList.map(address => this.processAddress(address)))));
+    }
+
+    action.finishAction(false, {});
+    return results;
+  }
+  /**
+   * Split all the addresses based on the maxConcurrent configuration
+   * bulkResolve them in iterations
+   */
+
+
+  bulkResolveGuard() {
+    const maxConcurrent = this.config.maxConcurrent || Number.MAX_SAFE_INTEGER; // rest capacity when there are addresses being processed
+
+    let capacity = maxConcurrent;
+    const adgs = this.adgMap.keys();
+
+    for (const adgFn of adgs) {
+      const addresses = this.adgMap.get(adgFn);
+
+      if (addresses && addresses.length > 0) {
+        if (addresses.length > capacity) {
+          if (addresses.length < maxConcurrent) {
+            /* to benefits from batching,
+               we dont want to split addresses for same adg if they can be in same iteration
+               example: having maxConcurrent: 10
+                               adg1: 6 addresses
+                               adg2: 8 addresses
+               ideal way is two iterations for both adg1 and adg2 instead of iter1: 6 adg1 + 4 adg2, iter2: 4 adg2
+             in addition to the example, if there is another adg3: 4 addresses, will do
+                iter1: 6 adg1 + 4 adg3
+                iter2: 8 adg2
+            */
+            continue;
+          } // if the length of address have exceed the maxConcurrent,
+          // split/resolve and update the rest to adgMap
+
+
+          const currentIteration = addresses.slice(0, capacity);
+          this.adgMap.set(adgFn, addresses.slice(capacity));
+          this.bulkResolve(adgFn, currentIteration);
+          break;
+        } else {
+          // if the length of address can fit in the capacity,
+          // resolve them all and remove the entry from adgMap
+          capacity = capacity - addresses.length;
+          this.adgMap.delete(adgFn);
+          this.bulkResolve(adgFn, addresses);
+        }
+      } else {
+        // in case of empty address list
+        this.adgMap.delete(adgFn);
+      }
+    }
+  }
+  /**
+   * Resolves the given adgFunction with the given resolutionGroup
+   * @param adgFn to resolve for the inputs provided in the resolutionContext
+   * @param addresses the list of addresses to be placed into a new BulkResolver
+   */
+
+
+  bulkResolve(adgFn, addresses) {
+    if (this.state == STATE.stopped) {
+      return;
+    }
+
+    const action = InstrumentedAction.startAction('komaci', bulkResolveSchema, {
+      instrumentWithoutLog: false,
+      postTimeInLog: true,
+      apiOptions: this.apiOptions
+    });
+    const adgInputs = addresses.map(address => {
+      return {
+        properties: {},
+        context: {
+          CurrentPageReference: address
+        }
+      };
+    });
+    const resolverInputStatus = addresses.map(() => STATE.running);
+    const bulkResolutionGroup = {
+      addresses,
+      resolverInputStatus
+    };
+    bulkResolutionGroup.adgInputs = adgInputs;
+    bulkResolutionGroup.bulkResolver = getBulkAdgResolver(adgFn, adgInputs, this.onBulkResolutionStatus.bind(this, bulkResolutionGroup, action));
+    this.resolutionGroups.push(bulkResolutionGroup);
+    bulkResolutionGroup.bulkResolver.start();
+  }
+  /**
+   * StatusCallback to BulkResolver, invoked when resolver emits a new status.
+   * Updates the prefetchService's status if applicable.
+   * @param bulkResolutionGroup
+   * @param action InstrumentationContext
+   * @param status
+   */
+
+
+  onBulkResolutionStatus(bulkResolutionGroup, action, status) {
+    const state = status.status.getState();
+    const index = status.index;
+    const {
+      addresses
+    } = bulkResolutionGroup;
+
+    if (index >= 0 && index < addresses.length) {
+      bulkResolutionGroup.resolverInputStatus[index] = state;
+    } else {
+      this.onUnexpectedCondition(`Invalid index provided by resolver: ${index}`);
+      return;
+    }
+
+    if (bulkResolutionGroup.bulkResolver?.areAllResolversDone()) {
+      action.finishAction(false, {
+        userSchemaData: {
+          keyCount: addresses.length
+        }
+      });
+    }
+
+    switch (state) {
+      case STATE.done:
+        this.onResolutionDone(status, bulkResolutionGroup);
+        break;
+
+      case STATE.stopped:
+        // NOTE: Prefetch initiates stop, so this is a noop
+        break;
+
+      case STATE.running:
+        break;
+
+      default:
+        this.onUnexpectedCondition(`Unexpected resolution status: ${JSON.stringify(status)}`);
+    }
+  }
+  /**
+   * Stops all bulkResolvers
+   */
+
+
+  stop() {
+    if (this.state == STATE.stopped) {
+      return;
+    }
+
+    this.resolutionGroups.forEach(bulkResolutionContext => {
+      const {
+        bulkResolver
+      } = bulkResolutionContext;
+
+      if (bulkResolver) {
+        bulkResolver.stop();
+      }
+    });
+    this.updateState(STATE.stopped);
+  }
+  /**
+   * Called upon unexpected conditions that may indicate to the consumer that
+   * the prefetchService or its associated resolver is in an invalid state
+   * @param message
+   */
+
+
+  onUnexpectedCondition(message) {
+    // eslint-disable-next-line no-console
+    console.log(`Komaci/prefetch - error, message: ${message}`);
+
+    this._activity.error(message);
+
+    this.updateState(STATE.error, message);
+  }
+  /**
+   * Called when resolution for a given address has completed, or was otherwise
+   * rejected.
+   * @param address that is done
+   * @param state completed when resolved, or rejected when either no ADG exists, or resolver emitted an error with the given address
+   * @param reasons reasons for rejected status, if any
+   */
+
+
+  onAddressDone(address, state, reasons) {
+    const {
+      onAddressProcessed
+    } = this.config;
+    const status = {
+      state: state,
+      address,
+      reasons: reasons
+    };
+
+    try {
+      onAddressProcessed?.(status);
+    } catch (error) {
+      this.onUnexpectedCondition(error?.message);
+    }
+  }
+  /**
+   * Updates the current PrefetchState to done if every bulkResolver has emitted
+   * a non-running status for all inputs.
+   */
+
+
+  updateStateIfAllDone(bulkResolutionContext, status) {
+    const bulkContexts = this.resolutionGroups.values();
+    let allDone = true;
+
+    for (const context of bulkContexts) {
+      if (context.bulkResolver && !context.bulkResolver.areAllResolversDone()) {
+        allDone = false;
+        break;
+      }
+    }
+
+    if (allDone) {
+      if (this.adgMap.size > 0) {
+        // if all current runs are all done but with addresses left in the adgMap
+        // go process them
+        this.bulkResolveGuard();
+      } else {
+        // prefetch is done when allIdel and nothing left in adgMap
+        // eslint-disable-next-line no-console
+        console.log(`Komaci/prefetch - duration: ${Date.now() - this._startTime}, size: ${this._size}.`);
+
+        this._activity.stop(prefetchServiceSchema, {
+          addressCount: this._size,
+          startTime: this._startTime
+        });
+
+        this.updateState(STATE.done, status.status.getErrorMessages().join('\n'));
+        bulkResolutionContext.bulkResolver = undefined;
+      }
+    }
+  }
+  /**
+   * Called when resolver emits a "sink" state for an address or all addresses
+   * @param status
+   * @param bulkResolutionContext
+   */
+
+
+  onResolutionDone(status, bulkResolutionContext) {
+    const index = status.index;
+    const {
+      addresses
+    } = bulkResolutionContext;
+    const addressState = status.status.getErrorMessages().length !== 0 ? 'rejected' : 'completed';
+    const impactedAddress = addresses[index];
+    this.onAddressDone(impactedAddress, addressState, status.status.getErrorMessages());
+    this.updateStateIfAllDone(bulkResolutionContext, status);
+  }
+  /**
+   * Updates PrefetchState and notifies consumer via config.onStateChanged callback
+   * @param newState the new state
+   * @param [message] state message, if any
+   */
+
+
+  updateState(newState, message) {
+    const {
+      onStateChanged
+    } = this.config;
+    const abandoned = []; // TODO: Abandoned Not yet implemented
+
+    if (ValidStatusTransitions.isValid(this.state, newState)) {
+      this.state = newState;
+
+      try {
+        onStateChanged?.({
+          state: newState,
+          abandoned,
+          message
+        });
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.log(error?.message);
+      }
+    } else {
+      const errorMessage = `Komaci/prefetch - Invalid state transition from resovler. Resolver emitted state: ${newState} while prefetch is in ${this.state}`; // eslint-disable-next-line no-console
+
+      console.log(errorMessage);
+
+      this._activity.error(errorMessage, 'invalid-prefetch-state-transition');
+    }
+  }
+
+  getState() {
+    return this.state;
+  }
+
+}

package/build/modules/komaci/prefetchTypes/prefetchTypes.d.ts

@@ -0,0 +1,85 @@
+import type { PageReference } from 'lwr/router';
+import type { ResolverExecutionState, AdgInput, AdgModule, IBulkResolver } from '@komaci/resolver';
+import { InstrumentationContext } from 'o11y/dist/modules/o11y/client/interfaces';
+export declare const ERROR_PREFIX = "[komaci prefetch]";
+/**
+ * Routing result for each address
+ */
+export declare type AdgRoutingResult<TAddress = PageReference> = {
+    address: TAddress;
+    success: boolean;
+    adgModule?: AdgModule;
+    reason?: string;
+};
+/**
+ * Addresses mapped to the same ADG are grouped together. Each grouping is
+ * associated with a bulkResolver which may emit state for either all inputs, or
+ * a single input. This interface is used by the prefetch service to track the
+ * state of the input addresses, associated adgInputs, the bulkResolver and
+ * statuses for each input.
+ */
+export declare type AdgResolutionGroup<TAddress = PageReference> = {
+    addresses: TAddress[];
+    adgInputs?: AdgInput[];
+    bulkResolver?: IBulkResolver;
+    resolverInputStatus: ResolverExecutionState[];
+};
+export interface IPrefetchService {
+    stop(): void;
+}
+export declare enum ResolutionStatusState {
+    running = "running",
+    done = "done",
+    error = "error",
+    stopped = "stopped"
+}
+export declare enum PrefetchStatusStates {
+    init = "init",
+    done = "done",
+    running = "running",
+    stopped = "stopped",
+    error = "error"
+}
+export declare enum AddressStatusStates {
+    completed = "completed",
+    rejected = "rejected"
+}
+export declare type PrefetchState = `${PrefetchStatusStates}`;
+export declare type AddressState = `${AddressStatusStates}`;
+export declare type AddressStatus<TAddress = PageReference> = {
+    state: AddressState;
+    address: TAddress;
+    reasons?: string[];
+};
+export declare type PrefetchStatus<TAddress = PageReference> = {
+    state: PrefetchState;
+    abandoned?: TAddress[];
+    message?: string;
+};
+export declare type PrefetchConfig<TAddress = PageReference> = {
+    /**
+     * Callback method to receive status notifications related to prefetch, i.e. 'running', 'done', see PrefetchStatusStates
+     */
+    onStateChanged?: (status: PrefetchStatus<TAddress>) => void;
+    /**
+     * Callback method to receive status notifications related to address resolution, see AddressStatusStates
+     */
+    onAddressProcessed?: (status: AddressStatus<TAddress>) => void;
+    /**
+     * Callback method to download an image, given its URL, and return a Promise when finished
+     */
+    downloadImage?: (imageURL: string) => Promise<unknown>;
+    /**
+     * Config parameter to control number of concurrent page resolutions and AdgInputs to BulkResolver.
+     */
+    maxConcurrent?: number;
+    /**
+     * // o11y configuration, to ensure we can establish contexts for concurrent uses of o11y.
+     */
+    instrumentationContext?: InstrumentationContext;
+    /**
+     * High volume priming is a special feature which causes us to only resolve each unique AdgModule once, even if multiple addresses for the module are passed.
+     */
+    highVolumePriming?: boolean;
+};
+//# sourceMappingURL=prefetchTypes.d.ts.map

package/build/modules/komaci/prefetchTypes/prefetchTypes.js

@@ -0,0 +1,30 @@
+export const ERROR_PREFIX = '[komaci prefetch]';
+/**
+ * Routing result for each address
+ */
+
+export let ResolutionStatusState;
+
+(function (ResolutionStatusState) {
+  ResolutionStatusState["running"] = "running";
+  ResolutionStatusState["done"] = "done";
+  ResolutionStatusState["error"] = "error";
+  ResolutionStatusState["stopped"] = "stopped";
+})(ResolutionStatusState || (ResolutionStatusState = {}));
+
+export let PrefetchStatusStates;
+
+(function (PrefetchStatusStates) {
+  PrefetchStatusStates["init"] = "init";
+  PrefetchStatusStates["done"] = "done";
+  PrefetchStatusStates["running"] = "running";
+  PrefetchStatusStates["stopped"] = "stopped";
+  PrefetchStatusStates["error"] = "error";
+})(PrefetchStatusStates || (PrefetchStatusStates = {}));
+
+export let AddressStatusStates;
+
+(function (AddressStatusStates) {
+  AddressStatusStates["completed"] = "completed";
+  AddressStatusStates["rejected"] = "rejected";
+})(AddressStatusStates || (AddressStatusStates = {}));

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@komaci/prefetch",
+    "version": "240.1.3",
+    "description": "Komaci prefetch service.",
+    "homepage": "https://komaci.dev/",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/salesforce/komaci.git",
+        "directory": "packages/@komaci/prefetch"
+    },
+    "bugs": {
+        "url": "https://github.com/salesforce/komaci/issues"
+    },
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "type": "module",
+    "types": "build/modules/komaci/prefetchTypes/prefetchTypes.d.ts",
+    "main": "build/index.js",
+    "scripts": {
+        "build": "node ../../../bin/pack-ts --dir src/modules build/modules && tsc -b ./tsconfig.json"
+    },
+    "files": [
+        "build/**/*.js",
+        "build/**/*.d.ts"
+    ],
+    "dependencies": {
+        "@komaci/module-shared": "240.1.3",
+        "@komaci/resolver": "240.1.3",
+        "@lwrjs/router": "0.6.0-alpha.15",
+        "o11y": "^240.7.0",
+        "o11y_schema": "^240.11.0"
+    },
+    "devDependencies": {
+        "@komaci/types": "240.1.3",
+        "wait-for-expect": "^3.0.2"
+    }
+}