@moltendb-web/angular

Official Angular integration for MoltenDb, providing a seamless reactive developer experience using modern Angular Signals.

Requirements: Angular 17 or higher. This library uses Angular Signals and standalone APIs introduced in Angular 17.

What's New in v2.0.0

• Bulk Delete with .where() — delete documents matching a filter clause without listing individual keys.
• Capped Collections (.maxSize()) — cap a collection to a maximum number of documents; oldest entries are evicted automatically when the limit is reached.
• TTL Collections (.ttl()) — set a time-to-live (in seconds) on a collection; documents are removed automatically after expiry.

Demo

See the library in action with a real-world demo application:

• 🔗 Demo repo: github.com/maximilian27/moltendb-angular
• ⚡ StackBlitz: Open in StackBlitz
• 🌠 **Live demo: ** moltendb-angular.maximilian-both27.workers.dev/laptops

Installation

npm install @moltendb-web/angular

@moltendb-web/core and @moltendb-web/query are automatically installed as dependencies — no need to install them separately.

Step 1: Configure Assets

MoltenDb runs its database engine inside a background Web Worker and relies on WebAssembly (WASM). You must tell Angular to serve these compiled files as public assets.

Update the assets array in your angular.json:

"assets": [
{
"glob": "moltendb-worker.js",
"input": "node_modules/@moltendb-web/core/dist",
"output": "/"
},
{
"glob": "moltendb_core.js",
"input": "node_modules/@moltendb-web/core/dist/wasm",
"output": "/wasm/"
},
{
"glob": "*.wasm",
"input": "node_modules/@moltendb-web/core/dist/wasm",
"output": "/wasm/"
}
]

Note: Restart your Angular dev server after modifying angular.json.

Step 2: Provide MoltenDb

Initialise MoltenDb in your root app.config.ts:

import {ApplicationConfig} from '@angular/core';
import {provideMoltenDb} from '@moltendb-web/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideMoltenDb({
      name: 'my_app_db',
      workerUrl: '/moltendb-worker.js',
    })
  ]
};

Step 3: Fetching and Mutating Data

Reactive data — moltenDbResource()

Use moltenDbResource to bind data to your template. It handles loading states, errors, and live collection updates automatically.

import {Component} from '@angular/core';
import {moltenDbResource} from '@moltendb-web/angular';

interface Laptop {
  _key: string;
  brand: string;
  model: string;
  price: number;
}

@Component({
  selector: 'app-laptops',
  template: `
    @if (laptops.isLoading() && !laptops.value()) {
      <p>Loading…</p>
    }
    @if (laptops.value(); as list) {
      <ul>
        @for (item of list; track item._key) {
          <li>{{ item.brand }} {{ item.model }} — {{ item.price | currency }}</li>
        }
      </ul>
    }
    @if (laptops.error()) {
      <p class="error">{{ laptops.error().message }}</p>
    }
  `
})
export class LaptopsComponent {
  laptops = moltenDbResource<Laptop[]>('laptops', (col) =>
      col.get()
          .where({in_stock: true})
          .sort([{field: 'price', order: 'asc'}])
          .exec() as Promise<Laptop[]>
  );
}

Imperative access — moltendbClient()

Use moltendbClient() for mutations and one-off queries triggered by user actions:

import {Component} from '@angular/core';
import {moltendbClient} from '@moltendb-web/angular';

@Component({...})
export class AdminComponent {
  private client = moltendbClient();

  async addLaptop() {
    await this.client.collection('laptops').set({
      lp_new: {brand: 'Framework', model: 'Laptop 16', price: 1049, in_stock: true}
    }).exec();
    // Any moltenDbResource watching 'laptops' refreshes automatically
  }
}

Hooks

moltendbClient()

Returns the MoltenDbClient instance for imperative database access. Must be called in an injection context.

moltenDbResource<T>(collection, queryFn)

Creates a reactive resource bound to a collection. Automatically re-fetches when the collection is mutated. Must be called in an injection context.

Returns a MoltenDbResource<T> with three readonly signals:

| Signal | Type | Description | |-------------|--------------------------|-------------------------------------| | value | Signal<T \| undefined> | The latest query result | | isLoading | Signal<boolean> | true while a fetch is in progress | | error | Signal<any \| null> | The last error, or null if none |

moltenDbReady()

Returns true once MoltenDb has finished initialising. Useful for gating UI until the database is ready. Must be called in an injection context.

import {Component} from '@angular/core';
import {moltenDbReady} from '@moltendb-web/angular';

@Component({
  selector: 'app-shell',
  template: `
    @if (!isReady()) {
      <p>⚙ Initialising database…</p>
    } @else {
      <ng-content />
    }
  `
})
export class AppShellComponent {
  isReady = moltenDbReady;
}

moltenDbIsLeader()

Returns true if the current tab is the Leader — the tab running the WASM worker and performing actual writes. Other tabs act as follower proxies. Must be called in an injection context.

import {Component} from '@angular/core';
import {moltenDbIsLeader} from '@moltendb-web/angular';

@Component({
  selector: 'app-tab-badge',
  template: `<span>{{ isLeader() ? '👑 Leader' : '🔗 Follower' }}</span>`
})
export class TabBadgeComponent {
  isLeader = moltenDbIsLeader;
}

moltenDbTerminate()

Terminates the MoltenDb worker. Must be called in an injection context.

moltenDbClearOpfs() (v2.0.0)

Flushes and closes the OPFS sync handle. Call this before moltenDbTerminate() — without it the browser throws a " No modification allowed" error when removing the OPFS directory. Must be called in an injection context.

import { Component } from '@angular/core';
import { moltenDbClearOpfs, moltenDbTerminate } from '@moltendb-web/angular';

@Component({
  selector: 'app-reset-button',
  template: `<button (click)="handleReset()">🗑 Reset All Data</button>`
})
export class ResetButtonComponent {
  private clearOpfs = moltenDbClearOpfs;
  private terminate = moltenDbTerminate;

  async handleReset() {
    if (!confirm('This will delete all local data and reload. Continue?')) return;
    // 1. Flush and close the OPFS sync handle
    await this.clearOpfs();
    // 2. Now safe to terminate the worker
    this.terminate();
    location.reload();
  }
}

moltenDbEvents(listener) (v2.0.0 — auto-unsubscribe)

Subscribes to real-time mutation events. The listener is called with a DbEvent whenever any document is created, updated, deleted, or a collection is dropped. The subscription is automatically cleaned up when the injection context (component/service) is destroyed — no ngOnDestroy or manual unsubscription needed. Must be called in an injection context.

import {Component} from '@angular/core';
import {moltenDbEvents} from '@moltendb-web/angular';
import type {DbEvent} from '@moltendb-web/angular';

@Component({
  selector: 'app-live-feed',
  template: `
    <ul>
      @for (e of events; track e) {
        <li>{{ e.event }} — {{ e.collection }}/{{ e.key }}</li>
      }
    </ul>
  `
})
export class LiveFeedComponent {
  events: DbEvent[] = [];

  constructor() {
    moltenDbEvents((evt) => {
      this.events = [evt, ...this.events].slice(0, 50);
    });
    // ✅ No ngOnDestroy needed — subscription is auto-cleaned up when component is destroyed
  }
}

API Reference

| Export | Type | Description | |-----------------------------------------|----------------|------------------------------------------------------------------------------------------------------------------------| | provideMoltenDb(config) | Provider | Registers MoltenDb as an Angular environment provider | | moltendbClient() | Injection hook | Returns the MoltenDbClient instance | | moltenDbReady() | Injection hook | Returns true once MoltenDb has finished initialising | | moltenDbIsLeader() | Injection hook | Returns true if the current tab is the Leader | | moltenDbTerminate() | Injection hook | Terminates the MoltenDb worker | | moltenDbClearOpfs() | Injection hook | (v2.0.0) Flush and close the OPFS sync handle — call before moltenDbTerminate() | | moltenDbResource(collection, queryFn) | Injection hook | Reactive resource with value, isLoading, error signals and auto-refresh | | moltenDbEvents(listener) | Injection hook | (v2.0.0) Subscribe to real-time DbEvent mutation events; auto-unsubscribes when the injection context is destroyed | | DbEvent | Type | Event object emitted on mutations: { event, collection, key, new_v } | | AngularMoltenDbOptions | Interface | Config passed to provideMoltenDb — extends MoltenDbOptions with a required name field | | MoltenDbResource<T> | Interface | Return type of moltenDbResource: { value, isLoading, error } signals |

Configuration

AngularMoltenDbOptions extends the core MoltenDbOptions with one required field:

| Option | Type | Default | Description | |---------------------|---------------------|--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | name | string | required | Database name (used as the OPFS directory name) | | inMemory | boolean | false | Run entirely in RAM — no OPFS writes. Data persists as long as at least one tab is open; any tab refresh or close wipes the shared store for all tabs | | encryptionKey | string | undefined | Password for at-rest encryption. If omitted, data is stored as plain JSON | | writeMode | 'async' \| 'sync' | 'async' | Storage write mode: 'async' for high throughput or 'sync' for durable writes | | maxBodySize | number | undefined | Maximum request body size in bytes | | maxKeysPerRequest | number | 1000 | Maximum number of keys allowed per JSON request | | workerUrl | string \| URL | undefined | Custom URL or path to moltendb-worker.js |

Notes

• provideMoltenDb() uses Angular's APP_INITIALIZER to block app bootstrap until the database is ready — no need to check a isReady flag in most components.
• Multiple apps using the same name will share the same underlying OPFS storage and sync across tabs via the built-in leader/follower mechanism.
• moltenDbResource re-fetches automatically when the bound collection is mutated by any tab — no manual refresh needed.