PouchORM

PouchORM adds typed models and named collections to PouchDB. It provides query and write helpers, optional class validation, change hooks, and synchronization management while keeping the underlying PouchDB database available.

Read the documentation or open the API reference.

Installation

Install PouchORM and its PouchDB peer dependency:

npm install pouchorm pouchdb

Install class-validator only when the application uses validation:

npm install class-validator

PouchORM 5 requires Node.js 20 or newer when used in Node. It is published as CommonJS with TypeScript declarations.

Quick start

Define a model and give its collection a stable name:

import { IModel, PouchCollection } from "pouchorm";

interface Person extends IModel {
  name: string;
  age: number;
}

class People extends PouchCollection<Person> {
  constructor(database = "app-data") {
    // This stable value is stored with every People document.
    super({ database, collection: "people" });
  }

  async beforeInit(): Promise<void> {
    // Create the index before collection queries begin.
    await this.addIndex(["age"], "people-by-age");
  }
}

const people = new People();

Create, query, update, and remove documents:

const ada = await people.upsert({
  name: "Ada Lovelace",
  age: 36,
});

// $gte is a Mango query operator; the second argument controls sorting.
const adults = await people.find(
  { age: { $gte: 18 } },
  { sort: [{ age: "desc" }] },
);

// Reuse the saved _id and _rev when updating or removing a document.
const updatedAda = await people.upsert({ ...ada, age: 37 });
await people.remove(updatedAda);

The collection value is stored in $collectionType on every document. Keep it stable across builds and releases; production minification must not determine persisted collection identity.

Documentation

• Getting started
• Models and collections
• Querying
• Creating and updating documents
• Validation
• Synchronization
• API reference
• Migrating from PouchORM 4
• Archived PouchORM 4 documentation

The current documentation is maintained for 5.x. The frozen 4.x documentation is retained for applications that have not migrated.

Contributing and security

See CONTRIBUTING.md before opening a pull request. Report security problems using the process in SECURITY.md.

License

MIT