FirelordJS 烈火君JS

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:

1. find something better: 200 cups
2. created something better: 2000 cups.

The bounty has been available and keeps increasing since July 14, 2022.

(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:

Firelord compile time error:

It has all the regular rulings plus new composite rulings. See also peeling composite query error messages

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"
    }
}

(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:

1. (Default) Non ESM with import statements (Pseudo ESM)

2. ✅ works with create-react-app

3. ✅ works with @vitejs/plugin-react-swc
4. ✅ works with @sveltejs/vite-plugin-svelte
5. ✅ works with nextjs with next-transpile-modules

6. ❌ does not work with @sveltejs/kit/vite

7. Real ESM (Not available on NPM)

8. ✅ works with @vitejs/plugin-react-swc

9. ✅ works with @sveltejs/vite-plugin-svelte
10. ✅ works with nextjs with next-transpile-modules
11. ❌ does not work with create-react-app, see issue

12. ❌ does not work with @sveltejs/kit/vite see issue

13. CommonJS

14. ❌ does not work with create-react-app

15. ❌ does not work with @vitejs/plugin-react-swc
16. ❌ does not work with @sveltejs/vite-plugin-svelte
17. ✅ works with nextjs.
18. ✅ 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

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 longer unions type but an intersection type: {a:number} & {b:string}. This limitation is lifted to allow users to fully utilize discriminated unions. Plus in future update operation Mandatory Field could mitigate this problem.

• Mandatory field update. Example, for field like updatedAt, it is mandatory to includes it every time you update the document. There are two ways to implement these feature: via Meta Type and via abstraction. With Meta Type(using special field value), it is less flexible because we no longer able to exclude it from all update operations. With abstraction, it is more flexible but require more works from user. I prefer via abstraction due to it does not shut down other use cases despite having lower user experience.

• Support tuple data type.

• Replace set merge with upset(update if exists, else set). It will receive 1 doc ref argument and 2 data arguments(partial data and complete data). It will attempt to update the document with partial data or create a document with complete data if the document does not exist.

• More in code documentation and tests.

• Add support for V2 Firestore function triggers(for Firelord admin version only).

1. Bytes type is not working correctly and is unusable.
2. The rule You can use at most one array-contains or array-contains-any clause per query. You can't combine array-contains with array-contains-any is not enabled, see this release note
3. The type check of composite query (or() / and()) value is wrong if the field is __name__ of collection reference, example: query(collectionRef, or(where("__name__", "==", "id_only_not_full_path"))) result in false negative because Firelord will ask for full path but we only need full path if the reference is group collection.
4. Significant lag when trying to import anything from the library.

• The name Firelord is a reference to the Firelord of Avatar.
• Undocumented releases are README updates.
• Contributing.
• Documentation Github

We are creating the best type safety tool chains for Firebase, and your support helps us make them possible:

✅ - Tested and production ready
📅 - Planning
✍️ - To Rewrite
🔨 - To Repurpose (rewrite to do something else)
🔥 - Maintaining
🏗️ - Building
🛑 - On Hold
❓ - May Discontinue/Cancel
❌ - Cancelled

1. FirelordJS - Typescript wrapper for Firestore Web. ✅🔥
2. Firelord - Typescript wrapper for Firestore Admin. ✅🔥
3. FireSageJS - Typescript wrapper for Realtime Database Web ✅
4. FireSage - Typescript wrapper for Realtime Database Admin. 📅❓
5. FireSword - (new purpose) Firestore Zod Runtime Validation (Firelord Code First Approach).✅📅🔨
6. FireLaw - (new purpose) Firestore Security Rules VS Code extension type linter based on Firelord type.🛑📅🔨
7. ??? - Firelord and Firesage Front End Intergration 📅
8. FireCall - Helper Function to write easier and safer Firebase onCall function.✅✍️❓
9. Firelordrn - Typescript wrapper for Firestore React Native ❌(Expo support Firebase JS SDK, which mean you can use Firelord Web version)