npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@dl-tech/realtime-mongo-nestjs

v1.2.0

Published

NestJS Module to enable Realtime Database for MongoDB (@nestjs/mongoose)

Downloads

75

Readme

NestJS MongoDB Realtime Database

Inspired by FireStore, this package utilizes @nestjs/mongoose and Change Streams to create a similar experience to how FireBase Realtime database functions.

Utilizing WebSockets from socket.io for client connections, and for regular REST Crud Operations, exposes the REST API, for the client SDK to use.

Installation

@dl-tech/realtime-mongo-nestjs depends on several NestJS dependencies that should already be installed, as well as some additional NestJS packages.

Ensure NestJS is installed

See official docs

npm i @nestjs/core @nestjs/common rxjs reflect-metadata

Install NestJS Mongoose

See official docs

npm i @nestjs/mongoose mongoose

Install NestJS WebSockets (socket.io)

This is needed for clients to connect with WebSockets using NestJS.

See official docs

npm i @nestjs/websockets @nestjs/platform-socket.io

Install RealtimeMongoDB

npm i @dl-tech/realtime-mongo-nestjs

Ensure enableShutdownHooks() is enabled in main.ts. This ensures that the Change Stream connection can be gracefully closed.

// main.ts
import { NestFactory } from "@nestjs/core";
import { useContainer } from "class-validator";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.enableShutdownHooks();

  await app.listen(4000);
}
void bootstrap();

app.enableShutdownHooks();

Usage

import { RealtimeMongoModule } from '@dl-tech/realtime-mongo-nestjs';

@Module({
  imports: [
    RealtimeMongoModule.forRoot({
      enableRestApi: true,
      enableWebsocket: true,
    }),
  ],
})
export class AppModule {}

Listen to Change Events (Server-Side)

Using the @ChangeStreamListener() decorator will register this class to be called whenever a Change Stream is received.

This package does not listen to every event in MongoDB, the events that will be caught are Insert, Update, Replace, Delete.

import {
  ChangeStreamListener,
  RealtimeEventHandler,
  RealtimeMongoEvent,
} from "@dl-tech/realtime-mongo-nestjs";

@ChangeStreamListener()
export class DatabaseEventService extends RealtimeEventHandler {
  async onChangeEvent(data: RealtimeMongoEvent) {
    // Do something with data
  };
}

Authentication

Rest API endpoints resolved by the package can be protected using NestJS's APP_GUARD, see docs here. However, global guards are not applied to WebSockets in NestJS, and @UseGuards() in WebSockets only guard message channels, and not the socket.io handshake.

There are two methods to secure socket.io during the handshake. First is either extending @nestjs/websockets adapter, this will secure your websockets globally, and not only for the package. Second, you can provide REALTIME_GUARD anywhere in the app, and the module will use that to guard your socket handshake.

Method One

// app.module.ts
import { Module } from "@nestjs/common";
import { 
  REALTIME_GUARD,
  RealtimeModule,
} from "@dl-tech/realtime-mongo-nestjs";
import { APP_GUARD } from "@nestjs/core";
import { AppGuard } from "./app.guard";

@Module({
  imports: [
    RealtimeModule.forRoot({
      enableRestApi: true,
      enableWebsocket: true,
    }),
  ],
  providers: [
    {
      provide: APP_GUARD,
      useClass: AppGuard,
    },
    {
      provide: REALTIME_GUARD,
      useClass: AppGuard,
    },
  ],
})
export class AppModule {}
// app.guard.ts
import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
import { Socket } from "socket.io";
import {
  CanRealtimeActivate,
  isRealtimeDatabase,
} from "@dl-tech/realtime-mongo-nestjs";

@Injectable()
export class AppGuard implements CanActivate, CanRealtimeActivate {
  canActivate(context: ExecutionContext): boolean | Promise<boolean> {
    if (isRealtimeDatabase(context)) {
      // Do some Logic
    }
    return true;
  }

  canRealtimeActivate(socket: Socket): boolean | Promise<boolean> {
    // Do some Logic
    return true;
  }
}

Method Two

// websocket.adapter.ts
import { IoAdapter } from '@nestjs/platform-socket.io';
import { Server, ServerOptions, Socket } from 'socket.io';
import { Injectable } from '@nestjs/common';
import { HttpAdapterHost } from '@nestjs/core';

@Injectable()
export class WebSocketAdapter extends IoAdapter {
  constructor(private readonly httpInstance: HttpAdapterHost) {
    super(httpInstance.httpAdapter.getHttpServer());
  }

  create(port: number, options?: ServerOptions & { namespace?: string; server?: any }): Server {
    const server = super.create(port, options);

    server.use(async (socket: Socket, next) => {
      // Do Logic here
      const isAllowed = true;
      if (!isAllowed) {
        next(new Error('Unauthorized'));
        return;
      }

      next();
    });

    return server;
  }

  createIOServer(port: number, options?: any): any {
    return new Server(this.httpInstance.httpAdapter.getHttpServer(), options);
  }
}
// main.ts
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { WebSocketAdapter } from './websocket.adapter.ts';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.enableShutdownHooks();
  app.useWebSocketAdapter(new WebSocketAdapter());

  await app.listen(4000);
}

void bootstrap();

isRealtimeDatabase

This function will let you know whether the ExecutionContext is for the Realtime Database Controller. If needed you can preform additional logic depending on that.

// app.guard.ts
import { CanActivate, ExecutionContext, Injectable } from "@nestjs/common";
import { Socket } from "socket.io";
import { isRealtimeDatabase } from "@dl-tech/realtime-mongo-nestjs";

@Injectable()
export class AppGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean | Promise<boolean> {
    if (isRealtimeDatabase(context)) {
      // Do some Logic
    }
    return true;
  }
}

Authorization

Limit the resources the authenticated user has access to.

User Context

First we need to give the RealtimeModule as way to extract the user from the request. This is so it can extract the user information for you, and provide it ready when the rule is being invoked.

In an express server, or NestJS, it is popular to attach the user object to the request object. In your Auth Guard, or whatever implementation you are using to attach the user object to the request object, give that context to the realtime database.

import { Module } from "@nestjs/common";
import { RealtimeModule } from "@dl-tech/realtime-mongo-nestjs";
import { Request } from 'express';
import { Socket } from 'socket.io';
import { User } from './user.types';

const mockUser = {
  _id: "66e5036b6426de44d501d00d",
  first_name: "Dennis",
  last_name: "Lysenko",
  age: 6,
};

@Module({
  imports: [
    RealtimeModule.forRoot({
      // ...
      accessGuard: {
        extractUserRest: (req: Request) => req._user as User,
        extractUserWS: (socket: Socket) => socket.data._user as User,
      },
      // ...
    }),
  ],
})
export class AppModule {}

Defining Rules

To limit what resources users has access to, create a new provider, and apply the @RealtimeRule(modelType) decorator. Pass in the class used to create the @nestjs/mongoose Schema, and the Module will use this class as the access guard.

// user.rule.ts
import {
  RealtimeRule,
  RealtimeRuleGuard,
} from "@dl-tech/realtime-mongo-nestjs";
import { UserDocument, UserModel } from "./user/user.model";
import { User } from "./user/user.types";
import { FilterQuery } from "mongoose";
import { ObjectId } from "mongodb";

@RealtimeRule(UserModel)
export class UserRule extends RealtimeRuleGuard<User, UserDocument> {
  // No authenticated users can create a user
  canCreate(user: User | null): FilterQuery<UserDocument> | boolean {
    if (!user) return false;

    return false;
  }

  // Only authenticated user can read itself
  canRead(user: User | null): FilterQuery<UserDocument> | boolean {
    if (!user) return false;

    return {
      _id: new ObjectId(user._id),
    };
  }

  // Only authenticated user can update itself
  canUpdate(user: User | null): FilterQuery<UserDocument> | boolean {
    if (!user) return false;

    return {
      _id: new ObjectId(user._id),
    };
  }

  // No authenicated user can delete
  canDelete(user: User | null): boolean {
    return false;
  }
}

Ensure the class extends RealtimeRuleGuard. The first generic type will be the authenticated user type that you use around your app. The second generic type will be the MongoDB Document type. This is just to help with FilterQuery auto completion.

In the RealtimeRuleGuard class, there are four methods, canCreate, canRead, canUpdate, and canDelete. These methods will run right before a query is sent to mongodb, and validate the users authorization to the resource. Each function expects either a boolean or a FilterQuery type. If a boolean is returned, the Rest API or the WebSocket service, will throw Forbidden Exception immediately, however, if a filter query is provided this will be appended to the query the client provided. This in turn will force them to query only the documents you specify, and their additional filters, will be appended with the filter provided from the rule.

For example:

If your rule states that only authenticated users can update their own posts, it would look like this. Assuming that in the Posts model, there is an owner_id field.

@RealtimeRule(UserModel)
export class UserRule extends RealtimeRuleGuard<User, UserDocument> {
  // ...
  canUpdate(user: User | null): FilterQuery<PostDocument> | boolean {
    if (!user) return false;

    return {
      owner_id: new ObjectId(user._id)
    };
  }
  // ...
}

The client will make a request like so:

// The user making the request is user A
fetch({
  method: "POST",
  url: "database/findOneAndUpdate?modelName=Posts",
  headers: {
    // Your NestJS Authentication method, you handle this.
    Authorization: "Bearer ... user_id: A"
  },
  // Lets pretend someone makes a fraudulent request to steal a post.
  data: JSON.stringify({
    filter: {
      // Client is trying to update post from user B
      owner_id: "B",
      // ...
    },
    update: {
      owner_id: "A"
    }
  })
})

Once the request is made, and your server authenticates the user, and attaches the user to the request object, the rule is then invoked, and the final query to MonogDB will look like so:

db.posts.findOneAndUpdate(
   {
      owner_id: "B",
      $and: [
         { owner_id: "A" }
      ]
   },
   {
      owner_id: "A"
   }
)

The above query to the database, will result in nothing, since the server injected the filter from the rule. This is great, when you dont want the client to worry about what they are allowed to access.