Dashlet (the instance handle)

The object returned by installDashletGlobal(options). It is a plain handle — a promise plus subscriptions and methods — composable with any framework’s state and lifecycle primitives (no framework constructs).

1. Signature

interface Dashlet {
    readonly init: Promise<InitContext>;
    onInit(listener: (ctx: InitContext, info: InitInfo) => void): () => void;
    onUpdate(listener: (ctx: InitContext, info: UpdateInfo) => void): () => void;
    onError(listener: (error: unknown) => void): () => void;
    call<T = unknown>(method: string, params?: unknown[]): Promise<T>;
    // the seven portable facade methods (below)
    openIndexData(options: OpenIndexDataOptions): Promise<boolean | undefined>;
    openObject(objectId: string | number): Promise<boolean | undefined>;
    openLocation(options: OpenLocationOptions): Promise<void>;
    openHitListByIds(options: OpenHitListByIdsOptions): Promise<void>;
    refreshHitListObjects(ids: Array<string | number>): Promise<boolean | undefined>;
    getSelectedObjects(): Promise<SelectedObjectRef[]>;
    resetSessionTimeout(): Promise<void>;
    getWebclientApi(): WebclientApi;
    getRichClientApi(): RichClientApi;
    destroy(): void;
}

2. Members

Member Kind Description

init

property

The init promise — init (resolves exactly once, never rejects, bounded).

onInit

method

Subscribe to init emissions — onInit (including the late-subscriber replay and the rich-client re-emission).

onUpdate

method

The reserved update slot — onUpdate (selection/context changes after init).

onError

method

Subscribe to failures — onError (timeouts, host errors, listener errors).

call

method

The thin method passthrough — call (string-based; routes portable names through the same dispatch core as the facade).

openIndexData

method

Open the index data of an object — openIndexData.

openObject

method

Open the object in its natural view — openObject.

openLocation

method

Open the object’s location — openLocation.

openHitListByIds

method

Open a mixed hit list — openHitListByIds (the fire-and-forget quirk lives there).

refreshHitListObjects

method

Refresh objects in open hit lists — refreshHitListObjects.

getSelectedObjects

method

The selected objects, normalized in both clients — getSelectedObjects.

resetSessionTimeout

method

Reset the session timeout — resetSessionTimeout (documented no-op in the rich client).

getWebclientApi

method

The webclient handle — getWebclientApi (the seven endpoints + raw call, asynchronous; cached; wrong environment = descriptive TypeError).

getRichClientApi

method

The rich-client handle — getRichClientApi (the full osjx* bridge + has() + raw call, synchronous; cached; wrong environment = descriptive TypeError).

destroy

method

Stops polling, removes listeners, detaches the wire (described below).

The seven portable facade methods route through the same dispatch core as call(method, params) (a single shared table), so the typed facade and the string-based call cannot drift — the wire posts, the resolve values, and the error paths are identical.

3. destroy()

destroy(): void

Tears the dashlet down: stops the detection polling and the warm-up timer, removes the host-callback handler, destroys the webclient wire, and clears the shared message sink only if it still belongs to this instance (a sibling dashlet on the same window may have replaced it).

Ordering guarantee: if the dashlet is still in the detecting state, destroy settles the init promise as standalone first (the promise must still resolve — it never hangs) and only then flips the state to destroyed. Subsequent method calls on a destroyed dashlet reject with a plain Error('dashlet destroyed').

4. Examples

const dashlet = installDashletGlobal();

const offInit = dashlet.onInit((ctx) => render(ctx));
const offUpdate = dashlet.onUpdate((ctx) => rerender(ctx));

// later, on teardown:
offInit();
offUpdate();
dashlet.destroy();