PickLogic

A format for bundling JSON objects with selection conditions
An engine to do the selecting

Created by Global Strategies for NoviGuide

❯ Quick Start

Install with npm:

1$ npm install picklogic

Install with yarn:

1$ yarn add picklogic

❯ Demo

Clone the PickLogic Demo repo, install dependencies, and run:

1$ git clone git@github.com:GlobalStrategies/picklogic-demo.git
2$ yarn
3$ yarn demo

❯ Concept

Suppose you have two objects that you need to choose between:

const NORMAL = { "color": "green", "message": "Your temperature is normal." }
const FEVER = { "color": "red", "message": "You have a fever." }

You could write conditions to choose:

if ((system === FAHRENHEIT && temperature > 100) || (system === CELSIUS && temperature > 37.8)) { return FEVER; }

Or you could include the conditions with the data, thinking of them as the criteria to select the JSON object:

{
  "pickCriteria": <CRITERIA>,
  "payload": { "color": "red", "message": "You have a fever." }
}

The criteria can be encoded as equally acceptable sets of conditions that must be fulfilled:

{
  "pickCriteria": [
    {
      IF system === FAHRENHEIT && temperature > 100
    },
    {
      IF system === CELSIUS && temperature > 37.8
    }
  ],
  "payload": { "color": "red", "message": "You have a fever." }
}

If any of the pickCriteria are satisfied, the payload is delivered. The array elements can be thought of as conditions separated by ORs. We call each of these condition sets sufficientToPick. We then translate the AND conditions to array elements within each sufficientToPick property:

{
  "pickCriteria": [
    {
      "sufficientToPick": [system === FAHRENHEIT, temperature > 100]
    },
    {
      "sufficientToPick": [system === CELSIUS, temperature > 37.8]
    }
  ],
  "payload": { "color": "red", "message": "You have a fever." }
}

Finally we rewrite conditions in this form:

"sufficientToPick": [
  {
    "dataKey": "system",
    "operator": "=",
    "referenceValue": "FAHRENHEIT"
  },
  {
    "dataKey": "temperature",
    "operator": ">",
    "referenceValue": 100
  }
]

❯ API

Pickable

A pickable is a JSON object that includes an id, the pickCriteria under which it should be selected, and the payload it should deliver if selected. The Pickable class constructor function is a convenience for making this JSON format human-readable.

Params

• pickable {Object}: A pickable JSON object of the form { "id": {string}, "pickCriteria": {Array}, "payload": {Object} }
• defaultKey {string}: (optional). If all conditions perform logic on the same key, this property can be passed in and the "dataKey" property can be left out of all conditions.
• lowerRanked {boolean}: (optional). Important only for condition readouts; determines whether an "always pick" condition is rendered as ALWAYS or IF not otherwise diverted. If an "always pick" condition (pickCriteria: []) is the only pickable in a set (lowerRanked = false), the conditionality is simply output as ALWAYS. Otherwise, it must be a final "catch-all" (lowerRanked = true), so the conditionality is output as IF not otherwise diverted.

Example

const pickable = new Pickable(FEVER_PICKABLE, null, true)

readoutsForPickableWithLocalized()

Outputs an object containing simplified string versions of the conditions, optionally localizing fixed words like IF and AND. This can be used to help non-engineers validate the conditional logic.

Params

• localized {function}: (optional). A function that takes keywords and outputs localized equivalents (keywords used are ALWAYS, AND, OR, IF, NOT, NO, and 'not previously diverted'.

Example

pickable.readoutsForPickableWithLocalized()

Sample output

[{ 
  conjunction: 'IF',
  conditionString: 'system = F & temperature > 100'
}, {
  conjunction: 'OR',
  conditionString: 'system = C & temperature > 37.8'
}]

This can be easily converted to a simple text format, as seen in the demo.

Picker

The Picker class digests passed JSON conditions (pickables) and can evaluate them against passed data hashes.

Params

• pickables {Array}: The JSON pickables to select among, each of the form { "id": {string}, "pickCriteria": {Array}, "payload": {Object} }. You can optionally include a "logicRank": {number} property to evaluate the conditions on each object in a specific order.
• defaultKey {string}: (optional) If all conditions perform logic on the same key, this property can be passed in and the "dataKey" property can be left out of all conditions.

Example

const picker = new Picker(jsonFile.pickables, 'temperature')

pickForData()

Given the passed data, get a matching JSON object, if any.

Params

• data {Object}: The data object should be a hash in the form { [dataKey]: { "value": {string | number | boolean | Array}, "datatype": {string} }.

Example

const pick = picker.pickForData({ system: { value: 'FAHRENHEIT', datatype: 'string' }, temperature: { value: 101, datatype: 'number' } })