Skip to main content
Version: 5.x

Getting started

Install the packages​

Install PouchORM and its PouchDB peer dependency:

npm install pouchorm pouchdb

Install class-validator only if the application will validate class models:

npm install class-validator

Define a model and collection​

Every model extends IModel. Every collection receives a database name and a stable collection name.

import { IModel, PouchCollection } from "pouchorm";

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

class People extends PouchCollection<Person> {
  constructor(database = "app-data") {
    // PouchORM stores this explicit name in $collectionType.
    super({ database, collection: "people" });
  }

  async beforeInit(): Promise<void> {
    // Add indexes needed by sorted queries before the collection is ready.
    await this.addIndex(["age"], "people-by-age");
  }
}

const people = new People();

The collection value is stored in $collectionType on every document. Keep it stable across builds and releases. Do not derive it from a JavaScript class name, because minification can change class names.

Save a document​

upsert creates a document without an _id and updates a document that already has one:

// With no _id, upsert generates a UUIDv7 for this new document.
const ada = await people.upsert({
  name: "Ada Lovelace",
  age: 36,
});

The returned document includes its PouchDB _id and _rev values along with PouchORM metadata.

Query the collection​

Use a Mango selector. PouchORM adds the collection name to the selector:

// $gte means "greater than or equal to" in a Mango selector.
const adults = await people.find(
  { age: { $gte: 18 } },
  { sort: [{ age: "desc" }] },
);

Call find() without a selector to return every document in the collection.

Update and remove the document​

Pass a saved _id to update that document. The default update replaces stored application fields:

// Spreading ada carries its current _id and _rev into the update.
const updatedAda = await people.upsert({ ...ada, age: 37 });
await people.remove(updatedAda);

Read Creating and updating documents before implementing partial updates or bulk operations.

Next steps​