CollectionProperty

CollectionProperty provides a standard means for accessing remote data and was inspired by Backbone collections. The protocol for interacting with the data source is delegated to an endpoint so the same application logic can work with data from a RESTful api, graphql, local test data, or even an in-browser database like localforage. F.lux ships with support for two endpoints, RestEndpointProperty and PojoEndpointProperty.

F.lux ships with a example using collections in a todo application utilizing an in memory data source. The example uses a local data source to make setup dead simple while still demonstrating the basic features of creating and interacting with collections.

Basic operations

• add(state, mergeOp)
• all()
• clear()</li> <li>create(model)</li> <li>destroy(id)</li> <li>fetch(filter, mergeOp)</li> <li>find(id)</li> <li>get(id)</li> <li>has(id)</li> <li>remove(id)`

Utility functions

• entries()
• every(iteratee, context)
• filter(iteratee, context)
• groupBy(callback, context)
• keys()
• map(iteratee, context)
• reduce(iteratee, acc, context)
• some(iteratee, context)
• sortBy(...iteratee)
• values()

Model access

Properties managed by a collection receive an f.lux accessor ($()) with additional capabilities related to the collection. The accessor class is $ShadowModelAccess.

• collection() - gets the Collection managing this model
• destroy() - permanently deletes the model from the collection using CollectionProperty#destroy
• id() - gets the ID used by the data source for tracking the model
• isWaiting() - is a network operation in progress associated with this model
• isDirty() - has the model been modified since it was last saved/retrieved
• isNew() - gets whether the model has yet to be written to the collection's endpoint
• remove() - removes the model from the collection using CollectionProperty#remove
• save() - save the model using CollectionProperty#save

Paging

The collection provides redimentary paging support for potentially large collections. The current implementation simply grows the collection size wtih each call to fetchNext() and does not make any efforts to remove previous models. (A likely future enhancement)

• fetchNext() - gets the next group of models
• isPaging() - gets if a paging request is outstanding (only one paging request per collection allowed at one time)
• hasMorePages() - does the endpoint have additional models
• nextOffset() - gets the offset for the next paging request
• resetPaging() - resets the internal paging variables
• setLimit() - change the number of models requested with each fetchNext() request

Endpoints

Collections represent a protocol independent means of managing persistent models that exist outside the application state. Endpoints implement the protocol connection to the data source. F.lux endpoints have been implemented for RESTful server apis, in-memory, GraphQL, Sqlite, and Couchbase. F.lux ships with support for RESTful servers and in-memory.

A simple, explicit example of creating a collection and assigning an endpoint:

const rootProperty = store.root();
const collection = new CollectionProperty(colType);
const ep = new RestEndpointProperty.createFor("http://some-url.com/an-api");

collection.setEndpoint(ep);

root._keyed.addProperty("aCollection", collection);

The Todo Collection Example demonstrates a more typical example of setting up a collection.

Query filters

Collection models are retrieved in full using CollectionProperty#fetch that has the following signature:

fetch(filter=null, mergeOp=REPLACE_OPTION, replaceAll=true)

where:

• filter - a query filter object or null for no endpoint filtering
• mergeOp - one of DEFAULTS_OPTION, MERGE_OPTION, or REPLACE_OPTION and specifies how to combine an existing model with a matching ID with a newly retrieved model.
• replaceAll - a boolean where true means replace the current colleciton models with the returned models.

The filter parameter is a specialized object generated by the endpoint method queryBuilder(). A query builder is specialized to the endpoint and expose the following methods:

• equals(name, value)
• gt(name, value)
• gte(name, value)
• lt(name, value)
• lte(name, value)

An example of using a query builder is:

const qb = colleciton.endpoint.queryBuilder();

qb.equals("name", "fred");

collection.fetch(qb);

Errors

Methods utilizing the collection endpoint are asynchronous and return a Promise. Errors generated during an endpoint operation reject using an Error with several specialized properties:

• status - an HTTP status code for the error type
• endpointError - the error object generated by the endpoint

Auto-checkpointing

The Property class supports checkpointing state that can be reset at a later time using Property#resetToCheckpoint. Collections support setting an 'auto-checkpoint' flag that will result in managed models automatically setting a checkpoint on change. This handy for situations like a 'Cancel' button on a form where all changes need to be undone. The checkpoints are automatically cleared when a model is saved.

• isAutocheckpoint()
• setAutocheckpoint(auto)

Middleware

A middleware operation is invoked before each asynchronous/network operation involving the endpoint. Middleware operations are functions with the following format

function middleware(collectionShadow, collectionProperty, op): Promise

Middleware functions must return a Promise and are invoked in the order registered. A function generating an error will terminate the middleware chain and the collection operation will not be performed.

• CreateOp - invoked prior to create rquests
• DestroyOp - invoked prior to destroy rquests
• FetchOp - invoked prior to fetch rquests
• FindOp - invoked prior to find rquests
• UpdateOp - invoked prior to update rquests
• `` -

Events

A colleciton is an Event Emitter and generates the following events:

• ChangeEvent - collection changes
• DeletedEvent - collection destroy() success
• FetchedEvent - collection fetch() success
• FoundEvent - collection find() success
• ErrorEvent - error during an operation
• SavedEvent - collection save() success

Events are can be utilized to handle authorization errors, offline support, logging, or debugging tools.