Types (Typescript) about firestore-jest-mock HOT 13 CLOSED

👋

Yeah, I think this is a major undertaking to do properly and the bandaid of just having types isn't sustainable given how big this library already is. It make sense to do a full port to TypeScript and cut that as a major release (v1.0.0). Then we can always backfill support if bugs are discovered for version 0.19.0

from firestore-jest-mock.

I agree very strongly! I created an API and a Frontend all written in Typescript. This is the only module so far, that I need to manually type now. Would be so awesome if you could add types to it.

from firestore-jest-mock.

I'm not a TypeScript expert and am still working on getting full parity firebase's API in this library. So, PRs are definitely welcome if someone wants to take this on.

from firestore-jest-mock.

I'm going a "quick" refactor into Typescript. It's not super clean, but I'll upload it to my fork this week and share it with the team here. If there is interest, we can clean it up and make it mainstream.

There are a couple of options. One is just to keep a ts definition file going. And the other is to rewrite the lib in Typescript completely. The second might be best as there is very little code that has to be modified. I am wrapping in my advancements to the Auth mocking that I added for my own projects that I think might be helpful for others as well.

from firestore-jest-mock.

@Brian-McBride I think a TS definition file is a good first step. We did this in another open-source library I maintain. Then, we can think about converting to TypeScript as a 1.0.0 release

from firestore-jest-mock.

Adding types shouldn't be terribly difficult. This isn't a particularly large codebase, and its internal types are complex enough that I would prefer just to port most things directly, rather than wait and just add declarations files. I've already done a lot of porting in #67 for your review.

from firestore-jest-mock.

Since I've already implemented most of the more complex typings in #67, this should be easy. However, a full TypeScript migration will be a multi-step process. I think the long-term benefits of a full migration are self-evident, so I'll start by describing my idea for how we might go about it.

My current plan to implement a TypeScript port is as follows:

1. [Done] Define a .d.ts file for each of our .js modules. This will involve minimal impact on the source code itself, as we're simply declaring in TypeScript syntax what we have already defined in JavaScript. This step will take place in several sequential pull requests so that we can thoroughly define and bikeshed both the way we name and share our internal types and the way users will consume our external types.
2. [#183] Establish a TypeScript build step. Currently, we only export our raw .js files in-place. Step 2 involves moving our code into a src/ directory, then running that code through the TypeScript compiler. Since JavaScript is valid TypeScript, our source code will not itself be affected. (EDIT: This is no longer a breaking change)
3. Combine our .js and .d.ts files into regular .ts files. This is the most involved part of the porting process, as it requires cannibalizing our existing source files and replacing them with new ones. This step should take place in multiple pull requests. It may also take considerably more time than the other steps, as other branches and forks which depend on our source code will have to migrate their own work similarly.

The first step alone should satisfy most users of this package in both JavaScript and TypeScript. While the last two steps are not strictly required for a JavaScript project, I believe their long-term benefits are well worth the work. I'm probably speaking to the choir here, but here is a small sampling of my thoughts, and why I'm so gung-ho about moving to TypeScript:

• A migration to TypeScript will force us and future contributors to respect our declared typings. JavaScript, even when run through the TypeScript compiler, is by default exempt from type checking. Our .d.ts files may easily become out of sync with our source code, leading to frustration for our users who expect this package to respect its own invariants.
• A full migration eliminates TypeErrors and ReferenceErrors almost entirely. These sorts of errors would be handled at compile-time before new builds of firestore-jest-mock are published to GitHub or NPM.
• Future work will be simple to grok because we would not need to consider separate type declarations and source definitions, as would be the case following Step 1. Type declarations and definitions are the same thing in TypeScript most of the time, just as we're used to in JavaScript.

If we're careful about how we go about this transition, I believe a full migration like this will go smoothly and be for the overall benefit of every user of firestore-jest-mock.

from firestore-jest-mock.

For those curious, #78 is waiting for review. Expect more PRs to come in the near future.

from firestore-jest-mock.

@Brian-McBride or @devbucket would you have time to review #78 as a first pass for types?

from firestore-jest-mock.

More phase-1 typings in #90.

from firestore-jest-mock.

#93 finishes basic types and should allow TypeScript users and VSCode Intellisense to consume correct typings for exported mock functions. (It also fixes a bug where TypeScript projects would fail to build if they tried to import mock functions because the index files didn't point to anything before #93. Sorry about that.)

from firestore-jest-mock.

Been a while 😅

Following up on a TypeScript port, there are several migration decisions to make which I should not be the one to make, since this project is not mine, and is currently in use in several projects. If someone else wants to take point on a TypeScript port between now and kingdom come, or before I finally get around to it, please do!

• Need to move source code somewhere that makes sense to a potential tsc config. Does the conventional src/ and lib/ architecture make sense here? (EDIT: #183 uses src/ and workspace root instead, to avoid breaking userspace import paths. We may consider a breaking change to compile into lib/ later on.)
• Userland imports would need to change to point to the compiled output, rather than the source. Or aliases need to be created to point at the appropriate source code. (EDIT: This breaking change is no longer necessary, per the previous point.)
• Probably other considerations, too.

from firestore-jest-mock.

Turns out it's easier than I thought to add a build step, so long as we aren't picky about where the build output goes. tsc is capable of taking a source directory and compiling that into a parent directory, so breaking userspace import paths might not be necessary for a basic TS port! (See #183)

from firestore-jest-mock.