Error model

Every failure surfaces as a rejected promise or through the onError subscription — never as an uncaught throw.

1. TimeoutError

The exported TimeoutError class distinguishes host-wait timeouts from plain errors:

class TimeoutError extends Error {
    readonly operation: string;  // the awaited operation that timed out
    readonly timeoutMs: number;  // the configured bound that elapsed
}
// error.name === 'DashletTimeoutError'
// error.message === '<operation> timed out after <timeoutMs>ms'

Check for timeouts with instanceof TimeoutError (exported alongside DEFAULT_TIMEOUT_MS and withTimeout) or by the name 'DashletTimeoutError'.

The default bound is DEFAULT_TIMEOUT_MS = 5000, configurable through DashletOptions.timeoutMs (see DashletOptions).

2. Bounded await semantics

The enaio contract defines no response guarantee. Every host interaction that awaits a reply — the init wait and every method call — is wrapped in a configurable response timeout: the race resolves with the work’s result when it settles first and rejects with a TimeoutError otherwise, and the timer is always cleaned up. A timeout is therefore a rejectable/observable failure state, never an indefinite hang. The underlying primitive is withTimeout.

3. Failure source → shape

Failure source Rejection shape

Host never answers within timeoutMs

TimeoutError (name 'DashletTimeoutError')

Webclient host answers with an { error } payload

A wrapper error carrying name 'DashletHostError' around the host error (the call remains bounded by the response timeout)

Rich-client bridge call throws, or the bridge method is missing

Descriptive rejection — a rejected promise, never an uncaught throw

Invalid option value at install time (e.g. an expectedOrigin that is neither a URL nor a file-origin-group member; "*" is always rejected)

Descriptive TypeError

Unknown method via call() in the rich client

Descriptive TypeError

Any portable method or call() in standalone

Bounded TimeoutError — no host reply path exists, so callers can render a fallback instead of hanging

Other code replaced window.osDashletInit (rich client only)

No rejection: one plain Error per dashlet instance through onError, message prefix Dashlet: window.osDashletInit was replaced by other code

Two clarifications:

  • The standalone init wait is not an error — dashlet.init resolves (within detectionTimeoutMs) with the observable degraded standalone context; only the method calls reject.

  • A webclient host error rejects only the specific awaiting call; it does not destroy the dashlet or affect later calls.