or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

changes-monitoring.mddatabase-management.mddocument-operations.mdindex.mdplugins-adapters.mdreplication-sync.md
tile.json

tessl/npm-pouchdb

PouchDB is a pocket-sized database inspired by Apache CouchDB that runs in the browser and Node.js.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/pouchdb@9.0.x

To install, run

npx @tessl/cli install tessl/npm-pouchdb@9.0.0

index.mddocs/

PouchDB

PouchDB is an open-source JavaScript database inspired by Apache CouchDB that is designed to run well within the browser and Node.js. PouchDB was created to help web developers build applications that work as well offline as they do online, providing seamless data synchronization between local and remote databases.

Package Information

  • Package Name: pouchdb
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install pouchdb

Core Imports

For Node.js environments:

const PouchDB = require('pouchdb');

For ES modules:

import PouchDB from 'pouchdb';

For browsers, include the script:

<script src="pouchdb.js"></script>
<!-- PouchDB is available as global variable -->

Basic Usage

const PouchDB = require('pouchdb');

// Create a database
const db = new PouchDB('my-database');

// Create a document
await db.put({
  _id: 'user1',
  name: 'Alice',
  email: 'alice@example.com'
});

// Retrieve a document
const user = await db.get('user1');
console.log(user.name); // 'Alice'

// Get all documents
const result = await db.allDocs({ include_docs: true });
console.log(result.rows);

// Listen for changes
const changes = db.changes({
  since: 'now',
  live: true,
  include_docs: true
}).on('change', function(info) {
  console.log('Change detected:', info);
});

// Replicate with remote database
const sync = PouchDB.sync(db, 'http://localhost:5984/remote-db', {
  live: true,
  retry: true
}).on('change', function(info) {
  console.log('Sync change:', info);
});

Architecture

PouchDB is built around several key architectural components:

  • Adapter System: Pluggable storage backends for different environments (LevelDB for Node.js, IndexedDB for browsers, HTTP for remote CouchDB)
  • Plugin Architecture: Extensible system allowing additional functionality through plugins
  • Event-Driven: EventEmitter-based architecture for changes, replication, and database lifecycle events
  • Promise-Based API: Modern async API with Promise support and callback compatibility
  • CouchDB Compatibility: Full compatibility with CouchDB's HTTP API and replication protocol
  • Offline-First Design: Built for applications that work equally well online and offline

The adapter system allows PouchDB to automatically choose the best storage mechanism for each environment while maintaining a consistent API across all platforms.

Capabilities

Database Creation and Management

Core database lifecycle operations including creation, configuration, information retrieval, and cleanup.

// Constructor
new PouchDB(name: string, options?: PouchDBOptions): PouchDB;

// Database information and management
db.info(): Promise<DatabaseInfo>;
db.destroy(options?: DestroyOptions): Promise<void>;
db.close(): Promise<void>;
db.compact(options?: CompactOptions): Promise<CompactResponse>;

Database Management

Document Operations

Complete CRUD operations for documents including creation, retrieval, updates, deletions, and bulk operations.

db.put(document: Document, options?: PutOptions): Promise<PutResponse>;
db.get(docId: string, options?: GetOptions): Promise<Document>;
db.post(document: Document, options?: PostOptions): Promise<PostResponse>;
db.remove(document: Document | string, options?: RemoveOptions): Promise<RemoveResponse>;
db.bulkDocs(documents: Document[], options?: BulkDocsOptions): Promise<BulkResponse[]>;
db.allDocs(options?: AllDocsOptions): Promise<AllDocsResponse>;

Document Operations

Changes and Monitoring

Real-time monitoring of database changes with filtering, continuous feeds, and event-driven updates.

db.changes(options?: ChangesOptions): Changes;

Changes and Monitoring

Replication and Synchronization

Bidirectional synchronization with remote databases, including continuous replication and conflict resolution.

// Instance methods
db.replicate.from(source: string | PouchDB, options?: ReplicationOptions): Replication;
db.replicate.to(target: string | PouchDB, options?: ReplicationOptions): Replication;
db.sync(remoteDB: string | PouchDB, options?: SyncOptions): Sync;

// Static methods
PouchDB.replicate(source: string | PouchDB, target: string | PouchDB, options?: ReplicationOptions): Replication;
PouchDB.sync(source: string | PouchDB, target: string | PouchDB, options?: SyncOptions): Sync;

Replication and Synchronization

Plugin and Adapter System

Extensible architecture for adding functionality and storage backends.

// Plugin system
PouchDB.plugin(plugin: Plugin): typeof PouchDB;

// Adapter management
PouchDB.adapter(name: string, adapter: Adapter, addToPreferred?: boolean): void;
PouchDB.defaults(options: PouchDBOptions): typeof PouchDB;

Plugins and Adapters

Types

interface PouchDBOptions {
  adapter?: string;
  auto_compaction?: boolean;
  revs_limit?: number;
  view_adapter?: string;
  purged_infos_limit?: number;
  [key: string]: any;
}

interface Document {
  _id: string;
  _rev?: string;
  _attachments?: { [name: string]: Attachment };
  _deleted?: boolean;
  [key: string]: any;
}

interface DatabaseInfo {
  db_name: string;
  doc_count: number;
  update_seq: number | string;
  purge_seq?: number | string;
  compact_running: boolean;
  disk_size?: number;
  data_size?: number;
  instance_start_time: string;
  host: string;
  auto_compaction?: boolean;
}

interface PutResponse {
  ok: boolean;
  id: string;
  rev: string;
}

interface GetOptions {
  rev?: string;
  revs?: boolean;
  revs_info?: boolean;
  conflicts?: boolean;
  attachments?: boolean;
  binary?: boolean;
}

interface AllDocsOptions {
  include_docs?: boolean;
  startkey?: string;
  endkey?: string;
  limit?: number;
  skip?: number;
  descending?: boolean;
  keys?: string[];
}

interface ChangesOptions {
  since?: number | string;
  limit?: number;
  descending?: boolean;
  include_docs?: boolean;
  conflicts?: boolean;
  attachments?: boolean;
  live?: boolean;
  continuous?: boolean;
  heartbeat?: number;
  timeout?: number;
  filter?: string | Function;
  view?: string;
  doc_ids?: string[];
}

interface ReplicationOptions {
  continuous?: boolean;
  retry?: boolean;
  filter?: string | Function;
  query_params?: object;
  doc_ids?: string[];
  checkpoint?: string | boolean;
  batch_size?: number;
  batches_limit?: number;
}