Transporter

What is Transporter?

Transporter is a easy-to-use layer on top of whatever data storage engine you currently use.

How to install.

• NPM: npm install transporterjs
• Source: Clone -> Copy index.js and optionally index.js.map to a folder in your project directory and import.

Importing

Use const {requiredclasses} = require('transporterjs') replacing requiredclasses with the classes you need for your project. If you want to import everything, use:

import {DataStructure, ManagedDataStructure, CustomBackendService, BackendService} = require('transporterjs')

How does Transporter work?

We support two different methods of upgrading data:

1. Overwrite. You give Transporter your entire dataset and it gives you the entire set back. Simple. See the adapt() function.
2. Feed. You give Transporter your entire dataset and it gives you back each object in your set, one at a time. See the adaptEach() function.

To use either of these functions, you must instantiate an instance of DataStructure. The constructor take two arguments, adaptProperties, which is an array of String, and adaptObject, an array of JavaScript objects. adaptProperties must be an array of strings in the format "oldkey-newkey". In this example, if you had an object with the key "oldkey", you would recieve an object with the key "newkey", but the same value.

If you want to use Transporter as a fully-managed data engine, check out ManagedDataStructure documentation. Basically, it is a wrapper for a PostgreSQL or any other database engine. It comes standard with updating features.

Warnings/Notes

• If you don't include a property in the adaptProperties array, that property won't be copied. If you need an object retained, use the same key.

Usage

DataStructure

The generic class for anything you need to adapt. You must fill the objects property.

Constructor

new DataStructure(properties: [string])

• properties: An array of properly formatted Adapter Strings

adapt()

Arguments

• None

Return value

• Array of objects, adapted.

adaptEach()

Arguments

• item: Callback function of type (object or {}) -> void. The adapted object will be the first and only argument sent to this function.

Return value

• None

ManagedDataStructure

A fancy DataStructure that is designed for non-local backends such as PostgreSQL. This class is a wrapper for a BackendService.

Constructor

new ManagedDataSource(properties:[string], primaryKey:string, version:string, service:BackendService)

• adaptProperties: An array of properly formatted Adapter Strings
• primaryKey: A primary key that Transporter will use. Optional but recommended. If you don't use it, you'll have to specify a column in every request.
• version: An arbitrary version. This can be a number, string, anything. If the requested entry in the database doesn't have the same version number as this, Transporter will update the entry.
• backendService: A service that ManagedDataSource will call. Create a subclass of BackendService to use. Currently, only a CustomBackendService is available. Check out the documentation for more information.

insert(object:{})

Forwards object to the backendService's insert() function.

Arguments

• object: A object that you want to insert into this database.

remove(value:any,key:string = this.primaryKey)

Forwards arguments to the backendService's remove() function. Anything found in the column key that matches value will be removed.

Arguments

• value: Anything that you want to be deleted.
• key: Optional. If this is null, it will default to primaryKey.

getAll():Promise<[{}]>

Async function to get all objects from a dataset.

Arguments

None

Return value

• Array of object in a Promise for async reasons.

get(value:any,key:string = this.primaryKey):Promise<{}>

Async function to get one object where the value of key key matches the provided value.

Arguments

• value: Anything that you want to be retrieved.
• key: Optional. If this is null, it will default to primaryKey.

Return value

• object in a Promise for async reasons. If the object isn't already updated to the latest version specified in version, Transporter will update it.

BackendService

This is an abstract class that you can subclass to become a data source for a ManagedDataStructure.

Required Functions

• insert(object): Insert object
• remove(key, value): Remove object where key = value
• getAll() => Promise<[{}]>: Return all objects (async)
• getOne(key, value) => Promise<{}>: Return object where key = value

CustomBackendService

The easiest way to have a custom BackendService without subclassing. All of the callback handlers are parameterized versions of the BackendService required functions. Check the BackendService documentation for more info.

Constructor

new CustomBackendService(insert:(item:{})=>void, remove:(key:any, value:any)=>void, getAll:()=>[{}], getOne:(key:string, value:any)=>{})

• insert: A callback handler to insert. You get an object passed to this handler.
• remove: A callback handler to remove. You get a key and value passed to this handler.
• getAll: A callback handler to get all of the items. Return a Promise with all the items.
• getOne: A callback handler to get just one item. You get a key and value passed to this handler. Return a Promise with a JavaScript object.

Adapter Strings

What are adapter strings?

Adapter strings are just normal strings of the format 'nameofoldkey-nameofnewkey`.