voznik / ngx-odm

Angular 14+ wrapper for RxDB

@ngx-odm/rxdb

Angular 10+ wrapper for RxDB - A realtime Database for the Web

Demo

demo - based on TodoMVC

Table of contents

• @ngx-odm/rxdb
  • Demo
  • Table of contents
  • General info
  • Technologies
  • Install
  • Usage
    • In your AppModule
    • In your FeatureModule
    • In your FeatureService
  • Features
  • Diagrams
  • Status
  • Inspiration
  • Contact

General info

If you don't want to setup RxDB manually in your next Angular project - just import NgxRxdbModule

Technologies

RxDB	Angular 10+

Install

npm install @ngx-odm/rxdb

Usage

In your AppModule

@NgModule({
  imports: [
    // ... other imports
    // ...
    NgxRxdbModule.forRoot({
      // optional, NgxRxdbConfig extends RxDatabaseCreator, will be merged with default config
      name: 'ngx',                        // <- name (required, 'ngx')
      adapter: 'idb',                     // <- storage-adapter (required, default: 'idb')
      password: '123456789',              // <- password (optional)
      multiInstance: true,                // <- multiInstance (optional, default: true)
      queryChangeDetection: false,        // <- queryChangeDetection (optional, default: false)
      options: {                          // NgxRxdb options (optional)
        schemas: [ ...CollectionConfigs], // array of NgxRxdbCollectionConfig (optional)
        dumpPath: 'assets/dump.json'      // path to datbase dump file (optional)
      }
    }),
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

In your FeatureModule

Schemas define how your data looks. Which field should be used as primary, which fields should be used as indexes and what should be encrypted. The schema also validates that every inserted document of your collections conforms to the schema. Every collection has its own schema. With RxDB, schemas are defined with the jsonschema-standard which you might know from other projects. https://rxdb.info/rx-schema.html

// create or import your schema
const todoSchema: RxSchema = require('../../../assets/data/todo.schema.json');
// create config
// NgxRxdbCollectionConfig extends RxCollectionCreator
const todoCollectionConfig: NgxRxdbCollectionConfig = {
  name: 'todo',                           // <- name (required)
  schema: todoSchema,                     // <- name (required)
  statics: {},                            // <- collection methods (optional)
  methods: {},                            // <- instance-methods methods (optional)
  options: {
    initialDocs: [] // docs to be imported into empty collection (optional)
  }
};

@NgModule({
  imports: [
    // ... other imports
    NgxRxdbModule.forFeature(todoCollectionConfig),
  ],
  // declarations
  // providers
})
export class TodosModule {}

In your FeatureService

@Injectable()
export class TodosService {
  // store & get filter as property of a `local` document
  filter$ = this.collectionService
    .getLocal('local', 'filterValue')
    .pipe(startWith('ALL'), distinctUntilChanged());
  // get count of documents in collection as observable (use fast calculation with static colection method)
  count$ = this.collectionService.count();

  constructor(private collectionService: NgxRxdbCollectionService<Todo>) {}
  // get documents from collection as observable using `RxQuery` mango-queries
  selectTodos(): Observable<Todo[]> {
    return this.filter$.pipe(
      switchMap(filterValue => {
        const queryObj = {
          selector: {
            createdAt: {
              $gt: null,
            },
            completed: filterValue === 'COMPLETED',
          },
          sort: [{ createdAt: 'desc' } as any],
        };
        return this.collectionService.docs(queryObj);
      })
    );
  }

  // add new document
  add(name: string): void {
    const payload: Todo = { guid: uuid(), name, done: false, dateCreated: Date.now() };
    this.collectionService.insert(payload);
  }

  // update prop od existing document
  toggle(guid: string, done: boolean): void {
    this.collectionService.update(guid, { done });
  }

  // use `bulk` to delete all dcouments by qeury
  removeDoneTodos(): void {
    const rulesObject = { done: { $eq: true } };
    this.collectionService.removeBulkBy(rulesObject);
  }
  // ...
}

Features

By using this module you can

• Automatically initialize db with settings, optionally provide db dumb to pre-fill with collections & documents
• Automatically initialize RxCollection for each lazy-loaded Feature module with config
• Work straight with db.collection or via NgxRxdbCollectionService wrapper with some helper methods

To-do list:

• Enable sync
• ...

Diagrams

NgxRxdbModule Initialization UML

NgxRxdbModule Initialization UML

Status

Project is: in progress

Inspiration

Project inspired by

• rxdb-angular2-example
• Angular NgRx Material Starter
• The Angular Library Series from Angular In Depth

Contact

Created by @voznik - feel free to contact me!