From 775ea2935922dd04cd82a542c0ca9e017a1c6c92 Mon Sep 17 00:00:00 2001 From: Taylor Downs Date: Tue, 21 Dec 2021 23:12:15 -0700 Subject: [PATCH] add dv, update docs --- ast.json | 140 ++++++++++++++++++++++++++++++++++--------------- lib/Adaptor.js | 115 +++++++++++++++++++++++----------------- src/Adaptor.js | 108 ++++++++++++++++++++++---------------- 3 files changed, 229 insertions(+), 134 deletions(-) diff --git a/ast.json b/ast.json index de33138..2fa6fda 100644 --- a/ast.json +++ b/ast.json @@ -74,57 +74,57 @@ { "title": "example", "description": "create('programs', {\n name: 'name 20',\n shortName: 'n20',\n programType: 'WITHOUT_REGISTRATION',\n});", - "caption": "-a `program`" + "caption": "a program" }, { "title": "example", "description": "create('events', {\n program: 'eBAyeGv0exc',\n orgUnit: 'DiszpKrYNg8',\n status: 'COMPLETED',\n});", - "caption": "-an `event`" + "caption": "an event" }, { "title": "example", "description": "create('trackedEntityInstances', {\n orgUnit: 'TSyzvBiovKh',\n trackedEntityType: 'nEenWmSyUEp',\n attributes: [\n {\n attribute: 'w75KJ2mc4zz',\n value: 'Gigiwe',\n },\n ]\n});", - "caption": "-a `trackedEntityInstance`" + "caption": "a trackedEntityInstance" }, { "title": "example", "description": "create('dataSets', { name: 'OpenFn Data Set', periodType: 'Monthly' });", - "caption": "-a `dataSet`" + "caption": "a dataSet" }, { "title": "example", "description": "create('dataSetNotificationTemplates', {\n dataSetNotificationTrigger: 'DATA_SET_COMPLETION',\n notificationRecipient: 'ORGANISATION_UNIT_CONTACT',\n name: 'Notification',\n messageTemplate: 'Hello',\n deliveryChannels: ['SMS'],\n dataSets: [],\n});", - "caption": "-a `dataSetNotification`" + "caption": "a dataSetNotification" }, { "title": "example", "description": "create('dataElements', {\n aggregationType: 'SUM',\n domainType: 'AGGREGATE',\n valueType: 'NUMBER',\n name: 'Paracetamol',\n shortName: 'Para',\n});", - "caption": "-a `dataElement`" + "caption": "a dataElement" }, { "title": "example", "description": "create('dataElementGroups', {\n name: 'Data Element Group 1',\n dataElements: [],\n});", - "caption": "-a `dataElementGroup`" + "caption": "a dataElementGroup" }, { "title": "example", "description": "create('dataElementGroupSets', {\n name: 'Data Element Group Set 4',\n dataDimension: true,\n shortName: 'DEGS4',\n dataElementGroups: [],\n});", - "caption": "-a `dataElementGroupSet`" + "caption": "a dataElementGroupSet" }, { "title": "example", "description": "create('dataValueSets', {\n dataElement: 'f7n9E0hX8qk',\n period: '201401',\n orgUnit: 'DiszpKrYNg8',\n value: '12',\n});", - "caption": "-a `dataValueSet`" + "caption": "a dataValueSet" }, { "title": "example", "description": "create('dataValueSets', {\n dataSet: 'pBOMPrpg1QX',\n completeDate: '2014-02-03',\n period: '201401',\n orgUnit: 'DiszpKrYNg8',\n dataValues: [\n {\n dataElement: 'f7n9E0hX8qk',\n value: '1',\n },\n {\n dataElement: 'Ix2HsbDMLea',\n value: '2',\n },\n {\n dataElement: 'eY5ehpbEsB7',\n value: '3',\n },\n ],\n});", - "caption": "-a `dataValueSet` with related `dataValues`" + "caption": "a dataValueSet with related dataValues" }, { "title": "example", "description": "create('enrollments', {\n trackedEntityInstance: 'bmshzEacgxa',\n orgUnit: 'TSyzvBiovKh',\n program: 'gZBxv9Ujxg0',\n enrollmentDate: '2013-09-17',\n incidentDate: '2013-09-17',\n});", - "caption": "-an `enrollment`" + "caption": "an enrollment" } ] }, @@ -214,52 +214,52 @@ { "title": "example", "description": "update('programs', 'qAZJCrNJK8H', {\n name: '14e1aa02c3f0a31618e096f2c6d03bed',\n shortName: '14e1aa02',\n programType: 'WITHOUT_REGISTRATION',\n});", - "caption": "-a program" + "caption": "a program" }, { "title": "example", "description": "update('events', 'PVqUD2hvU4E', {\n program: 'eBAyeGv0exc',\n orgUnit: 'Ngelehun CHC',\n status: 'COMPLETED',\n storedBy: 'admin',\n dataValues: [],\n});", - "caption": "an `event`" + "caption": "an event" }, { "title": "example", "description": "update('trackedEntityInstances', 'IeQfgUtGPq2', {\n created: '2015-08-06T21:12:37.256',\n orgUnit: 'TSyzvBiovKh',\n createdAtClient: '2015-08-06T21:12:37.256',\n trackedEntityInstance: 'IeQfgUtGPq2',\n lastUpdated: '2015-08-06T21:12:37.257',\n trackedEntityType: 'nEenWmSyUEp',\n inactive: false,\n deleted: false,\n featureType: 'NONE',\n programOwners: [\n {\n ownerOrgUnit: 'TSyzvBiovKh',\n program: 'IpHINAT79UW',\n trackedEntityInstance: 'IeQfgUtGPq2',\n },\n ],\n enrollments: [],\n relationships: [],\n attributes: [\n {\n lastUpdated: '2016-01-12T00:00:00.000',\n displayName: 'Last name',\n created: '2016-01-12T00:00:00.000',\n valueType: 'TEXT',\n attribute: 'zDhUuAYrxNC',\n value: 'Russell',\n },\n {\n lastUpdated: '2016-01-12T00:00:00.000',\n code: 'MMD_PER_NAM',\n displayName: 'First name',\n created: '2016-01-12T00:00:00.000',\n valueType: 'TEXT',\n attribute: 'w75KJ2mc4zz',\n value: 'Catherine',\n },\n ],\n});", - "caption": "a `trackedEntityInstance`" + "caption": "a trackedEntityInstance" }, { "title": "example", "description": "update('dataSets', 'lyLU2wR22tC', { name: 'OpenFN Data Set', periodType: 'Weekly' });", - "caption": "-a `dataSet`" + "caption": "a dataSet" }, { "title": "example", "description": "update('dataSetNotificationTemplates', 'VbQBwdm1wVP', {\n dataSetNotificationTrigger: 'DATA_SET_COMPLETION',\n notificationRecipient: 'ORGANISATION_UNIT_CONTACT',\n name: 'Notification',\n messageTemplate: 'Hello Updated,\n deliveryChannels: ['SMS'],\n dataSets: [],\n});", - "caption": "-a `dataSetNotification`" + "caption": "a dataSetNotification" }, { "title": "example", "description": "update('dataElements', 'FTRrcoaog83', {\n aggregationType: 'SUM',\n domainType: 'AGGREGATE',\n valueType: 'NUMBER',\n name: 'Paracetamol',\n shortName: 'Para',\n});", - "caption": "-a `dataElement`" + "caption": "a dataElement" }, { "title": "example", "description": "update('dataElementGroups', 'QrprHT61XFk', {\n name: 'Data Element Group 1',\n dataElements: [],\n});", - "caption": "-a `dataElementGroup`" + "caption": "a dataElementGroup" }, { "title": "example", "description": "update('dataElementGroupSets', 'VxWloRvAze8', {\n name: 'Data Element Group Set 4',\n dataDimension: true,\n shortName: 'DEGS4',\n dataElementGroups: [],\n});", - "caption": "-a `dataElementGroupSet`" + "caption": "a dataElementGroupSet" }, { "title": "example", "description": "update('dataValueSets', 'AsQj6cDsUq4', {\n dataElement: 'f7n9E0hX8qk',\n period: '201401',\n orgUnit: 'DiszpKrYNg8',\n value: '12',\n});", - "caption": "-a `dataValueSet`" + "caption": "a dataValueSet" }, { "title": "example", "description": "update('dataValueSets', 'Ix2HsbDMLea', {\n dataSet: 'pBOMPrpg1QX',\n completeDate: '2014-02-03',\n period: '201401',\n orgUnit: 'DiszpKrYNg8',\n dataValues: [\n {\n dataElement: 'f7n9E0hX8qk',\n value: '1',\n },\n {\n dataElement: 'Ix2HsbDMLea',\n value: '2',\n },\n {\n dataElement: 'eY5ehpbEsB7',\n value: '3',\n },\n ],\n});", - "caption": "-a `dataValueSet` with related `dataValues`" + "caption": "a dataValueSet with related dataValues" }, { "title": "example", @@ -344,12 +344,17 @@ { "title": "example", "description": "get('dataValueSets', {\n dataSet: 'pBOMPrpg1QX',\n orgUnit: 'DiszpKrYNg8',\n period: '201401',\n fields: '*',\n});", - "caption": "Get all data values for the 'pBOMPrpg1QX' dataset." + "caption": "all data values for the 'pBOMPrpg1QX' dataset" }, { "title": "example", "description": "get('programs', { orgUnit: 'TSyzvBiovKh', fields: '*' });", - "caption": "get all programs for an organization unit" + "caption": "all programs for an organization unit" + }, + { + "title": "example", + "description": "get('trackedEntityInstances', {\n ou: 'DiszpKrYNg8',\n filters: ['flGbXLXCrEo:Eq:124'],\n});", + "caption": "a single tracked entity instance by a unique external ID" } ] }, @@ -403,7 +408,7 @@ { "title": "example", "description": "discover('post', '/trackedEntityInstances')", - "caption": "Example getting a list of `parameters allowed` on a given `endpoint` for specific `http method`" + "caption": "a list of parameters allowed on a given endpoint for specific http method" } ] }, @@ -530,15 +535,15 @@ }, { "title": "example", - "description": "patch('dataElements', 'FTRrcoaog83',\n{\n name: 'New Name',\n});", - "caption": "Example `patching` a `data element`" + "description": "patch('dataElements', 'FTRrcoaog83', { name: 'New Name' });", + "caption": "a dataElement" } ] }, "valid": true }, { - "name": "del", + "name": "destroy", "params": [ "resourceType", "path", @@ -661,18 +666,18 @@ }, { "title": "example", - "description": "del('trackedEntityInstances', 'LcRd6Nyaq7T');", - "caption": "Example`deleting` a `tracked entity instance`" + "description": "destroy('trackedEntityInstances', 'LcRd6Nyaq7T');", + "caption": "a tracked entity instance" } ] }, "valid": true }, { - "name": "attrVal", + "name": "findAttributeValue", "params": [ - "tei", - "attributeName" + "trackedEntityInstance", + "attributeDisplayName" ], "docs": { "description": "Gets an attribute value by its case-insensitive display name", @@ -684,7 +689,7 @@ }, { "title": "example", - "description": "attrVal(tei.attributes, 'first name')" + "description": "findAttributeValue(state.data.trackedEntityInstances[0], 'first name')" }, { "title": "function", @@ -698,7 +703,7 @@ "type": "NameExpression", "name": "Object" }, - "name": "tei" + "name": "trackedEntityInstance" }, { "title": "param", @@ -707,7 +712,7 @@ "type": "NameExpression", "name": "string" }, - "name": "attributeName" + "name": "attributeDisplayName" }, { "title": "returns", @@ -722,10 +727,10 @@ "valid": true }, { - "name": "attribute", + "name": "attr", "params": [ - "attributeId", - "attributeValue" + "attribute", + "value" ], "docs": { "description": "Converts an attribute ID and value into a DSHI2 attribute object", @@ -737,7 +742,7 @@ }, { "title": "example", - "description": "attribute('w75KJ2mc4zz', 'Elias')" + "description": "attr('w75KJ2mc4zz', 'Elias')" }, { "title": "function", @@ -751,7 +756,7 @@ "type": "NameExpression", "name": "string" }, - "name": "attributeId" + "name": "attribute" }, { "title": "param", @@ -760,7 +765,60 @@ "type": "NameExpression", "name": "string" }, - "name": "attributeValue" + "name": "value" + }, + { + "title": "returns", + "description": null, + "type": { + "type": "NameExpression", + "name": "object" + } + } + ] + }, + "valid": true + }, + { + "name": "dv", + "params": [ + "dataElement", + "value" + ], + "docs": { + "description": "Converts a dataElement and value into a DSHI2 dataValue object", + "tags": [ + { + "title": "public", + "description": null, + "type": null + }, + { + "title": "example", + "description": "dv('f7n9E0hX8qk', 12)" + }, + { + "title": "function", + "description": null, + "name": null + }, + { + "title": "param", + "description": "A data element ID.", + "type": { + "type": "NameExpression", + "name": "string" + }, + "name": "dataElement" + }, + { + "title": "param", + "description": "The value for that data element.", + "type": { + "type": "NameExpression", + "name": "string" + }, + "name": "value" }, { "title": "returns", diff --git a/lib/Adaptor.js b/lib/Adaptor.js index ed93012..197293c 100644 --- a/lib/Adaptor.js +++ b/lib/Adaptor.js @@ -9,9 +9,10 @@ exports.update = update; exports.get = get; exports.discover = discover; exports.patch = patch; -exports.del = del; -exports.attrVal = attrVal; -exports.attribute = attribute; +exports.destroy = destroy; +exports.findAttributeValue = findAttributeValue; +exports.attr = attr; +exports.dv = dv; Object.defineProperty(exports, "field", { enumerable: true, get: function () { @@ -201,19 +202,19 @@ _axios.default.interceptors.response.use(function (response) { * @param {Object} [options] - Optional `options` to define URL parameters (E.g. `filters`, `dimensions` and `import parameters`), axios configurations (E.g. `auth`) and DHIS 2 api version to use. * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} - * @example -a `program` + * @example a program * create('programs', { * name: 'name 20', * shortName: 'n20', * programType: 'WITHOUT_REGISTRATION', * }); - * @example -an `event` + * @example an event * create('events', { * program: 'eBAyeGv0exc', * orgUnit: 'DiszpKrYNg8', * status: 'COMPLETED', * }); - * @example -a `trackedEntityInstance` + * @example a trackedEntityInstance * create('trackedEntityInstances', { * orgUnit: 'TSyzvBiovKh', * trackedEntityType: 'nEenWmSyUEp', @@ -224,9 +225,9 @@ _axios.default.interceptors.response.use(function (response) { * }, * ] * }); - * @example -a `dataSet` + * @example a dataSet * create('dataSets', { name: 'OpenFn Data Set', periodType: 'Monthly' }); - * @example -a `dataSetNotification` + * @example a dataSetNotification * create('dataSetNotificationTemplates', { * dataSetNotificationTrigger: 'DATA_SET_COMPLETION', * notificationRecipient: 'ORGANISATION_UNIT_CONTACT', @@ -235,7 +236,7 @@ _axios.default.interceptors.response.use(function (response) { * deliveryChannels: ['SMS'], * dataSets: [], * }); - * @example -a `dataElement` + * @example a dataElement * create('dataElements', { * aggregationType: 'SUM', * domainType: 'AGGREGATE', @@ -243,26 +244,26 @@ _axios.default.interceptors.response.use(function (response) { * name: 'Paracetamol', * shortName: 'Para', * }); - * @example -a `dataElementGroup` + * @example a dataElementGroup * create('dataElementGroups', { * name: 'Data Element Group 1', * dataElements: [], * }); - * @example -a `dataElementGroupSet` + * @example a dataElementGroupSet * create('dataElementGroupSets', { * name: 'Data Element Group Set 4', * dataDimension: true, * shortName: 'DEGS4', * dataElementGroups: [], * }); - * @example -a `dataValueSet` + * @example a dataValueSet * create('dataValueSets', { * dataElement: 'f7n9E0hX8qk', * period: '201401', * orgUnit: 'DiszpKrYNg8', * value: '12', * }); - * @example -a `dataValueSet` with related `dataValues` + * @example a dataValueSet with related dataValues * create('dataValueSets', { * dataSet: 'pBOMPrpg1QX', * completeDate: '2014-02-03', @@ -283,7 +284,7 @@ _axios.default.interceptors.response.use(function (response) { * }, * ], * }); - * @example -an `enrollment` + * @example an enrollment * create('enrollments', { * trackedEntityInstance: 'bmshzEacgxa', * orgUnit: 'TSyzvBiovKh', @@ -331,13 +332,13 @@ function create(resourceType, data, options, callback) { * @param {Object} [options] - Optional `options` to define URL parameters (E.g. `filters`, `dimensions` and `import parameters`), axios configurations (E.g. `auth`) and DHIS 2 api version to use. * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} - * @example -a program + * @example a program * update('programs', 'qAZJCrNJK8H', { * name: '14e1aa02c3f0a31618e096f2c6d03bed', * shortName: '14e1aa02', * programType: 'WITHOUT_REGISTRATION', * }); - * @example an `event` + * @example an event * update('events', 'PVqUD2hvU4E', { * program: 'eBAyeGv0exc', * orgUnit: 'Ngelehun CHC', @@ -345,7 +346,7 @@ function create(resourceType, data, options, callback) { * storedBy: 'admin', * dataValues: [], * }); - * @example a `trackedEntityInstance` + * @example a trackedEntityInstance * update('trackedEntityInstances', 'IeQfgUtGPq2', { * created: '2015-08-06T21:12:37.256', * orgUnit: 'TSyzvBiovKh', @@ -385,9 +386,9 @@ function create(resourceType, data, options, callback) { * }, * ], * }); - * @example -a `dataSet` + * @example a dataSet * update('dataSets', 'lyLU2wR22tC', { name: 'OpenFN Data Set', periodType: 'Weekly' }); - * @example -a `dataSetNotification` + * @example a dataSetNotification * update('dataSetNotificationTemplates', 'VbQBwdm1wVP', { * dataSetNotificationTrigger: 'DATA_SET_COMPLETION', * notificationRecipient: 'ORGANISATION_UNIT_CONTACT', @@ -396,7 +397,7 @@ function create(resourceType, data, options, callback) { * deliveryChannels: ['SMS'], * dataSets: [], * }); - * @example -a `dataElement` + * @example a dataElement * update('dataElements', 'FTRrcoaog83', { * aggregationType: 'SUM', * domainType: 'AGGREGATE', @@ -404,26 +405,26 @@ function create(resourceType, data, options, callback) { * name: 'Paracetamol', * shortName: 'Para', * }); - * @example -a `dataElementGroup` + * @example a dataElementGroup * update('dataElementGroups', 'QrprHT61XFk', { * name: 'Data Element Group 1', * dataElements: [], * }); - * @example -a `dataElementGroupSet` + * @example a dataElementGroupSet * update('dataElementGroupSets', 'VxWloRvAze8', { * name: 'Data Element Group Set 4', * dataDimension: true, * shortName: 'DEGS4', * dataElementGroups: [], * }); - * @example -a `dataValueSet` + * @example a dataValueSet * update('dataValueSets', 'AsQj6cDsUq4', { * dataElement: 'f7n9E0hX8qk', * period: '201401', * orgUnit: 'DiszpKrYNg8', * value: '12', * }); - * @example -a `dataValueSet` with related `dataValues` + * @example a dataValueSet with related dataValues * update('dataValueSets', 'Ix2HsbDMLea', { * dataSet: 'pBOMPrpg1QX', * completeDate: '2014-02-03', @@ -492,15 +493,20 @@ function update(resourceType, path, data, options, callback) { * @param {Object} [options] - Optional `options` to define URL parameters beyond filters, request configuration (e.g. `auth`) and DHIS2 api version to use. * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} state - * @example Get all data values for the 'pBOMPrpg1QX' dataset. + * @example all data values for the 'pBOMPrpg1QX' dataset * get('dataValueSets', { * dataSet: 'pBOMPrpg1QX', * orgUnit: 'DiszpKrYNg8', * period: '201401', * fields: '*', * }); - * @example get all programs for an organization unit + * @example all programs for an organization unit * get('programs', { orgUnit: 'TSyzvBiovKh', fields: '*' }); + * @example a single tracked entity instance by a unique external ID + * get('trackedEntityInstances', { + * ou: 'DiszpKrYNg8', + * filters: ['flGbXLXCrEo:Eq:124'], + * }); */ @@ -587,7 +593,7 @@ function get(resourceType, filters, options, callback) { * @param {string} httpMethod - The HTTP to inspect parameter usage for a given endpoint, e.g., `get`, `post`,`put`,`patch`,`delete` * @param {string} endpoint - The path for a given endpoint. E.g. `/trackedEntityInstances` or `/dataValueSets` * @returns {Operation} - * @example Example getting a list of `parameters allowed` on a given `endpoint` for specific `http method` + * @example a list of parameters allowed on a given endpoint for specific http method * discover('post', '/trackedEntityInstances') */ @@ -650,11 +656,8 @@ function discover(httpMethod, endpoint) { * @param {{apiVersion: number,operationName: string,responseType: string}} [options] - Optional options for update method. Defaults to `{operationName: 'patch', apiVersion: state.configuration.apiVersion, responseType: 'json'}` * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} - * @example Example `patching` a `data element` - * patch('dataElements', 'FTRrcoaog83', - * { - * name: 'New Name', - * }); + * @example a dataElement + * patch('dataElements', 'FTRrcoaog83', { name: 'New Name' }); */ // TODO: @Elias, can this be deleted in favor of update? How does DHIS2 handle PATCH vs PUT? // I need to investigate on this. But I think DHIS 2 forces to send all properties back when we do an update. If that's confirmed then this may be needed. @@ -720,13 +723,13 @@ function patch(resourceType, path, data, params, options, callback) { * @param {{apiVersion: number,operationName: string,resourceType: string}} [options] - Optional `options` for `del` operation. Defaults to `{operationName: 'delete', apiVersion: state.configuration.apiVersion, responseType: 'json'}` * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} - * @example Example`deleting` a `tracked entity instance` - * del('trackedEntityInstances', 'LcRd6Nyaq7T'); + * @example a tracked entity instance + * destroy('trackedEntityInstances', 'LcRd6Nyaq7T'); */ // TODO: @Elias, can this be implemented using the same pattern as update but without data? -function del(resourceType, path, data, params, options, callback) { +function destroy(resourceType, path, data, params, options, callback) { return state => { var _options$operationNam2, _options4, _options$responseType2, _options5, _queryParams3, _queryParams4, _options$apiVersion2, _options6, _CONTENT_TYPES$respon2; @@ -774,34 +777,52 @@ function del(resourceType, path, data, params, options, callback) { * Gets an attribute value by its case-insensitive display name * @public * @example - * attrVal(tei.attributes, 'first name') + * findAttributeValue(state.data.trackedEntityInstances[0], 'first name') * @function - * @param {Object} tei - A tracked entity instance (TEI) object - * @param {string} attributeName - The 'displayName' to search for in the TEI's attributes + * @param {Object} trackedEntityInstance - A tracked entity instance (TEI) object + * @param {string} attributeDisplayName - The 'displayName' to search for in the TEI's attributes * @returns {string} */ -function attrVal(tei, attributeName) { - var _tei$attributes, _tei$attributes$find; +function findAttributeValue(trackedEntityInstance, attributeDisplayName) { + var _trackedEntityInstanc, _trackedEntityInstanc2; - return tei === null || tei === void 0 ? void 0 : (_tei$attributes = tei.attributes) === null || _tei$attributes === void 0 ? void 0 : (_tei$attributes$find = _tei$attributes.find(a => (a === null || a === void 0 ? void 0 : a.displayName.toLowerCase()) == attributeName.toLowerCase())) === null || _tei$attributes$find === void 0 ? void 0 : _tei$attributes$find.value; + return trackedEntityInstance === null || trackedEntityInstance === void 0 ? void 0 : (_trackedEntityInstanc = trackedEntityInstance.attributes) === null || _trackedEntityInstanc === void 0 ? void 0 : (_trackedEntityInstanc2 = _trackedEntityInstanc.find(a => (a === null || a === void 0 ? void 0 : a.displayName.toLowerCase()) == attributeDisplayName.toLowerCase())) === null || _trackedEntityInstanc2 === void 0 ? void 0 : _trackedEntityInstanc2.value; } /** * Converts an attribute ID and value into a DSHI2 attribute object * @public * @example - * attribute('w75KJ2mc4zz', 'Elias') + * attr('w75KJ2mc4zz', 'Elias') + * @function + * @param {string} attribute - A tracked entity instance (TEI) attribute ID. + * @param {string} value - The value for that attribute. + * @returns {object} + */ + + +function attr(attribute, value) { + return { + attribute, + value + }; +} +/** + * Converts a dataElement and value into a DSHI2 dataValue object + * @public + * @example + * dv('f7n9E0hX8qk', 12) * @function - * @param {string} attributeId - A tracked entity instance (TEI) attribute ID. - * @param {string} attributeValue - The value for that attribute. + * @param {string} dataElement - A data element ID. + * @param {string} value - The value for that data element. * @returns {object} */ -function attribute(attributeId, attributeValue) { +function dv(dataElement, value) { return { - attribute: attributeId, - value: attributeValue + dataElement, + value }; } \ No newline at end of file diff --git a/src/Adaptor.js b/src/Adaptor.js index b35e385..03e9383 100644 --- a/src/Adaptor.js +++ b/src/Adaptor.js @@ -128,19 +128,19 @@ axios.interceptors.response.use( * @param {Object} [options] - Optional `options` to define URL parameters (E.g. `filters`, `dimensions` and `import parameters`), axios configurations (E.g. `auth`) and DHIS 2 api version to use. * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} - * @example -a `program` + * @example a program * create('programs', { * name: 'name 20', * shortName: 'n20', * programType: 'WITHOUT_REGISTRATION', * }); - * @example -an `event` + * @example an event * create('events', { * program: 'eBAyeGv0exc', * orgUnit: 'DiszpKrYNg8', * status: 'COMPLETED', * }); - * @example -a `trackedEntityInstance` + * @example a trackedEntityInstance * create('trackedEntityInstances', { * orgUnit: 'TSyzvBiovKh', * trackedEntityType: 'nEenWmSyUEp', @@ -151,9 +151,9 @@ axios.interceptors.response.use( * }, * ] * }); - * @example -a `dataSet` + * @example a dataSet * create('dataSets', { name: 'OpenFn Data Set', periodType: 'Monthly' }); - * @example -a `dataSetNotification` + * @example a dataSetNotification * create('dataSetNotificationTemplates', { * dataSetNotificationTrigger: 'DATA_SET_COMPLETION', * notificationRecipient: 'ORGANISATION_UNIT_CONTACT', @@ -162,7 +162,7 @@ axios.interceptors.response.use( * deliveryChannels: ['SMS'], * dataSets: [], * }); - * @example -a `dataElement` + * @example a dataElement * create('dataElements', { * aggregationType: 'SUM', * domainType: 'AGGREGATE', @@ -170,26 +170,26 @@ axios.interceptors.response.use( * name: 'Paracetamol', * shortName: 'Para', * }); - * @example -a `dataElementGroup` + * @example a dataElementGroup * create('dataElementGroups', { * name: 'Data Element Group 1', * dataElements: [], * }); - * @example -a `dataElementGroupSet` + * @example a dataElementGroupSet * create('dataElementGroupSets', { * name: 'Data Element Group Set 4', * dataDimension: true, * shortName: 'DEGS4', * dataElementGroups: [], * }); - * @example -a `dataValueSet` + * @example a dataValueSet * create('dataValueSets', { * dataElement: 'f7n9E0hX8qk', * period: '201401', * orgUnit: 'DiszpKrYNg8', * value: '12', * }); - * @example -a `dataValueSet` with related `dataValues` + * @example a dataValueSet with related dataValues * create('dataValueSets', { * dataSet: 'pBOMPrpg1QX', * completeDate: '2014-02-03', @@ -210,7 +210,7 @@ axios.interceptors.response.use( * }, * ], * }); - * @example -an `enrollment` + * @example an enrollment * create('enrollments', { * trackedEntityInstance: 'bmshzEacgxa', * orgUnit: 'TSyzvBiovKh', @@ -254,13 +254,13 @@ export function create(resourceType, data, options, callback) { * @param {Object} [options] - Optional `options` to define URL parameters (E.g. `filters`, `dimensions` and `import parameters`), axios configurations (E.g. `auth`) and DHIS 2 api version to use. * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} - * @example -a program + * @example a program * update('programs', 'qAZJCrNJK8H', { * name: '14e1aa02c3f0a31618e096f2c6d03bed', * shortName: '14e1aa02', * programType: 'WITHOUT_REGISTRATION', * }); - * @example an `event` + * @example an event * update('events', 'PVqUD2hvU4E', { * program: 'eBAyeGv0exc', * orgUnit: 'Ngelehun CHC', @@ -268,7 +268,7 @@ export function create(resourceType, data, options, callback) { * storedBy: 'admin', * dataValues: [], * }); - * @example a `trackedEntityInstance` + * @example a trackedEntityInstance * update('trackedEntityInstances', 'IeQfgUtGPq2', { * created: '2015-08-06T21:12:37.256', * orgUnit: 'TSyzvBiovKh', @@ -308,9 +308,9 @@ export function create(resourceType, data, options, callback) { * }, * ], * }); - * @example -a `dataSet` + * @example a dataSet * update('dataSets', 'lyLU2wR22tC', { name: 'OpenFN Data Set', periodType: 'Weekly' }); - * @example -a `dataSetNotification` + * @example a dataSetNotification * update('dataSetNotificationTemplates', 'VbQBwdm1wVP', { * dataSetNotificationTrigger: 'DATA_SET_COMPLETION', * notificationRecipient: 'ORGANISATION_UNIT_CONTACT', @@ -319,7 +319,7 @@ export function create(resourceType, data, options, callback) { * deliveryChannels: ['SMS'], * dataSets: [], * }); - * @example -a `dataElement` + * @example a dataElement * update('dataElements', 'FTRrcoaog83', { * aggregationType: 'SUM', * domainType: 'AGGREGATE', @@ -327,26 +327,26 @@ export function create(resourceType, data, options, callback) { * name: 'Paracetamol', * shortName: 'Para', * }); - * @example -a `dataElementGroup` + * @example a dataElementGroup * update('dataElementGroups', 'QrprHT61XFk', { * name: 'Data Element Group 1', * dataElements: [], * }); - * @example -a `dataElementGroupSet` + * @example a dataElementGroupSet * update('dataElementGroupSets', 'VxWloRvAze8', { * name: 'Data Element Group Set 4', * dataDimension: true, * shortName: 'DEGS4', * dataElementGroups: [], * }); - * @example -a `dataValueSet` + * @example a dataValueSet * update('dataValueSets', 'AsQj6cDsUq4', { * dataElement: 'f7n9E0hX8qk', * period: '201401', * orgUnit: 'DiszpKrYNg8', * value: '12', * }); - * @example -a `dataValueSet` with related `dataValues` + * @example a dataValueSet with related dataValues * update('dataValueSets', 'Ix2HsbDMLea', { * dataSet: 'pBOMPrpg1QX', * completeDate: '2014-02-03', @@ -411,15 +411,20 @@ export function update(resourceType, path, data, options, callback) { * @param {Object} [options] - Optional `options` to define URL parameters beyond filters, request configuration (e.g. `auth`) and DHIS2 api version to use. * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} state - * @example Get all data values for the 'pBOMPrpg1QX' dataset. + * @example all data values for the 'pBOMPrpg1QX' dataset * get('dataValueSets', { * dataSet: 'pBOMPrpg1QX', * orgUnit: 'DiszpKrYNg8', * period: '201401', * fields: '*', * }); - * @example get all programs for an organization unit + * @example all programs for an organization unit * get('programs', { orgUnit: 'TSyzvBiovKh', fields: '*' }); + * @example a single tracked entity instance by a unique external ID + * get('trackedEntityInstances', { + * ou: 'DiszpKrYNg8', + * filters: ['flGbXLXCrEo:Eq:124'], + * }); */ export function get(resourceType, filters, options, callback) { return state => { @@ -502,7 +507,7 @@ export function get(resourceType, filters, options, callback) { * @param {string} httpMethod - The HTTP to inspect parameter usage for a given endpoint, e.g., `get`, `post`,`put`,`patch`,`delete` * @param {string} endpoint - The path for a given endpoint. E.g. `/trackedEntityInstances` or `/dataValueSets` * @returns {Operation} - * @example Example getting a list of `parameters allowed` on a given `endpoint` for specific `http method` + * @example a list of parameters allowed on a given endpoint for specific http method * discover('post', '/trackedEntityInstances') */ export function discover(httpMethod, endpoint) { @@ -603,11 +608,8 @@ export function discover(httpMethod, endpoint) { * @param {{apiVersion: number,operationName: string,responseType: string}} [options] - Optional options for update method. Defaults to `{operationName: 'patch', apiVersion: state.configuration.apiVersion, responseType: 'json'}` * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} - * @example Example `patching` a `data element` - * patch('dataElements', 'FTRrcoaog83', - * { - * name: 'New Name', - * }); + * @example a dataElement + * patch('dataElements', 'FTRrcoaog83', { name: 'New Name' }); */ // TODO: @Elias, can this be deleted in favor of update? How does DHIS2 handle PATCH vs PUT? // I need to investigate on this. But I think DHIS 2 forces to send all properties back when we do an update. If that's confirmed then this may be needed. @@ -686,11 +688,11 @@ export function patch(resourceType, path, data, params, options, callback) { * @param {{apiVersion: number,operationName: string,resourceType: string}} [options] - Optional `options` for `del` operation. Defaults to `{operationName: 'delete', apiVersion: state.configuration.apiVersion, responseType: 'json'}` * @param {function} [callback] - Optional callback to handle the response * @returns {Operation} - * @example Example`deleting` a `tracked entity instance` - * del('trackedEntityInstances', 'LcRd6Nyaq7T'); + * @example a tracked entity instance + * destroy('trackedEntityInstances', 'LcRd6Nyaq7T'); */ // TODO: @Elias, can this be implemented using the same pattern as update but without data? -export function del(resourceType, path, data, params, options, callback) { +export function destroy(resourceType, path, data, params, options, callback) { return state => { resourceType = expandReferences(resourceType)(state); @@ -754,15 +756,18 @@ export function del(resourceType, path, data, params, options, callback) { * Gets an attribute value by its case-insensitive display name * @public * @example - * attrVal(tei.attributes, 'first name') + * findAttributeValue(state.data.trackedEntityInstances[0], 'first name') * @function - * @param {Object} tei - A tracked entity instance (TEI) object - * @param {string} attributeName - The 'displayName' to search for in the TEI's attributes + * @param {Object} trackedEntityInstance - A tracked entity instance (TEI) object + * @param {string} attributeDisplayName - The 'displayName' to search for in the TEI's attributes * @returns {string} */ -export function attrVal(tei, attributeName) { - return tei?.attributes?.find( - a => a?.displayName.toLowerCase() == attributeName.toLowerCase() +export function findAttributeValue( + trackedEntityInstance, + attributeDisplayName +) { + return trackedEntityInstance?.attributes?.find( + a => a?.displayName.toLowerCase() == attributeDisplayName.toLowerCase() )?.value; } @@ -770,17 +775,28 @@ export function attrVal(tei, attributeName) { * Converts an attribute ID and value into a DSHI2 attribute object * @public * @example - * attribute('w75KJ2mc4zz', 'Elias') + * attr('w75KJ2mc4zz', 'Elias') * @function - * @param {string} attributeId - A tracked entity instance (TEI) attribute ID. - * @param {string} attributeValue - The value for that attribute. + * @param {string} attribute - A tracked entity instance (TEI) attribute ID. + * @param {string} value - The value for that attribute. * @returns {object} */ -export function attribute(attributeId, attributeValue) { - return { - attribute: attributeId, - value: attributeValue, - }; +export function attr(attribute, value) { + return { attribute, value }; +} + +/** + * Converts a dataElement and value into a DSHI2 dataValue object + * @public + * @example + * dv('f7n9E0hX8qk', 12) + * @function + * @param {string} dataElement - A data element ID. + * @param {string} value - The value for that data element. + * @returns {object} + */ +export function dv(dataElement, value) { + return { dataElement, value }; } export {