feat: attachments example

examples/demo/src/app/app.module.ts

@@ -4,6 +4,8 @@ import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
 import { RouterModule, Routes } from '@angular/router';
 import { NgxRxdbModule } from '@ngx-odm/rxdb';
 import { getRxDatabaseCreator } from '@ngx-odm/rxdb/config';
+import { RxDBAttachmentsPlugin } from 'rxdb/plugins/attachments';
+import { RxDBLeaderElectionPlugin } from 'rxdb/plugins/leader-election';
 import { AppComponent } from './app.component';
 
 const routes: Routes = [
@@ -27,10 +29,15 @@ const routes: Routes = [
  NgxRxdbModule.forRoot(
  getRxDatabaseCreator({
  name: 'demo',
- localDocuments: true,
+ localDocuments: false,
  multiInstance: true,
  ignoreDuplicate: false,
  options: {
+ plugins: [
+ // will be loaded by together with core plugins
+ RxDBAttachmentsPlugin,
+ RxDBLeaderElectionPlugin,
+ ],
  storageType: localStorage['_ngx_rxdb_storage'] ?? 'dexie',
  dumpPath: 'assets/data/db.dump.json',
  },

examples/demo/src/app/todos/todos.component.html

@@ -31,6 +31,7 @@ <h1>todos</h1>
  <li
  *ngFor="let todo of $.todos | byStatus: $.filter; trackBy: trackByFn"
  [class.completed]="todo.completed"
+ (contextmenu)="showContextMenu($event, todo)"
  >
  <div class="view">
  <input
@@ -106,3 +107,37 @@ <h1>todos</h1>
  </button>
  </footer>
 </section>
+
+<dialog [open]="isDialogOpen">
+ Attachments:
+ <ul *ngIf="selectedTodo?._attachments">
+ <li *ngFor="let attachment of selectedTodo._attachments | keyvalue">
+ <a
+ href="javascript:void(0);"
+ (click)="todosService.downloadAttachment(selectedTodo.id, attachment.key)"
+ >
+ {{ attachment.key }} - {{ attachment.value.type }}
+ </a>
+ &nbsp;
+ <button
+ type="button"
+ (click)="todosService.removeAttachment(selectedTodo.id, attachment.key)"
+ >
+ ❌
+ </button>
+ </li>
+ </ul>
+ <form method="dialog" (ngSubmit)="selectedTodo = undefined; isDialogOpen = false">
+ <button type="button" (click)="fileInput.click()">Upload txt attachment</button>
+ <input
+ type="file"
+ accept=".txt"
+ #fileInput
+ style="display: none"
+ (change)="
+ todosService.uploadAttachment(selectedTodo.id, $any($event.target).files[0])
+ "
+ />
+ <button>OK</button>
+ </form>
+</dialog>

examples/demo/src/app/todos/todos.component.ts

@@ -42,7 +42,17 @@ export class TodosComponent {
  );
  count$ = this.todosService.count$;
 
+ isDialogOpen = false;
+ selectedTodo: Todo = undefined;
+
  trackByFn = (index: number, item: Todo) => {
  return item.last_modified;
  };
+
+ showContextMenu(event: Event, todo: Todo) {
+ event.preventDefault();
+ this.selectedTodo = todo;
+ this.isDialogOpen = true;
+ console.log('showContextMenu', todo);
+ }
 }

examples/demo/src/app/todos/todos.model.ts

@@ -4,6 +4,7 @@ export interface Todo {
  completed: boolean;
  createdAt: string;
  last_modified: number;
+ _attachments?: any[];
 }
 
 export type TodosFilter = 'ALL' | 'COMPLETED' | 'ACTIVE';

examples/demo/src/app/todos/todos.service.ts

@@ -2,11 +2,13 @@
 import { Injectable, inject } from '@angular/core';
 import { NgxRxdbCollection, NgxRxdbCollectionService } from '@ngx-odm/rxdb/collection';
 import { DEFAULT_LOCAL_DOCUMENT_ID } from '@ngx-odm/rxdb/config';
-import type { RxDatabaseCreator } from 'rxdb';
+import { RxAttachment, type RxDatabaseCreator } from 'rxdb';
 import { Observable, distinctUntilChanged, startWith } from 'rxjs';
 import { v4 as uuid } from 'uuid';
 import { Todo, TodosFilter, TodosLocalState } from './todos.model';
 
+const withAttachments = true;
+
 @Injectable()
 export class TodosService {
  private collectionService: NgxRxdbCollection<Todo> = inject<NgxRxdbCollection<Todo>>(
@@ -22,7 +24,8 @@ export class TodosService {
  count$ = this.collectionService.count();
 
  todos$: Observable<Todo[]> = this.collectionService.docs(
- this.collectionService.queryParams$
+ this.collectionService.queryParams$,
+ withAttachments
  );
 
  get dbOptions(): Readonly<RxDatabaseCreator> {
@@ -107,4 +110,27 @@ export class TodosService {
  filter
  );
  }
+
+ async uploadAttachment(id: string, file: File) {
+ await this.collectionService.putAttachment(id, {
+ id: file.name, // (string) name of the attachment
+ data: file, // createBlob('meowmeow', 'text/plain'), // (string|Blob) data of the attachment
+ type: 'text/plain', // (string) type of the attachment-data like 'image/jpeg'
+ });
+ }
+
+ async downloadAttachment(id: string, a_id: string) {
+ const data = await this.collectionService.getAttachmentById(id, a_id);
+ const url = URL.createObjectURL(data);
+ const a = document.createElement('a');
+ a.href = url;
+ a.download = a_id;
+ document.body.appendChild(a);
+ a.click();
+ document.body.removeChild(a);
+ }
+
+ async removeAttachment(id: string, a_id: string) {
+ await this.collectionService.removeAttachment(id, a_id);
+ }
 }

examples/demo/src/assets/data/todo.schema.json

@@ -35,5 +35,8 @@
  }
  },
  "__indexes": ["createdAt"],
- "primaryKey": "id"
+ "primaryKey": "id",
+ "attachments": {
+ "encrypted": false
+ }
 }

examples/standalone/src/app/app.config.ts

@@ -5,6 +5,8 @@ import { provideAnimationsAsync } from '@angular/platform-browser/animations/asy
 import { provideRouter, withRouterConfig } from '@angular/router';
 import { provideRxDatabase } from '@ngx-odm/rxdb';
 import { getRxDatabaseCreator } from '@ngx-odm/rxdb/config';
+import { RxDBAttachmentsPlugin } from 'rxdb/plugins/attachments';
+import { RxDBLeaderElectionPlugin } from 'rxdb/plugins/leader-election';
 import { appRoutes } from './app.routes';
 
 export const appConfig: ApplicationConfig = {
@@ -21,6 +23,11 @@ export const appConfig: ApplicationConfig = {
  ignoreDuplicate: false,
  // storage: getRxStorageDexie(), // INFO: can be ommited, will be provide by `storageType` string
  options: {
+ plugins: [
+ // will be loaded by together with core plugins
+ RxDBAttachmentsPlugin,
+ RxDBLeaderElectionPlugin,
+ ],
  storageType: localStorage['_ngx_rxdb_storage'] ?? 'dexie',
  dumpPath: 'assets/data/db.dump.json',
  },

packages/rxdb/collection/src/lib/rxdb-collection.service.ts

@@ -25,6 +25,8 @@ import {
  type RxLocalDocument,
  type RxStorageWriteError,
  type RxCollection as _RxCollection,
+ RxAttachment,
+ RxAttachmentCreator,
 } from 'rxdb';
 import { RxReplicationState } from 'rxdb/plugins/replication';
 import {
@@ -367,6 +369,51 @@ export class NgxRxdbCollection<T extends Entity = { id: EntityId }> {
  return this.collection.remove();
  }
 
+ async getAttachments(docId: string): Promise<Blob[] | null> {
+ await this.ensureCollection();
+ const doc = await this.collection.findOne(docId).exec();
+ if (!doc) {
+ return null;
+ }
+ const attachmentsData = doc.allAttachments().map(a => a.getData());
+ return Promise.all(attachmentsData);
+ }
+
+ async getAttachmentById(docId: string, attachmentId: string): Promise<Blob | null> {
+ await this.ensureCollection();
+ const doc = await this.collection.findOne(docId).exec();
+ if (!doc) {
+ return null;
+ }
+ const attachment = doc.getAttachment(attachmentId);
+ if (!attachment) {
+ return null;
+ }
+ return attachment.getData();
+ }
+
+ async putAttachment(docId: string, attachment: RxAttachmentCreator): Promise<void> {
+ await this.ensureCollection();
+ const doc = await this.collection.findOne(docId).exec();
+ if (!doc) {
+ throw new Error(`Document with id "${docId}" not found.`);
+ }
+ await doc.putAttachment(attachment);
+ }
+
+ async removeAttachment(docId: string, attachmentId: string): Promise<void> {
+ await this.ensureCollection();
+ const doc = await this.collection.findOne(docId).exec();
+ if (!doc) {
+ throw new Error(`Document with id "${docId}" not found.`);
+ }
+ const attachment = doc.getAttachment(attachmentId);
+ if (!attachment) {
+ throw new Error(`Attachment with id "${attachmentId}" not found.`);
+ }
+ await attachment.remove();
+ }
+
  /**
  * Add one of RxDB-supported middleware-hooks to current collection, e.g run smth on document postSave.
  * By default runs in series

packages/rxdb/config/src/lib/rxdb.config.ts

@@ -8,6 +8,7 @@ import type {
  RxCollectionCreator,
  RxDatabaseCreator,
  RxJsonSchema,
+ RxPlugin,
 } from 'rxdb';
 import { RxReplicationState } from 'rxdb/plugins/replication';
 import { getRxStorageDexie } from 'rxdb/plugins/storage-dexie';
@@ -102,6 +103,7 @@ interface NgxRxdbConfigOptions {
  storageOptions?: {};
  dumpPath?: string;
  useQueryParams?: boolean;
+ plugins?: RxPlugin[];
 }
 
 type RxDatabaseCreatorPartialStorage = SetOptional<RxDatabaseCreator, 'storage'>;
@@ -134,6 +136,7 @@ export function getRxDatabaseCreator(config: NgxRxdbConfig): RxDatabaseCreator {
  const dbConfig: RxDatabaseCreator = {
  name,
  storage,
+ options,
  ...rest,
  };
  return dbConfig;

packages/rxdb/core/src/lib/rxdb-plugin.loader.ts

@@ -1,31 +1,35 @@
 import { isDevMode } from '@angular/core';
 import { RxDBPUseQueryParamsPlugin } from '@ngx-odm/rxdb/query-params';
 import { NgxRxdbUtils } from '@ngx-odm/rxdb/utils';
-import { addRxPlugin } from 'rxdb';
+import { RxPlugin, addRxPlugin } from 'rxdb';
 import { RxDBCleanupPlugin } from 'rxdb/plugins/cleanup';
 import { RxDBJsonDumpPlugin } from 'rxdb/plugins/json-dump';
-import { RxDBLeaderElectionPlugin } from 'rxdb/plugins/leader-election';
 import { RxDBLocalDocumentsPlugin } from 'rxdb/plugins/local-documents';
 import { RxDBMigrationPlugin } from 'rxdb/plugins/migration-schema';
 import { RxDBUpdatePlugin } from 'rxdb/plugins/update';
 import { RxDBPreparePlugin } from './rxdb-prepare.plugin';
 
 /**
- * Loads all the necessary RxDB plugins for the application to work.
+ * Loads all the necessary and additional RxDB plugins for the application to work.
+ * @param plugins
  * @returns A Promise that resolves when all the plugins have been loaded.
  * @throws If there was an error loading the plugins.
  */
-export async function loadRxDBPlugins(): Promise<void> {
+export async function loadRxDBPlugins(plugins: RxPlugin[] = []): Promise<void> {
  try {
- // plugins
+ // vendor
  addRxPlugin(RxDBLocalDocumentsPlugin);
- addRxPlugin(RxDBLeaderElectionPlugin);
  addRxPlugin(RxDBJsonDumpPlugin);
  addRxPlugin(RxDBMigrationPlugin);
  addRxPlugin(RxDBUpdatePlugin);
+ addRxPlugin(RxDBCleanupPlugin);
+ // custom
  addRxPlugin(RxDBPreparePlugin);
  addRxPlugin(RxDBPUseQueryParamsPlugin);
- addRxPlugin(RxDBCleanupPlugin);
+ // additional plugins
+ for (const plugin of plugins) {
+ addRxPlugin(plugin);
+ }
 
  /** * to reduce the build-size, we use some plugins in dev-mode only */
  if (isDevMode() && !NgxRxdbUtils.isTestEnvironment()) {

packages/rxdb/core/src/lib/rxdb.service.ts

@@ -51,7 +51,7 @@ export class NgxRxdbService {
  */
  async initDb(config: RxDatabaseCreator): Promise<void> {
  try {
- await loadRxDBPlugins();
+ await loadRxDBPlugins(config.options?.plugins);
  this.dbInstance = await createRxDatabase(config).catch(e => {
  throw new Error(e.message ?? e);
  });

packages/rxdb/utils/src/lib/utils.ts

@@ -74,8 +74,7 @@ export namespace NgxRxdbUtils {
  *
  * Differences from lodash:
  * - does not give any special consideration for arguments objects, strings, or prototype objects (e.g. many will have `'length'` in the returned array)
- *
- * @internal
+ * @param object
  */
  export function keys<T>(object: Nil | T): Array<StringifiedKey<T>> {
  let val = keysOfNonArray(object);

tsconfig.base.json

@@ -35,10 +35,10 @@
  "packages/rxdb/config/src/index.ts"
  ],
  "@ngx-odm/rxdb/core": ["dist/packages/rxdb/core", "packages/rxdb/core/src/index.ts"],
- "@ngx-odm/rxdb/query-params": ["packages/rxdb/query-params/src/index.ts"],
- "@ngx-odm/rxdb/replication-kinto": ["packages/rxdb/replication-kinto/src/index.ts"],
- "@ngx-odm/rxdb/signals": ["packages/rxdb/signals/src/index.ts"],
- "@ngx-odm/rxdb/testing": ["packages/rxdb/testing/src/index.ts"],
+ "@ngx-odm/rxdb/query-params": [ "dist/packages/rxdb/query-params", "packages/rxdb/query-params/src/index.ts"],
+ "@ngx-odm/rxdb/replication-kinto": ["dist/packages/rxdb/replication-kinto", "packages/rxdb/replication-kinto/src/index.ts"],
+ "@ngx-odm/rxdb/signals": ["dist/packages/rxdb/signals", "packages/rxdb/signals/src/index.ts"],
+ "@ngx-odm/rxdb/testing": ["dist/packages/rxdb/testing", "packages/rxdb/testing/src/index.ts"],
  "@ngx-odm/rxdb/utils": [
  "dist/packages/rxdb/utils",
  "packages/rxdb/utils/src/index.ts"