The Parameter API

From MakeProAudio MediaWiki
Jump to navigation Jump to search

Overview

parameters-js is a real-time, value synchronization system. It is designed as a convenience library to inform interested parties in knowing that a value they are interested in has changed, by either listening to value changes or by binding to that value, such that all interested parties remain in sync in real time.
Over time, parameters-js has evolved into not just synchronizing values, but also synchronizing metadata. This combination of value and metadata is now wrapped inside an object called a Parameter.

Typically in a real-time application, several components across the application’s architecture need to be able to read from and write to a common value. In an event-driven system like node js, it would be very feasible to transfer these values via events, in which case, every interested party would necessarily need to become or have an instance of an event emitter. Topic names, event sources, latent creation and destruction of events, etc. would need to be managed resulting in development overhead. This is where Parameters become effective.

Parameters are lightweight objects that can be loosely used to keep values across different components in a large application with multiple moving parts.

The current implementation of the parameters-js library is very top-down; implementation was done to cater to the demands of the use cases of makehaus-js, so several functions may be unimplemented.

Branching

The develop branch is the default development branch.

Cloning

Clone the repository and from the working directory execute

https://github.com/makeproaudio/parameters-js.git
npm i

This will pull all necessary dependencies as defined in package.json into the node_modules/ folder.

Repository Structure

Only relevant files used in development are mentioned below:

.vscode/
dist/
node_modules/
src/
        parameter/
                *
package.json
tsconfig.json
rollup.config.js
prettier.config.js

Initial Setup

Nothing special apart from instructions mentioned in the Initial Setup For Typescript Projects

Typical Development Workflow

The development workflow described below is for those developers who want to modify the core parameters-js repository and not for those who wish to have a dependency on the parameters-js npm package. To use makehaus-js as a dependency, execute the following command from your package’s working directory:

npm i @makeproaudio/parameters-js

In addition to the Typical Development Workflow For Typescript Projects:

  • The parameters-js is written as a library and since it does not have any examples section or test code, it has no “direct” entry point.

Deployment

Nothing special to note in addition to Deployment For Typescript Projects.

Making A Standalone Build

Nothing special to note in addition to Deployment For Typescript Projects.

Publishing A New Version

Nothing special to note in addition to Deployment For Typescript Projects.

Technology

  • rxjs - an event streaming and processing library based on the reactive programming paradigm
  • node js events module - the native ‘events’ module of the node js runtime

Architecture

The main components of the library are:

  • Types
  • Registry
  • Value
  • Metadata
  • Synapse And Binding

Types

The Type of a Parameter indicates the acceptable Value type of that Parameter. Classically, Parameters can be of the following types:

  • Number - value is a number
  • NumberArray - value is a number amongst a supplied array of numbers
  • String - values is a string
  • StringArray - values is a string amongst a supplied array of strings
  • Boolean - value is a boolean

Super Parameter

It is not possible to interchange the types of these Parameters amongst themselves, i.e., it is not possible to change a Number Parameter to a String Parameter. This was found to be a major limitation in serving certain use cases, where the Type of a Parameter needed to be flexible. To cater to this use case, a new Type of Parameter was created:

  • SuperParameter - value can be anything amongst the classically supported Parameter Types

The SuperParameter adds an abstract, opinionated logical layer over different Parameter Types. Refer to SuperParameter (src/parameter/parameter-types.ts) for more details. To change the Type of a SuperParameter, a SuperParameterTypeChangeRequest (src/parameter/parameter-types.ts) has to be used.

Registry

Parameters are lightweight objects that are typically created and destroyed very often. The ParametersRegistry (src/parameter/parameters.ts) provides a convenient way to manage them. It is the only acceptable way to create a new Parameter.

To create a Parameter via the Registry, you need to supply a unique id and a namespace. There are use cases where an object anticipates the creation of a Parameter with a specific id. The namespace is required for advanced filtering use cases where Parameters may be latently generated. In this case, the Registry informs the interested parties of the creation of the Parameter.

To fulfil this latent Parameter creation use case, rxjs is used in a very trivial fashion.

Value

At any point in time, a Parameter can have exactly one Value. The Parameter Type determines the type of the Value the Parameter can accommodate.

Metadata

Metadata is a map of key value pairs which a Parameter can use to store any metadata relevant to it. The Metadata comes handy when metadata of Parameters is to be kept in sync. For example, in MakeHaus, colour and label are two metadata elements of Parameters.

Synapse And Binding

Binding is the act of a Parameter (P) attaching itself to another Parameter (X) to essentially “behave” like a clone of the other. That means:

  • If the Value/Metadata of P changes, the Value/Metadata of X follows
  • If the Value/Metadata of X changes, the Value/Metadata of P changes

Synapse (src/parameter/synapse.ts) is the underlying implementation which achieves this behaviour.

The Synapse is the Parameter’s source of truth in a system where a value can be updated from multiple sources. At any point of time, a Parameter can only be a part of one Synapse.

Synapse scheme

Synapses are not visible in user land - they hold only development relevance.

Directional Nature Of Binding

Binding is a directional phenomenon:

  • P bindFROM X indicates that P absorbs the Value/Metadata of X, hence in this example, P’s new value becomes 10
  • P bindTO X indicates that P would push its Value/Metadata on to X, hence in this example, if the bind call was TO, X’s new Value would become 99

Outlook

  • Examples / Tests - Add examples and/or test code for the library
  • Implement BindTo Functionality - At the time of writing this document, the BindTo implementation from the Parameter class was removed due to an unknown bug. Ideally a fresh implementation for BindTo needs to be done.
  • Implement Synchronization Of Metadata - Currently, Parameters do not receive callbacks when Metadata of bound Parameters change
  • Implementation Networking Of Parameters - Currently, parameters-js is not designed to synchronize Parameters across the Network.