@opendaw/lib-box 0.0.6

package/dist/graph.js

@@ -0,0 +1,262 @@
+import { assert, ByteArrayInput, ByteArrayOutput, Checksum, isDefined, Listeners, Option, panic, UUID } from "@opendaw/lib-std";
+import { Dispatchers } from "./dispatchers";
+import { DeleteUpdate, NewUpdate, PointerUpdate, PrimitiveUpdate } from "./updates";
+import { GraphEdges } from "./graph-edges";
+export class BoxGraph {
+    #boxFactory;
+    #boxes;
+    #deferredPointerUpdates;
+    #updateListeners;
+    #immediateUpdateListeners;
+    #transactionListeners;
+    #dispatchers;
+    #edges;
+    #finalizeTransactionObservers;
+    #inTransaction = false;
+    #constructingBox = false;
+    constructor(boxFactory = Option.None) {
+        this.#boxFactory = boxFactory;
+        this.#boxes = UUID.newSet(box => box.address.uuid);
+        this.#deferredPointerUpdates = [];
+        this.#dispatchers = Dispatchers.create();
+        this.#updateListeners = new Listeners();
+        this.#immediateUpdateListeners = new Listeners();
+        this.#transactionListeners = new Listeners();
+        this.#edges = new GraphEdges();
+        this.#finalizeTransactionObservers = [];
+    }
+    beginTransaction() {
+        assert(!this.#inTransaction, "Transaction already in progress");
+        this.#inTransaction = true;
+        this.#transactionListeners.proxy.onBeginTransaction();
+    }
+    endTransaction() {
+        assert(this.#inTransaction, "No transaction in progress");
+        this.#inTransaction = false;
+        this.resolvePointers();
+        // it is possible that new observers will be added while executing
+        while (this.#finalizeTransactionObservers.length > 0) {
+            this.#finalizeTransactionObservers.splice(0).forEach(observer => observer());
+            if (this.#finalizeTransactionObservers.length > 0) {
+                console.debug(`${this.#finalizeTransactionObservers.length} new observers while notifying`);
+            }
+        }
+        this.#transactionListeners.proxy.onEndTransaction();
+    }
+    inTransaction() { return this.#inTransaction; }
+    constructingBox() { return this.#constructingBox; }
+    resolvePointers() {
+        if (this.#deferredPointerUpdates.length === 0) {
+            return;
+        }
+        this.#deferredPointerUpdates.forEach(({ pointerField, update }) => this.#processPointerValueUpdate(pointerField, update));
+        this.#deferredPointerUpdates.length = 0;
+    }
+    createBox(name, uuid, constructor) {
+        this.#boxFactory.unwrap("No box-factory installed")(name, this, uuid, constructor);
+    }
+    stageBox(box, constructor) {
+        this.#assertTransaction();
+        assert(!this.#constructingBox, "Cannot construct box while other box is constructing");
+        if (isDefined(constructor)) {
+            this.#constructingBox = true;
+            constructor(box);
+            this.#constructingBox = false;
+        }
+        const added = this.#boxes.add(box);
+        assert(added, `${box} already staged`);
+        const update = new NewUpdate(box.address.uuid, box.name, box.toArrayBuffer());
+        this.#updateListeners.proxy.onUpdate(update);
+        this.#immediateUpdateListeners.proxy.onUpdate(update);
+        return box;
+    }
+    subscribeTransaction(listener) {
+        return this.#transactionListeners.subscribe(listener);
+    }
+    subscribeToAllUpdates(listener) {
+        return this.#updateListeners.subscribe(listener);
+    }
+    subscribeToAllUpdatesImmediate(listener) {
+        return this.#immediateUpdateListeners.subscribe(listener);
+    }
+    subscribeVertexUpdates(propagation, address, procedure) {
+        return this.#dispatchers.subscribe(propagation, address, procedure);
+    }
+    subscribeEndTransaction(observer) { this.#finalizeTransactionObservers.push(observer); }
+    unstageBox(box) {
+        this.#assertTransaction();
+        const deleted = this.#boxes.removeByKey(box.address.uuid);
+        assert(deleted === box, `${box} could not be found to unstage`);
+        this.#edges.unwatchVerticesOf(box);
+        const update = new DeleteUpdate(box.address.uuid, box.name, box.toArrayBuffer());
+        this.#updateListeners.proxy.onUpdate(update);
+        this.#immediateUpdateListeners.proxy.onUpdate(update);
+    }
+    findBox(uuid) {
+        return this.#boxes.opt(uuid);
+    }
+    findVertex(address) {
+        return this.#boxes.opt(address.uuid).flatMap(box => box.searchVertex(address.fieldKeys));
+    }
+    boxes() { return this.#boxes.values(); }
+    edges() { return this.#edges; }
+    checksum() {
+        const checksum = new Checksum();
+        this.boxes().forEach(box => box.write(checksum));
+        return checksum.result();
+    }
+    onPrimitiveValueUpdate(field, oldValue, newValue) {
+        this.#assertTransaction();
+        if (field.isAttached() && !this.#constructingBox) {
+            const update = new PrimitiveUpdate(field.address, field.serialization(), oldValue, newValue);
+            this.#dispatchers.dispatch(update);
+            this.#updateListeners.proxy.onUpdate(update);
+            this.#immediateUpdateListeners.proxy.onUpdate(update);
+        }
+    }
+    onPointerAddressUpdated(pointerField, oldValue, newValue) {
+        this.#assertTransaction();
+        const update = new PointerUpdate(pointerField.address, oldValue, newValue);
+        if (this.#constructingBox) {
+            this.#deferredPointerUpdates.push({ pointerField, update });
+        }
+        else {
+            this.#processPointerValueUpdate(pointerField, update);
+            this.#immediateUpdateListeners.proxy.onUpdate(update);
+        }
+    }
+    #processPointerValueUpdate(pointerField, update) {
+        const oldVertex = pointerField.targetVertex.unwrapOrNull();
+        pointerField.resolve();
+        const newVertex = pointerField.targetVertex.unwrapOrNull();
+        if (oldVertex !== newVertex) {
+            oldVertex?.pointerHub.onRemoved(pointerField);
+            newVertex?.pointerHub.onAdded(pointerField);
+            if (oldVertex !== null) {
+                this.#edges.disconnect(pointerField);
+            }
+            if (newVertex !== null) {
+                this.#edges.connect(pointerField, newVertex);
+            }
+        }
+        this.#dispatchers.dispatch(update);
+        this.#updateListeners.proxy.onUpdate(update);
+    }
+    dependenciesOf(box) {
+        const boxes = new Set();
+        const pointers = new Set();
+        const trace = (box) => {
+            if (boxes.has(box)) {
+                return;
+            }
+            boxes.add(box);
+            box.outgoingEdges()
+                .filter(([pointer]) => !pointers.has(pointer))
+                .forEach(([source, target]) => {
+                pointers.add(source);
+                if (target.pointerRules.mandatory &&
+                    target.pointerHub.incoming().every(pointer => pointers.has(pointer))) {
+                    return trace(target.box);
+                }
+            });
+            box.incomingEdges()
+                .forEach(pointer => {
+                pointers.add(pointer);
+                if (pointer.mandatory) {
+                    trace(pointer.box);
+                }
+            });
+        };
+        trace(box);
+        boxes.delete(box);
+        return { boxes: boxes, pointers: Array.from(pointers).reverse() };
+    }
+    verifyPointers() {
+        console.debug("validate requirements");
+        this.#edges.validateRequirements();
+        this.#edges.verifyPointers();
+        console.debug("verify pointers");
+        let count = 0 | 0;
+        const verify = (vertex) => {
+            for (const field of vertex.fields()) {
+                field.accept({
+                    visitPointerField: (pointer) => {
+                        if (pointer.targetAddress.nonEmpty()) {
+                            const isResolved = pointer.targetVertex.nonEmpty();
+                            const inGraph = this.findVertex(pointer.targetAddress.unwrap()).nonEmpty();
+                            assert(isResolved, `pointer ${pointer.address} is broken`);
+                            assert(inGraph, `Cannot find target for pointer ${pointer.address}`);
+                            count++;
+                        }
+                    },
+                    visitObjectField: (object) => verify(object)
+                });
+            }
+        };
+        this.#boxes.forEach((box) => verify(box));
+        console.debug("verification complete.");
+        return { count };
+    }
+    debugBoxes() {
+        console.table(this.#boxes.values().reduce((dict, box) => {
+            dict[UUID.toString(box.address.uuid)] = {
+                class: box.name,
+                "incoming links": box.incomingEdges().length,
+                "outgoing links": box.outgoingEdges().length,
+                "est. memory (bytes)": box.estimateMemory()
+            };
+            return dict;
+        }, {}));
+    }
+    debugDependencies() {
+        console.debug("Dependencies:");
+        this.boxes().forEach(box => {
+            console.debug(`\t${box}`);
+            for (const dependency of this.dependenciesOf(box).boxes) {
+                console.debug(`\t\t${dependency}`);
+            }
+        });
+    }
+    addressToDebugPath(address) {
+        return address.flatMap(address => address.isBox()
+            ? this.findBox(address.uuid).map(box => box.name)
+            : this.findBox(address.uuid)
+                .flatMap(box => box.searchVertex(address.fieldKeys)
+                .map(vertex => vertex.isField() ? vertex.debugPath : panic("Unknown address"))));
+    }
+    toArrayBuffer() {
+        const output = ByteArrayOutput.create();
+        const boxes = this.#boxes.values();
+        output.writeInt(boxes.length);
+        boxes.forEach(box => {
+            const buffer = box.serialize();
+            output.writeInt(buffer.byteLength);
+            output.writeBytes(new Int8Array(buffer));
+        });
+        return output.toArrayBuffer();
+    }
+    fromArrayBuffer(arrayBuffer) {
+        assert(this.#boxes.isEmpty(), "Cannot call fromArrayBuffer if boxes is not empty");
+        const input = new ByteArrayInput(arrayBuffer);
+        const numBoxes = input.readInt();
+        this.beginTransaction();
+        const boxes = [];
+        for (let i = 0; i < numBoxes; i++) {
+            const length = input.readInt();
+            const int8Array = new Int8Array(length);
+            input.readBytes(int8Array);
+            const boxStream = new ByteArrayInput(int8Array.buffer);
+            const creationIndex = boxStream.readInt();
+            const name = boxStream.readString();
+            const uuid = UUID.fromDataInput(boxStream);
+            boxes.push({ creationIndex, name, uuid, boxStream });
+        }
+        boxes
+            .sort((a, b) => a.creationIndex - b.creationIndex)
+            .forEach(({ name, uuid, boxStream }) => this.createBox(name, uuid, box => box.read(boxStream)));
+        this.endTransaction();
+    }
+    #assertTransaction() {
+        assert(this.#inTransaction, () => "Modification only prohibited in transaction mode.");
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./address";
+export * from "./array";
+export * from "./box";
+export * from "./dispatchers";
+export * from "./editing";
+export * from "./field";
+export * from "./graph";
+export * from "./graph-edges";
+export * from "./object";
+export * from "./pointer";
+export * from "./pointer-hub";
+export * from "./primitive";
+export * from "./sync";
+export * from "./sync-source";
+export * from "./sync-target";
+export * from "./updates";
+export * from "./vertex";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA;AACvB,cAAc,OAAO,CAAA;AACrB,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,SAAS,CAAA;AACvB,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,aAAa,CAAA;AAC3B,cAAc,QAAQ,CAAA;AACtB,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA"}

package/dist/index.js

@@ -0,0 +1,25 @@
+const key = Symbol.for("@openDAW/lib-box");
+if (globalThis[key]) {
+    console.debug(`%c${key.description}%c is already available in ${globalThis.constructor.name}.`, "color: hsl(10, 83%, 60%)", "color: inherit");
+}
+else {
+    globalThis[key] = true;
+    console.debug(`%c${key.description}%c is now available in ${globalThis.constructor.name}.`, "color: hsl(200, 83%, 60%)", "color: inherit");
+}
+export * from "./address";
+export * from "./array";
+export * from "./box";
+export * from "./dispatchers";
+export * from "./editing";
+export * from "./field";
+export * from "./graph";
+export * from "./graph-edges";
+export * from "./object";
+export * from "./pointer";
+export * from "./pointer-hub";
+export * from "./primitive";
+export * from "./sync";
+export * from "./sync-source";
+export * from "./sync-target";
+export * from "./updates";
+export * from "./vertex";

package/dist/object.d.ts

@@ -0,0 +1,17 @@
+import { Field, FieldConstruct, Fields } from "./field";
+import { UnreferenceableType } from "./pointer";
+import { DataInput, DataOutput, Nullish, Option } from "@opendaw/lib-std";
+import { VertexVisitor } from "./vertex";
+export declare abstract class ObjectField<FIELDS extends Fields> extends Field<UnreferenceableType, FIELDS> {
+    #private;
+    protected constructor(construct: FieldConstruct<UnreferenceableType>);
+    protected abstract initializeFields(): FIELDS;
+    accept<RETURN>(visitor: VertexVisitor<RETURN>): Nullish<RETURN>;
+    fields(): Iterable<Field>;
+    getField<K extends keyof FIELDS>(key: K): FIELDS[K];
+    optField<K extends keyof FIELDS>(key: K): Option<FIELDS[K]>;
+    read(input: DataInput): void;
+    write(output: DataOutput): void;
+    toJSON(): FIELDS;
+}
+//# sourceMappingURL=object.d.ts.map

package/dist/object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object.d.ts","sourceRoot":"","sources":["../src/object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAC,MAAM,SAAS,CAAA;AACrD,OAAO,EAAC,mBAAmB,EAAC,MAAM,WAAW,CAAA;AAC7C,OAAO,EAAY,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAc,MAAM,kBAAkB,CAAA;AAE/F,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAA;AAEtC,8BAAsB,WAAW,CAAC,MAAM,SAAS,MAAM,CAAE,SAAQ,KAAK,CAAC,mBAAmB,EAAE,MAAM,CAAC;;IAG/F,SAAS,aAAa,SAAS,EAAE,cAAc,CAAC,mBAAmB,CAAC;IAMpE,SAAS,CAAC,QAAQ,CAAC,gBAAgB,IAAI,MAAM;IAE7C,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/D,MAAM,IAAI,QAAQ,CAAC,KAAK,CAAC;IACzB,QAAQ,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,CAAC,SAAS,MAAM,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAE3D,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAC5B,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAE/B,MAAM;CACT"}

package/dist/object.js

@@ -0,0 +1,19 @@
+import { Field } from "./field";
+import { asDefined, Option, safeExecute } from "@opendaw/lib-std";
+import { Serializer } from "./serializer";
+export class ObjectField extends Field {
+    #fields;
+    constructor(construct) {
+        super(construct);
+        this.#fields = this.initializeFields();
+    }
+    accept(visitor) {
+        return safeExecute(visitor.visitObjectField, this);
+    }
+    fields() { return Object.values(this.#fields); }
+    getField(key) { return asDefined(this.#fields[key]); }
+    optField(key) { return Option.wrap(this.#fields[key]); }
+    read(input) { Serializer.readFields(input, this.#fields); }
+    write(output) { Serializer.writeFields(output, this.#fields); }
+    toJSON() { return this.#fields; }
+}

package/dist/pointer-hub.d.ts

@@ -0,0 +1,26 @@
+import { PointerField, PointerTypes } from "./pointer";
+import { Vertex } from "./vertex";
+import { int, Option, Subscription } from "@opendaw/lib-std";
+export interface PointerListener {
+    onAdd(pointer: PointerField): void;
+    onRemove(pointer: PointerField): void;
+}
+export declare class PointerHub implements Iterable<PointerField> {
+    #private;
+    static validate(pointer: PointerField, target: Vertex): Option<string>;
+    constructor(vertex: Vertex);
+    subscribeImmediate(listener: PointerListener, ...filter: ReadonlyArray<PointerTypes>): Subscription;
+    subscribeTransactual(listener: PointerListener, ...filter: ReadonlyArray<PointerTypes>): Subscription;
+    catchupAndSubscribeTransactual(listener: PointerListener, ...filter: ReadonlyArray<PointerTypes>): Subscription;
+    filter<P extends PointerTypes>(...types: ReadonlyArray<P>): Array<PointerField<P>>;
+    size(): int;
+    isEmpty(): boolean;
+    nonEmpty(): boolean;
+    contains(pointer: PointerField): boolean;
+    incoming(): ReadonlyArray<PointerField>;
+    onAdded(pointerField: PointerField): void;
+    onRemoved(pointerField: PointerField): void;
+    [Symbol.iterator](): Iterator<PointerField>;
+    toString(): string;
+}
+//# sourceMappingURL=pointer-hub.d.ts.map

package/dist/pointer-hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer-hub.d.ts","sourceRoot":"","sources":["../src/pointer-hub.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAE,YAAY,EAAC,MAAM,WAAW,CAAA;AACpD,OAAO,EAAC,MAAM,EAAC,MAAM,UAAU,CAAA;AAC/B,OAAO,EAAO,GAAG,EAAwB,MAAM,EAAoB,YAAY,EAAC,MAAM,kBAAkB,CAAA;AAGxG,MAAM,WAAW,eAAe;IAC5B,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;IAClC,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAA;CACxC;AAED,qBAAa,UAAW,YAAW,QAAQ,CAAC,YAAY,CAAC;;IACrD,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;gBAkB1D,MAAM,EAAE,MAAM;IAO1B,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,YAAY;IAInG,oBAAoB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,YAAY;IAIrG,8BAA8B,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,YAAY;IAoB/G,MAAM,CAAC,CAAC,SAAS,YAAY,EAAE,GAAG,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAKlF,IAAI,IAAI,GAAG;IACX,OAAO,IAAI,OAAO;IAClB,QAAQ,IAAI,OAAO;IACnB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO;IACxC,QAAQ,IAAI,aAAa,CAAC,YAAY,CAAC;IAEvC,OAAO,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAUzC,SAAS,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAQ3C,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,YAAY,CAAC;IAE3C,QAAQ,IAAI,MAAM;CAuCrB"}

package/dist/pointer-hub.js

@@ -0,0 +1,110 @@
+import { Iterables, Listeners, Option, panic } from "@opendaw/lib-std";
+import { Address } from "./address";
+export class PointerHub {
+    static validate(pointer, target) {
+        if (pointer.address.equals(target.address)) {
+            return Option.wrap(`PointerField cannot point to itself: ${pointer}`);
+        }
+        if (!target.pointerRules.accepts.some((type) => type === pointer.pointerType)) {
+            console.warn(target.pointerRules);
+            return Option.wrap(`${pointer.toString()} does not satisfy any of the allowed types (${(target.pointerRules)}).`);
+        }
+        return Option.None;
+    }
+    #vertex;
+    #immediateListeners;
+    #transactualListeners;
+    #inTransaction = Option.None;
+    constructor(vertex) {
+        this.#vertex = vertex;
+        this.#immediateListeners = new Listeners();
+        this.#transactualListeners = new Listeners();
+    }
+    subscribeImmediate(listener, ...filter) {
+        return this.#addFilteredListener(this.#immediateListeners, listener, filter);
+    }
+    subscribeTransactual(listener, ...filter) {
+        return this.#addFilteredListener(this.#transactualListeners, listener, filter);
+    }
+    catchupAndSubscribeTransactual(listener, ...filter) {
+        const added = Address.newSet(pointer => pointer.address);
+        added.addMany(this.filter(...filter));
+        added.forEach(pointer => listener.onAdd(pointer));
+        // This takes track of the listeners notification state.
+        // It is possible that the pointer has been added, but it has not been notified yet.
+        // That would cause the listener.onAdd method to be involked twice.
+        return this.subscribeTransactual({
+            onAdd: (pointer) => {
+                if (added.add(pointer)) {
+                    listener.onAdd(pointer);
+                }
+            },
+            onRemove: (pointer) => {
+                added.removeByKey(pointer.address);
+                listener.onRemove(pointer);
+            }
+        }, ...filter);
+    }
+    filter(...types) {
+        return (types.length === 0 ? this.incoming() : Iterables.filter(this, (pointerField) => types.some((type) => type === pointerField.pointerType)));
+    }
+    size() { return this.incoming().length; }
+    isEmpty() { return this.size() === 0; }
+    nonEmpty() { return this.size() > 0; }
+    contains(pointer) { return this.incoming().some(incoming => pointer.address.equals(incoming.address)); }
+    incoming() { return this.#vertex.graph.edges().incomingEdgesOf(this.#vertex); }
+    onAdded(pointerField) {
+        const issue = PointerHub.validate(pointerField, this.#vertex);
+        if (issue.nonEmpty()) {
+            return panic(issue.unwrap());
+        }
+        if (this.#inTransaction.isEmpty()) {
+            this.#vertex.graph.subscribeEndTransaction(this.#onEndTransaction);
+            this.#inTransaction = Option.wrap(new Set(this));
+        }
+        this.#immediateListeners.proxy.onAdd(pointerField);
+    }
+    onRemoved(pointerField) {
+        if (this.#inTransaction.isEmpty()) {
+            this.#vertex.graph.subscribeEndTransaction(this.#onEndTransaction);
+            this.#inTransaction = Option.wrap(new Set(this));
+        }
+        this.#immediateListeners.proxy.onRemove(pointerField);
+    }
+    [Symbol.iterator]() { return this.incoming().values(); }
+    toString() {
+        return `{Pointers ${this.#vertex.address}, pointers: ${Array.from(this)
+            .map((pointerField) => pointerField.toString())}}`;
+    }
+    #addFilteredListener(listeners, listener, filter) {
+        return listeners.subscribe({
+            onAdd: (pointer) => {
+                if (filter.length === 0 || filter.some((type) => type === pointer.pointerType)) {
+                    listener.onAdd(pointer);
+                }
+            },
+            onRemove: (pointer) => {
+                if (filter.length === 0 || filter.some((type) => type === pointer.pointerType)) {
+                    listener.onRemove(pointer);
+                }
+            }
+        });
+    }
+    #onEndTransaction = () => {
+        if (this.#vertex.isAttached()) {
+            const beforeState = this.#inTransaction.unwrap("Callback without transaction");
+            const afterState = new Set(this);
+            beforeState.forEach(pointer => {
+                if (!afterState.has(pointer)) {
+                    this.#transactualListeners.proxy.onRemove(pointer);
+                }
+            });
+            afterState.forEach(pointer => {
+                if (!beforeState.has(pointer)) {
+                    this.#transactualListeners.proxy.onAdd(pointer);
+                }
+            });
+        }
+        this.#inTransaction = Option.None;
+    };
+}

package/dist/pointer.d.ts

@@ -0,0 +1,32 @@
+import { DataInput, DataOutput, Nullish, Observer, Option, Subscription } from "@opendaw/lib-std";
+import { Vertex, VertexVisitor } from "./vertex";
+import { Address } from "./address";
+import { PointerHub } from "./pointer-hub";
+import { Field, FieldConstruct } from "./field";
+declare const _Unreferenceable: unique symbol;
+export type UnreferenceableType = typeof _Unreferenceable;
+export type PointerTypes = number | string | UnreferenceableType;
+export declare class PointerField<P extends PointerTypes = PointerTypes> extends Field<UnreferenceableType, never> {
+    #private;
+    static create<P extends PointerTypes>(construct: FieldConstruct<UnreferenceableType>, pointerType: P, mandatory: boolean): PointerField<P>;
+    private constructor();
+    get pointerHub(): PointerHub;
+    get pointerType(): P;
+    get mandatory(): boolean;
+    accept<RETURN>(visitor: VertexVisitor<RETURN>): Nullish<RETURN>;
+    subscribe(observer: Observer<this>): Subscription;
+    catchupAndSubscribe(observer: Observer<this>): Subscription;
+    refer<TARGET extends PointerTypes>(vertex: Vertex<P & TARGET extends never ? never : TARGET>): void;
+    defer(): void;
+    get targetVertex(): Option<Vertex>;
+    set targetVertex(option: Option<Vertex>);
+    get targetAddress(): Option<Address>;
+    set targetAddress(newValue: Option<Address>);
+    isEmpty(): boolean;
+    nonEmpty(): boolean;
+    resolve(): void;
+    read(input: DataInput): void;
+    write(output: DataOutput): void;
+}
+export {};
+//# sourceMappingURL=pointer.d.ts.map

package/dist/pointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.d.ts","sourceRoot":"","sources":["../src/pointer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAsB,YAAY,EAAC,MAAM,kBAAkB,CAAA;AACnH,OAAO,EAAC,MAAM,EAAE,aAAa,EAAC,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAC,OAAO,EAAC,MAAM,WAAW,CAAA;AACjC,OAAO,EAAC,UAAU,EAAC,MAAM,eAAe,CAAA;AACxC,OAAO,EAAC,KAAK,EAAE,cAAc,EAAC,MAAM,SAAS,CAAA;AAG7C,QAAA,MAAM,gBAAgB,eAA4B,CAAA;AAElD,MAAM,MAAM,mBAAmB,GAAG,OAAO,gBAAgB,CAAA;AAEzD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,CAAA;AAEhE,qBAAa,YAAY,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,CAAE,SAAQ,KAAK,CAAC,mBAAmB,EAAE,KAAK,CAAC;;IACtG,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,YAAY,EAAE,SAAS,EAAE,cAAc,CAAC,mBAAmB,CAAC,EAC9C,WAAW,EAAE,CAAC,EACd,SAAS,EAAE,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC;IAU1E,OAAO;IASP,IAAI,UAAU,IAAI,UAAU,CAA+C;IAE3E,IAAI,WAAW,IAAI,CAAC,CAA2B;IAC/C,IAAI,SAAS,IAAI,OAAO,CAAyB;IAEjD,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAI/D,SAAS,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY;IAIjD,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY;IAM3D,KAAK,CAAC,MAAM,SAAS,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,SAAS,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC,GAAG,IAAI;IAInG,KAAK,IAAI,IAAI;IAEb,IAAI,YAAY,IAAI,MAAM,CAAC,MAAM,CAAC,CAA4B;IAC9D,IAAI,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAQtC;IAED,IAAI,aAAa,IAAI,MAAM,CAAC,OAAO,CAAC,CAA6B;IACjE,IAAI,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,EAM1C;IAED,OAAO,IAAI,OAAO;IAClB,QAAQ,IAAI,OAAO;IAEnB,OAAO,IAAI,IAAI;IASf,IAAI,CAAC,KAAK,EAAE,SAAS;IAIrB,KAAK,CAAC,MAAM,EAAE,UAAU;CAS3B"}

package/dist/pointer.js

@@ -0,0 +1,82 @@
+import { Option, panic, safeExecute } from "@opendaw/lib-std";
+import { Address } from "./address";
+import { PointerHub } from "./pointer-hub";
+import { Field } from "./field";
+import { Propagation } from "./dispatchers";
+const _Unreferenceable = Symbol("Unreferenceable");
+export class PointerField extends Field {
+    static create(construct, pointerType, mandatory) {
+        return new PointerField(construct, pointerType, mandatory);
+    }
+    #pointerType;
+    #mandatory;
+    #targetVertex = Option.None;
+    #targetAddress = Option.None;
+    constructor(field, pointerType, mandatory) {
+        super(field);
+        this.#pointerType = pointerType;
+        this.#mandatory = mandatory;
+        if (mandatory) {
+            this.graph.edges().watchVertex(this);
+        }
+    }
+    get pointerHub() { return panic(`${this} cannot be pointed to`); }
+    get pointerType() { return this.#pointerType; }
+    get mandatory() { return this.#mandatory; }
+    accept(visitor) {
+        return safeExecute(visitor.visitPointerField, this);
+    }
+    subscribe(observer) {
+        return this.graph.subscribeVertexUpdates(Propagation.This, this.address, () => observer(this));
+    }
+    catchupAndSubscribe(observer) {
+        observer(this);
+        return this.graph.subscribeVertexUpdates(Propagation.This, this.address, () => this.graph.subscribeEndTransaction(() => observer(this)));
+    }
+    refer(vertex) {
+        this.targetVertex = Option.wrap(vertex);
+    }
+    defer() { this.targetVertex = Option.None; }
+    get targetVertex() { return this.#targetVertex; }
+    set targetVertex(option) {
+        if (option.nonEmpty()) {
+            const issue = PointerHub.validate(this, option.unwrap());
+            if (issue.nonEmpty()) {
+                panic(issue.unwrap());
+            }
+        }
+        this.targetAddress = option.map(vertex => vertex.address);
+    }
+    get targetAddress() { return this.#targetAddress; }
+    set targetAddress(newValue) {
+        const oldValue = this.#targetAddress;
+        if ((oldValue.isEmpty() && newValue.isEmpty())
+            || (newValue.nonEmpty() && oldValue.unwrapOrNull()?.equals(newValue.unwrap())) === true) {
+            return;
+        }
+        this.#targetAddress = newValue;
+        this.graph.onPointerAddressUpdated(this, oldValue, newValue);
+    }
+    isEmpty() { return this.targetAddress.isEmpty(); }
+    nonEmpty() { return this.targetAddress.nonEmpty(); }
+    resolve() {
+        const targetAddress = this.targetAddress;
+        const target = targetAddress.flatMap((address) => this.graph.findVertex(address));
+        if (targetAddress.nonEmpty() && target.isEmpty()) {
+            return panic(`${targetAddress.unwrapOrNull()?.toString()} could not be resolved`);
+        }
+        this.#targetVertex = target;
+    }
+    read(input) {
+        this.targetAddress = input.readBoolean() ? Option.wrap(Address.read(input)) : Option.None;
+    }
+    write(output) {
+        this.#targetAddress.match({
+            none: () => output.writeBoolean(false),
+            some: address => {
+                output.writeBoolean(true);
+                address.write(output);
+            }
+        });
+    }
+}