# 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, callingcommit('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 arecommit('module/set', object)
for single item modules andcommit('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
intotarget
. Mutatestarget
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 Route
s 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
# 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
# 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 andcommit('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 (opens new window).
Param | Type |
---|---|
target | Object |
source | Object |