Add Typescript type definitions for workbox-sw

[wessberg]

R: @jeffposnick @addyosmani @gauntface

Fixes #1410

This PR adds Typescript type definitions for workbox-sw and provides them from the types property of the package.json of that package.

The type declarations are complete and based on the reference docs.

Also, during linting, ESLint complained about a few invalid JSDoc comments in some other files, so I've also fixed those.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here (e.g. I signed it!) and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

[wessberg]

CLA has been signed

[googlebot]

CLAs look good, thanks!

[coveralls]

Coverage decreased (-0.2%) to 86.833% when pulling 09d2f7e on wessberg:master into 116a873 on GoogleChrome:master.

[prateekbh]

Also, just an fyi and to check if there is no collision between the two.

The TS for workbox generateSW options is here: Polymer/polymer-build#309

[wessberg]

@prateekbh There are no collisions between the two 😊. Your typings cover workbox-build whereas these strictly cover workbox-sw and related namespaces.

[arkhamvm]

It's will be great! Any news about adding?

[wessberg]

I added typings for streams such that the typings fully support v3.2.0

[josephliccini]

Awesome to see TypeScript support!!

Though, I think there might be a bug in these:

Shouldn't it be Promise<Response> | undefined, not Promise<Response | undefined>?

[josephliccini]

Also, it would be cool if we could get an interface for custom plugins to implement that would have the type checking enabled. It would basically enforce that any plugins are of this shape: https://developers.google.com/web/tools/workbox/guides/using-plugins#custom_plugins

[josephliccini]

Here are the plugin typings:

// Custom type for Officehome
declare interface WorkboxPlugin {
    readonly cacheWillUpdate?: (context: CacheWillUpdatePluginContext) => Response
    readonly cacheDidUpdate?: (context: CacheDidUpdatePluginContext) => void;
    readonly cachedResponseWillBeUsed?: (context: CacheResponseWillBeUsedPluginContext) => Response
    readonly requestWillFetch?: (context: RequestWillFetchPluginContext) => Request;
    readonly fetchDidFail?: (context: FetchDidFailPluginContext) => void;
};

interface CacheWillUpdatePluginContext {
    readonly request: Request;
    readonly response: Response;
}

interface CacheDidUpdatePluginContext {
    readonly cacheName: string;
    readonly request: Request;
    readonly oldResponse: Response;
    readonly newResponse: Response;
}

interface CacheResponseWillBeUsedPluginContext {
    readonly cacheName: string;
    readonly request: Request;
    readonly matchOptions: any; // <-- What should this be? `object`?
    readonly cachedResponse: Response;
}

interface RequestWillFetchPluginContext {
    readonly request: Request;
}

interface FetchDidFailPluginContext {
    readonly originalRequest: Request;
    readonly request: Request;
    readonly error: Error;
}

Also, had to modify this type:

type Plugin = BroadcastUpdatePlugin | RangeRequestsPlugin | CacheableResponsePlugin | BackgroundSyncPlugin | ExpirationPlugin | WorkboxPlugin;

[wessberg]

@josephliccini Yes, you're right. I fixed the signature of handleRequest. Thanks!

I also added typings for Custom Workbox Plugins (Exported as a named export). Thanks for your typings! I corrected them a little bit (cacheWillUpdate can return Response OR null, and cachedResponseWillBeUsed can return Response OR null)

[josephliccini]

Hey @wessberg looks like custom plugin callbacks that return values support returning Promises as well.

#1507

you can see it used in the source here:
https://github.com/GoogleChrome/workbox/blob/685e81673d5c190209137dcaf6871f9fd5d98ce5/packages/workbox-range-requests/Plugin.mjs

and for requestWillFetch:

workbox/packages/workbox-core/_private/fetchWrapper.mjs

Lines 65 to 67 in 49ec72a

	request = await plugin[pluginEvents.REQUEST_WILL_FETCH].call(plugin, {
	request: request.clone(),
	});

So looks like we should update typings for custom plugins to support Response, null, or Promise<Response | null>

[jeffposnick]

Hello @wessberg!

First off, apologies for the delay in acting on this PR.

After discussing it with the other current maintainers, we don't feel like we can commit to maintaining these typings over time. We appreciate the work you put into creating them to begin with, but stale typings seem inevitable as we make changes to the codebase given our lack of familiarity with TypeScript.

I'm familiar enough with TypeScript to know that some folks submit "unofficial" .d.ts entries to https://definitelytyped.org/, and if you're willing to, I'd encourage you to go that route. We'd be happy to add a badge to our docs linking to your submission for other developers who want to find them.

Would you be willing to go that route?

[wessberg]

@josephliccini, I've updated the typings to support returning Promise<Response> from cachedResponseWillBeUsed and cacheWillUpdate. Nice catch!

@jeffposnick, that is completely understandable 👍. I'll try to add the typings to DefinitelyTyped instead such that they can be installed from @types/workbox-sw.

[jeffposnick]

I'm going to close this PR in favor of the DefinitelyTyped approach.

Once there's something published that you want us to link to, pass along the URL.

[wessberg]

@jeffposnick, the typings have been published now!
Here's the URL: https://www.npmjs.com/package/@types/workbox-sw