Skip to content

Latest commit

 

History

History
189 lines (119 loc) · 10 KB

database.md

File metadata and controls

189 lines (119 loc) · 10 KB
Raw

FirebaseDatabaseLite Reference

Developer-facing classes included in the firebase_database_lite folder.

FirebaseDatabase class

The Firebase Database service interface.

Do not call this constructor directly. Instead, use firebase.database().

See Installation & Setup in JavaScript for a full guide on how to use the Firebase Database service.

Modules

ServerValue

Properties

Property Type (cast as) Description
app Node (FirebaseApp) The app associated with the FirebaseDatabase service instance.

Methods

Method Returns Typical usage
get_reference(<path>) FirebaseReference Returns a ref to the specified node in the database. WARNING: Not fully tested.
get_reference_lite(<path>) FirebaseReference Returns a ref to the specified node in the database. Limited support for array fakies.

You should always use get_reference_lite() instead of get_reference() if not using Firebase array fakies (and you shouldn't be using them). Array fakies are a headache to code for behind the scenes. If you do use array fakies, the lite version of this method still supports them somewhat (as whole objects) in case that fits your use case for them. Otherwise, the heavier version makes a good effort in supporting array fakies in all sorts of crazy ways... but testing it fully has exhausted me a bit too much for a feature I don't need. Too many edge cases.

Source JavaScript docs

Differences from the JavaScript SDK:

  • ref() renamed to get_reference(). (Similar to Java's getReference() and Unity's GetReference().)
  • This lite version does not implement all features.

FirebaseReference class

A FirebaseReference (ref) represents a specific location in your Realtime Database and can be used for reading or writing data to that Database location.

You can reference the root or child location in your Database by calling firebase.database().get_reference() or firebase.database().get_reference("child/path") (or get_reference_lite(<path>)).

Signals

Signal Passes Typical usage
"value_changed" FirebaseDataSnapshot Read and listen for changes to the entire contents of a path. The snapshot passed to the callback contains the entire contents with the updated data.
"child_added" FirebaseDataSnapshot Retrieve lists of items or listen for additions to a list of items. This event is triggered once for each existing child and then again every time a new child is added to the specified path. The callback is passed a snapshot containing the new child's data.
"child_changed" FirebaseDataSnapshot Listen for changes to the items in a list. This event is triggered any time a child node is modified. This includes any modifications to descendants of the child node. The snapshot passed to the callback contains the updated data for the child.
"child_removed" FirebaseDataSnapshot Listen for items being removed from a list. This event is triggered when an immediate child is removed. The snapshot passed to the callback contains the data for the removed child.

Properties

Property Type Description
key any (String or null) The last part of the ref's path.
path String The (read-only) path this ref points to.

Methods

🔻 = asynchronous. These should be called from inside a yield() in a linear procedure.

Method Returns (cast as) Typical usage
🔻fetch() any (FirebaseDataSnapshot or FirebaseError) Fetch a snapshot of all the data at the ref's path.
fetch_local() any (FirebaseDataSnapshot or FAILED) Return a deep copy of the current local copy of the listener's snapshot.
🔻push(<data>) any (FirebaseReference or FirebaseError) Add to a list of data (ref should point to a parent node of a list). Returns a new ref to a generated unique-key.
🔻put(data) any (any or FirebaseError) Write or replace data at the ref's path. Returns the data written.
🔻remove() any (OK or FirebaseError) Remove all data at the ref's path.
🔻update(data) any (any or FirebaseError) Update some of the keys at the ref's path without replacing all of the data. Accepts relative paths in the top-level key names. Returns the data written.
Method Returns Typical usage
disable_listener() void Turn off all listener signals.
🔻enable_listener() void Set up a realtime listener at the ref's path.

Listening to data changes

You can listen for data-change events by turning on a ref's listener:

ref.connect("child_added", self, "_do_something")
ref.connect("child_changed", self, "_do_something_else")
ref.connect("child_removed", self, "_do_something_elser")
ref.enable_listener()

Like shown above, you can skip the yield on enable_listener() if you don't need to wait for initial signaling to finish. Signals can be connected before or after enabling the listener, depending on your needs. Note that enabling a listener will trigger a "child_added" signal for each existing child, followed by a single "value_changed" signal. If you don't need these initial "child_added" signals, connect the "child_added" signal after enable_listener() has finished (by yielding it until "completed", or by connecting and waiting for that first "value_changed" signal).

Source JavaScript docs

Differences from the JavaScript SDK:

  • on() replaced with two methods: enable_listener() and GDScript's connect() to connect listener signals to methods. The signals do not pass a sibling key as a second argument because ordering is not supported in this lite version. There are no signals equivalent to the optional cancel callback yet (if ever).
  • off() replaced with two methods: disable_listener() and GDScript's disconnect() to disconnect listener signals from methods.
  • get() renamed to fetch(), as get is reserved by the Object base class.
  • set() renamed to put(), as set is reserved by the Object base class.
  • once() tabled due to confusion around it. Partly replaced by fetch_local(). May be added in some fashion eventually.
  • "value" signal renamed to "value_changed". (Similar to Java's onDataChange() and Unity's ValueChanged.)
  • path read-only property added.
  • This lite version does not implement all features.

FirebaseDataSnapshot class

A FirebaseDataSnapshot contains data from a Database location.

Any time you read data from the Database, you receive the data as a FirebaseDataSnapshot, such as with fetch(). A FirebaseDataSnapshot is passed to the event callbacks you attach with connect(). You can extract the contents of the snapshot by calling the value() method.

Modules

ServerValue

Properties

Property Type Description
key any (String or null) The last part of the ref's path.

Methods

Method Returns Typical usage
value() any Returns a deep copy of the snapshot. Depending on the data in the snapshot, the value() method may return a scalar type (string, number, or boolean), an array, or a dictionary. It may also return null, indicating that the snapshot is empty (contains no data).

Source JavaScript docs

Differences from the JavaScript SDK:

  • val() renamed to value(). (Similar to Java's getValue() and Unity's Value.)
  • This lite version does not implement all features.

ServerValue module

The FirebaseDatabase class contains the ServerValue property pointing to a static script resource. Usage looks like this:

yield(ref.put({"created_at": db.ServerValue.TIMESTAMP}), "completed")
yield(ref.update({"one_up": db.ServerValue.increment(1)}), "completed")

Constants

Constant Type Description
TIMESTAMP Dictionary A placeholder value for auto-populating the current timestamp (time since the Unix epoch, in milliseconds) as determined by the Firebase servers.

Functions

Method Returns Typical usage
increment(delta) Dictionary Returns a placeholder value that can be used to atomically increment the current database value by the provided delta.

Source JavaScript docs

Working with data offline

More robust Firebase SDKs write changes locally before sending to the remote database. Thus, if connection is lost, they will pool changes and make a best effort to send all pooled changes when they can. This package, however, has not yet gone to such efforts because it is a lot of work for a feature I don't need.

Instead, a local snapshot of data is only kept if you have enabled the listener on a DB reference point, and is updated only after changes are made to the remote and broadcast back to the listeners. Thus, the local copy is a best-effort representation of the remote copy. If you lose connection to the remote, you still have access to the local copy, but it won't update until connection is re-established. All this helps this lite package stay lite -- and also happens to be the round-trip paradigm I prefer.