You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+16-16Lines changed: 16 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ The **Observable Runtime** implements reactivity in both [Observable Framework](
6
6
7
7
### Runtimes
8
8
9
-
#### new Runtime(builtins, global)
9
+
#### new Runtime(*builtins*, *global*)
10
10
11
11
[Source](https://github.com/observablehq/runtime/blob/main/src/runtime.js) · Returns a new [runtime](#runtimes). If *builtins* is specified, each property on the *builtins* object defines a builtin variable for the runtime. These builtins are available as named inputs to any [defined variables](#variable_define) on any [module](#modules) associated with this runtime. If a *global* function is specified, it will be invoked with the name of any unresolved reference, and must return the corresponding value or undefined (to trigger a ReferenceError); if *global* is not specified, unresolved values will be resolved from the global window.
12
12
@@ -30,31 +30,31 @@ This would produce the following output:
30
30
31
31
Unlike [variables](#variables), builtins cannot depend on the value of other variables or builtins; they are defined with no inputs. If a builtin is defined as a function, it will be invoked lazily to determine the value of the builtin. If you wish for the value of a builtin to be a function, the builtin must be defined either as a promise that resolves to a function or as a function that returns a function. Builtins may also be defined as generators for dynamic values.
32
32
33
-
#### runtime.module(define, observer)
33
+
#### *runtime*.module(*define*, *observer*)
34
34
35
35
[Source](https://github.com/observablehq/runtime/blob/main/src/runtime.js) · Returns a new [module](#modules) for this [runtime](#runtimes).
36
36
37
37
If *define* is specified, it is a function which defines the new module’s [variables](#variables) by calling *runtime*.module (with no arguments) and then calling [*module*.variable](#module_variable) on the returned module as desired. If this runtime already has a module for the specified *define* function, the existing module is returned; otherwise, a new module is created, and the *define* function is called, being passed this runtime and the specified *observer* factory function. If *define* is not specified, a new module is created and returned.
38
38
39
39
If an *observer* factory function is specified, it is called for each named variable in the returned module, being passed the variable’s name.
40
40
41
-
#### runtime.dispose()
41
+
#### *runtime*.dispose()
42
42
43
43
[Source](https://github.com/observablehq/runtime/blob/main/src/runtime.js) · Disposes this runtime, invalidating all active variables and disabling future computation.
44
44
45
45
### Modules
46
46
47
47
A module is a namespace for [variables](#variables); within a module, variables should typically have unique names. [Imports](#variable_import) allow variables to be referenced across modules.
48
48
49
-
#### module.variable(observer)
49
+
#### *module*.variable(*observer*)
50
50
51
51
[Source](https://github.com/observablehq/runtime/blob/main/src/module.js) · Returns a new [variable](#variables) for this [module](#modules). The variable is initially undefined.
52
52
53
53
If *observer* is specified, the specified [observer](#observers) will be notified when the returned variable changes state, via the [observer.*pending*](#observer_pending), [observer.*fulfilled*](#observer_fulfilled) and [observer.*rejected*](#observer_rejected) methods. See the [standard inspector](https://github.com/observablehq/inspector/blob/master/README.md) for a convenient default observer implementation.
54
54
55
55
A variable without an associated *observer* is only computed if any transitive output of the variable has an *observer*; variables are computed on an as-needed basis for display. This is particularly useful when the runtime has multiple modules (as with [imports](#variable_import)): only the needed variables from imported modules are computed.
56
56
57
-
#### module.derive(specifiers, source)
57
+
#### *module*.derive(*specifiers*, *source*)
58
58
59
59
[Source](https://github.com/observablehq/runtime/blob/main/src/module.js) · Returns a derived copy of this [module](#modules), where each variable in *specifiers* is replaced by an [import](#variable_import) from the specified *source* module. The *specifiers* are specified as an array of objects with the following properties:
[Source](https://github.com/observablehq/runtime/blob/main/src/module.js) · A convenience method for [*variable*.define](#variable_define); equivalent to:
[Source](https://github.com/observablehq/runtime/blob/main/src/module.js) · A convenience method for [*variable*.import](#variable_import); equivalent to:
95
95
96
96
```js
97
97
module.variable().import(name, alias, from)
98
98
```
99
99
100
-
#### module.builtin(name, value)
100
+
#### *module*.builtin(*name*, *value*)
101
101
102
102
[Source](https://github.com/observablehq/runtime/blob/main/src/module.js) · Defines a built-in constant that is visible to all variables in this module. _Caution: any built-ins must be defined before variables are defined, and must not be redefined after._ For example, to define a `FileAttachment` function:
[Source](https://github.com/observablehq/runtime/blob/main/src/module.js) · Redefines the *variable* with the specified *name* on this module. If no such variable exists, or if more than one variable has the specified *name*, throws a runtime error.
111
111
112
-
#### module.value(name)
112
+
#### *module*.value(*name*)
113
113
114
114
[Source](https://github.com/observablehq/runtime/blob/main/src/module.js) · Returns a promise to the next value of the *variable* with the specified *name* on this module. If no such variable exists, or if more than one variable has the specified *name*, throws a runtime error.
115
115
116
116
### Variables
117
117
118
118
A variable defines a piece of state in a reactive program, akin to a cell in a spreadsheet. Variables may be named to allow the definition of derived variables: variables whose value is computed from other variables’ values. Variables are scoped by a [module](#modules) and evaluated by a [runtime](#runtimes).
[Source](https://github.com/observablehq/runtime/blob/main/src/variable.js) · Redefines this variable to have the specified *name*, taking the variables with the names specified in *inputs* as arguments to the specified *definition* function. If *name* is null or not specified, this variable is anonymous and may not be referred to by other variables. The named *inputs* refer to other variables (possibly [imported](#variable_import)) in this variable’s module. Circular inputs are not allowed; the variable will throw a ReferenceError upon evaluation. If *inputs* is not specified, it defaults to the empty array. If *definition* is not a function, the variable is defined to have the constant value of *definition*.
123
123
@@ -177,7 +177,7 @@ b.define("bar", 2);
177
177
178
178
Likewise deleting *a* or *b* would allow the other variable to resolve to its desired value.
179
179
180
-
#### variable.import(name, alias, module)
180
+
#### *variable*.import(*name*, *alias*, *module*)
181
181
182
182
[Source](https://github.com/observablehq/runtime/blob/main/src/variable.js) · Redefines this variable as an alias of the variable with the specified *name* in the specified [*module*](#modules). The subsequent name of this variable is the specified *name*, or if specified, the given *alias*. The order of arguments corresponds to the standard import statement: `import {name as alias} from "module"`. For example, consider a module which defines a variable named `foo`:
183
183
@@ -213,22 +213,22 @@ To import `foo` into *module1* under the alias `bar`:
213
213
module1.variable().import("foo", "bar", module0);
214
214
```
215
215
216
-
#### variable.delete()
216
+
#### *variable*.delete()
217
217
218
218
[Source](https://github.com/observablehq/runtime/blob/main/src/variable.js) · Deletes this variable’s current definition and name, if any. Any variable in this module that references this variable as an input will subsequently throw a ReferenceError. If exactly one other variable defined this variable’s previous name, such that that variable throws a ReferenceError due to its duplicate definition, that variable’s original definition is restored.
219
219
220
220
### Observers
221
221
222
222
An observer watches a [variable](#variables), being notified via asynchronous callback whenever the variable changes state. See the [standard inspector](https://github.com/observablehq/inspector) for a reference implementation.
223
223
224
-
#### observer.pending()
224
+
#### *observer*.pending()
225
225
226
226
Called shortly before the variable is computed. For a generator variable, this occurs before the generator is constructed, but not before each subsequent value is pulled from the generator.
227
227
228
-
#### observer.fulfilled(value)
228
+
#### *observer*.fulfilled(*value*)
229
229
230
230
Called shortly after the variable is fulfilled with a new *value*.
231
231
232
-
#### observer.rejected(error)
232
+
#### *observer*.rejected(*error*)
233
233
234
234
Called shortly after the variable is rejected with the given *error*.
0 commit comments