Keys and Parameters

The library offers a flexible and typesafe means to create Parameters to store values like primitive types, collection types or domain specific types.

A Parameter is a Key and Value where the Value must be from a set of defined primitive types including binary data. The Value of a Parameter is always considered to be an Array of the type (i.e. if a single value is stored it is at array location 0). A Parameter is immutable; a modification to an existing Parameter will return a new instance.

A Value can also have Units, which must be of the defined types. See Units for more information. At this time Units are informational only – no calculation or conversion support is provided. Some systems may provide a key value with different units, and receiver can inspect the Units to make a decision on how to handle the value.

A ParameterSet is a Set of Parameter. Various other message types include a ParameterSet (e.g. Setup, Event). A key is unique in a ParameterSet since it is a Set.

How to create a Parameter using the helper functions

• Choose an appropriate KeyType from the tables below.
• Calling the set method on KeyType helper and supplying a string keyName will return a suitably typed parameter instance.

Example snippets for creating parameter of simple, array and matrix type

Typescript

// primitives
const booleanParam: Parameter<BooleanKey> = booleanKey('flag').set([false])

const intParam: Parameter<IntKey> = intKey('RandomKeyName').set([123, 12432])
// intParam.keyName === 'RandomKeyName'
// intParam.keyTag === 'IntKey'
// intParam.values === [123, 12432]
// intParam.units === 'NoUnits' // default unit is `NoUnits`
// -------------

// arrays
const filterkey = intArrayKey('filter')
const filterParam: Parameter<IntArrayKey> = filterkey.set([
  [1, 2, 3],
  [4, 5, 6]
])
// -------------

// matrices
const positionMatrixKey = byteMatrixKey('positions', 'meter')
const positions: Parameter<ByteMatrixKey> = positionMatrixKey.set([
  [
    [1, 2],
    [3, 4]
  ],
  [
    [5, 6],
    [7, 8]
  ]
])

Primitive Data types

Primitive	Typescript Key Type	Helper functions
Int	IntKey	intKey
Long	LongKey	longKey
Short	ShortKey	shortKey
Float	FloatKey	floatKey
Double	DoubleKey	doubleKey
Byte	ByteKey	byteKey
String	StringKey	stringKey
Char	CharKey	charKey
Boolean	BooleanKey	booleanKey
UTCTime	UTCTimeKey	utcTimeKey
TAITime	TAITimeKey	taiTimeKey

Array Data types

Primitive	Typescript Key Type	Helper functions
IntArray	IntArrayKey	intArrayKey
LongArray	LongArrayKey	longArrayKey
ShortArray	ShortArrayKey	shortArrayKey
FloatArray	FloatArrayKey	floatArrayKey
DoubleArray	DoubleArrayKey	doubleArrayKey
ByteArray	ByteArrayKey	byteArrayKey

Matrix Data types

Primitive	Typescript Key Type	Helper functions
IntMatrix	IntMatrixKey	intMatrixKey
LongMatrix	LongMatrixKey	longMatrixKey
ShortMatrix	ShortMatrixKey	shortMatrixKey
FloatMatrix	FloatMatrixKey	floatMatrixKey
DoubleMatrix	DoubleMatrixKey	doubleMatrixKey
ByteMatrix	ByteMatrixKey	byteMatrixKey

Domain Specific Types

• choice : A key for a choice item similar to an enumeration
• struct : Structs can be used to create a hierarchy of parameters

Primitive	Typescript Key Type	Helper functions
Choice	ChoiceKey	choiceKey
Struct	StructKey	Struct

Example snippets for creating choice and struct parameters

Typescript

// choice key

const choices = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] as const

const weekDaysKey = choiceKey('weekDaysKey', choices)
const weekDayParam = weekDaysKey.set('Mon', 'Wed')
// weekDayParam === Parameter('weekDaysKey', 'ChoiceKey', ['Mon', 'Wed'], 'NoUnits')

// -------------

// example for struct key
// leaf parameters
const ra: Parameter<StringKey> = stringKey('ra').set(['12:13:14.1'])
const dec = stringKey('dec').set(['32:33:34.4'])
const epoch = doubleKey('epoch').set([1970.0])

// initialise struct key
const struct = new Struct().add(ra)
struct.madd([dec, epoch])

// create struct Parameter using structKey
const structParameter = structKey('my struct').set([struct])

Coordinate Types

Primitive	Typescript Key Type	Helper functions
RaDec	RaDecKey	raDecKey
EqCoord	EqCoordKey	eqCoordKey
SolarSystemCoord	SolarSystemCoordKey	solarSystemCoordKey
MinorPlanetCoord	MinorPlanetCoordKey	minorPlanetCoordKey
CometCoord	CometCoordKey	cometCoordKey
AltAzCoord	AltAzCoordKey	altAzCoordKey
Coord (*)	CoordKey	coordKey

Example snippet for creating coordinate parameters

Typescript

const cometCoord = new CometCoord(
  'BASE',
  2000,
  324000000000,
  7200000000,
  360000000000,
  1.4,
  0.234
)
const cometParam: Parameter<CometCoordKey> = cometCoordKey(
  'comet key',
  'degree'
).set([cometCoord])

//coord key is base trait of all coordinate key types.
const coordParam: Parameter<CoordKey> = coordKey('base coordinate').set([
  cometCoord
])