Skip to main content

realm.instruction

An instruction is a bit of HiveScript code that is executed by the server in response to events or changes to data.

Methods

realm.instruction.create(id, options)

Creates a new instruction that will run immediatly upon creation. This method will throw an error if the instruction already exists or if an instruction with the same instructionString already exists.

  • id a unique identifier for this instruction within its realm
  • options optional parameters that define the area
  • options.label a name for the instructions
  • options.instructionString a (multiline) string with the HiveScript code
  • options.data key/value meta data for the instruction
  • returns Promise success / error message
await realm.instruction.create('operations/ins1', {
label: 'Highlight scooters with low charge',
instructionString: `
when object(type="scooter", charge<0.2)
then set("color", "red")
`,
data: {
createdBy: 'Mike'
}
})

realm.instruction.get(id)

Creates a new instruction that will run immediatly upon creation

  • id a unique identifier for this instruction within its realm
  • returns Promise instruction definition
const instructionDef = await realm.instruction.get('operations/ins1');
{
instructionString: '\n' +
' when object(type="scooter", charge<0.2)\n' +
' then set("color", "red")\n',
label: 'Highlight scooters with low charge',
data: { createdBy: 'Mike' }
}

realm.instruction.update(id, options)

Updates an existing instruction. If the value of instructionString has changed, the current instruction will be stopped and the updated version started.

  • id a unique identifier for this instruction within its realm
  • options optional parameters that define the area
  • options.label a name for the instructions
  • options.instructionString a (multiline) string with the HiveScript code
  • options.data key/value meta data for the instruction
  • returns Promise success / error message

realm.instruction.list()

Returns a list of all instructions that are currently active for this realm, incliding their ID, label and data, but not their code. To retrieve the code, use realm.instruction.get(id) for an individual instruction.

  • returns Promise realm list
realmList = await realm.instruction.list();
{
'operations/ins1': {
id: 'operations/ins1',
label: 'Highlight scooters with low charge',
data: { createdBy: 'Mike' }
}
}

realm.instruction.delete(id)

Stops an existing instruction from running and deletes its code and associated data.

  • returns Promise success / error message
await realm.instruction.delete('operations/ins1');

realm.instruction.subscribe()

Creates a subscription providing a realtime feed of instructions being created, updated and deleted.

  • returns subscription
const subscription = await realm.instruction.subscribe();
subscription.on('update', data => {
//data = list of subscriptions
})

realm.instruction.subscribeToLogs()

Within the HiveScript code of the instruction, you can call debug(arg1,arg2,argn). The output of the debug function will be send to the subscription generated by subscribeToLogs(). This is useful both for developing and monitoring HiveScript instructions. Think of it like attaching a listener to stdin.

  • returns subscription
const logSubscription = realm.instruction.subscribeToLogs()
logSubscription.on('update', data => {
// data will be the currently processed context + the log message
})
await realm.instruction.create('operations/ins1', {
instructionString: `
when object(type="scooter", charge<0.2)
then
debug("we found one")
set("color", "red")
`,
})