Obj makes objects and reads and writes them. Its functions take the object as the first argument and work whether or
not the object is in a database yet, so a getter that needs the database returns undefined outside one instead of
throwing. org.dxos.echo#F-3.3
Obj.make checks the props against the type and gives the object an id. Reserved fields such as Obj.Meta go in the
same props. Here the meta records the object’s key in an external system. org.dxos.echo#F-3.1
Read a field like any property. Writes go inside Obj.update; a write outside it throws. All the writes in one callback
reach subscribers as one change.
A live object always shows the latest state. Obj.getSnapshot returns a frozen copy that later updates do not touch, which
is what you want to keep a before-and-after or hand data to code that must not write it.
Perform mutations on an echo object within a controlled context.
All mutations within the callback are batched and trigger a single notification
when the callback completes. Direct mutations outside of Obj.update will throw
an error for echo objects.
This function also works with nested objects within echo objects (e.g., Template structs)
that are reactive at runtime.
@param ― obj - The echo object to mutate. Use Relation.update for relations.
@param ― callback - The callback that performs mutations on the object.
@example
const person = Obj.make(Person, { name: 'John', age: 25 });
Returns an immutable snapshot of an object.
The snapshot is branded with SnapshotKindId instead of KindId,
making it distinguishable from the reactive object at the type level.
@performance ― O(n) in entity size; deep-copies plain data (refs are shared, not resolved) into a frozen object per
call.
Perform mutations on an echo object within a controlled context.
All mutations within the callback are batched and trigger a single notification
when the callback completes. Direct mutations outside of Obj.update will throw
an error for echo objects.
This function also works with nested objects within echo objects (e.g., Template structs)
that are reactive at runtime.
@param ― obj - The echo object to mutate. Use Relation.update for relations.
@param ― callback - The callback that performs mutations on the object.
@example
const person = Obj.make(Person, { name: 'John', age: 25 });
The callback runs synchronously after each committed change. Query subscriptions over the object re-evaluate at the same
time. org.dxos.echo#F-3.2 In React, use the hooks in the React guide
instead.
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:
A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.
Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(newError('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
// Error: Whoops, something bad happened
// at [eval]:5:15
// at Script.runInThisContext (node:vm:132:18)
// at Object.runInThisContext (node:vm:309:38)
// at node:internal/process/execution:77:19
// at [eval]-wrapper:6:22
// at evalScript (node:internal/process/execution:76:60)
// at node:internal/main/eval_string:23:3
const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);
myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(newError('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
Perform mutations on an echo object within a controlled context.
All mutations within the callback are batched and trigger a single notification
when the callback completes. Direct mutations outside of Obj.update will throw
an error for echo objects.
This function also works with nested objects within echo objects (e.g., Template structs)
that are reactive at runtime.
@param ― obj - The echo object to mutate. Use Relation.update for relations.
@param ― callback - The callback that performs mutations on the object.
@example
const person = Obj.make(Person, { name: 'John', age: 25 });
Add a tag to the object.
Must be called within an Obj.update callback.
NOTE: TypeScript's structural typing allows readonly objects to be passed to Mutable<T>
parameters, so there is no compile-time error. Enforcement is runtime-only.
@performance ― O(t) in the tag count; dedupes by tag id before appending.
Each change to an object is a Change with the device that made it, the time, and the heads of the document after it.
Obj.getChanges lists them, for the whole object or one field, where each carries the value before and after.
Obj.getVersion reads the object at a change’s heads. Changes and branches explains the
model.
per document change that
touched the object, carrying its snapshot before and after. Given property, only the changes that
touched that property, carrying its value. Pass an entry's heads to
getVersion
to read the
whole object as that change left it.
Changes belong to the object's Automerge document, so time, actor and ops describe the whole
change, which may also have written other objects in the same document. Edits to the content of a
referenced object (e.g. a Ref<Text>) are that object's history, not this one's.
@example
for (const { time, before, after } of Obj.getChanges(task, { property: 'status' })) {
console.log(newDate(time), before, '→', after);
}
@performance ― O(document history): diffs every change of the Automerge document and snapshots each match; not cached.
Returns a copy of a section of an array.
For both start and end, a negative index can be used to indicate an offset from the end of the array.
For example, -2 refers to the second to last element of the array.
@param ― start The beginning index of the specified portion of the array.
If start is undefined, then the slice begins at index 0.
@param ― end The end index of the specified portion of the array. This is exclusive of the element at the index 'end'.
If end is undefined, then the slice extends to the end of the array.
slice(-1);
5
const last: ValueChange<string>
last.
actor: string
Writer that made the change; for a document change, an Automerge actor, which is a device, not a member.
actor; // the device that made the change
6
const last: ValueChange<string>
last.
ValueChange<string>.before: string | undefined
The value before the change; undefined where the object (or property) did not exist yet.
before; // 'Ada'
7
const last: ValueChange<string>
last.
ValueChange<string>.after: string | undefined
The value after the change; undefined where the change removed the property.
after; // 'Ada Lovelace'
8
9
// The object as it was after a change, without touching the live object.
Get an immutable snapshot of the object at the given historical heads — a detached instance, not a
pin on the live object. Only the surface that asks for it sees the historical value; the live
object and every other surface are unaffected. The functional alternative to a read-time-travel pin.
@performance ― O(object size) plus the Automerge cost of viewing the document at heads; nothing is cached.
Converts object to its JSON representation.
Accepts both reactive objects and snapshots.
JSON.stringify(obj) gives the same result for an in-memory object, which shares this serializer.
A database-backed object carries its own toJSON, which reads the document rather than the target
and still differs in two ways: it omits @uri, and it leaves Uint8Array values unencoded.
Prefer this function where the two must agree.
@performance ― O(n) in entity size; serializes the whole entity on every call.
