Skip to content

Firebase Realtime Database Library | For NodeJS server with FirebaseAdminSdk

Notifications You must be signed in to change notification settings

phamngocduy98/node_flashdata_library

Repository files navigation

FlashData - Realtime Database

npm GitHub Workflow Status npm node-lts (scoped) npm peer dependency version (scoped) GitHub package.json dependency version (prod)

npm i @phamngocduy98/flashdata

A realtime database library that making it easier to CRUD data with typescript

How to use

0. You need to know before using this library:

While realtime database stores data in a JSON tree. It can be structured by documents and collections like Firebase Firestore after flattening the data structure.
So, your data is now collections and documents :D

1. Define document type class

Define properties of your document by extending DocumentData class

import {DocumentData} from "@phamngocduy98/flashdata";

export class User extends DocumentData {
    name: string;
    avatarUrl: string;

    constructor(name: string, avatarUrl: string) {
        super();
        this.name = name;
        this.avatarUrl = avatarUrl;
    }
}

2. Define nested document:

If you have a Room that contains a State document:

export class Room extends DocumentData {
    @NestedDocument(State)
    state!: State;

    constructor(state: State) {
        super();
        this.state = state;
    }
}

3. Define collections:

For example, you have a root collection whose name is users Use @Collection decorator tells the library what is the type of collection's document.

import {Collection, Database, RealtimeCollection} from "@phamngocduy98/flashdata";
import {User} from "./";

export class MyDatabase extends Database {
    @Collection(User)
    users!: RealtimeCollection<User>;
}

Then you have subcollection, here is the example how to define a subcollection:

import {Collection, DocumentData} from "@phamngocduy98/flashdata";
import {Player} from "./Player";

export class State extends DocumentData {
    @Collection(Player)
    players!: Map<string, Player>;

    constructor(public roomId: string, players: Map<string, Player>) {
        super();
        this.players = players;
    }
}

Oh! Did you see the difference here?
Collection in Database is kept in type of RealtimeCollection while Subcollection in State document is stored as Map.
The library convert subcollection into map to make it easier to read data.

4. Define a Map:

Map is just a collection of primitives type instead of document. Here is example how to use it:

export class State extends DocumentData {
    @MapArray("number")
    setup!: Map<string, number>;
    constructor(setup: Map<string, number>) {
        super();
        this.setup = setup;
    }
}

5. CRUD

For example, you have a root rooms collection, a room contains a nested State document. Then inside State there is a subcollection players.

Create
let testRoomDoc: RealtimeDocument<Room> = await db.rooms.create(
    "test_room",
    new Room(
        new State(
            "111",
            new Map([
                ["1", 1],
                ["2", 2]
            ]),
            new Map<string, Player>([["duy1", new Player("duy1", "Duy", "avatar", true)]])
        )
    )
);
Read
testRoomDoc = await db.rooms.child("test_room");
let room: Room = await testRoomDoc.value();
console.log(room);
Nested document
let stateDoc: RealtimeDocument<State> = testRoomDoc.nested<State>("state")!;
let state: State = await stateDoc.value();
console.log(state);
Sub collection:
let players: RealtimeCollection<Player> = stateDoc.subCollection<Player>("players");
let playerDoc: RealtimeDocument<Player> = players.child("duy1"); // as Map
playerDoc = players.getAt(0); // use collection as Array (while document are sorted by id and id is increment overtime)
players.set("player1", new Player()); // set value of key player1
players.add(new Player()); // create using auto key id
let allPlayers: Map<string, Player> = await players.children(); // get all
players.clearCollection(); // delete all collection data
Map
let setup: RealtimeMap<number> = stateDoc.subMap("setup");
await setup.clear();
await setup.set("setup1", 2); // add (or overwrite) at key = "setup1" with value "2"
let setup1 = setup.get("setup1");
await setup.remove("setup1"); // remove a key

await setup.add(1); // add with auto ID (or use a an array)
let setup0 = setup.getAt(0); // if you use map as an array
await setup.removeAt(0); // remove if you use map as an array
Get a deep item from path:
playerDoc = db.getChild("rooms/test_room/state/players/duy1") as RealtimeDocument<Player>;
Get root / parent:
// get root:
playerDoc.root;
// get parent:
playerDoc.parent;
UPDATE:
testRoomDoc.update({
    state: {
        roomId: "222"
    }
});
DELETE:
testRoomDoc.delete();
SET:

overwrite (the same as delete() then update())

testRoomDoc.set(new Room());

Linking support like FlashStore

Coming soon in the next update.