blackbox-services
v1.0.0
Published
Interfaces matching the schema definitions of a Blackbox service and associated helper functions.
Downloads
3
Readme
blackbox-services
Interfaces matching the schema definitions of a Blackbox service and associated helper functions.
The blackbox-services package provides interfaces that match the Blackbox API specification and helper functions for delivering its hierarchical service structure including generation of verbose responses, trimming responses with hierarchical data linking, and generating service objects.
The features provided in this package are primarily designed for use with the code generated by the Blackbox CLI.
For further information about the Blackbox Specification refer to the Blackbox website.
Table of Contents
Install
npm i blackbox-services
Usage
Mark a class as a hierarchical node in an API:
@hierarchical({path:"/weather/temperature"})
class Temperature {
...
}
Wrap an object in a VerboseObject for compliance with the Blackbox API specification response to the verbose query parameter.
myServiceMethod({verbose}:{verbose:boolean}):MyDatatype|VerboseObject {
return verboseResponse(new MyDatatype(), verbose)
}
Trim descendant nodes from an object for compliance with Blackbox API specification hierarcical data linking (only parameters whose type has been marked as hierarchical will be replaced with a Link):
myServiceMethod({depth}:{depth:number}):MyDatatype|VerboseObject {
return trimToDepth(new MyDatatype(), depth)
}
Create a service object for a parent service (one that contains sub-services) from an OpenAPI Document:
makeServiceObject(oasDoc, 'my-parent-service')
Process all child paths grouped by their parent:
findParentPaths(oasDoc).forEach((parentPath:string) => {
findChildren(oasDoc, parentPath).forEach((childPath:string) => {
...
})
})
An example of creating a Blackbox API can be found on the Blackbox website.
API
Interfaces
ServiceType provides an interface to match the Service Type definition in the Blackbox API specification including uri:string
, name:string
, format:string
and description:string
properties.
Links are used by VerboseObject
s in verbose mode and for hierarchical data linking according to the Blackbox API specification including href:string
and description?:string
properties.
Links: A map of Link
s.
ServiceLink extends the Link
interface to provide an array of ServiceType
s used by the links
property of the service data structure according to the Blackbox API specification.
ServiceLinks: A map of ServiceLink
s.
Service models the service data structure according to the Blackbox API specification including description:string
, bbversion:string
and links:ServiceLinks
properties.
NamedReference provides a simple interface including a name:string
property for convenience when working with objects that are identified by their name.
VerboseObject provides an interface to match the verbose mode responseaccording to the Blackbox API specification including a links?:Links
property.
Helper Functions
hierarchical(params:{path:string}): Provides a decorator for marking a class as hierarchical. The path
parameter specifies the URL to the service that serves the datatype defined by the class. The path is used by the trimToDepth()
function to identify nodes that can be trimmed and to generate the link to the service when the node is trimmed.
nameOf(data:NamedReference):NamedReference: Returns an object with the name
property from the given data and some private properties used by the blackbox-service package.
verboseResponse(target:T|T[], verbose:boolean = false):(VerboseObject&T)|(VerboseObject&T)[]: Returns a VerboseObject
combined with the given target or a VerboseObject
array with each given target combined with a VerboseObject
.
verboseResponseArray(targets:T[], verbose:boolean = false):(VerboseObject&T)[]: Returns a VerboseObject
array with each given target combined with a VerboseObject
.
trimToDepth(entity:any, depth:number = 0):any: Trims descendant nodes from an object and replaces them with Link
s for compliance with Blackbox API specification hierarcical data linking. Only parameters whose type has been marked as hierarchical will be replaced with a Link. Depth is measured from the root such that for a depth of zero all immediate children that are hierarchical will be replaced; for a depth of one immediate children will be preserved and their immediate children will be replaced, and so on.
trimToDepthArray(entity:any[], depth:number = 0):any[]: Trims each element of the array as per trimToDepth()
.
hasChildren(oasDoc:any, path:string):boolean: Searches the given OpenAPI document for any paths that are children of path
and returns true if any are found. For example, given path /weather
, the function will return true if it finds any other paths such as /weather/temperature
.
findParentPaths(oasDoc:any):string[]: Searches the given OpenAPI document for all paths that are immediate children of the root path (/
) and for which hasChildren()
returns true. For example, given paths /weather
, /weather/temperature
, /myservice
, /myservice/mysubservice
, /myotherservice
, only /weather
and /myservice
are considered parents since /myotherservice
does not have any sub-services. Note that a parent path corresponds to a parent service that should provide a Service
object that includes links to each child service in its links
property.
findChildren(oasDoc:any, rootServiceName:string):string[]: Searches the given OpenAPI document for any paths that are children of path
and returns all matches in an array. For example, given path /weather
, the function will return true if it finds any other paths such as /weather/temperature
.
makeServiceObject(oasDoc:any, rootServiceName:string):Service: Creates a Service
object for the service with the given name according to the given OpenAPI document.
Maintainers
Contributing
PRs accepted.
Small note: If editing the README, please conform to the standard-readme specification.
License
MIT © 2019 Ben Millar