Scope

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

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:35

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:23
onError	public	ErrorHandler | undefined	Receives errors raised in what this scope owns; unset, they go to the parent.	js-api/src/u2core/scope.ts:25
parent	readonly	Scope | undefined	The scope this one is disposed with, if any.	js-api/src/u2core/scope.ts:21
onUnhandledError	static	ErrorHandler	Where errors no scope handles go. Default: console.error('u2:', error, '(<label>)').	js-api/src/u2core/scope.ts:18

Accessors

abortSignal

Get Signature

get abortSignal(): AbortSignal

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

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:66

Whether dispose ran.

Returns

boolean

---

ambient

Get Signature

get static ambient(): Scope | undefined

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

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:43

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:136

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

---

child()

child(label?): Scope

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

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:128

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:263

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:78

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:168

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:115

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:252

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:226

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:154

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:209

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:189

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

Parameters

Parameter	Type
fn	() => void
ms?	number

Returns

() => void

---

runWith()

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

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

Runs fn with scope ambient; undefined runs it with NO owner — for what must outlive whoever is building (a platform view opened from a row).

Type Parameters

Type Parameter
T

Parameters

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

Returns

T