Abstract Class: Action<P, Input>
Something a user starts from the instance page, with a small form: pair a device, open a pairing
window, remove a paired controller. Write one class per action and list it in the plugin's static
actions; only id and run() are required. Use an action for work the user triggers once;
use an actuator for a signal a Loxone output drives.
The runtime validates the input against input, builds the action, runs it and disposes it when
run() settles or the plugin stops. One action runs at a time per instance. What run()
returns is shown to the user (a message of at most 2000 characters, optionally with a panel part
such as a QR code) and not logged; what it throws is shown as the failure and also written to the
instance log, so keep codes out of error messages. Inputs may hold secrets such as pairing codes:
don't log them.
Example
A button that pairs a device with a code the user types:
export class PairAction extends Action<MatterPlugin, { code: string }> {
static readonly id = "pair"
static readonly label = "Pair device"
static readonly input = z.object({ code: z.string().regex(/^\d{11}$/) })
async run() {
const node = await this.plugin.controller.pair(this.input.code)
return `Paired ${node.name}`
}
}
Extends
Type Parameters
P
Input
Input = unknown
Constructors
Constructor
new Action<
P,Input>(plugin,input):Action<P,Input>
input is validated against the static input schema, with defaults applied
Parameters
plugin
P
input
Input
Returns
Action<P, Input>
Overrides
Properties
MAX_TIMER_MS
readonlystaticMAX_TIMER_MS:2147483647=2_147_483_647
the largest delay setTimeout/setInterval honour; Node turns anything longer into 1 ms
Inherited from
plugin
readonlyplugin:P
input
readonlyinput:Input
Accessors
isDisposed
Get Signature
get isDisposed():
boolean
true from the moment dispose() starts, not when it finishes
Returns
boolean
Inherited from
Methods
dispose()
dispose():
Promise<void>
Releases everything registered with this object. Plugin code seldom needs it: the runtime disposes plugins, sensors and actuators, and own() disposes children. Call it yourself for an object you created without own(), or to end a child early.
Runs all teardowns in reverse registration order and keeps going when one fails. Idempotent: every call returns the same promise, so a second caller also waits for async teardowns.
Returns
Promise<void>
Throws
AggregateError collecting every teardown error, after all teardowns have run
Inherited from
onDispose()
protectedonDispose(teardown):void
Registers a callback that runs on dispose(), for cleanup the helpers don't cover (closing a socket, flushing a buffer). Async callbacks are awaited one after the other, last registered first, so a flush can use what was registered before it. Keep the total under the five seconds a stop has.
Parameters
teardown
Returns
void
Throws
Error if already disposed
Inherited from
useClock()
protecteduseClock(clock):void
Sets the clock for every() and after() calls from now on, unless one is set already; without one they run on the system clock. Timers started before keep the clock they started on. Plugin, Sensor and Actuator set it from the plugin's context.
Parameters
clock
Clock | undefined
Returns
void
Inherited from
currentClock()
protectedcurrentClock():Clock
The clock this object runs on: every() and after() use it, and a Disposable that isn't a
plugin, sensor or actuator reads the time from it (this.currentClock().now()).
Returns
Inherited from
own()
protectedown<T>(resource):T
ties the lifetime of a child resource to this object; returns it so construction and registration fit in one expression. A Disposable child without a clock of its own runs on this one's, looked up when a timer starts, so a chain of owners (plugin → client → poller) shares the plugin's clock. Timers a child starts in its constructor, before it is owned, run on the system clock.
Type Parameters
T
T extends DisposableLike
Parameters
resource
T
Returns
T
Inherited from
every()
protectedevery(ms,fn): () =>void
runs fn every ms milliseconds until disposed or until the returned cancel function is called. The first run is after ms, not at once; call fn yourself first if you want an immediate run. Runs are not queued: a slow async fn can overlap its next run, so guard it yourself if needed.
Parameters
ms
number
fn
() => void
Returns
() => void
Throws
RangeError unless 0 < ms <= MAX_TIMER_MS
Inherited from
after()
protectedafter(ms,fn): () =>void
runs fn once after ms milliseconds unless disposed before; returns a cancel function. Both firing and cancelling forget the teardown, so repeated use does not accumulate entries. Delays beyond MAX_TIMER_MS are scheduled in steps, so they don't fire early.
The delay counts elapsed time, not wall-clock time: a clock step (an NTP sync after boot) is not noticed. For a deadline given as a wall-clock time, wait in shorter slices and re-check the time each time.
Parameters
ms
number
fn
() => void
Returns
() => void
Throws
RangeError for negative or non-finite delays
Inherited from
listen()
protectedlisten(emitter,event,listener):void
Subscribes listener to event of an EventEmitter (or anything with on/off) and removes it
again on dispose(), so a long-lived emitter such as the plugin's poller does not keep a
disposed sensor alive. Prefer it to calling emitter.on yourself.
Parameters
emitter
event
string | symbol
listener
Returns
void
Inherited from
run()
abstractrun():ActionResult|Promise<ActionResult>
does the work; the returned text (or message and panel part) tells the user what happened
Returns
ActionResult | Promise<ActionResult>
progress()
protectedprogress(text,fraction?):void
Tells the user how a long action gets on ("Searching the network…", 0.4 for 40 %), shown in its dialog while it runs. Sent at most four times a second, the latest always; does nothing on hosts that show no progress. It isn't logged, but every open Nexus page receives it, so keep codes and secrets for the answer.
Parameters
text
string
fraction?
number
Returns
void