cht-conf 4.1.2 → 4.2.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [4.2.0](https://github.com/medic/cht-conf/compare/v4.1.3...v4.2.0) (2024-12-11)
+
+
+### Features
+
+* **#373:** merge-contacts action ([#647](https://github.com/medic/cht-conf/issues/647)) ([006554c](https://github.com/medic/cht-conf/commit/006554cf3a414d9577e05c6dfaef3bbd59849403)), closes [#373](https://github.com/medic/cht-conf/issues/373)
+
+## [4.1.3](https://github.com/medic/cht-conf/compare/v4.1.2...v4.1.3) (2024-11-13)
+
+
+### Bug Fixes
+
+* **#644:** support node 22 ([d8ece55](https://github.com/medic/cht-conf/commit/d8ece55cd601ae8f4f1a98cd496394f14c5ded0d)), closes [#644](https://github.com/medic/cht-conf/issues/644)
+
 ## [4.1.2](https://github.com/medic/cht-conf/compare/v4.1.1...v4.1.2) (2024-10-09)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cht-conf",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "description": "Configure CHT deployments",
   "main": "./src/lib/main.js",
   "engines": {
@@ -9,9 +9,7 @@
   "scripts": {
     "clean": "rm -rf ./build/",
     "eslint": "eslint 'src/**/*.js' test/*.js 'test/**/*.js'",
-    "docker-start-couchdb": "npm run docker-stop-couchdb && docker run -d -p 6984:5984 --rm --name cht-conf-couchdb couchdb:2.3.1 && sh test/scripts/wait_for_response_code.sh 6984 200 CouchDB",
-    "docker-stop-couchdb": "docker stop cht-conf-couchdb || true",
-    "test": "npm run eslint && npm run docker-start-couchdb && npm run clean && mkdir -p build/test && cp -r test/data build/test/data && cd build/test && nyc --reporter=html mocha --forbid-only \"../../test/**/*.spec.js\" --exclude \"../../test/e2e/**/*.spec.js\" && cd ../.. && npm run docker-stop-couchdb",
+    "test": "npm run clean && mkdir -p build/test && cp -r test/data build/test/data && cd build/test && nyc --reporter=html mocha \"../../test/**/*.spec.js\" --exclude \"../../test/e2e/**/*.spec.js\"",
     "test-e2e": "mocha --config test/e2e/.mocharc.js",
     "semantic-release": "semantic-release"
   },

package/src/fn/edit-contacts.js

@@ -105,69 +105,89 @@ function getIDs(csv, docType) {
   return rows.map((item) => idPrefix + item[index]);
 }
 
-function processDocs(docType, csv, documentDocs, args) {
-  const { rows, cols } = fs.readCsv(csv);
-  const uuidIndex = cols.indexOf(DOCUMENT_ID);
-  const colNames = args.colNames;
-  let toIncludeColumns, toIncludeIndex;
-  if (!colNames.length) {
-    warn(' No columns specified, the script will add all the columns in the CSV!');
-    toIncludeColumns = cols;
-    toIncludeIndex = [];
-
-  } else {
-    if (!columnsAreValid(cols,colNames)) {
-      throw Error('The column name(s) specified do not exist.');
-    }
-
-    toIncludeColumns = cols.filter(column => colNames.includes(column.split(':')[0]));
-    toIncludeIndex = toIncludeColumns.map(column => cols.indexOf(column));
-
-    if (toIncludeColumns.includes(DOCUMENT_ID)) {
-      toIncludeIndex.splice(toIncludeColumns.indexOf(DOCUMENT_ID),1);
-    }
-  }
-
-  if (toIncludeColumns.includes(DOCUMENT_ID)) {
-    toIncludeColumns.splice(toIncludeColumns.indexOf(DOCUMENT_ID),1);
-  }
-  return rows
-    .map(r => processCsv(docType, toIncludeColumns, r, uuidIndex, toIncludeIndex, documentDocs));
-}
-
 function columnsAreValid(csvColumns, toIncludeColumns) {
   const splitCsvColumns = csvColumns.map(column => column && column.split(':')[0]);
   return toIncludeColumns.every(column => splitCsvColumns.includes(column));    
 }
+const parseColName = colName => colName.split(':')[0];
+const getColNamesToInclude = (csvColNames, targetColNames) => {
+  const filteredCsvColNames = csvColNames.filter(colName => colName !== DOCUMENT_ID);
+  if (!targetColNames.length) {
+    warn(' No columns specified, the script will add all the columns in the CSV!');
+    return filteredCsvColNames;
+  }
+  
+  if (!columnsAreValid(filteredCsvColNames, targetColNames)) {
+    throw Error('The column name(s) specified do not exist.');
+  }
+
+  return filteredCsvColNames.filter(column => targetColNames.includes(parseColName(column)));
+};
 
-function processCsv(docType, cols, row, uuidIndex, toIncludeIndex, documentDocs) {
+const getCsvColNameIndex = csvColNames => colName => csvColNames.indexOf(colName);
+const mapColNamesToCsvIndex = (csvColNames, toIncludeColumns) => toIncludeColumns.map(getCsvColNameIndex(csvColNames));
+
+
+const getDocIdForCsvRow = (docType, uuidIndex) => row => {
   const documentId = row[uuidIndex];
   const idPrefix =  docType === 'contact' ? '' : 'org.couchdb.user:';
-  const doc = documentDocs[idPrefix + documentId];
+  return `${idPrefix}${documentId}`;
+};
 
+const getCsvRowFilterFn = (uuidIndex, toIncludeIndex) => {
   if (toIncludeIndex.length > 0) {
-    row = toIncludeIndex.map(index => row[index]);
-  } else {
-    row.splice(uuidIndex,1);
+    return row => toIncludeIndex.map(index => row[index]);
   }
 
-  for(let i=0; i<cols.length; ++i) {
-    const { col, val, excluded } = toDocs.parseColumn(cols[i], row[i]);
+  return row => {
+    const updatedRow = [...row];
+    updatedRow.splice(uuidIndex, 1);
+    return updatedRow;
+  };
+};
+
+const isColNameProtected = col => EDIT_RESERVED_COL_NAMES.includes(col.split('.')[0]);
+const processCsvColumn = (doc, row) => (colName, index) => {
+  const { col, val, excluded } = toDocs.parseColumn(colName, row[index]);
     
-    if (EDIT_RESERVED_COL_NAMES.includes(col.split('.')[0])) {
-      throw new Error(`Cannot set property defined by column '${col}' - this property name is protected.`);
-    }
+  if (isColNameProtected(col)) {
+    throw new Error(`Cannot set property defined by column '${col}' - this property name is protected.`);
+  }
 
-    toDocs.setCol(doc, col, val);
-    if (excluded) { 
-      model.exclusions.push({
-        doc: doc,
-        propertyName: col,
-      });
-    }
+  toDocs.setCol(doc, col, val);
+  if (excluded) { 
+    model.exclusions.push({
+      doc,
+      propertyName: col,
+    });
   }
-  return doc;
-}
+};
+const processCsvRow = colNames => ([doc, row]) => colNames.forEach(processCsvColumn(doc, row));
+
+const getColIndexesToInclude = (colNames, cols, toIncludeColumns) => {
+  if(colNames.length) {
+    return mapColNamesToCsvIndex(cols, toIncludeColumns);
+  } 
+  return [];
+};
+
+const processDocs = (docType, csv, documentDocs, args) => {
+  const { rows, cols } = fs.readCsv(csv);
+  const uuidIndex = cols.indexOf(DOCUMENT_ID);
+  const colNamesToInclude = getColNamesToInclude(cols, args.colNames);
+  const colIndexesToInclude = getColIndexesToInclude(args.colNames, cols, colNamesToInclude);
+  const getFilteredCsvRow = getCsvRowFilterFn(uuidIndex, colIndexesToInclude);
+
+  const rowDocs = rows
+    .map(getDocIdForCsvRow(docType, uuidIndex))
+    .map(id => documentDocs[id]);
+
+  rows
+    .map(getFilteredCsvRow)
+    .map((row, index) => [rowDocs[index], row])
+    .map(processCsvRow(colNamesToInclude));
+  return rowDocs;
+};
 
 const processDocuments =  async (docType, csv, ids, db, args) => {
   const documentDocs = await fetchDocumentList(db, ids, args);
@@ -196,4 +216,4 @@ const parseExtraArgs = (projectDir, extraArgs = []) => {
 module.exports = {
   requiresInstance: true,
   execute
-};
+};

package/src/fn/merge-contacts.js

@@ -0,0 +1,69 @@
+const minimist = require('minimist');
+const path = require('path');
+
+const environment = require('../lib/environment');
+const pouch = require('../lib/db');
+const { info } = require('../lib/log');
+
+const HierarchyOperations = require('../lib/hierarchy-operations');
+
+module.exports = {
+  requiresInstance: true,
+  execute: () => {
+    const args = parseExtraArgs(environment.pathToProject, environment.extraArgs);
+    const db = pouch();
+    const options = {
+      docDirectoryPath: args.docDirectoryPath,
+      force: args.force,
+    };
+    return HierarchyOperations(db, options).merge(args.sourceIds, args.destinationId);
+  }
+};
+
+// Parses extraArgs and asserts if required parameters are not present
+const parseExtraArgs = (projectDir, extraArgs = []) => {
+  const args = minimist(extraArgs, { boolean: true });
+
+  const sourceIds = (args.sources || args.source || '')
+    .split(',')
+    .filter(Boolean);
+
+  if (!args.destination) {
+    usage();
+    throw Error(`Action "merge-contacts" is missing required contact ID ${bold('--destination')}. Other contacts will be merged into this contact.`);
+  }
+
+  if (sourceIds.length === 0) {
+    usage();
+    throw Error(`Action "merge-contacts" is missing required contact ID(s) ${bold('--sources')}. These contacts will be merged into the contact specified by ${bold('--destination')}`);
+  }
+
+  return {
+    destinationId: args.destination,
+    sourceIds,
+    docDirectoryPath: path.resolve(projectDir, args.docDirectoryPath || 'json_docs'),
+    force: !!args.force,
+  };
+};
+
+const bold = text => `\x1b[1m${text}\x1b[0m`;
+const usage = () => {
+  info(`
+${bold('cht-conf\'s merge-contacts action')}
+When combined with 'upload-docs' this action moves all of the contacts and reports under ${bold('sources')} to be under ${bold('destination')}.
+The top-level ${bold('source contact(s)')} are deleted and no data from this document is merged or preserved.
+
+${bold('USAGE')}
+cht --local merge-contacts -- --destination=<destination_id> --sources=<source_id1>,<source_id2>
+
+${bold('OPTIONS')}
+--destination=<destination_id>
+  Specifies the ID of the contact that should receive the moving contacts and reports.
+
+--sources=<source_id1>,<source_id2>
+  A comma delimited list of IDs of contacts which will be deleted. The hierarchy of contacts and reports under it will be moved to be under the destination contact.
+
+--docDirectoryPath=<path to stage docs>
+  Specifies the folder used to store the documents representing the changes in hierarchy.
+`);
+};

package/src/fn/move-contacts.js

@@ -1,105 +1,34 @@
 const minimist = require('minimist');
 const path = require('path');
-const userPrompt = require('../lib/user-prompt');
 
 const environment = require('../lib/environment');
-const fs = require('../lib/sync-fs');
-const lineageManipulation = require('../lib/lineage-manipulation');
-const lineageConstraints = require('../lib/lineage-constraints');
 const pouch = require('../lib/db');
-const { warn, trace, info } = require('../lib/log');
+const { info } = require('../lib/log');
 
-const HIERARCHY_ROOT = 'root';
-const BATCH_SIZE = 10000;
+const HierarchyOperations = require('../lib/hierarchy-operations');
 
 module.exports = {
   requiresInstance: true,
   execute: () => {
     const args = parseExtraArgs(environment.pathToProject, environment.extraArgs);
     const db = pouch();
-    prepareDocumentDirectory(args);
-    return updateLineagesAndStage(args, db);
+    const options = {
+      docDirectoryPath: args.docDirectoryPath,
+      force: args.force,
+    };
+    return HierarchyOperations(db, options).move(args.sourceIds, args.destinationId);
   }
 };
 
-const prettyPrintDocument = doc => `'${doc.name}' (${doc._id})`;
-const updateLineagesAndStage = async (options, db) => {
-  trace(`Fetching contact details for parent: ${options.parentId}`);
-  const parentDoc = await fetch.contact(db, options.parentId);
-
-  const constraints = await lineageConstraints(db, parentDoc);
-  const contactDocs = await fetch.contactList(db, options.contactIds);
-  await validateContacts(contactDocs, constraints);
-
-  let affectedContactCount = 0, affectedReportCount = 0;
-  const replacementLineage = lineageManipulation.createLineageFromDoc(parentDoc);
-  for (let contactId of options.contactIds) {
-    const contactDoc = contactDocs[contactId];
-    const descendantsAndSelf = await fetch.descendantsOf(db, contactId);
-
-    // Check that primary contact is not removed from areas where they are required
-    const invalidPrimaryContactDoc = await constraints.getPrimaryContactViolations(contactDoc, descendantsAndSelf);
-    if (invalidPrimaryContactDoc) {
-      throw Error(`Cannot remove contact ${prettyPrintDocument(invalidPrimaryContactDoc)} from the hierarchy for which they are a primary contact.`);
-    }
-
-    trace(`Considering lineage updates to ${descendantsAndSelf.length} descendant(s) of contact ${prettyPrintDocument(contactDoc)}.`);
-    const updatedDescendants = replaceLineageInContacts(descendantsAndSelf, replacementLineage, contactId);
-
-    const ancestors = await fetch.ancestorsOf(db, contactDoc);
-    trace(`Considering primary contact updates to ${ancestors.length} ancestor(s) of contact ${prettyPrintDocument(contactDoc)}.`);
-    const updatedAncestors = replaceLineageInAncestors(descendantsAndSelf, ancestors);
-
-    minifyLineageAndWriteToDisk([...updatedDescendants, ...updatedAncestors], options);
-
-    const movedReportsCount = await moveReports(db, descendantsAndSelf, options, replacementLineage, contactId);
-    trace(`${movedReportsCount} report(s) created by these affected contact(s) will be updated`);
-
-    affectedContactCount += updatedDescendants.length + updatedAncestors.length;
-    affectedReportCount += movedReportsCount;
-
-    info(`Staged updates to ${prettyPrintDocument(contactDoc)}. ${updatedDescendants.length} contact(s) and ${movedReportsCount} report(s).`);
-  }
-
-  info(`Staged changes to lineage information for ${affectedContactCount} contact(s) and ${affectedReportCount} report(s).`);
-};
-
-/*
-Checks for any errors which this will create in the hierarchy (hierarchy schema, circular hierarchies)
-Confirms the list of contacts are possible to move
-*/
-const validateContacts = async (contactDocs, constraints) => {
-  Object.values(contactDocs).forEach(doc => {
-    const hierarchyError = constraints.getHierarchyErrors(doc);
-    if (hierarchyError) {
-      throw Error(`Hierarchy Constraints: ${hierarchyError}`);
-    }
-  });
-
-  /*
-  It is nice that the tool can move lists of contacts as one operation, but strange things happen when two contactIds are in the same lineage.
-  For example, moving a district_hospital and moving a contact under that district_hospital to a new clinic causes multiple colliding writes to the same json file.
-  */
-  const contactIds = Object.keys(contactDocs);
-  Object.values(contactDocs)
-    .forEach(doc => {
-      const parentIdsOfDoc = (doc.parent && lineageManipulation.pluckIdsFromLineage(doc.parent)) || [];
-      const violatingParentId = parentIdsOfDoc.find(parentId => contactIds.includes(parentId));
-      if (violatingParentId) {
-        throw Error(`Unable to move two documents from the same lineage: '${doc._id}' and '${violatingParentId}'`);
-      }
-    });
-};
-
 // Parses extraArgs and asserts if required parameters are not present
 const parseExtraArgs = (projectDir, extraArgs = []) => {
   const args = minimist(extraArgs, { boolean: true });
 
-  const contactIds = (args.contacts || args.contact || '')
+  const sourceIds = (args.contacts || args.contact || '')
     .split(',')
     .filter(id => id);
 
-  if (contactIds.length === 0) {
+  if (sourceIds.length === 0) {
     usage();
     throw Error('Action "move-contacts" is missing required list of contacts to be moved');
   }
@@ -110,28 +39,15 @@ const parseExtraArgs = (projectDir, extraArgs = []) => {
   }
 
   return {
-    parentId: args.parent,
-    contactIds,
+    destinationId: args.parent,
+    sourceIds,
     docDirectoryPath: path.resolve(projectDir, args.docDirectoryPath || 'json_docs'),
     force: !!args.force,
   };
 };
 
-const prepareDocumentDirectory = ({ docDirectoryPath, force }) => {
-  if (!fs.exists(docDirectoryPath)) {
-    fs.mkdir(docDirectoryPath);
-  } else if (!force && fs.recurseFiles(docDirectoryPath).length > 0) {
-    warn(`The document folder '${docDirectoryPath}' already contains files. It is recommended you start with a clean folder. Do you want to delete the contents of this folder and continue?`);
-    if(userPrompt.keyInYN()) {
-      fs.deleteFilesInFolder(docDirectoryPath);
-    } else {
-      throw new Error('User aborted execution.');
-    }
-  }
-};
-
+const bold = text => `\x1b[1m${text}\x1b[0m`;
 const usage = () => {
-  const bold = text => `\x1b[1m${text}\x1b[0m`;
   info(`
 ${bold('cht-conf\'s move-contacts action')}
 When combined with 'upload-docs' this action effectively moves a contact from one place in the hierarchy to another.
@@ -144,148 +60,9 @@ ${bold('OPTIONS')}
   A comma delimited list of ids of contacts to be moved.
 
 --parent=<parent_id>
-  Specifies the ID of the new parent. Use '${HIERARCHY_ROOT}' to identify the top of the hierarchy (no parent).
+  Specifies the ID of the new parent. Use '${HierarchyOperations.HIERARCHY_ROOT}' to identify the top of the hierarchy (no parent).
 
 --docDirectoryPath=<path to stage docs>
   Specifies the folder used to store the documents representing the changes in hierarchy.
 `);
 };
-
-const moveReports = async (db, descendantsAndSelf, writeOptions, replacementLineage, contactId) => {
-  const contactIds = descendantsAndSelf.map(contact => contact._id);
-
-  let skip = 0;
-  let reportDocsBatch;
-  do {
-    info(`Processing ${skip} to ${skip + BATCH_SIZE} report docs`);
-    reportDocsBatch = await fetch.reportsCreatedBy(db, contactIds, skip);
-
-    const updatedReports = replaceLineageInReports(reportDocsBatch, replacementLineage, contactId);
-    minifyLineageAndWriteToDisk(updatedReports, writeOptions);
-
-    skip += reportDocsBatch.length;
-  } while (reportDocsBatch.length >= BATCH_SIZE);
-
-  return skip;
-};
-
-const minifyLineageAndWriteToDisk = (docs, parsedArgs) => {
-  docs.forEach(doc => {
-    lineageManipulation.minifyLineagesInDoc(doc);
-    writeDocumentToDisk(parsedArgs, doc);
-  });
-};
-
-const writeDocumentToDisk = ({ docDirectoryPath }, doc) => {
-  const destinationPath = path.join(docDirectoryPath, `${doc._id}.doc.json`);
-  if (fs.exists(destinationPath)) {
-    warn(`File at ${destinationPath} already exists and is being overwritten.`);
-  }
-
-  trace(`Writing updated document to ${destinationPath}`);
-  fs.writeJson(destinationPath, doc);
-};
-
-const fetch = {
-  /*
-  Fetches all of the documents associated with the "contactIds" and confirms they exist.
-  */
-  contactList: async (db, ids) => {
-    const contactDocs = await db.allDocs({
-      keys: ids,
-      include_docs: true,
-    });
-
-    const missingContactErrors = contactDocs.rows.filter(row => !row.doc).map(row => `Contact with id '${row.key}' could not be found.`);
-    if (missingContactErrors.length > 0) {
-      throw Error(missingContactErrors);
-    }
-
-    return contactDocs.rows.reduce((agg, curr) => Object.assign(agg, { [curr.doc._id]: curr.doc }), {});
-  },
-
-  contact: async (db, id) => {
-    try {
-      if (id === HIERARCHY_ROOT) {
-        return undefined;
-      }
-
-      return await db.get(id);
-    } catch (err) {
-      if (err.name !== 'not_found') {
-        throw err;
-      }
-
-      throw Error(`Contact with id '${id}' could not be found`);
-    }
-  },
-
-  /*
-  Given a contact's id, obtain the documents of all descendant contacts
-  */
-  descendantsOf: async (db, contactId) => {
-    const descendantDocs = await db.query('medic/contacts_by_depth', {
-      key: [contactId],
-      include_docs: true,
-    });
-
-    return descendantDocs.rows
-      .map(row => row.doc)
-      /* We should not move or update tombstone documents */
-      .filter(doc => doc && doc.type !== 'tombstone');
-  },
-
-  reportsCreatedBy: async (db, contactIds, skip) => {
-    const reports = await db.query('medic-client/reports_by_freetext', {
-      keys: contactIds.map(id => [`contact:${id}`]),
-      include_docs: true,
-      limit: BATCH_SIZE,
-      skip: skip,
-    });
-
-    return reports.rows.map(row => row.doc);
-  },
-
-  ancestorsOf: async (db, contactDoc) => {
-    const ancestorIds = lineageManipulation.pluckIdsFromLineage(contactDoc.parent);
-    const ancestors = await db.allDocs({
-      keys: ancestorIds,
-      include_docs: true,
-    });
-
-    const ancestorIdsNotFound = ancestors.rows.filter(ancestor => !ancestor.doc).map(ancestor => ancestor.key);
-    if (ancestorIdsNotFound.length > 0) {
-      throw Error(`Contact '${prettyPrintDocument(contactDoc)} has parent id(s) '${ancestorIdsNotFound.join(',')}' which could not be found.`);
-    }
-
-    return ancestors.rows.map(ancestor => ancestor.doc);
-  },
-};
-
-const replaceLineageInReports = (reportsCreatedByDescendants, replaceWith, startingFromIdInLineage) => reportsCreatedByDescendants.reduce((agg, doc) => {
-  if (lineageManipulation.replaceLineage(doc, 'contact', replaceWith, startingFromIdInLineage)) {
-    agg.push(doc);
-  }
-  return agg;
-}, []);
-
-const replaceLineageInContacts = (descendantsAndSelf, replacementLineage, contactId) => descendantsAndSelf.reduce((agg, doc) => {
-  const startingFromIdInLineage = doc._id === contactId ? undefined : contactId;
-  const parentWasUpdated = lineageManipulation.replaceLineage(doc, 'parent', replacementLineage, startingFromIdInLineage);
-  const contactWasUpdated = lineageManipulation.replaceLineage(doc, 'contact', replacementLineage, contactId);
-  if (parentWasUpdated || contactWasUpdated) {
-    agg.push(doc);
-  }
-  return agg;
-}, []);
-
-const replaceLineageInAncestors = (descendantsAndSelf, ancestors) => ancestors.reduce((agg, ancestor) => {
-  let result = agg;
-  const primaryContact = descendantsAndSelf.find(descendant => ancestor.contact && descendant._id === ancestor.contact._id);
-  if (primaryContact) {
-    ancestor.contact = lineageManipulation.createLineageFromDoc(primaryContact);
-    result = [ancestor, ...result];
-  }
-
-  return result;
-}, []);

package/src/lib/hierarchy-operations/hierarchy-data-source.js

@@ -0,0 +1,103 @@
+const lineageManipulation = require('./lineage-manipulation');
+
+const HIERARCHY_ROOT = 'root';
+const BATCH_SIZE = 10000;
+
+/*
+Fetches all of the documents associated with the "contactIds" and confirms they exist.
+*/
+async function getContactsByIds(db, ids) {
+  const contactDocs = await db.allDocs({
+    keys: ids,
+    include_docs: true,
+  });
+
+  const missingContactErrors = contactDocs.rows.filter(row => !row.doc).map(row => `Contact with id '${row.key}' could not be found.`);
+  if (missingContactErrors.length > 0) {
+    throw Error(missingContactErrors);
+  }
+
+  const contactDict = {};
+  contactDocs.rows.forEach(({ doc }) => contactDict[doc._id] = doc);
+  return contactDict;
+}
+
+async function getContact(db, id) {
+  try {
+    if (id === HIERARCHY_ROOT) {
+      return undefined;
+    }
+
+    return await db.get(id);
+  } catch (err) {
+    if (err.status !== 404) {
+      throw err;
+    }
+
+    throw Error(`Contact with id '${id}' could not be found`);
+  }
+}
+
+/*
+Given a contact's id, obtain the documents of all descendant contacts
+*/
+async function getContactWithDescendants(db, contactId) {
+  const descendantDocs = await db.query('medic/contacts_by_depth', {
+    key: [contactId],
+    include_docs: true,
+  });
+
+  return descendantDocs.rows
+    .map(row => row.doc)
+    // We should not move or update tombstone documents
+    // Not relevant for 4.x cht-core versions, but needed in older versions.
+    .filter(doc => doc && doc.type !== 'tombstone');
+}
+
+async function getReportsForContacts(db, createdByIds, createdAtId, skip) {
+  const createdByKeys = createdByIds.map(id => [`contact:${id}`]);
+  const createdAtKeys = createdAtId ? [
+    [`patient_id:${createdAtId}`],
+    [`patient_uuid:${createdAtId}`],
+    [`place_id:${createdAtId}`],
+    [`place_uuid:${createdAtId}`]
+  ] : [];
+
+  const reports = await db.query('medic-client/reports_by_freetext', {
+    keys: [
+      ...createdByKeys,
+      ...createdAtKeys,
+    ],
+    include_docs: true,
+    limit: BATCH_SIZE,
+    skip,
+  });
+
+  const docsWithId = reports.rows.map(({ doc }) => [doc._id, doc]);
+  return Array.from(new Map(docsWithId).values());
+}
+
+async function getAncestorsOf(db, contactDoc) {
+  const ancestorIds = lineageManipulation.pluckIdsFromLineage(contactDoc.parent);
+  const ancestors = await db.allDocs({
+    keys: ancestorIds,
+    include_docs: true,
+  });
+
+  const ancestorIdsNotFound = ancestors.rows.filter(ancestor => !ancestor.doc).map(ancestor => ancestor.key);
+  if (ancestorIdsNotFound.length > 0) {
+    throw Error(`Contact '${contactDoc?.name}' (${contactDoc?._id}) has parent id(s) '${ancestorIdsNotFound.join(',')}' which could not be found.`);
+  }
+
+  return ancestors.rows.map(ancestor => ancestor.doc);
+}
+
+module.exports = {
+  BATCH_SIZE,
+  HIERARCHY_ROOT,
+  getAncestorsOf,
+  getContactWithDescendants,
+  getContact,
+  getContactsByIds,
+  getReportsForContacts,
+};