Add support to cht-datasource for getting a person with lineage

api/src/controllers/person.js

@@ -3,14 +3,18 @@ const ctx = require('../services/data-context');
 const serverUtils = require('../server-utils');
 const auth = require('../auth');
 
-const getPerson = (qualifier) => ctx.bind(Person.v1.get)(qualifier);
+const getPerson = ({ withLineage }) => ctx.bind(
+  withLineage
+    ? Person.v1.getWithLineage
+    : Person.v1.get
+);
 
 module.exports = {
   v1: {
     get: serverUtils.doOrError(async (req, res) => {
       await auth.check(req, 'can_view_contacts');
       const { uuid } = req.params;
-      const person = await getPerson(Qualifier.byUuid(uuid));
+      const person = await getPerson(req.query)(Qualifier.byUuid(uuid));
       if (!person) {
         return serverUtils.error({ status: 404, message: 'Person not found' }, req, res);
       }

shared-libs/cht-datasource/.eslintrc.js

@@ -31,6 +31,7 @@ module.exports = {
         ['@typescript-eslint/no-confusing-void-expression']: ['error', { ignoreArrowShorthand: true }],
         ['@typescript-eslint/no-empty-interface']: ['error', { allowSingleExtends: true }],
         ['@typescript-eslint/no-namespace']: 'off',
+        ['@typescript-eslint/no-non-null-assertion']: 'off',
         ['jsdoc/require-jsdoc']: ['error', {
           require: {
             ArrowFunctionExpression: true,

shared-libs/cht-datasource/src/libs/core.ts

@@ -5,6 +5,9 @@ import { DataContext } from './data-context';
  */
 export type Nullable<T> = T | null;
 
+/** @internal */
+export const isNotNull = <T>(value: T | null): value is T => value !== null;
+
 /**
  * An array that is guaranteed to have at least one element.
  */
@@ -38,18 +41,30 @@ export const isDataObject = (value: unknown): value is DataObject => {
   if (!isRecord(value)) {
     return false;
   }
-  return Object.values(value).every((v) => isDataPrimitive(v) || isDataArray(v) || isDataObject(v));
+  return Object
+    .values(value)
+    .every((v) => isDataPrimitive(v) || isDataArray(v) || isDataObject(v));
 };
 
-/** @internal */
+/**
+ * Ideally, this function should only be used at the edge of this library (when returning potentially cross-referenced
+ * data objects) to avoid unintended consequences if any of the objects are edited in-place. This function should not
+ * be used for logic internal to this library since all data objects are marked as immutable.
+ * @internal
+ */
 export const deepCopy = <T extends DataObject | DataArray | DataPrimitive>(value: T): T => {
   if (isDataPrimitive(value)) {
     return value;
   }
   if (isDataArray(value)) {
     return value.map(deepCopy) as unknown as T;
   }
-  return { ...Object.values(value).map(deepCopy) } as unknown as T;
+
+  return Object.fromEntries(
+    Object
+      .entries(value)
+      .map(([key, value]) => [key, deepCopy(value)])
+  ) as unknown as T;
 };
 
 /** @internal */
@@ -74,6 +89,17 @@ export const hasFields = (
   fields: NonEmptyArray<{ name: string, type: string }>
 ): boolean => fields.every(field => hasField(value, field));
 
+/** @internal */
+export interface Identifiable { readonly _id: string }
+
+/** @internal */
+export const isIdentifiable = (value: unknown): value is { readonly _id: string } => isRecord(value)
+  && hasField(value, { name: '_id', type: 'string' });
+
+/** @internal */
+export const findById = <T extends Identifiable>(values: T[], id: string): Nullable<T> => values
+  .find(v => v._id === id) ?? null;
+
 /** @internal */
 export abstract class AbstractDataContext implements DataContext {
   readonly bind = <T>(fn: (ctx: DataContext) => T): T => fn(this);

shared-libs/cht-datasource/src/libs/doc.ts

@@ -1,17 +1,13 @@
-import { DataObject, hasFields, isRecord } from './core';
+import { DataObject, hasField, Identifiable, isIdentifiable, isRecord } from './core';
 
 /**
  * A document from the database.
  */
-export interface Doc extends DataObject {
-  readonly _id: string;
+export interface Doc extends DataObject, Identifiable {
   readonly _rev: string;
 }
 
 /** @internal */
-export const isDoc = (value: unknown): value is Doc => {
-  return isRecord(value) && hasFields(value, [
-    { name: '_id', type: 'string' },
-    { name: '_rev', type: 'string' }
-  ]);
-};
+export const isDoc = (value: unknown): value is Doc => isRecord(value)
+  && isIdentifiable(value)
+  && hasField(value, { name: '_rev', type: 'string' });

shared-libs/cht-datasource/src/local/libs/doc.ts

@@ -18,28 +18,24 @@ export const getDocById = (db: PouchDB.Database<Doc>) => async (uuid: string): P
 /** @internal */
 export const getDocsByIds = (db: PouchDB.Database<Doc>) => async (uuids: string[]): Promise<Doc[]> => {
   const keys = Array.from(new Set(uuids.filter(uuid => uuid.length)));
-  if (keys.length === 0) {
+  if (!keys.length) {
     return [];
   }
   const response = await db.allDocs({ keys, include_docs: true });
   return response.rows
-    .filter(row => isDoc(row.doc))
-    .map(row => row.doc as Doc);
+    .map(({ doc }) => doc)
+    .filter((doc): doc is Doc => isDoc(doc));
 };
 
-/**
- * Returns the identified document along with the parent documents recorded for its lineage. The returned array is
- * sorted such that the identified document is the first element and the parent documents are in order of lineage.
- * @internal
- */
-export const getLineageDocsById = (medicDb: PouchDB.Database<Doc>) => (
-  uuid: string
-): Promise<Nullable<Doc>[]> => medicDb
-  .query('medic-client/docs_by_id_lineage', {
-    startkey: [uuid],
-    endkey: [uuid, {}],
+/** @internal */
+export const queryDocsByKey = (
+  db: PouchDB.Database<Doc>,
+  view: string
+) => async (key: string): Promise<Nullable<Doc>[]> => db
+  .query(view, {
+    startkey: [key],
+    endkey: [key, {}],
     include_docs: true
   })
-  .then(({ rows }) => rows
-    .map(({ doc }) => doc ?? null)
-    .filter((doc): doc is Nullable<Doc> => doc === null || isDoc(doc)));
+  .then(({ rows }) => rows.map(({ doc }) => isDoc(doc) ? doc : null));
+

shared-libs/cht-datasource/src/local/libs/lineage.ts

@@ -0,0 +1,83 @@
+import { Contact, NormalizedParent } from '../../libs/contact';
+import {
+  DataObject,
+  findById,
+  isIdentifiable,
+  isNonEmptyArray,
+  isNotNull,
+  NonEmptyArray,
+  Nullable
+} from '../../libs/core';
+import { Doc } from '../../libs/doc';
+import { queryDocsByKey } from './doc';
+
+/**
+ * Returns the identified document along with the parent documents recorded for its lineage. The returned array is
+ * sorted such that the identified document is the first element and the parent documents are in order of lineage.
+ * @internal
+ */
+export const getLineageDocsById = (
+  medicDb: PouchDB.Database<Doc>
+): (id: string) => Promise<Nullable<Doc>[]> => queryDocsByKey(medicDb, 'medic-client/docs_by_id_lineage');
+
+/** @internal */
+export const getPrimaryContactIds = (places: NonEmptyArray<Nullable<Doc>>): string[] => places
+  .filter(isNotNull)
+  .map(({ contact }) => contact)
+  .filter(isIdentifiable)
+  .map(({ _id }) => _id)
+  .filter((_id) => _id.length > 0);
+
+/** @internal */
+export const hydratePrimaryContact = (contacts: Doc[]) => (place: Nullable<Doc>): Nullable<Doc> => {
+  if (!place || !isIdentifiable(place.contact)) {
+    return place;
+  }
+  const contact = findById(contacts, place.contact._id);
+  if (!contact) {
+    return place;
+  }
+  return {
+    ...place,
+    contact
+  };
+};
+
+const getParentUuid = (index: number, contact?: NormalizedParent): Nullable<string> => {
+  if (!contact) {
+    return null;
+  }
+  if (index === 0) {
+    return contact._id;
+  }
+  return getParentUuid(index - 1, contact.parent);
+};
+
+const mergeLineage = (lineage: DataObject[], parent: DataObject): DataObject => {
+  if (!isNonEmptyArray(lineage)) {
+    return parent;
+  }
+  const child = lineage.at(-1)!;
+  const mergedChild = {
+    ...child,
+    parent: parent
+  };
+  return mergeLineage(lineage.slice(0, -1), mergedChild);
+};
+
+/** @internal */
+export const hydrateLineage = (
+  contact: Contact,
+  lineage: Nullable<Doc>[]
+): Contact => {
+  const fullLineage = lineage
+    .map((place, index) => {
+      if (place) {
+        return place;
+      }
+      // If no doc was found, just add a placeholder object with the id from the contact
+      return { _id: getParentUuid(index, contact.parent) };
+    });
+  const hierarchy = [contact, ...fullLineage];
+  return mergeLineage(hierarchy.slice(0, -1), hierarchy.at(-1)!) as Contact;
+};

shared-libs/cht-datasource/src/local/person.ts

@@ -1,13 +1,13 @@
 import { Doc } from '../libs/doc';
 import contactTypeUtils from '@medic/contact-types-utils';
-import { isNonEmptyArray, Nullable } from '../libs/core';
+import { deepCopy, isNonEmptyArray, Nullable } from '../libs/core';
 import { UuidQualifier } from '../qualifier';
 import * as Person from '../person';
-import { getDocById, getLineageDocsById } from './libs/doc';
+import { getDocById, getDocsByIds } from './libs/doc';
 import { LocalDataContext, SettingsService } from './libs/data-context';
-import { getContactWithLineage } from './libs/contact';
 import { isNormalizedParent } from '../libs/contact';
 import logger from '@medic/logger';
+import { getLineageDocsById, getPrimaryContactIds, hydrateLineage, hydratePrimaryContact } from './libs/lineage';
 
 /** @internal */
 export namespace v1 {
@@ -39,17 +39,23 @@ export namespace v1 {
   /** @internal */
   export const getWithLineage = ({ medicDb, settings }: LocalDataContext) => {
     const getLineageDocs = getLineageDocsById(medicDb);
+    const getMedicDocsById = getDocsByIds(medicDb);
     return async (identifier: UuidQualifier): Promise<Nullable<Person.v1.PersonWithLineage>> => {
       const [person, ...lineagePlaces] = await getLineageDocs(identifier.uuid);
       if (!isPerson(settings, identifier.uuid, person)) {
         return null;
       }
-      // Intentionally not validating lineage. For passivity, we do not want lineage problems to block retrieval.
+      // Intentionally not further validating lineage. For passivity, lineage problems should not block retrieval.
       if (!isNonEmptyArray(lineagePlaces)) {
         return person;
       }
 
-      return getContactWithLineage(medicDb, person, lineagePlaces);
+      const contactUuids = getPrimaryContactIds(lineagePlaces)
+        .filter(uuid => uuid !== person._id);
+      const contacts = [person, ...await getMedicDocsById(contactUuids)];
+      const linagePlacesWithContact = lineagePlaces.map(hydratePrimaryContact(contacts));
+      const personWithLineage = hydrateLineage(person, linagePlacesWithContact);
+      return deepCopy(personWithLineage);
     };
   };
 }

shared-libs/cht-datasource/src/person.ts

@@ -45,4 +45,19 @@ export namespace v1 {
       return getPerson(qualifier);
     };
   };
+
+  /**
+   * Returns a person for the given qualifier with the person's hierarchy lineage included.
+   * @param context the current data context
+   * @returns the person or `null` if no person is found for the qualifier
+   * @throws Error if the provided context or qualifier is invalid
+   */
+  export const getWithLineage = (context: DataContext) => {
+    assertDataContext(context);
+    const getPerson = adapt(context, Local.Person.v1.getWithLineage, Remote.Person.v1.getWithLineage);
+    return async (qualifier: UuidQualifier): Promise<Nullable<PersonWithLineage>> => {
+      assertPersonQualifier(qualifier);
+      return getPerson(qualifier);
+    };
+  };
 }