DataSource

This is a module for interfacing with data coming from any source in uniform way. A data source is a client side key-value store that exposes promised based async methods for working with data.

DataSource uses the Adapter pattern. By default the adapter uses the data sources in-memory key-value store as the source of truth and implements all of its methods(detailed below) with sensible defaults. If you need a custom implementation for things like getting data from a server via http or websockets or using localStorage, you would override the corresponding method in the adapter instance you provide to support reading / writing data to your custom location or dealing with custom queries or actions.

A simple example:

 var userDataSource = new DataSource<User>(new UserAdapter());
 userDataSource.setRecord('recordId', new User()).then((user : User) => {
  user.someMethod();
  return user;
 }).then((user : User) => {
  //do stuff
 });
 
 userDataSource.getRecord('recordId').then((user : User) => {
  //do stuff
 });
 
 userDataSource.addRecord('recordId2', someUser);
 

Data Source API

Adapter Source Interface

Adapters don't have direct references to the data source they work with. Instead they use an instance a DataSourceInterface. This interface provides a synchronous api into the data source.

DataSourceInterface

• get(id : string) : T get a record by id

• add(record : T) : T add a record

• set(id : string, record : T) : T update / change / remove (if record is null)

• remove(id : string) : T remoe a record

• clear() : void nuke the data source record store

• id(record : T) : string get an id for a given record

• records() : Array<T> get all the local records in the data source in an array. This is internally cached is relatively performant so calling this many times is fine.

DataSource Methods

• on(eventName : string, callback : (record : T) => void) : void DataSource is an event emitter that will emit the following events

  • recordAdded -- (record : T, id : string) => void -- when new records are added
  • recordChanged -- (record : T, oldRecord : T, id : string) => void when existing records change (via setRecord, not when properties change)
  • recordRemoved -- (record : T, id : string) => void when records are removed

• loadRecords() : Array<T> -- Loads all records form the backing store

• loadRecordsOnce() : Array<T> If loadRecords() has not been called on the data source, it will call loadRecords() on the adapter and return the results otherwise it will just return what is stored locally and will not execute the adapter's loadRecords() a second time. A use case for this method might be to load a bunch of records from the server, but be sure to only ever do it once since loading things from a server is slow.

• addRecord(record : T) : Promise<T> Adds a record to the data source, returns a promise that resolves the record that was added

• getRecord(id : string) : Promise<T> Gets a record and returns a promise resolving that record or null if no record was found.

• setRecord(id : string, record : T) : Promise<T> writes an update into the data source. if no record exists for the given id, the record will be added. if a record is prexisting for that id, it will be updated with the new record value. if record === null that record will be removed.

• updateRecord(record : T) : Promise<T> the same as setRecord but computes the id of the record by calling adapter.getRecordId(record)

• removeRecord(recordOrId : T|string) : Promise<T> Takes a record to remove or an Id of a record to remove and removes it from the data source. Returns a promise that resolves the removed record or null if no record was removed.

• addRecordCollection(records : Array<T>|IRecordStore<T>) : Promise<T[]> Adds every record in the records argument to the data source.

• getRecordCollection(ids : Array<string>) : Promise<T[]> Gets all records in the data source that have an id in the ids argument.

• removeRecordCollection(records : Array<T>|IRecordStore<T>) : Promise<T[]> Removes all records from the data source

• updateRecordCollection(records : Array<T>|IRecordStore<T>) : Promise<T[]> Updates each record in the records argument

• getRecordPage(pageSize : number, pageNumber : number, optionalArgs : ...args) : Promise<T[]> this is used for paging, you can supply anything you want in the optionalArgs parameter and that will be passed on to the adapter

• getRecordCount() : Promise<number> returns the total number of records in the data source, this is used in conjuction with getRecordPage to accurately show how many pages of records there might be on your server / whatever you are paging

• query(...args : any[]) : Promise<any> This is a way for you to define functionality outside of the normal data source methods, for instance finding all users with the name 'Matt' is not something any of the other data source methods know how to handle. It is up to you to define the behavior of this function in your adapter.

• action(...args : any[]) : Promise<any> Identical to query but sometimes makes more semantic sense

• clearLocalRecordStore() : void Clears the entire local record set and emits recordRemoved events for each record

• createManagedCollection(options? : ICollectionOptions) : Collection creates and manages a collection. Whenever a record is added / updated / removed from the data source that change will be automatically reflected in the collection that is returned. If an options parameter is supplied it will be passed through to the collection.

• manageCollection(collection : Collection) : Collection equivalent to createManagedCollection but you supply the collection to be managed instead of DataSource creating one for you

• awaitRecord(id : string) : Promise<T> Resolves when a record with id is added to the data source, or immediately if it is already there. This will not issue a call to getRecord for you.

• awaitRecords(ids : Array<string>) : Promise<T[]> The same as awaitRecord but will resolve when all ids are present in the data source or immediately if they are all there already.

• observeRecord(id : string, callback : (record : T) => void) : CancelFunction this is a more performant way to listen for changes on a specific record. This is far preferable to listening to recordChanged and checking if the id that changed is the id you are watching

• observeRecords(ids : Array<string>, callback : (record : T) => void) : CancelFunction Same as observeRecord but for many records at once. The callback is invoked for each record change.

• reset() : void resets the data source, removing all records and observers and event listeners. Unlike clearLocalRecordStore() this will not emit recordRemoved events

Adapter Methods To Override

• initialize() This function runs when the Adapter's config promise has resolved.

• loadRecords(localRecords : IRecordStore<T>) By default returns all records stored locally in the DataSource. The localRecords parameter is an object keyed by Id that contains all the records currently in the data source.

• addRecord(id : string, localRecord : T) : T|Promise<T> By default just adds the record to the data source

• removeRecord(record : T, id : string) : T|Promise<T> By default removed the record from the data source

• getRecord(id : string, localRecord : T) : T|Promise<T> Gets a record, by default returns localRecord

• setRecord(id : string, newRecord : T, localRecord :T) : T|Promise<T> updates a record, returns newRecord by default

• addRecordCollection(records : Array<T>|IRecordStore<T>) : T[]|Promise<T[]> calls adapter.addRecord() for each record in array

• getRecordCollection(ids : Array<string>) : T[]|Promise<T[]> calls adapter.getRecord(id) for each record in array

• removeRecordCollection(collection : T[]|IRecordStore<T>) : T[]|Promise<T[]> calls adapter.removeRecord() for each record in array

• updateRecordCollection(collection : T[]|IRecordStore<T>) : T[]|Promise<T[]> calls adapter.setRecord() from each record in array

• getRecordPage(pageSize : number, pageNumber : number, optionalArgs : any) : T[]|Promise<T[]> by default returns a subsection of the local data source records

• getRecordCount() : number|Promise<number>

• getRecordId() : string

• recordsEqual(a : T, b : T) : boolean

• action(actionName : string, ...args : any[]) : any

• query(queryName : string, ...args : any[]) : any

Collection

Collections are 'smart' arrays of things (doesnt have to be object types). They are sortable, filterable, pageable and groupable.

Interfaces

IRecordStore<T> {[id : string, record :T }

Note that because of the adapter pattern use METHODS DEFINED ON THE DATA SOURCE ARE NOT THE SAME AS THE METHODS DEFINED IN THE ADAPTER. Adapter methods often have different signatures than the correspondingly named method on the DataSource itself. For example, when calling dataSource.loadRecords() no parameters are expected, but when the data source invokes the adapter's version of loadRecords, it also passes along a copy of the local store.

Defining a method on the adapter DOES NOT expose it to the data source.