item-item v1.1.2

Item

Table of Contents

• This Doc (AKA Overview)
  • Basic Types
    • IItem
    • IFieldValue
    • IItemType
    • FieldType
    • IField
  • Concept Overview
  • Examples
• Sub Modules / Specific Concepts
  • Item Rule
  • Item Actions
  • Field Linking

• Related

  • Item Editing (Form Gen)

Basic Types

Oh items. Where to begin. How about basic schema first. Any item is basically a bag of values. Let's start with basic types:

IItem

IFieldValue

IItemType

(a rarely used object currently because we rarely do item type level validations but conceptually important)

Note: the type is currently the most important part of itemType and is used to narrow the set of IFields that apply to a given item (currently codified in BASE_FIELDS_BY_ITEM_TYPE).

FieldType

IField

(arguably the most important type in items)

Concept Overview

Conceptually, IItemType and IField are analagous to classes in code, and IItem and IFieldValue[] are respectively analagous to instances of the class. The difference, and really the entire point of items, is that not only is the content data stored serializably but the descriptions of how that data is used, collected, what values are alowed, etc are also stored in a non-code form. That is to say that rather than a piece of code (a class for example) codifying the behavior of how data is treated, a serializable object (an IField object for example) describes that behavior and a single core engine is the only piece of code used to enforce the behavior described by that data.

The benefits of this paradigm shift are a couple:

• Configuration: Changes to the behavior of a given piece of data are made by changing other data rather than code. This allows a user (or us) for example to configure their own behavior without making code changes. Rather than someone making changes to code to ensure that a field only allows numbers greater than 0, someone only needs to add a fieldValidation object, specifying that behavior, to the data of the field controlling that value. Because all behavior is data and not code, it can also be stored in the DB allowing per org or user behaviors that would otherwise require frightening switch statement type code.
• DRY: It stringently standardizes the types of behaviors allowed and how all data is treated. This allows us to render for example a grid of values that are Orgs in one case and Applications in another without a single code change. Because of this centralization of code, it dramatically DRY's out the code, leading to us only implementing one single select menu or a single request call, for example, each configured to modify its behavior rather than repreating ourselves in slightly varying ways.
• Validation: Because all behaviors are codified clearly in a standard format and not simply implied by code, it can make it easier to reason about what is possible within the system. That means in theory we can look at a single config describing a form step for example, and know (and write code against) whether the values collected can satisfy the contract of a given api call, etc.

Examples

(If you don't see something here check out item/src/field-processor/index.test.ts because every unique field configuration requires at least one example test case and that can help you understand how they are being used)

An Item:

const applicantItem = {
  // must be universally unique even for inline items
  id : 'a_UUID', 
  
  // a string (currently an enum) that specifies which set of Fields and which validations apply to this item
  itemType : 'APPLICANT',
  
   // a bag of fieldId (string )to IFieldValue[] | undefined, basically all the actual data
  fieldValues : {
  
    // field id is also unique within our system (but not UUID for readability, mostly enforced with code today)
    'applicant-phone' : [{raw : '3039690876'}] 
  }
}

A Field:

 export const APPLICANT_PHONE: IField = {
  id: 'applicant-phone', // unique id
  name: 'Phone', // the user readable name of the field, generally displayed in ui
  type: FieldTypeConst.TEXT, // the data type allowed by the field
};

The field id is used as the key in the fieldValues object of the item. The type will imply how values are collected and processed. For example, text will result in an being rendered when editing. It will also determine how the field is formatted and parsed among other things.

Examples TODO:

String field with replace patterns

Numeric field with parse display calcs

List Option field whose type is not Text

Random Stuff that should organizaed but dont want to forget

• Currently, there is a meaningful difference between a fieldValue being undefined versus []. In both cases the raw value is essentially undefined, but right now a defined [] means that fieldValue has been loaded and is known to be undefined. A true undefined is used to indicate that the fieldValue hasn't even come back from the DB or Api so its value is more akin to being unknown. This allows us to render a spinner on a particular field until its value is loaded, even when other fieldValues have been loaded.

• Validations live at three levels:

  • itemtype level - validations that apply to the entire set of items of a given (aka, only one item of this type can have a FEE_TYPE of DOCUMENTATION)
  • item level (conceptually only, not currently implemented) - validations that apply to the entire set of fieldValues for a single item (aka if phone number is supplied email cannot be supplied or something like that)
  • field level - validations applying to just a particular field (number must be greater than 0, or string cannot be longer than 10, etc)