FirelordJS
🔥High Precision Typescript Wrapper for Firestore Web, Providing Unparalleled Type Safe and Dev Experience
Install / Use
/learn @tylim88/FirelordJSREADME
V3
V3 will be a complete rewrite. Given Firebase’s ever-changing nature, I’m planning to remove rules-safety and focus solely on type-safety. Honestly, nobody cares about rules-safety — removing it will greatly simplify the library and make it much easier to maintain.
I’ll also drop the enforced best practices, taking a more liberal approach that lets users decide what works best for them.
The new API will follow a code-first approach, unlike the current type-first design — inspired by ElectroDB.
Due to limited manpower, there’s no ETA yet, but I’m aiming to finish it before 2026.
FirelordJS
FirelordJS is the only library capable of providing truly generic type safety while exposing almost all the API of the official Firestore SDK. The goal is to end Firestore typing madness.
Example of how Firelord transforms ServerTimestamp type in different operations:
FirelordJS:
- Lowest learning curve. API is nearly identical to the original API and simpler: Eliminates the repetitive tasks of writing collections ID and assigning the Firestore instance.
- Technical debt is the lowest (easy to revert to the official API).
- Minimum types creation and no type assertion.
- Offers truly generic type safe solutions, declare any data shape and unions.
- Supports deeply nested object type:
Record<string,Record<string,Record<string,...>>>, max 1000 levels. - Supports deeply nested sub collection, all children can track back all their ancestors type, max 100 generations.
- Generates all possible flatten paths combinations based on your declared type(e.g.:
a,a.b,a.b.c,a.b.d,a.x,a.x.y,a.x.z) with type safety. - Generates different types for different operations, see Transformative Types for complete list of type transformations.
- Package size is the smallest, 3 KB!
- Code generation and domain specific language are not required, just pure Typescript all the way.
- Supports @firebase/rules-unit-testing and emulator, no extra API is needed!
- Beyond source code testing, we also test built files and published package. (test source code -> build -> test built files -> publish -> test published files)
- No mock test, all 250 tests test against live database to ensure the highest certainty.
Firelord is the only library capable of typing against Firestore limitations. It also blocks undocumented errors and prevent pesky runtime errors like empty array errors filter, cursors and implicit data deletion in update operation. Firelord provides over 30 custom error messages to assist you in writing proper Firestore code! Here is an example:
<p align="center"> <img src="https://github.com/tylim88/FirelordJS/blob/main/img/custom.png?raw=true" alt="Example of how Firelord handles `ServerTimestamp` type in different operations" /> </p>Bounty
I am confident Firelord is the best among its kind in terms of best safety and developer experience. I stand behind my words, and I will buy you x cups of coffee if you:
- find something better: 300 cups
- created something better: 3000 cups.
The bounty has been available and keeps increasing since July 14, 2022.
Nested Composite Query Rulings
(Web feature only, admin can skip this section)
Rulings for or & and composite query are ready, rulings works with nested query, example:
Official SDK runtime error:
<p align="center"> <img src="https://github.com/tylim88/FirelordJS/blob/main/img/composite2.png?raw=true" alt="Example of how Firelord handles `ServerTimestamp` type in different operations" /> </p>Firelord compile time error:
<p align="center"> <img src="https://github.com/tylim88/FirelordJS/blob/main/img/composite1.png?raw=true" alt="Example of how Firelord handles `ServerTimestamp` type in different operations" /> </p>It has all the regular rulings plus new composite rulings. See also peeling composite query error messages
Eslint False Errors
Below ESLint rules give false error, please turn them off.
{
"rules": {
"@typescript-eslint/no-unsafe-assignment": "off",
"@typescript-eslint/no-unsafe-call": "off",
"@typescript-eslint/no-redundant-type-constituents": "off",
"@typescript-eslint/no-unsafe-return": "off",
"@typescript-eslint/no-unsafe-member-access": "off"
}
}
ESM? CommonJS?
(Web version's issue only, admin can skip this section)
FirelordJS built files are a bit complicated. It is not an ESM module(no "type":"module" in package.json) but it also does not transpile import statements to CommonJS.
Results tested with various build tools:
- (Default) Non ESM with
importstatements (Pseudo ESM)
- ✅ works with
create-react-app - ✅ works with
@vitejs/plugin-react-swc - ✅ works with
@sveltejs/vite-plugin-svelte - ✅ works with
nextjswithnext-transpile-modules - ❌ does not work with
@sveltejs/kit/vite
- Real ESM (Not available on NPM)
- ✅ works with
@vitejs/plugin-react-swc - ✅ works with
@sveltejs/vite-plugin-svelte - ✅ works with
nextjswithnext-transpile-modules - ❌ does not work with
create-react-app, see issue - ❌ does not work with
@sveltejs/kit/vitesee issue
- CommonJS
- ❌ does not work with
create-react-app - ❌ does not work with
@vitejs/plugin-react-swc - ❌ does not work with
@sveltejs/vite-plugin-svelte - ✅ works with
nextjs. - ✅ works with
@sveltejs/kit/vite
Using CommonJS Firelord with Firebase v9.17.0 and beyond break most of the build tools because of this Firebase issue
Pseudo ESM has the highest compatibility which is why it is the default package.
If you see cannot use import statement outside a module error, please install the CommonJS version with
npm i firelordjs@cjs
Types That You Need To Pay Attention To
These are types that are supported but be careful when using them. They are not limitations, but how things work.
Record<string, something> Support
By design Firelord banned mapped type, this was until version 2.5.10. To understand why mapped was banned in the first place and why it is possible now, see this issue. In short, querying mapped type requires extra information, make sure you know what you are doing.
Object Unions Type
Object unions type was banned before v2.6.2 because it brings uncertainty that cannot be handled reasonably. For example, with {a:number}|{b:string}, you can set {a:1} then update {b:"x"}, in this case the type is no long
