0
# Document Operations
1

2
Complete CRUD operations for individual and bulk document management, including document retrieval, creation, updating, deletion, and bulk operations.
3

4
## Capabilities
5

6
### Document Retrieval
7

8
Retrieves a single document by its ID with various options for revisions and metadata.
9

10
```javascript { .api }
11
/**
12
 * Get a document by ID from the remote database
13
 * @param id - Document ID to retrieve
14
 * @param opts - Retrieval options including revisions and conflicts
15
 * @param callback - Callback function receiving the document
16
 */
17
api.get(id, opts, callback): void;
18
```
19

20
**Usage Examples:**
21

22
```javascript
23
// Basic document retrieval
24
db.get('user:john', (err, doc) => {
25
  if (err) {
26
    console.error('Document not found:', err);
27
    return;
28
  }
29
  
30
  console.log('User name:', doc.name);
31
  console.log('User email:', doc.email);
32
});
33

34
// Get with revision history
35
db.get('user:john', { revs: true }, (err, doc) => {
36
  if (err) {
37
    console.error('Error:', err);
38
    return;
39
  }
40
  
41
  console.log('Revision history:', doc._revisions);
42
});
43

44
// Get with attachments
45
db.get('user:john', { attachments: true }, (err, doc) => {
46
  if (err) {
47
    console.error('Error:', err);
48
    return;
49
  }
50
  
51
  console.log('Attachments:', doc._attachments);
52
});
53
```
54

55
### Document Creation/Update
56

57
Creates a new document or updates an existing document.
58

59
```javascript { .api }
60
/**
61
 * Create or update a document in the remote database
62
 * @param doc - Document object to save
63
 * @param opts - Save options
64
 * @param callback - Callback function receiving save result
65
 */
66
api._put(doc, opts, callback): void;
67
```
68

69
**Usage Examples:**
70

71
```javascript
72
// Create new document
73
const newUser = {
74
  _id: 'user:jane',
75
  name: 'Jane Smith',
76
  email: 'jane@example.com',
77
  created: new Date().toISOString()
78
};
79

80
db.put(newUser, (err, result) => {
81
  if (err) {
82
    console.error('Save failed:', err);
83
    return;
84
  }
85
  
86
  console.log('Document saved with revision:', result.rev);
87
});
88

89
// Update existing document
90
db.get('user:jane', (err, doc) => {
91
  if (err) {
92
    console.error('Error retrieving document:', err);
93
    return;
94
  }
95
  
96
  doc.email = 'jane.smith@example.com';
97
  doc.updated = new Date().toISOString();
98
  
99
  db.put(doc, (err, result) => {
100
    if (err) {
101
      console.error('Update failed:', err);
102
      return;
103
    }
104
    
105
    console.log('Document updated with revision:', result.rev);
106
  });
107
});
108
```
109

110
### Document Deletion
111

112
Removes a document from the remote database.
113

114
```javascript { .api }
115
/**
116
 * Delete a document from the remote database
117
 * @param docOrId - Document object or document ID
118
 * @param optsOrRev - Options object or revision string
119
 * @param opts - Additional options (when second param is revision)
120
 * @param callback - Callback function receiving deletion result
121
 */
122
api.remove(docOrId, optsOrRev, opts, callback): void;
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
// Delete by document object
129
db.get('user:john', (err, doc) => {
130
  if (err) {
131
    console.error('Document not found:', err);
132
    return;
133
  }
134
  
135
  db.remove(doc, (err, result) => {
136
    if (err) {
137
      console.error('Deletion failed:', err);
138
      return;
139
    }
140
    
141
    console.log('Document deleted:', result.ok);
142
  });
143
});
144

145
// Delete by ID and revision
146
db.remove('user:john', '2-abc123', (err, result) => {
147
  if (err) {
148
    console.error('Deletion failed:', err);
149
    return;
150
  }
151
  
152
  console.log('Document deleted:', result.ok);
153
});
154
```
155

156
### Bulk Document Operations
157

158
Creates, updates, or deletes multiple documents in a single request.
159

160
```javascript { .api }
161
/**
162
 * Perform bulk document operations (create, update, delete)
163
 * @param req - Request object containing documents array
164
 * @param opts - Bulk operation options
165
 * @param callback - Callback function receiving bulk results
166
 */
167
api._bulkDocs(req, opts, callback): void;
168
```
169

170
**Usage Examples:**
171

172
```javascript
173
// Bulk create/update
174
const docs = [
175
  { _id: 'user:alice', name: 'Alice Brown', email: 'alice@example.com' },
176
  { _id: 'user:bob', name: 'Bob Wilson', email: 'bob@example.com' },
177
  { _id: 'user:charlie', name: 'Charlie Davis', email: 'charlie@example.com' }
178
];
179

180
db.bulkDocs(docs, (err, results) => {
181
  if (err) {
182
    console.error('Bulk operation failed:', err);
183
    return;
184
  }
185
  
186
  results.forEach((result, index) => {
187
    if (result.ok) {
188
      console.log(`Document ${index} saved with revision:`, result.rev);
189
    } else {
190
      console.error(`Document ${index} failed:`, result.error);
191
    }
192
  });
193
});
194

195
// Bulk delete
196
const docsToDelete = [
197
  { _id: 'user:alice', _rev: '1-abc123', _deleted: true },
198
  { _id: 'user:bob', _rev: '1-def456', _deleted: true }
199
];
200

201
db.bulkDocs(docsToDelete, (err, results) => {
202
  if (err) {
203
    console.error('Bulk deletion failed:', err);
204
    return;
205
  }
206
  
207
  console.log('Bulk deletion completed:', results);
208
});
209
```
210

211
### Bulk Document Retrieval
212

213
Retrieves multiple documents by their IDs in a single request.
214

215
```javascript { .api }
216
/**
217
 * Retrieve multiple documents by their IDs
218
 * @param opts - Options including docs array with IDs and revs
219
 * @param callback - Callback function receiving bulk get results
220
 */
221
api.bulkGet(opts, callback): void;
222
```
223

224
**Usage Examples:**
225

226
```javascript
227
// Get multiple documents
228
const docRequests = [
229
  { id: 'user:alice' },
230
  { id: 'user:bob' },
231
  { id: 'user:charlie', rev: '2-abc123' }
232
];
233

234
db.bulkGet({ docs: docRequests }, (err, result) => {
235
  if (err) {
236
    console.error('Bulk get failed:', err);
237
    return;
238
  }
239
  
240
  result.results.forEach((docResult, index) => {
241
    if (docResult.docs[0].ok) {
242
      console.log(`Document ${index}:`, docResult.docs[0].ok);
243
    } else {
244
      console.error(`Document ${index} error:`, docResult.docs[0].error);
245
    }
246
  });
247
});
248
```
249

250
### All Documents Retrieval
251

252
Retrieves all documents or a range of documents from the database.
253

254
```javascript { .api }
255
/**
256
 * Get all documents or documents by key range
257
 * @param opts - Query options including pagination, keys, and include_docs
258
 * @param callback - Callback function receiving documents list
259
 */
260
api.allDocs(opts, callback): void;
261
```
262

263
**Usage Examples:**
264

265
```javascript
266
// Get all document IDs
267
db.allDocs((err, result) => {
268
  if (err) {
269
    console.error('Error retrieving documents:', err);
270
    return;
271
  }
272
  
273
  console.log('Total documents:', result.total_rows);
274
  result.rows.forEach(row => {
275
    console.log('Document ID:', row.id);
276
  });
277
});
278

279
// Get all documents with content
280
db.allDocs({ include_docs: true }, (err, result) => {
281
  if (err) {
282
    console.error('Error retrieving documents:', err);
283
    return;
284
  }
285
  
286
  result.rows.forEach(row => {
287
    console.log('Document:', row.doc);
288
  });
289
});
290

291
// Get documents by key range
292
db.allDocs({
293
  startkey: 'user:',
294
  endkey: 'user:\uffff',
295
  include_docs: true
296
}, (err, result) => {
297
  if (err) {
298
    console.error('Error retrieving user documents:', err);
299
    return;
300
  }
301
  
302
  console.log(`Found ${result.rows.length} user documents`);
303
});
304
```
305

306
### Revision Differences
307

308
Finds missing document revisions for replication purposes.
309

310
```javascript { .api }
311
/**
312
 * Find missing document revisions for replication
313
 * @param req - Request object with document/revision mappings
314
 * @param opts - Options for revision diff
315
 * @param callback - Callback function receiving missing revisions
316
 */
317
api.revsDiff(req, opts, callback): void;
318
```
319

320
**Usage Examples:**
321

322
```javascript
323
// Check for missing revisions
324
const revisionMap = {
325
  'user:alice': ['1-abc123', '2-def456'],
326
  'user:bob': ['1-ghi789']
327
};
328

329
db.revsDiff(revisionMap, (err, result) => {
330
  if (err) {
331
    console.error('Error checking revisions:', err);
332
    return;
333
  }
334
  
335
  Object.keys(result).forEach(docId => {
336
    if (result[docId].missing) {
337
      console.log(`Missing revisions for ${docId}:`, result[docId].missing);
338
    }
339
  });
340
});
341
```
342

343
## Types
344

345
```javascript { .api }
346
// Document structure
347
interface PouchDoc {
348
  _id: string;
349
  _rev?: string;
350
  _deleted?: boolean;
351
  [key: string]: any;
352
}
353

354
// Get options
355
interface GetOptions {
356
  rev?: string;
357
  revs?: boolean;
358
  revs_info?: boolean;
359
  open_revs?: string[] | "all";
360
  conflicts?: boolean;
361
  attachments?: boolean;
362
  binary?: boolean;
363
  latest?: boolean;
364
}
365

366
// AllDocs options
367
interface AllDocsOptions {
368
  include_docs?: boolean;
369
  conflicts?: boolean;
370
  attachments?: boolean;
371
  startkey?: string;
372
  endkey?: string;
373
  key?: string;
374
  keys?: string[];
375
  limit?: number;
376
  skip?: number;
377
  descending?: boolean;
378
  inclusive_end?: boolean;
379
}
380

381
// AllDocs result
382
interface AllDocsResult {
383
  total_rows: number;
384
  offset: number;
385
  rows: AllDocsRow[];
386
}
387

388
interface AllDocsRow {
389
  id: string;
390
  key: string;
391
  value: { rev: string };
392
  doc?: PouchDoc;
393
}
394

395
// Bulk docs request
396
interface BulkDocsRequest {
397
  docs: PouchDoc[];
398
  new_edits?: boolean;
399
}
400

401
// Bulk get request
402
interface BulkGetRequest {
403
  docs: BulkGetDoc[];
404
  revs?: boolean;
405
  attachments?: boolean;
406
  latest?: boolean;
407
}
408

409
interface BulkGetDoc {
410
  id: string;
411
  rev?: string;
412
}
413

414
// Save result
415
interface SaveResult {
416
  ok: boolean;
417
  id: string;
418
  rev: string;
419
}
420

421
// Revs diff request/result
422
interface RevsDiffRequest {
423
  [docId: string]: string[];
424
}
425

426
interface RevsDiffResult {
427
  [docId: string]: {
428
    missing?: string[];
429
    possible_ancestors?: string[];
430
  };
431
}
432
```