MongoRealtime 🚀 #

A Dart package that allows you to listen in real-time to changes in a MongoDB database via a bridge with the Node.js package mongo-realtime.

[Banner]

Features #

• Listen to insert, update, delete, replace, drop events on MongoDB collections.
• Filter events by collection or specific document ID.
• Stream changes as Dart events.
• Easily manage multiple listeners.
• Lightweight and efficient.

Getting Started #

1. Install the Dart Package #

Add mongo_realtime to your pubspec.yaml or via:

dart pub add mongo_realtime

2. Set Up the Node.js Bridge (optional) #

This package relies on a Node.js bridge using mongo-realtime.

Install it with (on the server):

npm install mongo-realtime

Create a simple Node.js server:

const MongoRealtime = require("mongo-realtime");

// ...server initialization and db connection

// then init realtime with the same connection and server
MongoRealtime.init({
  uri: mongoose.connection,
  server: server,
});

Make sure your MongoDB instance is a replica set.

==IMPORTANT NOTE :== If your server is not using the mongo-reatime package, it should emit db events itself through a socket.

3. Use in Dart #

Basic usage

import 'package:mongo_realtime/mongo_realtime.dart';

void main() async {
  MongoRealtime.init("http://my_server:server_port", showLogs: false);

  // After calling init(), you can use MongoRealtime.instance or the getter 'realtime'

  final listener = MongoRealtime.instance.db().onChange(
    callback: (change) => print("Change: ${change.collection}"),
  );

  // connect to the server when autoConnect is false
  MongoRealtime.instance.connect(); // or realtime.connect();

  // Stop listening:
  listener.cancel();
}

See api overview for more details.

Using auth token

MongoRealtime.init(
  "http://my_server:server_port",
  token : "my_jwt_token", // or any string
  autoConnect: true, // default is false
  authData: {"role": "admin"}, // optional additional data
);

This will send the token to the server before connecting. The server can then verify it and accept or reject the connection.

Using multiple instances

final prodServer = MongoRealtime(
  "http://prod-server-url",
  onConnect: (s) {
    print("Connected to prod server");
  },
);
final devServer = MongoRealtime(
  "http://dev-server-url",
  onConnect: (s) {
    print("Connected to dev server");
  },
);

// Listen to changes
prodServer.col("users").onChange(
  callback: (change) => print("users changed on prod"),
);
devServer.col("posts").onChange(
  callback: (change) => print("posts changed on dev"),
);

Specific use cases

//  Listeners

realtime.col("users").doc("1234").onChange(types: [MongoChangeType.insert]); // when got a new user with id 1234

realtime.db(["notifications", "posts"]).onChange(types: [MongoChangeType.delete]); // when delete a notification or post

realtime.db().onChange(types: [MongoChangeType.drop]); // when drop any collection

realtime.listStreamMapped<String>(
  "usersWithName",
  fromMap: (doc) => doc["name"],
  filter: (value) {
    return value.toString().startsWith("A");
  })
.listen((s) => print(s)); // Stream of list of documents from "users" collection

Using streams instead of callback

void doSomething(change) {}
void doSomethingOnStream(change) {}

final listener = realtime.col(
  "notifications").onChange(
  types: [MongoChangeType.insert],
  callback: doSomething,
); //new notification

listener.stream.listen(doSomethingOnStream);

// Both functions will be called doSomething and doSomethingOnStream when changes

Listening to specific events

You can listen to any event (even db events or list stream events) on the socket juste like with socket.io

realtime.socket.on("custom-event", (data) {});
realtime.socket.on("db:update:users:1234", (data){}); // when user 1234 changes

API Overview #

• MongoRealtime.init(url,...): Connect to your bridge server.
• db(...) : Instance of MongoRealtimeDB.
• col(...) :Instance of MongoRealtimeCol.
• listStreamMapped<T>(...) : Stream of list of mapped objects from a collection.
• listStream(...) : Stream of list of documents from a collection.
• MongoRealtimeDB.col(...) : Same as MongoRealtimeDB.col(...).
• MongoRealtimeCol.doc(...) : Instance of MongoRealtimeDoc.
• MongoRealtimeDB.onChange(...): Listen to one or many collections.
• MongoRealtimeCol.onChange(...): Listen to a collection changes.
• MongoRealtimeDoc.onChange(...): Listen to doc changes.

Each listener provides:

• stream: A Stream<MongoChange>.
• cancel(): To remove the listener.

DB Events #

1st level : db:$operation_type

• db:change
• db:insert
• db:update
• db:delete
• db:drop
• db:replace
• db:invalidate

2nd level : $1st_level:$collection

• db:change:users
• db:insert:posts
• ...

3rd level : $2nd_level:$document_id

• db:update:users:XYZ
• db:delete:posts:229
• ...

List Stream Events #

• db:stream:{streamId}

License #

MIT License