Document Operations

/**
 * Get a document by ID from the remote database
 * @param id - Document ID to retrieve
 * @param opts - Retrieval options including revisions and conflicts
 * @param callback - Callback function receiving the document
 */
api.get(id, opts, callback): void;

// Basic document retrieval
db.get('user:john', (err, doc) => {
  if (err) {
    console.error('Document not found:', err);
    return;
  }
  
  console.log('User name:', doc.name);
  console.log('User email:', doc.email);
});

// Get with revision history
db.get('user:john', { revs: true }, (err, doc) => {
  if (err) {
    console.error('Error:', err);
    return;
  }
  
  console.log('Revision history:', doc._revisions);
});

// Get with attachments
db.get('user:john', { attachments: true }, (err, doc) => {
  if (err) {
    console.error('Error:', err);
    return;
  }
  
  console.log('Attachments:', doc._attachments);
});

/**
 * Create or update a document in the remote database
 * @param doc - Document object to save
 * @param opts - Save options
 * @param callback - Callback function receiving save result
 */
api._put(doc, opts, callback): void;

// Create new document
const newUser = {
  _id: 'user:jane',
  name: 'Jane Smith',
  email: 'jane@example.com',
  created: new Date().toISOString()
};

db.put(newUser, (err, result) => {
  if (err) {
    console.error('Save failed:', err);
    return;
  }
  
  console.log('Document saved with revision:', result.rev);
});

// Update existing document
db.get('user:jane', (err, doc) => {
  if (err) {
    console.error('Error retrieving document:', err);
    return;
  }
  
  doc.email = 'jane.smith@example.com';
  doc.updated = new Date().toISOString();
  
  db.put(doc, (err, result) => {
    if (err) {
      console.error('Update failed:', err);
      return;
    }
    
    console.log('Document updated with revision:', result.rev);
  });
});

/**
 * Delete a document from the remote database
 * @param docOrId - Document object or document ID
 * @param optsOrRev - Options object or revision string
 * @param opts - Additional options (when second param is revision)
 * @param callback - Callback function receiving deletion result
 */
api.remove(docOrId, optsOrRev, opts, callback): void;

// Delete by document object
db.get('user:john', (err, doc) => {
  if (err) {
    console.error('Document not found:', err);
    return;
  }
  
  db.remove(doc, (err, result) => {
    if (err) {
      console.error('Deletion failed:', err);
      return;
    }
    
    console.log('Document deleted:', result.ok);
  });
});

// Delete by ID and revision
db.remove('user:john', '2-abc123', (err, result) => {
  if (err) {
    console.error('Deletion failed:', err);
    return;
  }
  
  console.log('Document deleted:', result.ok);
});

/**
 * Perform bulk document operations (create, update, delete)
 * @param req - Request object containing documents array
 * @param opts - Bulk operation options
 * @param callback - Callback function receiving bulk results
 */
api._bulkDocs(req, opts, callback): void;

// Bulk create/update
const docs = [
  { _id: 'user:alice', name: 'Alice Brown', email: 'alice@example.com' },
  { _id: 'user:bob', name: 'Bob Wilson', email: 'bob@example.com' },
  { _id: 'user:charlie', name: 'Charlie Davis', email: 'charlie@example.com' }
];

db.bulkDocs(docs, (err, results) => {
  if (err) {
    console.error('Bulk operation failed:', err);
    return;
  }
  
  results.forEach((result, index) => {
    if (result.ok) {
      console.log(`Document ${index} saved with revision:`, result.rev);
    } else {
      console.error(`Document ${index} failed:`, result.error);
    }
  });
});

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

db.bulkDocs(docsToDelete, (err, results) => {
  if (err) {
    console.error('Bulk deletion failed:', err);
    return;
  }
  
  console.log('Bulk deletion completed:', results);
});

/**
 * Retrieve multiple documents by their IDs
 * @param opts - Options including docs array with IDs and revs
 * @param callback - Callback function receiving bulk get results
 */
api.bulkGet(opts, callback): void;

// Get multiple documents
const docRequests = [
  { id: 'user:alice' },
  { id: 'user:bob' },
  { id: 'user:charlie', rev: '2-abc123' }
];

db.bulkGet({ docs: docRequests }, (err, result) => {
  if (err) {
    console.error('Bulk get failed:', err);
    return;
  }
  
  result.results.forEach((docResult, index) => {
    if (docResult.docs[0].ok) {
      console.log(`Document ${index}:`, docResult.docs[0].ok);
    } else {
      console.error(`Document ${index} error:`, docResult.docs[0].error);
    }
  });
});

/**
 * Get all documents or documents by key range
 * @param opts - Query options including pagination, keys, and include_docs
 * @param callback - Callback function receiving documents list
 */
api.allDocs(opts, callback): void;

// Get all document IDs
db.allDocs((err, result) => {
  if (err) {
    console.error('Error retrieving documents:', err);
    return;
  }
  
  console.log('Total documents:', result.total_rows);
  result.rows.forEach(row => {
    console.log('Document ID:', row.id);
  });
});

// Get all documents with content
db.allDocs({ include_docs: true }, (err, result) => {
  if (err) {
    console.error('Error retrieving documents:', err);
    return;
  }
  
  result.rows.forEach(row => {
    console.log('Document:', row.doc);
  });
});

// Get documents by key range
db.allDocs({
  startkey: 'user:',
  endkey: 'user:\uffff',
  include_docs: true
}, (err, result) => {
  if (err) {
    console.error('Error retrieving user documents:', err);
    return;
  }
  
  console.log(`Found ${result.rows.length} user documents`);
});

/**
 * Find missing document revisions for replication
 * @param req - Request object with document/revision mappings
 * @param opts - Options for revision diff
 * @param callback - Callback function receiving missing revisions
 */
api.revsDiff(req, opts, callback): void;

// Check for missing revisions
const revisionMap = {
  'user:alice': ['1-abc123', '2-def456'],
  'user:bob': ['1-ghi789']
};

db.revsDiff(revisionMap, (err, result) => {
  if (err) {
    console.error('Error checking revisions:', err);
    return;
  }
  
  Object.keys(result).forEach(docId => {
    if (result[docId].missing) {
      console.log(`Missing revisions for ${docId}:`, result[docId].missing);
    }
  });
});

// Document structure
interface PouchDoc {
  _id: string;
  _rev?: string;
  _deleted?: boolean;
  [key: string]: any;
}

// Get options
interface GetOptions {
  rev?: string;
  revs?: boolean;
  revs_info?: boolean;
  open_revs?: string[] | "all";
  conflicts?: boolean;
  attachments?: boolean;
  binary?: boolean;
  latest?: boolean;
}

// AllDocs options
interface AllDocsOptions {
  include_docs?: boolean;
  conflicts?: boolean;
  attachments?: boolean;
  startkey?: string;
  endkey?: string;
  key?: string;
  keys?: string[];
  limit?: number;
  skip?: number;
  descending?: boolean;
  inclusive_end?: boolean;
}

// AllDocs result
interface AllDocsResult {
  total_rows: number;
  offset: number;
  rows: AllDocsRow[];
}

interface AllDocsRow {
  id: string;
  key: string;
  value: { rev: string };
  doc?: PouchDoc;
}

// Bulk docs request
interface BulkDocsRequest {
  docs: PouchDoc[];
  new_edits?: boolean;
}

// Bulk get request
interface BulkGetRequest {
  docs: BulkGetDoc[];
  revs?: boolean;
  attachments?: boolean;
  latest?: boolean;
}

interface BulkGetDoc {
  id: string;
  rev?: string;
}

// Save result
interface SaveResult {
  ok: boolean;
  id: string;
  rev: string;
}

// Revs diff request/result
interface RevsDiffRequest {
  [docId: string]: string[];
}

interface RevsDiffResult {
  [docId: string]: {
    missing?: string[];
    possible_ancestors?: string[];
  };
}