Cumulation

Read the Cumulation Documentation - interactive docs with the full API reference.

A browser and Node.js client for reading and writing records against a Retold-style RESTful data endpoint.

Cumulation is a small data-access library that talks to a Meadow-style REST API. It wraps the HTTP verbs (GET, PUT, POST, DELETE) for a configured entity, manages request cookies and headers, and includes a graph query layer that resolves entity joins from a Stricture-style data model and emits FoxHound filter URLs. It runs the same code in Node.js and in the browser through a bundled shim.

Features

• Entity REST Client -- read, create, update, and delete records for a configured Entity against a base Server URL
• Single and Plural Reads -- fetch one record by ID or a set of records via a filter/paging string
• Cookie and Header Management -- per-request cookies (serialized via the cookie module) and custom headers are attached automatically
• Graph Query Layer -- cumulation.graph.get() resolves joins between entities from a data model and builds FoxHound filter URLs for you
• Bunyan-style Logging -- a built-in console logger with trace/debug/info/warning/error channels and timing helpers
• Browser Compatible -- a browser shim attaches the constructor to window.Cumulation

Quick Start

const libCumulation = require('cumulation');

// Point the client at a RESTful endpoint and an entity
let libBook = new libCumulation(
	{
		Server: 'https://my.server.com/1.0/',
		Entity: 'Book'
	});

// Read a single record by ID -> GET https://my.server.com/1.0/Book/17
libBook.getRecord(17,
	(pError, pRecord) =>
	{
		console.log(pRecord);
	});

// Create a record -> POST https://my.server.com/1.0/Book
libBook.postRecord({ Title: 'Dune', Author: 'Frank Herbert' },
	(pError, pCreatedRecord) =>
	{
		console.log(pCreatedRecord);
	});

Installation

npm install cumulation

Configuration

Settings are passed to the constructor and merged over the defaults in source/Cumulation-Settings-Default.js.

Property	Type	Default	Description
Server	String	http://127.0.0.1:8080/	Base URL of the REST endpoint, with a trailing slash.
Entity	String	Unknown	Default entity (record set) name used to build request URLs.
Cookies	Object	{}	Key/value cookies serialized and sent on every request.
Headers	Object	{}	Custom headers merged into every request.
DebugLog	Boolean	false	When true, logs verbose request/response detail.
DataModel	Object	(none)	Stricture-style schema ({ Tables: { ... } }) consumed by the graph layer.
Online	Boolean	false	Declared in defaults; see Unknowns below.
Cached	Boolean	true	Declared in defaults; see Unknowns below.
CacheExpirationTime	Number	300000	Declared in defaults; see Unknowns below.

API

All record methods take a Node-style (pError, pResult) callback. pResult is the parsed JSON body of the response.

Method	Description
getRecord(pRecordID, fCallback)	GET a single record by ID. Alias of getRecordFromServer.
getRecords(pRecordsString, fCallback)	GET a set of records for the default entity using a filter/paging string.
getRecordsFromServerGeneric(pEntity, pRecordsString, fCallback)	GET a set of records for an explicit entity.
putRecord(pRecordObject, fCallback)	PUT (update) a record. Alias of putRecordToServer.
postRecord(pRecordObject, fCallback)	POST (create) a record. Alias of postRecordToServer.
deleteRecordFromServer(pRecordID, fCallback)	DELETE a record by ID.
parseFilter(pFilter)	Normalize a filter value to a string (passthrough for strings, stringifies numbers).
graph.get(pEntityName, pFilterObject, fCallback)	Graph-aware filtered read. See Graph Queries.
log.trace/debug/info/warning/error(pMessage, pObject)	Console logging channels.

See the API Reference for full signatures, URL construction, and behavior notes.

How It Works

A Cumulation instance is bound to one base Server and a default Entity. The record methods build URLs from those values:

getRecord(id)           -> GET    {Server}{Entity}/{id}
getRecords(filter)      -> GET    {Server}{Entity}s/{filter}
putRecord(record)       -> PUT    {Server}{Entity}
postRecord(record)      -> POST   {Server}{Entity}
deleteRecordFromServer  -> DELETE {Server}{Entity}/{id}

The plural read pluralizes the entity by appending s to the entity name. The graph layer (cumulation.graph) goes further: given a DataModel, it works out which entities join to one another and assembles FoxHound filter URLs so a caller can filter one entity by values that live on a joined entity.

Documentation

Detailed documentation is available in the docs/ folder:

Document	Description
Quick Start	Configure a client and run reads and writes
API Reference	Verified method signatures, URL construction, and settings
Graph Queries	Join resolution and FoxHound filter URLs via graph.get

Building

gulp minified   # browser bundle -> dist/cumulation.min.js (+ sourcemap)
gulp debug      # unminified browser bundle -> dist/cumulation.js

# or both at once
gulp build

Testing

npm test

Related Modules

• fable - Application services framework

License

MIT

Contributing

Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the Retold Contributing Guide.