rb-core-module

The Restboard core module

Getting started

First of all, you need to install the package in your project:

npm i --save rb-core-module

Now, you can start to define and use your resources:

import { createResource } from 'rb-core-module'

// Create a new resource
const users = createResource({
  name: 'users',
  provider: ..., // The data provider used to query the API
  ...
})

// Resources can then be used to interact with the remote API:
const me = await users.getOne(1)

RbResource

RbResource is a base class used to implement a proxy to interact with a remote API resource.

Options

Name	Description	Default
name	The unique resource name (e.g. users)
provider	The data provider used to interact with the API
key	The identifier attribute name	id
path	The resource base path (if different than name)	name
label	A human-readable description label for the resource	capitalized name
displayAttr	The attr used as representation of a single resource instance	key
stringify	A function used to get a human-readable reperesentation of a single resource instance	instance => instance[resource.displayAttr]
schema	The JSON schema representing the strcuture of resource instances	undefined
updateSchema	The JSON schema used on update	schema
createSchema	The JSON schema used on creation	schema
defaultParams	Default params passed to the data provider when fetching the API (e.g. default filters)	{}
isKeyEditable	If true, allows editing the key of an instance	false
actions	A map of actions executable on a single resource instance	{}
listeners	A list of callbacks to be called when the resource is marked as dirty	[]
methods	A dictionary of extra methods to extend the default resource API	{}
ui	An object containing UI-specific options and methods. A special formComponent key will be used to assign default form components for creation (ui.createFormComponent) and update (ui.updateFormComponent) if none are specified	{}

Methods

Signature	Description
getKey(instance)	Retrieve the primary key of the given resource instance
stringify(instance)	Render a string representation of the given resource instance
getOne(key, params)	Retrieve a single resource instance, identified by key and (optional) params
getMany(params)	Retrieve a list of resource instances according to the given (optional) params
createOne(data, params)	Insert a single resource instance with the given data and identified by (optional) params
updateOne(key, data, params)	Update a single resource instance, identified by key and (optional) params, with the given data
updateMany(data, params)	Update multiple resource instances according to data and (optional) params
deleteOne(key, params)	Delete a single resource instance identified by key and (optional) params
deleteMany(keys, params)	Delete multiple resource instances identified by the keys array and (optional) params
getRelation(key, name, opts)	Return the related resource identified by name, scoped to the instance identified by key. For opts see Relation options
getActions()	Return a dictionary of resource actions, where each action is bound to the resource
setDirty()	Set the resource lastUpdate with the current timestamp and notify registered listeners
addListener(callback)	Register a new listener callback
removeListener(callback)	Unregister a previously registered listener callback
mergeParams(params)	Merge given params with resource default ones

Relation options

Name	Description	Default
notifyParentOnDirty	If true mark also the parent resource as dirty on change	true

RbDataProvider

RbDataProvider is a generic interface used by resources to interact with a third-party API using the correct protocol and dialect.

Methods

Signature	Description
getOne(resourcePath, key, params)	See RbResource
getMany(resourcePath, params)	See RbResource
createOne(resourcePath, data, params)	See RbResource
updateOne(resourcePath, key, data, params)	See RbResource
updateMany(resourcePath, data, params)	See RbResource
deleteOne(resourcePath, key, params)	See RbResource
deleteMany(resourcePath, keys, params)	See RbResource

RbAuthProvider

RbAuthProvider is a generic interface used to perform authentication and authorization over a third-party API, abstracting the details of underlying strategies.

Methods

Signature	Description
login(credentials)	Attempt to log the user identified by the given credentials
logout()	Terminate the current authenticated session
recoverCredentials(challenge)	Attempt to recover user credentials providing a valid challenge response
activateOrResetCredentials(payload)	Activate or reset existing user credentials
checkAuth()	Check if the current authenticated session is still valid
getIdentity(user)	Given a user, retrieve its textual representation
getTenantIdentity(user)	Given a user, retireve its tenant identity
can(user, action, subject)	Check if the given user can perform action on the subject

Development

# Install dependencies
npm install

# Run tests
npm test

Contribute

If you want, you can also freely donate to fund the project development:

Have you found a bug?

Please open a new issue on:

https://github.com/restboard/rb-core-module/issues

License

Copyright (c) Emanuele Bertoldi

MIT License