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")
    `,
})