new: functionality for dataset/:name/entities added (getodk#823)

* new: functionality for dataset/:name/entities added

* updated get query to conditionally include submission and form information
Added more tests

* remove temp migration

* use Promise.all instead of waiting in forEach

* use Entity.Def.Metadata directly in the extender instead of manipulating the results
lower case api in source type

* incorporated PR comments

Author: sadiqkhoja

lib/model/frames/entity.js

@@ -9,16 +9,18 @@
 
 /* eslint-disable no-multi-spaces */
 
-const { embedded, Frame, table } = require('../frame');
+const { embedded, Frame, readable, table } = require('../frame');
 const { parseSubmissionXml } = require('../../data/entity');
 
 // These Frames don't interact with APIs directly, hence no readable/writable
 class Entity extends Frame.define(
   table('entities'),
-  'id',                  'uuid',
+  'id',                     'uuid', readable,
   'datasetId',
-  'createdAt',           'creatorId',
-  embedded('creator')
+  'createdAt', readable,    'creatorId', readable,
+  'updatedAt', readable,    'deletedAt', readable,
+  embedded('creator'),
+  embedded('currentVersion')
 ) {
   get def() { return this.aux.def; }
 
@@ -41,11 +43,24 @@ Entity.Partial = class extends Entity {};
 
 Entity.Def = Frame.define(
   table('entity_defs', 'def'),
-  'id',                  'entityId',
-  'createdAt',           'current',
-  'submissionDefId',
-  'label',
-  'data'
+  'id',                         'entityId',
+  'createdAt', readable,        'current', readable,
+  'submissionDefId',            'label', readable,
+  'creatorId', readable,        'userAgent', readable,
+  'data', readable,
+  embedded('creator'),
+  embedded('source')
 );
 
+Entity.Def.Metadata = class extends Entity.Def {
+
+  // we don't want `data` to be selected from database, hence return in forApi()
+  static get fields() {
+    return super.fields.filter(f => f !== 'data');
+  }
+};
+
+Entity.Def.Source = Frame.define(
+  'type', readable,             'details', readable
+);
 module.exports = { Entity };

lib/model/query/entities.js

@@ -8,13 +8,14 @@
 // except according to the terms contained in the LICENSE file.
 
 const { sql } = require('slonik');
-const { Actor, Entity } = require('../frames');
-const { unjoiner, page } = require('../../util/db');
+const { Actor, Entity, Submission, Form } = require('../frames');
+const { equals, extender, unjoiner, page } = require('../../util/db');
 const { map } = require('ramda');
 const { construct } = require('../../util/util');
 const { QueryOptions } = require('../../util/db');
 const { odataFilter } = require('../../data/odata-filter');
 const { odataToColumnMap } = require('../../data/entity');
+const { isTrue } = require('../../util/http');
 
 ////////////////////////////////////////////////////////////////////////////////
 // ENTITY CREATE
@@ -119,6 +120,60 @@ const processSubmissionEvent = (event) => (container) =>
 ////////////////////////////////////////////////////////////////////////////////
 // GETTING ENTITIES
 
+const _get = (includeSource) => {
+  const frames = [Entity];
+  if (includeSource) {
+    frames.push(Entity.Def.into('currentVersion'), Submission, Submission.Def.into('submissionDef'), Form);
+  } else {
+    frames.push(Entity.Def.Metadata.into('currentVersion'));
+  }
+  return extender(...frames)(Actor.into('creator'), Actor.alias('current_version_actors', 'currentVersionCreator'))((fields, extend, options, deleted = false) =>
+    sql`
+  SELECT ${fields} FROM entities
+  INNER JOIN entity_defs
+      ON entities.id = entity_defs."entityId" AND entity_defs.current
+  ${extend||sql`
+    LEFT JOIN actors ON actors.id=entities."creatorId"
+    LEFT JOIN actors current_version_actors ON current_version_actors.id=entity_defs."creatorId"
+  `}
+  ${!includeSource ? sql`` : sql`
+    LEFT JOIN submission_defs ON submission_defs.id = entity_defs."submissionDefId"
+    LEFT JOIN (
+      SELECT submissions.*, submission_defs."userAgent" FROM submissions
+      JOIN submission_defs ON submissions.id = submission_defs."submissionId" AND root
+    ) submissions ON submissions.id = submission_defs."submissionId"
+    LEFT JOIN forms ON submissions."formId" = forms.id
+  `} 
+  where ${equals(options.condition)} and entities."deletedAt" is ${deleted ? sql`not` : sql``} null
+  order by entity_defs.id, entities."createdAt" desc, entities.id desc
+`);
+};
+
+const getById = (datasetId, uuid, options = QueryOptions.none) => ({ maybeOne }) =>
+  _get(true)(maybeOne, options.withCondition({ datasetId, uuid }), isTrue(options.argData.deleted))
+    .then(map((entity) => {
+      const isSourceSubmission = !!entity.aux.currentVersion.submissionDefId;
+
+      // TODO: revisit this when working on POST /entities
+      const source = new Entity.Def.Source({
+        type: isSourceSubmission ? 'submission' : 'api',
+        details: isSourceSubmission ? {
+          xmlFormId: entity.aux.form.xmlFormId,
+          instanceId: entity.aux.submission.instanceId,
+          instanceName: entity.aux.submissionDef.instanceName
+        } : null
+      });
+
+      const currentVersion = new Entity.Def(entity.aux.currentVersion, { creator: entity.aux.currentVersionCreator, source });
+
+      return new Entity(entity, { currentVersion, creator: entity.aux.creator });
+    }));
+
+const getAll = (datasetId, options = QueryOptions.none) => ({ all }) =>
+  _get(false)(all, options.withCondition({ datasetId }), isTrue(options.argData.deleted))
+    .then(map((e) => e.withAux('currentVersion', e.aux.currentVersion.withAux('creator', e.aux.currentVersionCreator))));
+
+
 // This will check for an entity related to any def of the same submission
 // as the one specified. Used when trying to reapprove an edited submission.
 const getDefBySubmissionId = (submissionId) => ({ maybeOne }) =>
@@ -161,5 +216,6 @@ module.exports = {
   createNew, _processSubmissionDef,
   processSubmissionEvent, streamForExport,
   getDefBySubmissionId, getByUuid,
-  countByDatasetId
+  countByDatasetId, getById,
+  getAll
 };

lib/resources/entities.js

@@ -36,60 +36,24 @@ const getEntity = (i) => ({
   creatorId: 1
 });
 
-const populateEntities = () => {
-  const entities = [];
-  for (let i = 1; i <= 5; i+=1) {
-    entities.push({
-      ...getEntity(i),
-      currentVersion: getEntityDef()
-    });
-  }
-  return entities;
-};
-
 module.exports = (service, endpoint) => {
 
-  service.get('/projects/:id/datasets/:name/entities', endpoint(async ({ Projects }, { params, queryOptions, query }) => {
-
-    await Projects.getById(params.id, queryOptions).then(getOrNotFound);
-    const entities = populateEntities();
+  service.get('/projects/:projectId/datasets/:name/entities', endpoint(async ({ Datasets, Entities }, { params, auth, queryOptions }) => {
 
-    if (queryOptions.extended) {
-      for (let i = 0; i < 5; i+=1) {
-        entities[i].currentVersion.creator = getActor();
-        entities[i].creator = getActor();
-      }
-    }
+    const dataset = await Datasets.get(params.projectId, params.name, true).then(getOrNotFound);
 
-    if (query.deleted) {
-      entities[4].deletedAt = new Date();
-      return [entities[4]];
-    }
+    await auth.canOrReject('entity.list', dataset);
 
-    return entities;
+    return Entities.getAll(dataset.id, queryOptions);
   }));
 
-  service.get('/projects/:id/datasets/:name/entities/:uuid', endpoint(async ({ Projects }, { params, queryOptions }) => {
+  service.get('/projects/:projectId/datasets/:name/entities/:uuid', endpoint(async ({ Datasets, Entities }, { params, auth, queryOptions }) => {
 
-    await Projects.getById(params.id, queryOptions).then(getOrNotFound);
-    const entity = getEntity(1);
-    entity.updatedAt = '2023-01-02T09:00:00.000Z';
-    entity.currentVersion = {
-      ...getEntityDef(),
-      source: {
-        type: 'api',
-        details: null
-      },
-      data: {
-        firstName: 'Jane',
-        lastName: 'Roe',
-        city: 'Toronto'
-      },
-      versionNumber: 2,
-      label: 'Jane Roe',
-      createdAt: '2023-01-02T09:00:00.000Z'
-    };
-    return entity;
+    const dataset = await Datasets.get(params.projectId, params.name, true).then(getOrNotFound);
+
+    await auth.canOrReject('entity.read', dataset);
+
+    return Entities.getById(dataset.id, params.uuid, queryOptions).then(getOrNotFound);
   }));
 
   service.get('/projects/:id/datasets/:name/entities/:uuid/versions', endpoint(async ({ Projects }, { params, queryOptions }) => {

test/assertions.js

@@ -358,7 +358,6 @@ should.Assertion.add('EntityDef', function assertEntityDef() {
   this.params = { operator: 'to be an Entity Def (version)' };
 
 
-  this.obj.should.have.property('versionNumber').which.is.a.Number(); // May not be needed
   this.obj.should.have.property('label').which.is.a.String();
   this.obj.should.have.property('current').which.is.a.Boolean();
   this.obj.should.have.property('createdAt').which.is.a.isoDate();
@@ -389,14 +388,14 @@ should.Assertion.add('EntitySource', function Source() {
   this.obj.should.have.property('details');
 
   // details are there only in case of type is submission
-  if (this.obj.details != null) this.obj.details.should.be.SubmissionDetails();
+  if (this.obj.details != null) this.obj.details.should.be.EntitySourceSubmissionDetails();
 });
 
 // Entity Source Submission Details
-should.Assertion.add('SubmissionDetails', function SubmissionDetails() {
-  this.params = { operator: 'have Submission details' };
+should.Assertion.add('EntitySourceSubmissionDetails', function SubmissionDetails() {
+  this.params = { operator: 'have Entity Source Submission details' };
 
   this.obj.should.have.property('xmlFormId').which.is.a.String();
   this.obj.should.have.property('instanceId').which.is.a.String();
-  this.obj.should.have.property('instanceName').which.is.a.String();
+  this.obj.should.have.property('instanceName'); // can be null
 });