Dataset Reference - dsriseah/ursys GitHub Wiki

Items are Objects with an ID

The UR_Item is an object with an id and any number of additional properties. It's efined in dataset.ts as something like:

{ 
   _id: string;
   [key:string]:any;
}

DataBins are Item Collections with CRUD methods

DataBin (abstract-data-databin.ts) is the template class for implementing a "collection of objects with unique ids". To implement a new databin type, you extend this class (e.g. ItemList).

Each DataBin implementation has to implement the following methods:

// universal collection methods
abstract add(items): { added, error }
abstract read(ids?): { items, error }
abstract update(items): { updated, error }
abstract replace(items): { replaced, skipped, error}
abstract write(items): { added, updated, error }
abstract deletelDs(ids): { deleted, error }
abstract delete(items): { deleted, error }
abstract clear(): void
abstract get(ids): any[]

// universal find/query
abstract find(searchCriteria): items
abstract query(searchCriteria): RecordSet

// built-in notification system
on(eventName, eventListenerFunc): OpResult
off(eventName, eventListenerFunc): OpResult
notify(eventName, dataObj): OpResult

Datasets manage a Collection of DataBins

Dataset (class-data-dataset.ts) implements our notion of a collection of named DataBins or different types. Each dataset is associated with a DataURI, an address and identifier for the collection of databins.

// dataset create and modify
_getDataObj(): DataSetObj       // return Dataset obj
_setFromDataObj(datasetObj)     // set Dataset from obj
_serializeToJSON()              // return JSON string
_deserializeFromJSON(json)      // deserialize from JSON
getManifest(): ManifestObj      // return manifest for dataset
getDataBin(binName, binType)    // get obj with DataBin API
createDataBin(binName, binType) // add a databin
deleteDataBin(binName)          // delete a databin

// placeholder bin housekeeping
openDataBin(binName, binType)   // could allocate mem
closeDataBin(binName)           // could deallocate mem

// placeholder type-specific databin
createltemList(listName, opts)  // create an ItemList
clearltemList(listName)         // remove all items in itemlist
getltemList(listName): ItemList // return ItemList      

// other types are to be implemented as needed

RecordSets are results of DataBin Queries

RecordSet (class-data-recordset.ts) is a query-enabled object from the Databin.query() method. The query method shares the same search criteria as the Databin.find() method:

type SearchOptions {
  preFilter?: (items: UR_Item[]) => UR_Item[];
  missingFields?: string[];
  hasFields?: string[];
  matchCount?: number; // when set, limits the number of matches
  matchExact?: MatchObj;
  matchRange?: RangeObj;
  postFilter?: (items: UR_Item[]) => UR_Item[];
}

The difference between query and find is that the former returns the RecordSet object, whereas the latter return an array of Items.

To use the RecordSet object:

// basic access
.getItems()        // return result items[]
.getStats()        // return recordset stats 
.getSrcltems()     // return original itemset

// chainable methods
.format(formatOpts)  // return new derived recordset
.sort(sortOpts)      // return a sorted recordset
.analyze(testOpts)   // add groups, stats to recordset
.reset()             // reset RecordSet to source

// pagination methods
.paginate(pageSize)  // define page structure
.goPage(pageNum)     // set index
.nextPage()          // set index++ 
.prevPage()          // set index--
.getPage()           // return items in page index
.getPageIndex()      // return current page index
.getPageCount()      // get total pages
.getPageSize()       // get num of items per page
.isLastPage()        // true if last page
.isFirstPage()       // true if first page

Adapters implement low-level Dataset and DataBin APIs for cross-platform independence

(SERVER) DataObjAdapter (abstract-dataobj-adapter.ts) is the mediator between the Dataset API and the underlying storage mechanism used to persist data between sessions. It is an abstract class implemented by sna-dataobj-adapter for the server to (1) interpret SYNC requests from clients and (2) do the necessary platform-specific actions to execute requests.

// manifest
abstract getManifest(dataURI): Promise<UR_ManifestObj>
// whole dataset
abstract readDatasetObj(dataURI): Promise<DS_DatasetObj>
abstract writeDatasetObj(dataURI, datasetObj): Promise<any>
// dataset bins
abstract readDataBinObj(dataURI, binID): Promise<any>
abstract writeDataBinObj(dataURI, bindID, dataObj): Promise<any>

(CLIENT) DatasetAdapter (abstract-dataset-adapter.ts) is a client-side bridge that converts Dataset API calls to whatever a dataset server requires. In our default implementation, this is using URSYS messages SYNC:SRV_DSET and SYNC:SRV_DATA. It's used by SNA DataClient to send/receive commands.

selectDataset(dataURI): Promise<DatasetRes> // load dataset 
execDataset(datasetReq): Promise<DatasetRes> // request dataset operation
getDataObj(dataURI?): Promise<DatasetObj> // fetch dataset object
syncData(syncReq): Promise<DataSyncRes> // request databin operation
handleError(errData): Promise<any> // default handler for dataserver errors

DataClients send SYNC messages to the DataServer for interpretation and execution. The list of syncData (see method above) request operations mirror the DataBin API, and is defined in dataset.ts

ADD      UPDATE   WRITE   DELETE   REPLACE
CLEAR    GET      FIND    QUERY

The list of execDataset (see method above) requests mirror ops for whole Dataset API, and is defined in dataset.ts

LOAD             UNLOAD          PERSIST  
GET_MANIFEST     GET_DATA

Note

The DataClient writes its operations to the DataServer, which eventually sends an SYNC:CLI_DATA message that will update the local instance of Dataset. As common wisdom suggests, client write operations should not assume that the change has happened right after the remote write operation, but instead subscribe to databin changes.

⚠️ **GitHub.com Fallback** ⚠️