@financial-times/biz-ops-schema-sdk
v1.0.0
Published
In many ways, this is the beating heart of Biz Ops&TM;. It consumes the schema files that define what sort of records can be stored in the neo4j instance, and what relationships can exist between them. These schema files may exist locally or be hosted som
Downloads
243
Maintainers
Keywords
Readme
@financial-times/biz-ops-schema-sdk
This library provides a means to consume the Biz Ops schema so that applications can automatically keep up to date with changes to it.
Installation and usage
npm install @financial-times/biz-ops-schema-sdk
The package exports a singleton instance, and once initialised, @financial-times/biz-ops-schema
can be required multiple times in the application. It should be initialised once and once only per application. It also exports a reference to the underlying SDK
class, but this is only exposed for use by other packages' integration tests.
Configuring
Exposes an .init()
method, which accepts the following options (which can also be set using environment variables). In most cases it's recommended to use environment variables as this means .init() does not need to be called explicitly.
sourceUrl
|BIZ_OPS_SCHEMA_URL
- Url the sdk will poll to retrieve new versions of the schema.sourceData
- a javascript object containing a complete Biz Ops schema. Generally only used in tests
Initialising
Calling await schema.ready()
will automatically call schema.init()
(if not already called) with whatever options can be derived from the environment. This is the preferred way to initialise, but schema.init()
can be called manually when it is useful to control the exact point at which schema data is fetched. In particular, schema.init()
must be called with appropriate options when running on the client side.
Troubleshooting
It's important that an application installs only one copy of biz-ops-schema. If an application installs other packages, e.g. biz-ops-view, that install biz-ops-schema-sdk then
a) make sure the versions of biz-ops-schema-sdk specified in their package.json files are compatible
b) if multiple copies of biz-ops-schema-sdk exist in node_modules despite compatibility, run npm prune
or delete your node_modules and run a fresh install.
A note on lambdas
Previous versions of the schema sdk required explicitly specifying whether a polling or stale on refresh strategy for updating was used. This is now deduced from the environment the sdk is running in and does not need to be set explicitly.
The only difference between usage is that in a lambda compared schema.ready() shoudl be awaited at the beginning of each handler, whereas in a persistent server it's fine to await it once on app startup.
SDK API
Once initialised the sdk exposes a number of methods to access schema data:
Schema access APIs
All methods use an internal caching mechanism, which is flushed whenever the schema updates. For this reason
- It is safe to call these methods many times because the complex transformation of values is only executed on the first invocation
- It is an antipattern to store the result of any invocation in a variable for any non synchronous period of time - this may result in incorrect reading or writing of data
- There is an
onChange(func)
method that can be used to attach handlers that will be called every time the schema changes
getType(type, options)
Get an object defining the structure of a given type
. The following transforms will be executed on the raw yaml data.
- if no
pluralName
field is defined, it will be generated - any named stringPatterns will be converted to validation functions
The full object structure returned by getType() can been seen here
options
withRelationships
[default:true
]: Include the relationships for the type, expressed as graphql property definitions.groupProperties
[default:false
]: Each property may have afieldset
attribute. SettinggroupProperties: true
removes theproperties
object from the data, and replaces it withfieldsets
, where all properties are then grouped by fieldsetincludeMetaFields
[default:false
]: Determines whether to include metadatafields (prefixed with_
) in the schema object returnedincludeSyntheticFields
[default:true
]: Determines whether to include synthetic fields (those using a custom cypher statement) in the schema object returneduseMinimumViableRecord
[default:false
]: IfgroupProperties
istrue
, this will put any fields defined as being part of the minimum viable record (see model spec) together in a single fieldset
getTypes(options)
Get an array of objects defining the structure of all types. All options
for getType
are supported and determine the internal structure of each type. Additionally, the following options can be specified:
grouped
[default:false
] - determines whether to return the types as a flat array, or an object grouping types in categories. Each category specifies a label, description and list of types.
getEnums(options)
Retrieves an array of key:value objects defining the acceptable values of an enum
options
withMeta
: wrap the enum in an object which also has metadata about the enum (e.g. 'description'.). In this case, the actual enum options will be in aoptions
property
validateTypeName(typeName)
Validates that a type of the given name exists in the schema
validateCode (typeName, code)
Validates that a code string matches the validation pattern defined for codes for the given type
validatePropertyName ( propertyName )
Validates that a string is a valid name for an attribute (i.e. camelCase)
validateProperty(typeName, propertyName, propertyValue)
Validates that the value of a property for a given type is valid
normalizeTypeName
Should be used when reading a type name from e.g. a url. Currently is a noop, but will allow consistent rolling out of more forgiving url parsing in future if necessary
The methods below are unimplemented
describeGraphqlQuery(query)
Decorates a graphql query with metadata from the schema