feat: initial implementation of detect-changes module (#17)

 to subscribe database _changes feed, detect those affecting a report and triggering events

see #16

---------

Co-authored-by: Tom Winter <[email protected]>

.env

@@ -1,7 +1,9 @@
 SENTRY_DSN=
 PORT=
 DATABASE_URL=http://127.0.0.1:5984
-DATABASE_ADMIN=admin
+DATABASE_USER=admin
 DATABASE_PASSWORD=admin
 QUERY_URL=http://127.0.0.1:4984
 SCHEMA_CONFIG_ID=_design/sqlite:config
+REPORT_DATABASE_URL=http://127.0.0.1:5984
+REPORT_DATABASE_NAME=app

src/app.module.ts

@@ -6,6 +6,8 @@ import { ConfigModule, ConfigService } from '@nestjs/config';
 import { HttpModule } from '@nestjs/axios';
 import { ReportModule } from './report/report.module';
 import { ScheduleModule } from '@nestjs/schedule';
+import { ReportChangesModule } from './report-changes/report-changes.module';
+import { NotificationModule } from './notification/notification.module';
 
 const lowSeverityLevels: SeverityLevel[] = ['log', 'info'];
 
@@ -59,6 +61,8 @@ const lowSeverityLevels: SeverityLevel[] = ['log', 'info'];
       },
     }),
     ReportModule,
+    ReportChangesModule,
+    NotificationModule,
   ],
   controllers: [],
 })

src/couchdb/couch-db-client.service.ts

@@ -2,6 +2,7 @@ import { Injectable, Logger } from '@nestjs/common';
 import { catchError, map, Observable, of, switchMap } from 'rxjs';
 import { HttpService } from '@nestjs/axios';
 import { AxiosHeaders } from 'axios';
+import { CouchDbChangesResponse } from './dtos';
 
 @Injectable()
 export class CouchDbClient {
@@ -118,4 +119,25 @@ export class CouchDbClient {
   private handleError(err: any) {
     this.logger.debug(err);
   }
+
+  changes(
+    databaseUrl: string,
+    databaseName: string,
+    config?: any,
+  ): Observable<CouchDbChangesResponse> {
+    return this.httpService
+      .get<CouchDbChangesResponse>(
+        `${databaseUrl}/${databaseName}/_changes`,
+        config,
+      )
+      .pipe(
+        map((response) => {
+          return response.data;
+        }),
+        catchError((err) => {
+          this.handleError(err);
+          throw err;
+        }),
+      );
+  }
 }

src/couchdb/dtos.ts

@@ -26,3 +26,38 @@ export class FindResponse<T> {
 
   docs: T[];
 }
+
+/**
+ * Response from the CouchDB changes endpoint, listing database docs that have changed
+ * since the given last change (last_seq).
+ *
+ * see https://docs.couchdb.org/en/stable/api/database/changes.html
+ */
+export interface CouchDbChangesResponse {
+  /** Last change update sequence */
+  last_seq: string;
+
+  /** array of docs with changes */
+  results: CouchDbChangeResult[];
+
+  /** Count of remaining items in the feed */
+  pending: number;
+}
+
+/**
+ * A single result entry from a CouchDB changes feed,
+ * indicating one doc has changed.
+ *
+ * see https://docs.couchdb.org/en/stable/api/database/changes.html
+ */
+export interface CouchDbChangeResult {
+  /** _id of a doc with changes */
+  id: string;
+
+  /** List of document’s leaves with single field rev. */
+  changes: { rev: string }[];
+
+  seq: string;
+
+  doc?: any;
+}

src/domain/report-data-change-event.ts

@@ -0,0 +1,13 @@
+import { Reference } from './reference';
+import { ReportCalculation } from './report-calculation';
+
+/**
+ * Used as core that a report's calculated results have changed, due to updates in the underlying database.
+ */
+export interface ReportDataChangeEvent {
+  /** The report for which data has changed */
+  report: Reference;
+
+  /** The calculation containing the latest data after the change, ready to be fetched */
+  calculation: ReportCalculation;
+}