FirelordJS 烈火君JS

             

FirelordJS

FirelordJS is the only library capable of providing insane type safety while exposing almost all the API of the official Firestore SDK. The goal is to end Firestore typing madness.

import {
    getFirelord,
    getFirestore,
    MetaTypeCreator,
    serverTimestamp,
    ServerTimestamp,
    setDoc,
    where,
    query,
    getDoc,
    Timestamp,
} from 'firelordjs'
import { initializeApp } from 'firebase/app'
type Example = MetaTypeCreator<
    {
        a: ServerTimestamp
    },
    'SomeCollectionName'
>
const app = initializeApp({ projectId: '### PROJECT ID ###' })
const db = getFirestore(app)
const example = getFirelord<Example>(db, 'SomeCollectionName')

// In write operation, Firelord does not convert ServerTimestamp
setDoc(example.doc('SomeDocName'), { a: serverTimestamp() })
// In query operation, Firelord converts ServerTimestamp to Timestamp | Date
query(example.collection(), where('a', '<', new Date()))
query(example.collection(), where('a', '<', Timestamp.now()))
// In read operation, Firelord converts ServerTimestamp to Timestamp
getDoc(example.doc('SomeDocName')).then(snapshot => {
    const data = snapshot.data()
    if (data) {
        const a = data.a // Timestamp
    }
})

FirelordJS:

• Learning curve is the lowest (API is nearly identical to the original API).
• 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 you want.
• 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 Type Conversion for complete list of type transformations.
• Package size is the smallest.
• Doesn't need code generation and schema language, just pure Typescript.
• Supports @firebase/rules-unit-testing and emulator, no extra API is needed!
• Is tested beyond source code, we also test built files and published package. (test source code -> build -> test built files -> publish -> test published)
• No mock test, all 250 tests test against live database to ensure the highest certainty.
• Takes care pesky runtime errors like empty array errors(filter & cursors) and implicit data deletion in update operation.
• Eliminates the repetitive tasks of writing collections ID and assigning the Firestore instance.
• Blocks undocumented errors and provides over 30 custom error messages to assist you in writing proper Firestore code! Here is an example:

FirelordJS is the only library capable of typing against Firestore limitations.

I am confident it has the best type safe and nothing come close. I put money on my words and I will buy you x cups of coffee if you:

1. found something better: 150 cups
2. created something better: 1500 cups (you don't need to a make full fledge library, something that is minimally better is enough, open an issue if you want to take this challenge)

Nested Composite Query Rulings (v2.5+)

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

NextJS TroubleShooting

Use FirelordJS in NextJS

TO DO

• 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.

• Proper way to test published package.

• More in code documentation and tests.

Dropped TO DO

• Support for wide numeric key and wide string key (Record<number, unknown> and Record<string, unknown>). It still needs more consideration because this data type is pointless to query(we need to know what the key is first, it would be better to just save the document ID somewhere) and we need to constantly aware of the document size limit. If you don't care about query and you sure that the size limit will not exceed 1 MB, then this is for you. But allowing this also open up for mistake and bad practice for those who are not aware. Most likely I will not implement this but will give it deeper thoughts in the future. (Update: This is implemented, see this issue)

• Support for object unions type. Objects unions type seem to be a good type to have in NoSQL database because of how ever-changing NoSQL schema is. However, this is not the case 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}. So I will not implement this feature and will remove it from FireSageJS too. A better way to solve this is to use PossiblyReadAsUndefined label on newly add field instead(you can also label abandoned fields as PossiblyReadAsUndefined, but an easier way is to totally ignore them).

• Support for optional (? modifier). Optional is a highly requested feature because of how common it is, however because of how Firestore works: it is impossible to query a missing field. Example: it is impossible to query user that has no phone number if phone number field does not exist. Because of this, it is important to make sure every field exists. You may not need the field now, but you may need it later plus adding default value is simple, especially with such powerful typing library like Firelord. So in order to not accidentally cripple your query in the future, I will not implement this feature. Yes, set merge basically lead to the same problem, hence I encourage you to use upset instead (will be available in the future).

• Narrow read type base on query constraint. For example where('a', '==', true) will narrow the read type of field a to true, it should be able to narrow down complex case like where('a.b.c', '==', { d:[{e:1}] }). Expected to support == comparator for all types and possibly != comparator for literal type(type filtering for!= comparator poses great complexity hence I may not work on it). Update: I decided to give this up because with the introduction of composite query, it will be extremely difficult to implement this. Plus unlike narrowing down write type, narrowing down the read type does not contribute to type safety, it just makes thing slightly simpler(skip exhaustive check).

Possible Architecture Changes in V3

Firelord follows a type-first approach, which means that every entity starts with a type. While this approach has its benefits, it can be seen as objectively inferior to a code-first approach since we can always infer types from code(with code-first approach), but not the other way around(with type-first approach). A good example of this is tools that build on top of zod, like trpc, which provides both validation and type inference, but this is not possible for Firelord.

Some may question why embedded validation is necessary for databases API, as they are not endpoints(where data validation usually takes place). However, Firestore is a database that directly interacts with clients. Therefore, it is necessary to have validation for triggers, as security rules may not always suffice and do not have type safe.

Type-first approach offers better developer experience, but it doesn't anything at runtime. On the other hand, the code-first approach may require some initial trade-offs in developer experience, but it can do everything.

Another alternative is code generation, keeping the original developer experience and generate zod validation for those working with triggers. I want to avoid code generation if possible, because our single source of truth now involving 2 steps(changing types and generating code), which can be a potential point of failure if we forget to generate code after changing types.

Trivial

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

Related Projects

1. Firelord - Typescript wrapper for Firestore Admin
2. FireSword - Filter Firestore and RTDB Unknown Keys.
3. FireCall - Helper Function to write easier and safer Firebase onCall function.
4. FireSageJS - Typescript wrapper for Realtime Database