Route/Handler TypeScript normalization

packages/workbox-core/src/types.ts

@@ -23,10 +23,10 @@ export type PluginState = MapLikeObject;
  * Options passed to a `RouteMatchCallback` function.
  */
 export interface RouteMatchCallbackOptions {
-  url: URL;
-  sameOrigin: boolean;
+  event: ExtendableEvent;
   request: Request;
-  event?: ExtendableEvent;
+  sameOrigin: boolean;
+  url: URL;
 }
 
 /**
@@ -48,12 +48,23 @@ export interface RouteMatchCallback {
  * Options passed to a `RouteHandlerCallback` function.
  */
 export interface RouteHandlerCallbackOptions {
-  request: Request | string;
-  url?: URL;
+  event: ExtendableEvent;
+  request: Request;
+  url: URL;
   params?: string[] | MapLikeObject;
+}
+
+/**
+ * Options passed to a `ManualHandlerCallback` function.
+ */
+export interface ManualHandlerCallbackOptions {
+  request: Request | string;
   event?: ExtendableEvent;
 }
 
+export type HandlerCallbackOptions =
+    RouteHandlerCallbackOptions | ManualHandlerCallbackOptions;
+
 /**
  * The "handler" callback is invoked whenever a `Router` matches a URL/Request
  * to a `Route` via its `RouteMatchCallback`. This handler callback should
@@ -66,6 +77,18 @@ export interface RouteHandlerCallback {
   (options: RouteHandlerCallbackOptions): Promise<Response>;
 }
 
+/**
+ * The "handler" callback is invoked whenever a `Router` matches a URL/Request
+ * to a `Route` via its `RouteMatchCallback`. This handler callback should
+ * return a `Promise` that resolves with a `Response`.
+ *
+ * If a non-empty array or object is returned by the `RouteMatchCallback` it
+ * will be passed in as this handler's `options.params` argument.
+ */
+export interface HandlerCallback {
+  (options: HandlerCallbackOptions): Promise<Response>;
+}
+
 /**
  * An object with a `handle` method of type `RouteHandlerCallback`.
  *
@@ -95,10 +118,10 @@ export interface HandlerWillStartCallback {
 
 export interface CacheDidUpdateCallbackParam {
   cacheName: string;
-  oldResponse?: Response | null;
   newResponse: Response;
   request: Request;
   event?: ExtendableEvent;
+  oldResponse?: Response | null;
   state?: PluginState;
 }
 
@@ -107,10 +130,10 @@ export interface CacheDidUpdateCallback {
 }
 
 export interface CacheKeyWillBeUsedCallbackParam {
-  request: Request;
   mode: string;
-  params?: any;
+  request: Request;
   event?: ExtendableEvent;
+  params?: any;
   state?: PluginState;
 }
 
@@ -119,8 +142,8 @@ export interface CacheKeyWillBeUsedCallback {
 }
 
 export interface CacheWillUpdateCallbackParam {
-  response: Response;
   request: Request;
+  response: Response;
   event?: ExtendableEvent;
   state?: PluginState;
 }
@@ -132,9 +155,9 @@ export interface CacheWillUpdateCallback {
 export interface CachedResponseWillBeUsedCallbackParam {
   cacheName: string;
   request: Request;
-  matchOptions?: CacheQueryOptions;
   cachedResponse?: Response;
   event?: ExtendableEvent;
+  matchOptions?: CacheQueryOptions;
   state?: PluginState;
 }
 
@@ -143,8 +166,8 @@ export interface CachedResponseWillBeUsedCallback {
 }
 
 export interface FetchDidFailCallbackParam {
-  originalRequest: Request;
   error: Error;
+  originalRequest: Request;
   request: Request;
   event?: ExtendableEvent;
   state?: PluginState;
@@ -188,8 +211,8 @@ export interface HandlerWillRespondCallback {
 
 export interface HandlerDidRespondCallbackParam {
   request: Request;
-  response?: Response;
   event?: ExtendableEvent;
+  response?: Response;
   state?: PluginState;
 }
 
@@ -199,9 +222,9 @@ export interface HandlerDidRespondCallback {
 
 export interface HandlerDidCompleteCallbackParam {
   request: Request;
-  response?: Response;
   error?: Error;
   event?: ExtendableEvent;
+  response?: Response;
   state?: PluginState;
 }
 
@@ -214,29 +237,29 @@ export interface HandlerDidCompleteCallback {
  * cache operations.
  */
 export interface WorkboxPlugin {
-  handlerWillStart?: HandlerWillStartCallback;
   cacheDidUpdate?: CacheDidUpdateCallback;
+  cachedResponseWillBeUsed?: CachedResponseWillBeUsedCallback;
   cacheKeyWillBeUsed?: CacheKeyWillBeUsedCallback;
   cacheWillUpdate?: CacheWillUpdateCallback;
-  cachedResponseWillBeUsed?: CachedResponseWillBeUsedCallback;
   fetchDidFail?: FetchDidFailCallback;
   fetchDidSucceed?: FetchDidSucceedCallback;
-  requestWillFetch?: RequestWillFetchCallback;
-  handlerWillRespond?: HandlerWillRespondCallback;
-  handlerDidRespond?: HandlerDidRespondCallback;
   handlerDidComplete?: HandlerDidCompleteCallback;
+  handlerDidRespond?: HandlerDidRespondCallback;
+  handlerWillRespond?: HandlerWillRespondCallback;
+  handlerWillStart?: HandlerWillStartCallback;
+  requestWillFetch?: RequestWillFetchCallback;
 }
 
 export interface WorkboxPluginCallbackParam {
-  handlerWillStart: HandlerWillStartCallbackParam;
   cacheDidUpdate: CacheDidUpdateCallbackParam;
+  cachedResponseWillBeUsed: CachedResponseWillBeUsedCallbackParam;
   cacheKeyWillBeUsed: CacheKeyWillBeUsedCallbackParam;
   cacheWillUpdate: CacheWillUpdateCallbackParam;
-  cachedResponseWillBeUsed: CachedResponseWillBeUsedCallbackParam;
   fetchDidFail: FetchDidFailCallbackParam;
   fetchDidSucceed: FetchDidSucceedCallbackParam;
-  requestWillFetch: RequestWillFetchCallbackParam;
-  handlerWillRespond: HandlerWillRespondCallbackParam;
-  handlerDidRespond: HandlerDidRespondCallbackParam;
   handlerDidComplete: HandlerDidCompleteCallbackParam;
+  handlerDidRespond: HandlerDidRespondCallbackParam;
+  handlerWillRespond: HandlerWillRespondCallbackParam;
+  handlerWillStart: HandlerWillStartCallbackParam;
+  requestWillFetch: RequestWillFetchCallbackParam;
 }

packages/workbox-routing/src/NavigationRoute.ts

@@ -8,8 +8,10 @@
 
 import {assert} from 'workbox-core/_private/assert.js';
 import {logger} from 'workbox-core/_private/logger.js';
+import {RouteHandler, RouteMatchCallbackOptions} from 'workbox-core/types.js';
+
 import {Route} from './Route.js';
-import {Handler, MatchCallbackOptions} from './_types.js';
+
 import './_version.js';
 
 export interface NavigationRouteMatchOptions {
@@ -55,7 +57,7 @@ class NavigationRoute extends Route {
    * match the URL's pathname and search parameter, the route will handle the
    * request (assuming the denylist doesn't match).
    */
-  constructor(handler: Handler,
+  constructor(handler: RouteHandler,
       {allowlist = [/./], denylist = []}: NavigationRouteMatchOptions = {}) {
     if (process.env.NODE_ENV !== 'production') {
       assert!.isArrayOfClass(allowlist, RegExp, {
@@ -72,7 +74,7 @@ class NavigationRoute extends Route {
       });
     }
 
-    super((options: MatchCallbackOptions) => this._match(options), handler);
+    super((options: RouteMatchCallbackOptions) => this._match(options), handler);
 
     this._allowlist = allowlist;
     this._denylist = denylist;
@@ -88,7 +90,7 @@ class NavigationRoute extends Route {
    *
    * @private
    */
-  private _match({url, request}: MatchCallbackOptions): boolean {
+  private _match({url, request}: RouteMatchCallbackOptions): boolean {
     if (request && request.mode !== 'navigate') {
       return false;
     }

packages/workbox-routing/src/RegExpRoute.ts

@@ -8,9 +8,12 @@
 
 import {assert} from 'workbox-core/_private/assert.js';
 import {logger} from 'workbox-core/_private/logger.js';
+import {RouteHandler, RouteMatchCallback, RouteMatchCallbackOptions}
+    from 'workbox-core/types.js';
+
 import {HTTPMethod} from './utils/constants.js';
 import {Route} from './Route.js';
-import {Handler, MatchCallbackOptions, MatchCallback} from './_types.js';
+
 import './_version.js';
 
 
@@ -41,7 +44,7 @@ class RegExpRoute extends Route {
    * @param {string} [method='GET'] The HTTP method to match the Route
    * against.
    */
-  constructor(regExp: RegExp, handler: Handler, method?: HTTPMethod) {
+  constructor(regExp: RegExp, handler: RouteHandler, method?: HTTPMethod) {
     if (process.env.NODE_ENV !== 'production') {
       assert!.isInstance(regExp, RegExp, {
         moduleName: 'workbox-routing',
@@ -51,7 +54,7 @@ class RegExpRoute extends Route {
       });
     }
 
-    const match: MatchCallback = ({url}: MatchCallbackOptions) => {
+    const match: RouteMatchCallback = ({url}: RouteMatchCallbackOptions) => {
       const result = regExp.exec(url.href);
 
       // Return immediately if there's no match.

packages/workbox-routing/src/Route.ts

@@ -9,7 +9,8 @@
 import {assert} from 'workbox-core/_private/assert.js';
 import {HTTPMethod, defaultMethod, validMethods} from './utils/constants.js';
 import {normalizeHandler} from './utils/normalizeHandler.js';
-import {Handler, HandlerObject, MatchCallback} from './_types.js';
+import {RouteHandler, RouteHandlerObject, RouteMatchCallback}
+    from 'workbox-core/types.js';
 import './_version.js';
 
 
@@ -23,8 +24,8 @@ import './_version.js';
  * @memberof module:workbox-routing
  */
 class Route {
-  handler: HandlerObject;
-  match: MatchCallback;
+  handler: RouteHandlerObject;
+  match: RouteMatchCallback;
   method: HTTPMethod;
 
   /**
@@ -39,8 +40,8 @@ class Route {
    * against.
    */
   constructor(
-      match: MatchCallback,
-      handler: Handler,
+      match: RouteMatchCallback,
+      handler: RouteHandler,
       method: HTTPMethod = defaultMethod) {
     if (process.env.NODE_ENV !== 'production') {
       assert!.isType(match, 'function', {

packages/workbox-routing/src/Router.ts

@@ -8,8 +8,12 @@
 
 import {assert} from 'workbox-core/_private/assert.js';
 import {getFriendlyURL} from 'workbox-core/_private/getFriendlyURL.js';
-import {Handler, HandlerObject, HandlerCallbackOptions, MatchCallbackOptions}
-    from './_types.js';
+import {
+  RouteHandler,
+  RouteHandlerObject,
+  RouteHandlerCallbackOptions,
+  RouteMatchCallbackOptions,
+} from 'workbox-core/types.js';
 import {HTTPMethod, defaultMethod} from './utils/constants.js';
 import {logger} from 'workbox-core/_private/logger.js';
 import {normalizeHandler} from './utils/normalizeHandler.js';
@@ -46,8 +50,8 @@ interface CacheURLsMessageData {
  */
 class Router {
   private readonly _routes: Map<HTTPMethod, Route[]>;
-  private readonly _defaultHandlerMap: Map<HTTPMethod, HandlerObject>;
-  private _catchHandler?: HandlerObject;
+  private readonly _defaultHandlerMap: Map<HTTPMethod, RouteHandlerObject>;
+  private _catchHandler?: RouteHandlerObject;
 
   /**
    * Initializes a new Router.
@@ -120,7 +124,7 @@ class Router {
           }
 
           const request = new Request(...entry);
-          return this.handleRequest({request});
+          return this.handleRequest({request, event});
 
         // TODO(philipwalton): TypeScript errors without this typecast for
         // some reason (probably a bug). The real type here should work but
@@ -142,17 +146,16 @@ class Router {
    * appropriate Route's handler.
    *
    * @param {Object} options
-   * @param {Request} options.request The request to handle (this is usually
-   *     from a fetch event, but it does not have to be).
-   * @param {FetchEvent} [options.event] The event that triggered the request,
-   *     if applicable.
+   * @param {Request} options.request The request to handle.
+   * @param {ExtendableEvent} options.event The event that triggered the
+   *     request.
    * @return {Promise<Response>|undefined} A promise is returned if a
    *     registered route can handle the request. If there is no matching
    *     route and there's no `defaultHandler`, `undefined` is returned.
    */
   handleRequest({request, event}: {
     request: Request;
-    event?: ExtendableEvent;
+    event: ExtendableEvent;
   }): Promise<Response> | undefined {
     if (process.env.NODE_ENV !== 'production') {
       assert!.isInstance(request, Request, {
@@ -272,8 +275,9 @@ class Router {
    *     They are populated if a matching route was found or `undefined`
    *     otherwise.
    */
-  findMatchingRoute({url, sameOrigin, request, event}: MatchCallbackOptions):
-      {route?: Route; params?: HandlerCallbackOptions['params']} {
+  findMatchingRoute(
+    {url, sameOrigin, request, event}: RouteMatchCallbackOptions):
+      {route?: Route; params?: RouteHandlerCallbackOptions['params']} {
     const routes = this._routes.get(request.method as HTTPMethod) || [];
     for (const route of routes) {
       let params;
@@ -317,7 +321,7 @@ class Router {
    * @param {string} [method='GET'] The HTTP method to associate with this
    * default handler. Each method has its own default.
    */
-  setDefaultHandler(handler: Handler, method: HTTPMethod = defaultMethod) {
+  setDefaultHandler(handler: RouteHandler, method: HTTPMethod = defaultMethod) {
     this._defaultHandlerMap.set(method, normalizeHandler(handler));
   }
 
@@ -328,7 +332,7 @@ class Router {
    * @param {module:workbox-routing~handlerCallback} handler A callback
    * function that returns a Promise resulting in a Response.
    */
-  setCatchHandler(handler: Handler) {
+  setCatchHandler(handler: RouteHandler) {
     this._catchHandler = normalizeHandler(handler);
   }
 

packages/workbox-routing/src/_types.ts

@@ -6,25 +6,8 @@
   https://opensource.org/licenses/MIT.
 */
 
-import {
-  RouteHandler,
-  RouteHandlerObject,
-  RouteHandlerCallback,
-  RouteHandlerCallbackOptions,
-  RouteMatchCallback,
-  RouteMatchCallbackOptions
-} from 'workbox-core/types.js';
 import './_version.js';
 
- export {
-  RouteHandler as Handler,
-  RouteHandlerObject as HandlerObject,
-  RouteHandlerCallback as HandlerCallback,
-  RouteHandlerCallbackOptions as HandlerCallbackOptions,
-  RouteMatchCallback as MatchCallback,
-  RouteMatchCallbackOptions as MatchCallbackOptions,
-}
-
 // * * * IMPORTANT! * * *
 // ------------------------------------------------------------------------- //
 // jdsoc type definitions cannot be declared above TypeScript definitions or