entity-state v0.1.9

Entity State

Composable meta-logic for JSON-based data

An application retrieves data from a server or other external source. There is often a need for metadata that describes the circumstances of the data set. Entity State is a structure that seeks to meet the needs of such metadata in a standardized manner so that logic can easily be built to handle retrieval, processing, manipulation and display of such data.

Installation

npm install entity-data

Usage

// ES6
import { EntityState, Http } from 'entity-state';

// CommonJS
var EntityState = require('entity-state').EntityState;
var Http = require('entity-state').Http;

The structure

An entity state is an object that contains the data (like an object representing an entity or an array with a list of entities), and the metadata describing it. The object contains the following properties:

Example

{
  data: {
    id: 12345,
    name: 'Jon Snow',
    allegiances: [
      'House Stark',
      'The Night\s Watch'
    ]
    email: 'jon@winterfell.com'
  },
  pathChange: {
    name: 'Aegon Targaryen',
    allegiances.2: 'House Targaryen',
    email: 'jon@targaryen.org'
  },
  initializedAt: '2019-05-06T13:30:00Z',
  loadedAt: '2019-05-06T13:30:00Z',
  changedAt: '2019-05-06T13:32:14Z',
  pathError: {
    email: { message: 'The correct domain is targaryen.email' }
  }
}

API

EntityState

To avoid repeated logic for standard operations, the EntityState helper functions can be used or composed with local business logic.

.initialize(source, sourcePath)

Set the initial structure (with default properties) of a state object

source - The source that contains the existing state. Like if the target state is part of a bigger state object. sourcePath - Path inside source where the target state is located.

.load(data, source, sourcePath)

Load given data into the state. Like after fetching from a server, or when creating a new object locally for posting to a server later.

data - The data to load into the target state object. source - The source that contains the existing state. Like if the target state is part of a bigger state object. sourcePath - Path inside source where the target state is located.

.set(path, value, source, sourcePath)

Set a new value at the given path in the data

path - Path to where inside the data structure to set the value. Starts at the root of the data, not the whole state object. value - New value to set at given path in the data. source - The source that contains the existing state. Like if the target state is part of a bigger state object. sourcePath - Path inside source where the target state is located.

Example:

EntityState.set('foo', 'BAR', { data: { foo: 'FOO!' } })

Should return a new state object containing the following:

{
  data: {
    foo: 'BAR'
  }
}

.stage(path, value, source, sourcePath)

Stage a new value at a given path of the data in pathChange, while keeping the original set in data

path - Path to where in the data structure the new value should end up when merged with the original data. value - New value to set at given path in the data. source - The source that contains the existing state. Like if the target state is part of a bigger state object. sourcePath - Path inside source where the target state is located.

Example:

EntityState.stage('foo', 'BAR', { data: { foo: 'FOO!' } })

Should return a new state object containing the following:

{
  data: {
    foo: 'FOO!'
  },
  pathChange: {
    foo: 'BAR'
  }
}

.error(error, source, sourcePath)

Set an error in the state, that is regarding the whole data set or surrounding processes.

error - Error object source - The source that contains the existing state. Like if the target state is part of a bigger state object. sourcePath - Path inside source where the target state is located.

.pathError(path, error, source, sourcePath)

Set an error for a given path in the state

path - Path to the value in the data structure that the error is regarding. error - Error object source - The source that contains the existing state. Like if the target state is part of a bigger state object. sourcePath - Path inside source where the target state is located.

.clear(source, sourcePath)

Clear the state structure, removing both the data and all metadata

Example:

EntityData.clear({ user: { data: {} }, 'foo: 'BAR' }, 'user')

Should return a new source object containing the following:

{
  foo: 'BAR'
}

.clean(source, sourcePath)

Clean the structure, keeping the data but removing any local change or errors in the metadata

Example:

EntityData.clear({
  user: {
    data: {
      name: 'The name'
    },
    pathChange: {
      name: 'New name'
    }
  },
  foo: 'BAR'
}, 'user')

Should return a new source object containing the following:

{
  user: {
    data: {
      name: 'The name'
    }
  },
  foo: 'BAR'
}

.dataWithChanges(state)

Get a copy of the data from a given state object, with the local changes merged in to the structure

Example:

EntityData.dataWithChanges({
  data: {
    id: 123,
    name: 'Existing name'
  },
  pathChange: {
    name: 'New name'
  }
})

Should return a new data object like the following:

{
  id: 123,
  name: 'New name'
}

Http

Application state is often received via HTTP Requests. This is a small set of functions wrapping the Fetch API for simplified HTTP Requests.

.request(options = {})

Make HTTP Request

Options:

Examples:

const { response, statusCode } = await Http.request({
  baseUrl: 'http://www.example.com/',
  method: 'GET',
  path: 'users/123'
})

const { response, statusCode } = await Http.request({
  baseUrl: 'http://www.example.com/',
  method: 'POST',
  path: 'users/',
  body: {
    name: 'New user'
  }
})

.get(path, query, options = {})

Make GET request

Shortcut for Http.request({ method: 'GET', path, query, ...options })

.post(path, body, options = {})

Make POST request

Shortcut for Http.request({ method: 'POST', path, body, ...options })

.put(path, body, options = {})

Make PUT request

.patch(path, body, options = {})

Shortcut for Http.request({ method: 'PUT', path, body, ...options })

Make PATCH request

.delete(path, query, options = {})

Make DELETE request

Shortcut for Http.request({ method: 'DELETE', path, query, ...options })

.withOptions(options = {})

Make composed call functions to all methods with the given options merged in

Example:

const {
  get,
  post
} = Http.withOptions({
  baseUrl: 'http://www.example.com/'
})

Giving get/post functions that can be used with relative paths without providing the base url.

Entity State is being actively used, and is in development. Suggestions and contributions are very welcome!