ModelEventArgs

type ModelEventArgs = object;

Map from event name to payload shape, indexing the events that Model.on can subscribe to. Each entry below documents the trigger and payload semantics for one event.

Example

model.on('error', ({ workbookName, error }) => {
  console.warn(`Error in ${workbookName}: ${error.message}`);
});
model.on('recalc', m => console.log('recalc finished', m.id));

Properties

addsheet

addsheet: object;

A sheet was added to one of the model’s workbooks. Re-emitted from the underlying Workbook; subscribing on the model auto-installs the forwarder on every workbook in the model, including those attached after subscription.

index

index: number;

sheetName

sheetName: string;

workbookName

workbookName: string;

---

attach

attach: object;

A workbook was attached to the model (Model.addWorkbook / Model.attachWorkbook).

workbookName

workbookName: string;

---

beforerecalc

beforerecalc: Model;

Emitted at the start of Model.recalculate, before any cell is recalculated. Payload is the model.

---

detach

detach: object;

A workbook was detached from the model (Model.removeWorkbook).

workbookName

workbookName: string;

---

error

error: object;

A ModelError was raised during a model operation. seenBefore is true when the same error fingerprint has been emitted previously in this model’s lifetime, so consumers can deduplicate repeated errors.

error

error: ModelError;

seenBefore

seenBefore: boolean;

type

type: string;

workbookId

workbookId: string | undefined;

workbookName

workbookName: string | undefined;

---

listenererror

listenererror: object;

Emitted when a listener for another event throws. Listeners run in order and one that throws stops neither the others nor the engine call that emitted the event. With no listener for this event the exception is logged with console.error, as is a throw from a listener for this event itself. recalcEvent listeners are the exception: that stream is emitted from inside cell evaluation and a throw there aborts the recalc and does not trigger listenererror events.

error

error: unknown;

event

event: string;

---

metrics

metrics: MetricsEvent;

Function-call timing sample (one event per evaluated function or operator) emitted by a workbook during cell evaluation. The model re-emits a workbook’s metrics events when there are listeners on the model; the wiring is installed on every workbook in the model, including those attached after subscription.

---

native-update

native-update: object;

External workbook update from the host environment (e.g. GRID native), announcing that the named workbook should be considered modified at lastWrite. Apiary itself does not emit this event; it is forwarded by the host so consumers can invalidate caches.

action

action: string;

lastWrite

lastWrite: number;

workbookId

workbookId: string | undefined;

workbookName

workbookName: string | undefined;

---

recalc

recalc: Model;

Emitted at the end of Model.recalculate. Payload is the model.

---

recalcEvent

recalcEvent: RecalcEvent;

Per-cell recalculation event emitted during Model.recalculate (one event per recalculated cell, plus phase markers). Subscribe to trace recalculation; see RecalcEvent for the full payload shape.

---

removesheet

removesheet: object;

Emitted by a workbook when a sheet is removed, before the recalc that follows.

index

index: number;

sheetName

sheetName: string;

workbookName

workbookName: string;

---

renamesheet

renamesheet: object;

Emitted by a workbook when a sheet is renamed, before the recalc that follows.

index

index: number;

newName

newName: string;

oldName

oldName: string;

workbookName

workbookName: string;