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
• Usage
• API
• Maintainers
• Contributing
• License

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 VerboseObjects 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 Links.

ServiceLink extends the Link interface to provide an array of ServiceTypes used by the links property of the service data structure according to the Blackbox API specification.

ServiceLinks: A map of ServiceLinks.

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 Links 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

@ellipsistechnology

Contributing

PRs accepted.

Small note: If editing the README, please conform to the standard-readme specification.

License

MIT © 2019 Ben Millar