Json:Api for Vuex

# Classes

Api
ResourcefulApi
ResourceProxy
ModuleBuilder
ResourceBuilder
FosJsRoutingRouter
JsonApiRoute
JsonApiRouter
Route
Router
StaticRoute
StaticRouter
Performance

# Functions

createApiResourceMethodProxy(api, method, route)
checkConfigProperty(config, property, isRequiredProp)
isAbsoluteUri(uri)
setCallbackFns(callbacks)
createVueInstance(store, components, mountedCallback) ⇒ Promise.<Vue>
prepareModuleHashMap(modules)

Converts a module listing object (e.g. { myModule: myModule }) to the expected syntax for module registration.

By default, this Vuex usage interpretation expects non-api-bound modules to have a name-property which defines their namespaced name. This is necessary to facilitate auto-registration of the modules.

N.b.: There is no checking done to avoid overwrites of these modules by later-to-be-initialized api-bound modules.

createVuexStore(Can) ⇒ Promise.<Store>

Create Vuex Store with API Plugin

initJsonApiPlugin(config)

Initialize the API Plugin

May receive a configuration object but at least needs a configured router.

createAction(api, moduleName)

Create a new resource

deleteAction(api, moduleName)

Delete a resource

getAction(api, moduleName)

Get a resource

listAction(api, moduleName, defaultQuery, module)

Get a resource list

listRelatedAction(api, moduleName)

Get a resource list of a related resource

Handles /resource/{id}/relation routes

saveAction(api, isCollection, moduleName, defaultQuery)

Update an existing resource

hasChanges(state)

Determine if an object has been changed

itemsInRelationshipFormat(state) ⇒ object

Return a listing of a collection module in the format required for a relationships-property of that module's type

isCollection(apiMethods)

Check whether the api supports collections

isMissingModule(store, moduleName)

Check if a module is registered in the store

registerMissingModule(store, api, moduleName)

Register a standalone module to the store.

prepareQuery(query, defaultQuery)

Make sure we always have a query object

processResponseData(vuexInstance, vuexFns, api, currentModule, data, currentMethod, module)

Process the (normalized) data part of a response

setResourceObjectsForModule(vuexFns, currentModule, destinationModule, objects)
validateResourceObject(resourceObject, isCreateResource)

Do a crude check for common json:api resource properties. This is (probably) not a long-term solution!

Assumptions made:

  • Resource Objects always have a type and a data section
  • newly created resources must not have an id (this is slightly stricter than the specification allows for and may be changed in the future)
  • every other resource object should have an id
removeMutation(isCollection)

Remove a ResourceObject from a module's item(s)

As with most mutations, the behaviour of deletion is slightly different depending on wether we're dealing with a collection or a single item.

If we're working on a collection, this mutation has to called as commit('module/remove', id), while, when working with an item, calling commit('module/remove') is sufficient. For convenience, any payload given is ignored when in item-only operation.

resetItemsMutation(isCollection)

Reset a module's items and initial items state

setItemMutation(resourceBuilder, isCollection)
setMutation(store, resourceBuilder, isCollection)

Proxy for setting Resource Objects on a Module

Depending on the type of module (collection or single item) setting has two different behaviours and thus also two different signatures.

The Vuex.commit-Syntaxes for those different styles are

  • commit('module/set', object) for single item modules and
  • commit('module/set', { id, object }) for collection-type modules

Setting an object results in it being added to or updated in the item/items property of the module state.

setPaginationMutation(state, pagination)

Set pagination data from a meta.pagination object

registerBaseModule(store, api, moduleName)
getRelationship(store, relatedObject)
hasLoadableRelationship(obj)

Check if an object has a loadable relationship

hasLoadedRelationship(obj)

Check if an object has a loaded relationship

listRelationship(store, relatedObjects)
getRelationshipConfig(relatedObject) ⇒ Object

Config Getter for the RelationshipMethod

initialState(isCollection)

Return a new Object representing the initial state of a module

The state is returned from inside a self-calling closure to make absolutely sure we get pristine objects. This is a safety measure to guard against unintended cross-module reference bindings.

hasOwn(object, property)

Convenience wrapper to shorten the hasOwnProperty call

deepMerge(target, source) ⇒ Object

Performs a deep merge of source into target. Mutates target only but not its objects and arrays.

# Api

Kind: global class

# new Api()

Wrapper around json:api requests, sets content type and other defaults.

# api.setPreprocessingCallbacks(callbacks)

Kind: instance method of Api

Param Type
callbacks Array

# api.setErrorCallbacks(callbacks)

Kind: instance method of Api

Param Type
callbacks Array

# api.addPreprocessingCallback(callback)

Kind: instance method of Api

Param Type
callback function

# api.addErrorCallback(callback)

Kind: instance method of Api

Param Type
callback function

# api.resetPreprocessing()

Reset the response preprocessing to the default behaviour

Kind: instance method of Api

# api.resetErrorCallbacks()

Reset the response error to the default behaviour

Kind: instance method of Api

# api.addHeaders(headers)

Kind: instance method of Api

Param Type
headers Object

# ResourcefulApi

Kind: global class

# resourcefulApi.doRequest(method, url, params, data, options)

Extends Api::doRequest() to handle some data preprocessing.

The api modules don't require access to all of the response and they expect the response data to be normalized.

Kind: instance method of ResourcefulApi

Param Type
method String
url String
params Object
data Object
options Object

# resourcefulApi.setupResourcefulRequests(router)

Prepare the routable requests

Kind: instance method of ResourcefulApi

Param Type
router route.Router

# resourcefulApi.setStore(store)

Kind: instance method of ResourcefulApi

Param Type
store Vuex.Store

# resourcefulApi.setupApiModules(apiModulesToRegister)

Kind: instance method of ResourcefulApi

Param Type
apiModulesToRegister Array

# resourcefulApi.registerModule(moduleName, methods)

Kind: instance method of ResourcefulApi

Param Type
moduleName String
methods Route

# resourcefulApi.registerResourceMethods(routeName, methods)

Kind: instance method of ResourcefulApi

Param Type
routeName String
methods Route

# resourcefulApi.registerApiModule(moduleName)

Register an api module

After api initialization, this is the way to register non-default modules.

its purpose is to get called from store, where its referenced from the initJsonApiPlugin. At that point this is the store and not the api object

Kind: instance method of ResourcefulApi

Param Type
moduleName String

# resourcefulApi.getAvailableApiModules(onlyUnregistered) ⇒ Array

Get a list of available api modules

A module is available if it has defined routing. If onlyUnregistered is set to false, this list will also return already registered modules.

Kind: instance method of ResourcefulApi

Param Type Default
onlyUnregistered Boolean true

# ResourceProxy

Kind: global class

# new ResourceProxy()

ResourceProxy

A wrapper class for the available methods on a route. The actual proxied axios-clients will only be created once the first request on a method is made.

# resourceProxy.addRoute(route)

Adds a method to the resource

Kind: instance method of ResourceProxy

Param Type
route Route

# resourceProxy.methodNotAvailable(methodName)

Used by the resource method availability checks to indicate a missing method.

Kind: instance method of ResourceProxy

Param Type
methodName string

# ModuleBuilder

Kind: global class

# new ModuleBuilder()

JsonApi-based module builder for Vuex

This module builder will create a vuex module based on the assumption of working with valid json api resources.

  • the proposed json api 1.1 pagination style meta attributes (-> https://jsonapi.org/format/1.1/#fetching-pagination)

# moduleBuilder.ModuleBuilder

Kind: instance class of ModuleBuilder

# new exports.ModuleBuilder(store, api, moduleName, apiMethods, options, presetModuleName)

Module Builder for Json:Api bound Vuex Modules

Param Type Default Description
store Vuex
api ResourcefulApi
moduleName String
apiMethods Array
options Object additional objects for the module builder
presetModuleName String

# moduleBuilder.build()

Build the module for this builder instance

Kind: instance method of ModuleBuilder

# moduleBuilder.buildOptions()

Build the options

Kind: instance method of ModuleBuilder

# moduleBuilder.buildMutations()

Build the mutations

Kind: instance method of ModuleBuilder

# ResourceBuilder

Kind: global class

# resourceBuilder.build(jsonResourceObject)

Returns a new functional resource object

Functional resource objects are structurally identical to normal JSON:API resource objects but are enhanced with methods to simplify access to relationships.

Kind: instance method of ResourceBuilder

Param Type
jsonResourceObject Object

# resourceBuilder.buildRelationshipMethods(jsonResourceObject)

Adds Methods (get, load, list) to the relationships for getting / loading them Adds Shorthand Methods (rel / loadRel)

Kind: instance method of ResourceBuilder

Param Type
jsonResourceObject Object

# ResourceBuilder.strip(functionalResourceObject)

Convenience method to get a spec-conforming version of a resource object

Kind: static method of ResourceBuilder

Param Type
functionalResourceObject Object

# FosJsRoutingRouter

Kind: global class
See

  • https://github.com/isychev/fos-routing/
  • https://github.com/FriendsOfSymfony/FOSJsRoutingBundle

# new FosJsRoutingRouter()

Pluggable api router if you're using Symfony and the FosJsRouting Bundle

# JsonApiRoute

Kind: global class

# new JsonApiRoute()

Create a route from a Json:Api resource of the VuexJsonApiRoute-type:

{
  "type": "VuexJsonApiRoute",
  "attributes": {
    "module": "themodule",
    "method": "thehttpmethod"
    "url": "The URL of the Resource, can be relative to baseURL",
    "parameters": ["Parameters", "for", "the", "above", url"]
  }
}

# jsonApiRoute.JsonApiRoute

Kind: instance class of JsonApiRoute

# new exports.JsonApiRoute(routeResource)

Param Type
routeResource Object

# JsonApiRouter

Kind: global class

# new JsonApiRouter()

A simple router implementation querying a json:api endpoint which delivers all necessary route information

The endpoint must return a list of Route objects:

{
    "data": [
        {
            "type": "VuexJsonApiRoute",
            "id": 1,
            "attributes": {
                "parameters": [],
                "url": "api/route",
                "method": "list",
                "module": "route"
            }
       },
       {
           "type": "VuexJsonApiRoute",
           "id": 2,
           "attributes": {
               "parameters": [
                   "id"
               ],
               "url": "api/route/{id}",
               "method": "get",
                "module": "route"
           }
       }
    ]
}

To initialize this router, simply new it with the desired fetch path, e.g. new JsonApiRouter('/api/route').

# jsonApiRouter.JsonApiRouter

Kind: instance class of JsonApiRouter

# new exports.JsonApiRouter(baseUrl, fetchPath)

Param Type
baseUrl String
fetchPath String

# jsonApiRouter.updateRoutes() ⇒ *

Update routes

Kind: instance method of JsonApiRouter

# Route

Kind: global class

# route.Route

Kind: instance class of Route

# new exports.Route(module, action, url, parameters)

Param Type
module String
action String
url String
parameters Array

# route.prepare(parameters) ⇒ string

Prepare an url, replacing provided parameters

Kind: instance method of Route

Param
parameters

# route.hasParameter(parameter) ⇒ boolean

Check if a parameter is allowed

Kind: instance method of Route

Param
parameter

# route.isValidAction(action)

Kind: instance method of Route

Param Type
action String

# Router

Kind: global class

# new Router()

Basic router implementation for the ResourcefulApi.

Automagically creating api bound modules builds on an understanding of the available routes. To easily instantiate a Store bound to an endpoint, route information for that endpoint must be provided.

Since every endpoint is implemented differently and the choice where this route information comes from should be left to the endpoint developer, this library only assumes that route loading can be a asynchronous process which eventually returns and has a set of Route objects in this.routes, keyed by their module and methods. To ensure the latter, actually adding Routes should be done via addRoute.

# router.getRoutes() ⇒ Array.<Route>

Kind: instance method of Router

# router.addRoute(route)

Kind: instance method of Router

Param Type
route Route

# StaticRoute

Kind: global class

# new StaticRoute()

Parses a static route data object into a Route

[
  {
    "module": "MyApiModule",
    "action": "GET",
    "url": "/api/my-api-module/{id}",
    "parameters": ["id"]
  }
]

# StaticRouter

Kind: global class

# new StaticRouter()

Static router

It may be desirable to not do an additional request for getting the api routes and instead bake them into the code. To this avail, the StaticRouter can be initialized with a POJO of { id, url, parameters } whereas parameters are parts of the url which can be replaced.

When using the StaticRouter it is not necessary to call updateRoutes before passing the Router onwards.

# staticRouter.StaticRouter

Kind: instance class of StaticRouter
See: StaticRoute

# new exports.StaticRouter(routes)

Requires an array of route data objects.

Param Type
routes Array

# Performance

Kind: global class

# new Performance()

Wrapper around the performance markers api

# createApiResourceMethodProxy(api, method, route)

Kind: global function

Param Type
api Api
method String
route Route

# checkConfigProperty(config, property, isRequiredProp)

Kind: global function

Param Type
config object
property String
isRequiredProp Boolean

# isAbsoluteUri(uri)

Kind: global function

Param Type
uri String

# setCallbackFns(callbacks)

Kind: global function

Param Type
callbacks Array

# createVueInstance(store, components, mountedCallback) ⇒ Promise.<Vue>

Kind: global function

Param Type
store Vuex.Store
components Vue | object
mountedCallback function

# prepareModuleHashMap(modules)

Converts a module listing object (e.g. { myModule: myModule }) to the expected syntax for module registration.

By default, this Vuex usage interpretation expects non-api-bound modules to have a name-property which defines their namespaced name. This is necessary to facilitate auto-registration of the modules.

N.b.: There is no checking done to avoid overwrites of these modules by later-to-be-initialized api-bound modules.

Kind: global function

Param Type
modules object | array

# createVuexStore(Can) ⇒ Promise.<Store>

Create Vuex Store with API Plugin

Kind: global function
See: initJsonApiPlugin

Param Type Description
Can Object | Router either just pass a router or a full config object

# initJsonApiPlugin(config)

Initialize the API Plugin

May receive a configuration object but at least needs a configured router.

Kind: global function

Param Type Description
config Router | Object or router

# createAction(api, moduleName)

Create a new resource

Kind: global function

Param Type
api ResourcefulApi
moduleName String

# deleteAction(api, moduleName)

Delete a resource

Kind: global function

Param Type
api ResourcefulApi
moduleName String

# getAction(api, moduleName)

Get a resource

Kind: global function

Param Type
api ResourcefulApi
moduleName String

# listAction(api, moduleName, defaultQuery, module)

Get a resource list

Kind: global function

Param Type Description
api ResourcefulApi
moduleName String
defaultQuery Object
module Object storeModule at point of initialisation

# listRelatedAction(api, moduleName)

Get a resource list of a related resource

Handles /resource/{id}/relation routes

Kind: global function

Param Type
api ResourcefulApi
moduleName String

# saveAction(api, isCollection, moduleName, defaultQuery)

Update an existing resource

Kind: global function

Param Type
api ResourcefulApi
isCollection Boolean
moduleName String
defaultQuery Object

# hasChanges(state)

Determine if an object has been changed

Kind: global function

Param Type
state Object

# itemsInRelationshipFormat(state) ⇒ object

Return a listing of a collection module in the format required for a relationships-property of that module's type

Kind: global function

Param Type
state object

# isCollection(apiMethods)

Check whether the api supports collections

Kind: global function

Param Type Description
apiMethods object supported api methods (list, get, update, delete)

# isMissingModule(store, moduleName)

Check if a module is registered in the store

Kind: global function

Param Type
store Vuex
moduleName String

# registerMissingModule(store, api, moduleName)

Register a standalone module to the store.

Kind: global function

Param Type
store Vuex
api ResourcefulApi
moduleName String

# prepareQuery(query, defaultQuery)

Make sure we always have a query object

Kind: global function

Param Type
query object
defaultQuery object

# processResponseData(vuexInstance, vuexFns, api, currentModule, data, currentMethod, module)

Process the (normalized) data part of a response

Kind: global function

Param Type Description
vuexInstance Vuex
vuexFns Object
api ResourcefulApi
currentModule String name of the current storeModule
data Object payload from request
currentMethod String default = ''
module Object storeModule

# setResourceObjectsForModule(vuexFns, currentModule, destinationModule, objects)

Kind: global function

Param Type
vuexFns *
currentModule *
destinationModule *
objects *

# validateResourceObject(resourceObject, isCreateResource)

Do a crude check for common json:api resource properties. This is (probably) not a long-term solution!

Assumptions made:

  • Resource Objects always have a type and a data section
  • newly created resources must not have an id (this is slightly stricter than the specification allows for and may be changed in the future)
  • every other resource object should have an id

Kind: global function

Param Type
resourceObject Object
isCreateResource Boolean

# removeMutation(isCollection)

Remove a ResourceObject from a module's item(s)

As with most mutations, the behaviour of deletion is slightly different depending on wether we're dealing with a collection or a single item.

If we're working on a collection, this mutation has to called as commit('module/remove', id), while, when working with an item, calling commit('module/remove') is sufficient. For convenience, any payload given is ignored when in item-only operation.

Kind: global function

Param Type
isCollection Boolean

# resetItemsMutation(isCollection)

Reset a module's items and initial items state

Kind: global function

Param Type
isCollection Boolean

# setItemMutation(resourceBuilder, isCollection)

Kind: global function

Param Type
resourceBuilder resource.Builder
isCollection boolean

# setMutation(store, resourceBuilder, isCollection)

Proxy for setting Resource Objects on a Module

Depending on the type of module (collection or single item) setting has two different behaviours and thus also two different signatures.

The Vuex.commit-Syntaxes for those different styles are

  • commit('module/set', object) for single item modules and
  • commit('module/set', { id, object }) for collection-type modules

Setting an object results in it being added to or updated in the item/items property of the module state.

Kind: global function

Param Type
store Vuex.Store
resourceBuilder resource.Builder
isCollection Boolean

# setPaginationMutation(state, pagination)

Set pagination data from a meta.pagination object

Kind: global function

Param Type
state Object
pagination Object

# registerBaseModule(store, api, moduleName)

Kind: global function

Param Type
store Vuex.Store
api ResourcefulApi
moduleName String

# getRelationship(store, relatedObject)

Kind: global function

Param Type
store Vuex.Store
relatedObject Object

# hasLoadableRelationship(obj)

Check if an object has a loadable relationship

Kind: global function

Param Type
obj Object

# hasLoadedRelationship(obj)

Check if an object has a loaded relationship

Kind: global function

Param Type
obj Object

# listRelationship(store, relatedObjects)

Kind: global function

Param Type
store Vuex.Store
relatedObjects Array

# getRelationshipConfig(relatedObject) ⇒ Object

Config Getter for the RelationshipMethod

Kind: global function

Param
relatedObject

# initialState(isCollection)

Return a new Object representing the initial state of a module

The state is returned from inside a self-calling closure to make absolutely sure we get pristine objects. This is a safety measure to guard against unintended cross-module reference bindings.

Kind: global function

Param Type
isCollection Boolean

# hasOwn(object, property)

Convenience wrapper to shorten the hasOwnProperty call

Kind: global function

Param Type
object Object
property String

# deepMerge(target, source) ⇒ Object

Performs a deep merge of source into target. Mutates target only but not its objects and arrays.

Kind: global function
Returns: Object - merged Orbject
Author: inspired by jhildenbiddle.

Param Type
target Object
source Object