Symmetric-js NPM

About

Symmetric provides observable model and collection classes with support for field specifications that mirror backend sources with encoding functions and validation rules.

Requirements

The built-in sync function requires a fetch compatible function on window/self/ or global.

NOTE: When using create-react-app, fetch is already included. No need to add an additional dependency.

Configuration

autoValidate - auto validate model rules after X ms from a change - use -1 (default) to disable or 0 to run immediate
encoders - dictionary of encoding (converting to a string) functions keyed by types
decoders - dictionary of decoding (converting from a string) functions keyed by types
inputEncodings - dictionary of field types that are be used ONLY with encoding/decoding user input
formats - dictionary of field types to RegExp objects or functions that return a boolean
formatErrorMessage - function to format errors
batch - function to convert an array of fetch init objects into a single batched fetch init
unbatch - function to convert a single Response object to many Response objects
sync - function that wraps the call to fetch()
syncConfig - additional settings for the built-in sync function, see sync below

sync function

Basic options are:

url - required url to fetch
params - will be added to url as query string args
data - will set body with JSON.stringify(data) and Content-Type to application/json
auth - any authorization object that implements a prepare(request, opts) function
meta - provide an object here to receive with meta.set(key, value) the Link and X-Headers from the response as well as any meta data from unwrapping

Standard fetch options are:

https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch

method - defaults to 'GET'
headers - a dictionary of http headers to use, if setting 'Content-Type' note it is case-sensitive to avoid conflicts
body - the body of the request
mode - defaults to 'same-origin'
credentials - defaults to 'same-origin'
cache - defaults to 'no-cache'
redirect - defaults to 'follow'

Additional options with defaults provided by config.syncConfig are:

syncCamelCase - converts responses to camelCase keys before parsing. defaults to true
saveSnakeCase - defaults to true
querySnakeCase - defaults to true
saveEncoding - one of the following strings json, form, or form-json, defaults to json
saveArrayName - when saveEncoding is form or form-json, the form name to use when data is just an array
csrfCookieName - defaults to csrftoken
csrfHeaderName - defaults to X-CSRFToken
requestedWith - value of the X-Requested-With header, defaults to XMLHttpRequest
batchTimeout - will queue requests that happen within this timeframe into a single request, -1 (default) to disable or >= 0 to enable
batchUrl - the backend url that accepts batched requests
auth - an optional single auth object to use for all sync operations, defaults to null
unwrap - function to unwrap and enveloped response and return the extracted data unwrap(data, meta) => unwrapped, defaults to null
errorFactory - receives a Response object and should return or eventually resolve to rejected Promise
errorHandler - a callback to globally handle errors before they are thrown to the next Promise rejection handler

Subclassing

Model

toJSON() - return data for JSON stringification. The base method will encode each field
defaults() - return an object of default values for the fields when creating a new instance
field(key) - return the field specification for the given attribute key
url(options, operation) - return the url to use with the fetch, save, or delete
parse(data) - The base method will decode all fields that are a string and have an encoding type

Collection

The following methods should be implemented on subclasses:

model(attrs) - return a model class used to construct with the given attributes
url(options, operation) - return the url to use with the fetch or save
parse(data) - parse raw data from a fetch. The base method converts each item into models using the model() method.

Parsing

The base behavior of the parse() method on the model class is to decode any string values that have a specified encoding. The base behavior of the parse() method on the collection class is to pass each item in the data array to a model class constructor and create model instances inside the returned array. This is where the model() method is used.

When subclassing and providing custom parsing it is a good idea to call the base method and use the data it returns.

Field Specifications

Each field can specify one or more of the following:

choices - an array of valid choices the value must match
encoding - type of encoding to use, keys will match up to config encoders and decoders
rule - the validation rule, see below
title - title of an input for this field
subtitle - subtitle of an input for this field
instructions - string of instructions to present to the user for how to enter a value. Will be returned by formatErrorMessage() if set

Validation Rules

Each rule is a dictionary with one or more of the following:

required - if true, then the value may not be null or an empty string
type - checks to make sure that the value is properly decoded as this type
format - key into config formats to choose a RegExp or function to check
equals - value should exactly equal this or if an array match one of the values
min - values needs to pass a > test with this or the length must be longer than this if a string
max - values needs to pass a < test with this or the length must be less than this if a string

Serialization

serialize and deserialize Functions are provided to make it easier for storing and retrieving already loaded models and collections to and from local or session storage.