Scope

Defined in: js-api/src/u2core/scope.ts:54

Owner of effects, cleanups, listeners, timers and child scopes. Everything registered on a scope is released by a single dispose() call. Errors raised in what it owns are reported to onError, then up the parent chain, then to Scope.onUnhandledError — never thrown at whoever happened to write a signal.

Constructors

Constructor

new Scope(parent?, options?): Scope

Defined in: js-api/src/u2core/scope.ts:76

lazy: counted, tracked and linked to parent only once it owns something — an effect run that builds nothing costs nothing.

Parameters

Parameter	Type
parent?	Scope
options?	{ label?: string; lazy?: boolean; }
options.label?	string
options.lazy?	boolean

Returns

Scope

Properties

Property	Modifier	Type	Description	Defined in
label	readonly	string	What created it, for leak reports: scope, effect, row, popup, dialog, …	js-api/src/u2core/scope.ts:63
onError	public	ErrorHandler | undefined	Receives errors raised in what this scope owns; unset, they go to the parent.	js-api/src/u2core/scope.ts:65
parent	readonly	Scope | undefined	The scope this one is disposed with, if any.	js-api/src/u2core/scope.ts:61
onUnhandledError	static	ErrorHandler	Where errors no scope handles go. Default: console.error('u2:', error, '(<label>)').	js-api/src/u2core/scope.ts:58

Accessors

abortSignal

Get Signature

get abortSignal(): AbortSignal

Defined in: js-api/src/u2core/scope.ts:340

Aborted on dispose — hand it to fetch, addEventListener or anything cancellable.

Returns

AbortSignal

---

isDisposed

Get Signature

get isDisposed(): boolean

Defined in: js-api/src/u2core/scope.ts:146

Whether dispose ran.

Returns

boolean

---

ambient

Get Signature

get static ambient(): Scope | undefined

Defined in: js-api/src/u2core/scope.ts:90

The scope that owns whatever is being built right now, if any. Element factories bind signals to it; components created under it are disposed with it.

Returns

Scope | undefined

---

liveCount

Get Signature

get static liveCount(): number

Defined in: js-api/src/u2core/scope.ts:84

Scopes created and not yet disposed — a counter, so production holds no references.

Returns

number

Methods

bind()

bind<A, R>(fn): (...args) => R | undefined

Defined in: js-api/src/u2core/scope.ts:220

Wraps a handler the library or the platform calls later: it runs with this scope ambient, inside one batch, does nothing once the scope is disposed, and reports a throw instead of propagating it (answering undefined) — and the rejection of a promise it answers.

Type Parameters

Type Parameter
A extends unknown[]
R

Parameters

Parameter	Type
fn	(...args) => R

Returns

(...args) => R | undefined

---

build()

build<T>(fn): T

Defined in: js-api/src/u2core/scope.ts:125

Runs fn now with this scope ambient, so what it builds is owned here; synchronous, and a throw propagates.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
fn	() => T

Returns

T

Example

const control = owner.build(() => new DG.U2.Control());

See

https://public.datagrok.ai/js/samples/ui/widgets/u2-task

---

child()

child(label?): Scope

Defined in: js-api/src/u2core/scope.ts:151

A scope disposed with this one, or earlier on its own.

Parameters

Parameter	Type
label?	string

Returns

Scope

---

disown()

disown(dispose): this

Defined in: js-api/src/u2core/scope.ts:212

Drops a cleanup registered by own — for things that come and go many times over the owner's life (an overlay reopened on every click) and would otherwise leave a dead closure behind on every round.

Parameters

Parameter	Type
dispose	() => void

Returns

this

---

dispose()

dispose(): void

Defined in: js-api/src/u2core/scope.ts:448

Runs every cleanup (untracked, each on its own — one throwing does not stop the rest; the errors are reported after all ran), aborts abortSignal and leaves the parent.

Returns

void

---

effect()

effect(fn): this

Defined in: js-api/src/u2core/scope.ts:158

Runs fn now and on every change of the signals it reads. Each run gets its own child scope, ambient while fn runs and disposed before the next run and with this scope: what a run builds dies with it. A returned function is that run's cleanup. A throw is reported, not propagated.

Parameters

Parameter	Type
fn	() => void

Returns

this

---

listen()

listen(target, type, handler, options?): () => void

Defined in: js-api/src/u2core/scope.ts:349

Adds a listener removed on dispose; the handler runs as bind runs it. Answers the remover.

Parameters

Parameter	Type
target	EventTarget
type	string
handler	(e) => void
options?	AddEventListenerOptions

Returns

() => void

---

own()

own(dispose): this

Defined in: js-api/src/u2core/scope.ts:199

Registers a cleanup to run on dispose. Runs immediately if already disposed.

Parameters

Parameter	Type
dispose	() => void

Returns

this

---

reportError()

reportError(error): void

Defined in: js-api/src/u2core/scope.ts:437

Hands an error to onError, else up the parent chain, else to Scope.onUnhandledError.

Parameters

Parameter	Type
error	unknown

Returns

void

---

requestFrame()

requestFrame(fn): () => void

Defined in: js-api/src/u2core/scope.ts:410

An animation frame cancelled on dispose; fn runs as bind runs it. Answers the canceller. Falls back to a 16 ms timeout where there are no frames (Node).

Parameters

Parameter	Type
fn	(time) => void

Returns

() => void

---

run()

run<T>(fn): T | undefined

Defined in: js-api/src/u2core/scope.ts:237

Runs fn now the way bind runs a handler.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
fn	() => T

Returns

T | undefined

---

setInterval()

setInterval(fn, ms): () => void

Defined in: js-api/src/u2core/scope.ts:392

An interval cleared on dispose; fn runs as bind runs it. Answers the canceller.

Parameters

Parameter	Type
fn	() => void
ms	number

Returns

() => void

---

setTimeout()

setTimeout(fn, ms?): () => void

Defined in: js-api/src/u2core/scope.ts:371

A timeout cleared on dispose; fn runs as bind runs it. Answers the canceller.

Parameters

Parameter	Type
fn	() => void
ms?	number

Returns

() => void

---

subscribe()

subscribe<T>(source, handler): () => void

Defined in: js-api/src/u2core/scope.ts:247

Subscribes handler to source — an rxjs observable, a platform event stream, anything with a subscribe method — until this scope is disposed. The handler runs as bind runs one. With u2 debug on the subscription is a live subscription scope with its creation stack. Answers the unsubscribe.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
source	ObservableLike<T>
handler	(value) => void

Returns

() => void

Example

owner.subscribe(grok.events.onViewRemoved, (view) => grok.shell.info(view.name));

See

https://public.datagrok.ai/js/samples/ui/widgets/u2-task

---

task()

task<R>(fn, options?): TaskRun

Defined in: js-api/src/u2core/scope.ts:273

Runs async work for this scope: fn starts now with the scope ambient, and after each await gets back in with t.build(…), which does nothing once the scope is disposed or the run cancelled; t.signal aborts then. With serial, one run of that queue is in flight: a run asked for meanwhile waits, and a newer one replaces it. A throw or a rejection is reported as bind reports one.

Type Parameters

Type Parameter
R

Parameters

Parameter	Type
fn	(t) => R | PromiseLike<R>
options?	TaskOptions

Returns

TaskRun

Example

owner.task(async (t) => {
  const df = await grok.data.getDemoTable('demog.csv');
  t.build(() => host.append(ui.divText(`${df.rowCount} rows`)));
}, {serial: 'load'});

See

https://public.datagrok.ai/js/samples/ui/widgets/u2-task

---

root()

static root(label): Scope

Defined in: js-api/src/u2core/scope.ts:107

A new tree on purpose — what outlives whoever is building (a platform view opened from a row): a scope with no owner, counted and named label in leak reports. Whoever holds it disposes it.

Parameters

Parameter	Type
label	string

Returns

Scope

Example

const session = DG.U2.Scope.root('campaign session');
session.build(() => new DG.U2.Control());

See

https://public.datagrok.ai/js/samples/ui/widgets/u2-task

---

runWith()

static runWith<T>(scope, fn): T

Defined in: js-api/src/u2core/scope.ts:97

Runs fn with scope ambient; undefined runs it with NO owner.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
scope	Scope | undefined
fn	() => T

Returns

T

Deprecated

Use Scope.build (owner.build(fn)); for what must outlive whoever is building, a new tree under Scope.root.

---

thenable()

static thenable(x): PromiseLike<unknown> | undefined

Defined in: js-api/src/u2core/scope.ts:132

x as a promise when it is one — a native promise, or an object or function with a callable then — else undefined. Reading then never throws here: a proxy that answers every name (a DG.Row) may throw on it, and such an x is no promise. The one test of "did a handler answer a promise" for u2 and its hosts.

Parameters

Parameter	Type
x	unknown

Returns

PromiseLike<unknown> | undefined