0
# PouchDB HTTP Adapter
1

2
PouchDB HTTP Adapter is a plugin that enables PouchDB to connect to remote CouchDB servers and HTTP-compatible databases. It provides a complete implementation of the PouchDB adapter interface for HTTP/HTTPS protocols, supporting both Node.js and browser environments with authentication, cookie management, and comprehensive database operations.
3

4
## Package Information
5

6
- **Package Name**: pouchdb-adapter-http
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install pouchdb-adapter-http`
10

11
## Core Imports
12

13
```javascript
14
// Import PouchDB and the HTTP adapter
15
import PouchDB from 'pouchdb-core';
16
import HttpAdapter from 'pouchdb-adapter-http';
17

18
// Register the adapter
19
PouchDB.plugin(HttpAdapter);
20
```
21

22
For CommonJS:
23

24
```javascript
25
const PouchDB = require('pouchdb-core');
26
const HttpAdapter = require('pouchdb-adapter-http');
27

28
PouchDB.plugin(HttpAdapter);
29
```
30

31
## Basic Usage
32

33
```javascript
34
import PouchDB from 'pouchdb-core';
35
import HttpAdapter from 'pouchdb-adapter-http';
36

37
PouchDB.plugin(HttpAdapter);
38

39
// Connect to remote CouchDB
40
const db = new PouchDB('http://localhost:5984/mydb', {
41
  auth: {
42
    username: 'admin',
43
    password: 'password'
44
  }
45
});
46

47
// Basic document operations
48
const doc = await db.put({
49
  _id: 'user:john',
50
  name: 'John Doe',
51
  email: 'john@example.com'
52
});
53

54
const retrieved = await db.get('user:john');
55
console.log(retrieved.name); // 'John Doe'
56
```
57

58
## Architecture
59

60
The HTTP adapter implements the PouchDB adapter interface to provide:
61

62
- **HTTP Communication**: Uses `fetch` API with cookie support for all database operations
63
- **Authentication**: Supports Basic Auth with automatic header management
64
- **Error Handling**: Translates HTTP status codes to PouchDB-compatible errors
65
- **Adapter Registration**: Registers both 'http' and 'https' adapter types with PouchDB
66
- **Browser/Node Compatibility**: Works in both browser and Node.js environments
67

68
## Capabilities
69

70
### Database Operations
71

72
Core database management functionality including connection setup, database info retrieval, and lifecycle operations.
73

74
```javascript { .api }
75
// Constructor for HTTP adapter
76
function HttpPouch(opts, callback);
77

78
// Database information
79
api._info(callback): void;
80
api.id(callback): void;
81

82
// Database lifecycle
83
api._destroy(options, callback): void;
84
api._close(callback): void;
85
api.compact(opts, callback): void;
86
```
87

88
[Database Operations](./database-operations.md)
89

90
### Document Operations
91

92
Complete CRUD operations for individual and bulk document management.
93

94
```javascript { .api }
95
// Single document operations
96
api.get(id, opts, callback): void;
97
api._put(doc, opts, callback): void;
98
api.remove(docOrId, optsOrRev, opts, callback): void;
99

100
// Bulk operations
101
api._bulkDocs(req, opts, callback): void;
102
api.bulkGet(opts, callback): void;
103
api.allDocs(opts, callback): void;
104
api.revsDiff(req, opts, callback): void;
105
```
106

107
[Document Operations](./document-operations.md)
108

109
### Attachment Operations
110

111
File attachment management with support for binary data and proper content types.
112

113
```javascript { .api }
114
// Attachment CRUD operations
115
api.getAttachment(docId, attachmentId, opts, callback): void;
116
api.putAttachment(docId, attachmentId, rev, blob, type, callback): void;
117
api.removeAttachment(docId, attachmentId, rev, callback): void;
118
```
119

120
[Attachment Operations](./attachment-operations.md)
121

122
### Changes Feed
123

124
Real-time database changes streaming with filtering and continuous monitoring support.
125

126
```javascript { .api }
127
// Changes feed with various options
128
api._changes(opts): { cancel: function };
129
```
130

131
[Changes Feed](./changes-feed.md)
132

133
### HTTP Utilities
134

135
Low-level HTTP access and utility functions for custom requests.
136

137
```javascript { .api }
138
// Direct HTTP access
139
api.fetch(path, options): Promise<Response>;
140

141
// Adapter validation
142
HttpPouch.valid(): boolean;
143
```
144

145
[HTTP Utilities](./http-utilities.md)
146

147
## Types
148

149
```javascript { .api }
150
// Constructor options
151
interface HttpPouchOptions {
152
  name: string;
153
  auth?: {
154
    username: string;
155
    password: string;
156
  };
157
  headers?: { [key: string]: string };
158
  fetch?: Function;
159
  skip_setup?: boolean;
160
}
161

162
// Common callback pattern
163
type PouchCallback<T> = (error: Error | null, result?: T) => void;
164

165
// Document structure
166
interface PouchDoc {
167
  _id: string;
168
  _rev?: string;
169
  [key: string]: any;
170
}
171

172
// Database info response
173
interface DatabaseInfo {
174
  db_name: string;
175
  doc_count: number;
176
  doc_del_count: number;
177
  update_seq: string | number;
178
  purge_seq: string | number;
179
  compact_running: boolean;
180
  disk_size: number;
181
  data_size: number;
182
  instance_start_time: string;
183
  disk_format_version: number;
184
  committed_update_seq: string | number;
185
  host: string;
186
}
187
```