Welcome to the Wiki.

Tutorial

Define Data

Create a data entity

Add a folder /src/entities/<entity-name>

This folder is where we are going to store our new entity definitions.

Add a new file /src/entities/<entity-name>/<entity-name>.js

Our first file will hold the class that defines what kind of data our entity is comprised of.

Primarily we will use this class to create new instances of a particular entity type with some standard behaviors and we get to use the keyword new for some added semantic value.

Be sure to rename things where it makes sense. You don’t really want to make an entity called entity do you?

/** @module entities/entity */
import { _baseRecord } from '..'

class Entity extends _baseRecord {
    constructor(exampleString) {
        super()

        this.type = this.constructor.name.toLowerCase()

        /**  Fields */
        this.example = exampleString // ! required
        
        return this
    }
}

export { myEntity }

Add a new file /src/entities/<entity-name>/<entity-name>.schema.js

Our schema file helps us define what kind of data to expect in each of thekeys defined by our original entity file from the previous step.

The schema uses Joi definitions to help validate our entities.

/** @module entities/mySchema */
import Joi from 'joi'

/**
 * my schema object
 * uses the module system to use common fields
 * but sets fields with our validation types
 * @constructor
 */
const mySchema = {
    type: 'object',
    properties: Joi.object().keys({}),
    /** fields required before saving */
    required: [],
    validate(instance) {
        return this.properties.validate(instance)
    },
}

export { mySchema }

Add a barrel file /src/entities/<entity-name>/index.js

export * from './<entity-name>'
export * from './<entity-name>.schema'

Create an entity schema

Pass an object to the Joi.object().keys() function. Name each key after the keys used in your entity and add the desired Joi data type as the value.

For example: if you havethis.email to store a string in your entity you would add an email key to the object you pass like this: Joi.object().keys({ email: Joi.string() })

/** @module entities/mySchema */
import Joi from 'joi'
import { allModules, responseSchema } from '..'

/**
 * entity schema object
 * uses the module system to use common fields
 * but sets fields with our validation types
 * @constructor
 */
const mySchema = {
    type: 'object',
    properties: Joi.object().keys({
        /** _baseRecord fields */
        createdAt: Joi.string(),
        _id: Joi.string(),
        lastUpdatedAt: Joi.string(),
        type: Joi.string(),

        /** our fields */
        example: Joi.string(),

        /** fields that should match backend service*/
        user_id: Joi.number(),
        profile_id: Joi.number(),
        responses: Joi.array().items(), // response entity schema goes here
        user_type: Joi.string(),
    }),
    /** fields required before saving */
    required: [],
    validate(instance) {
        return this.properties.validate(instance)
    },
}

export { mySchema }

Use the entity schema in your entity file

Import your schema from the schema file, and use it to validate our entity instance.

Add a isValid() method to the entity class and use it to fire the schema.validate() from the Joi.object().

Be sure to return a true or false result so we can use this function for flow control.

/** @module entities/entity */
import { _baseRecord, allModules } from '..'
import { mySchema } from './entity.schema'

class Entity extends _baseRecord {
    constructor(exampleString, ...moduleData) {
        super()

        this.type = this.constructor.name.toLowerCase()

        /**  Fields */
        this.example = exampleString // ! required

        /** Pass destructured data to the module system */
        Object.assign(this, moduleData)

        return this
    }
    /**
     * validate this record
     * @return {boolean} is it valid or not?
     */
    isValid() {
        const validate = mySchema.validate(this)

        /**
         * Log out some useful error messages
         */
        if (validate.error) {
            console.error(`error: ${validate.error} - ${this.type} validation`)
        }

        /** validate(this) always returns something so force it to a bool */
        return !validate.error ? true : false
    }
}

export { myEntity }

Retrieve Data

Create a data service for our new entity

Storing Data

Calling a data service from a component

Nomenclature

entity

entity schema

service

component