Interface DevtoolsHook

Type declaration

• • (
        entity: { "~@dxos/echo/Kind": Object; id: string },
    ): {
        annotations: {
            [key: string & Brand<"~@dxos/echo/AnnotationKey">]: unknown;
        };
        convergenceKey?: string;
        createdAt?: number;
        key?: string;
        keys: { id: string; source: string }[];
        tags: Ref<Tag>[];
        updatedAt?: number;
        version?: string;
    }

  • Get the metadata for an object. Returns mutable meta when passed a mutable object (inside Obj.update callback). Returns read-only meta when passed a regular object or snapshot.

    Parameters

    • entity: { "~@dxos/echo/Kind": Object; id: string }

    Returns {
        annotations: {
            [key: string & Brand<"~@dxos/echo/AnnotationKey">]: unknown;
        };
        convergenceKey?: string;
        createdAt?: number;
        key?: string;
        keys: { id: string; source: string }[];
        tags: Ref<Tag>[];
        updatedAt?: number;
        version?: string;
    }

    • Readonlyannotations: { [key: string & Brand<"~@dxos/echo/AnnotationKey">]: unknown }

      Dictionary of annotations to this entity.

    • Optional ReadonlyconvergenceKey?: string

      Caller-supplied domain identity, unique within a space: two entities carrying the same convergence key are the same entity and are merged into one. Declared by assigning this field inside an update callback — Entity.update(x, (x) => { Entity.getMeta(x).convergenceKey = '…' }) — so it batches with the caller's other writes; there is deliberately no dedicated setter.

      Objects only: the merge engine ignores the field on relations and types (not merge subjects yet), and treats the empty string as no key — both are verified at detection, in the worker, and in the client executor rather than at write time, since the field replicates from peers that cannot be trusted to have validated it.

      Opaque to the storage engine — callers that need generations encode them in the string (e.g. com.example.seed@2), which yields distinct entities because the strings differ. Distinct from key/version above, which record the registry entry an instance was created from (provenance, not identity).

    • Optional ReadonlycreatedAt?: number

      Unix ms timestamp when this entity was created. Read-only; sourced from the system section of the automerge document — not stored in meta.

    • Optional Readonlykey?: string

      Fully-qualified registry key for the object (FQN format, e.g. com.example.type.foo). Identifies the canonical registry entry the object instance was created from.

    • Readonlykeys: { id: string; source: string }[]

    • Readonlytags: Ref<Tag>[]

      Tags applied to this entity, as references to Tag objects.

    • Optional ReadonlyupdatedAt?: number

      Unix ms timestamp of the last automerge change on this entity's document. Read-only; derived from the automerge change graph — not stored in meta.

    • Optional Readonlyversion?: string

      Semantic version of the registry entry the object was created from. Must be a valid semver string (e.g. 1.2.3).

    Example

    // Read-only access outside change callback
    const meta = Obj.getMeta(person);  // ReadonlyMeta
    
    // Mutable access inside change callback
    Obj.update(person, (obj) => {
      const meta = Obj.getMeta(obj);     // EntityMeta (mutable)
      meta.tags.push(Ref.make(tag));     // tags are refs to Tag objects
    });
    Copy

    Performance

    O(1); returns the live (memoized) meta proxy, not a copy.

  • (
        entity: Unknown | Snapshot<Unknown>,
    ): {
        annotations: {
            readonly [key: string & Brand<"~@dxos/echo/AnnotationKey">]: unknown;
        };
        convergenceKey?: string;
        createdAt?: number;
        key?: string;
        keys: readonly { id: string; source: string }[];
        tags: readonly {
            "[RefTypeId]": {
                _T: {
                    "~@dxos/echo/Kind": Object;
                    hue?: string;
                    id: string;
                    label: string;
                };
            };
            atom: {
                "[NodeInspectSymbol]": {};
                "~effect/reactivity/Atom": "~effect/reactivity/Atom";
                equals: {};
                idleTTL?: number;
                initialValueTarget?: { readonly keepAlive: boolean; readonly lazy: boolean; readonly read: {}; readonly equals: {}; readonly refresh?: {} | undefined; readonly label?: readonly [name: string, stack: string] | undefined; readonly idleTTL?: number | undefined; ... 5 more ...; readonly [NodeInspectSymbol]: {}; };
                keepAlive: boolean;
                label?: readonly [string, string];
                lazy: boolean;
                pipe: {};
                read: {};
                refresh?: {};
                toJSON: {};
                toString: {};
            };
            encode: {};
            isAvailable: boolean;
            load: {};
            noInline: {};
            onResolved: {};
            peek: {};
            pipe: {};
            target: | undefined
            | { "~@dxos/echo/Kind": Object; hue?: string; id: string; label: string };
            tryLoad: {};
            uri: URI;
        }[];
        updatedAt?: number;
        version?: string;
    }

  • Get the metadata for an object. Returns mutable meta when passed a mutable object (inside Obj.update callback). Returns read-only meta when passed a regular object or snapshot.

    Parameters

    • entity: Unknown | Snapshot<Unknown>

    Returns {
        annotations: {
            readonly [key: string & Brand<"~@dxos/echo/AnnotationKey">]: unknown;
        };
        convergenceKey?: string;
        createdAt?: number;
        key?: string;
        keys: readonly { id: string; source: string }[];
        tags: readonly {
            "[RefTypeId]": {
                _T: {
                    "~@dxos/echo/Kind": Object;
                    hue?: string;
                    id: string;
                    label: string;
                };
            };
            atom: {
                "[NodeInspectSymbol]": {};
                "~effect/reactivity/Atom": "~effect/reactivity/Atom";
                equals: {};
                idleTTL?: number;
                initialValueTarget?: { readonly keepAlive: boolean; readonly lazy: boolean; readonly read: {}; readonly equals: {}; readonly refresh?: {} | undefined; readonly label?: readonly [name: string, stack: string] | undefined; readonly idleTTL?: number | undefined; ... 5 more ...; readonly [NodeInspectSymbol]: {}; };
                keepAlive: boolean;
                label?: readonly [string, string];
                lazy: boolean;
                pipe: {};
                read: {};
                refresh?: {};
                toJSON: {};
                toString: {};
            };
            encode: {};
            isAvailable: boolean;
            load: {};
            noInline: {};
            onResolved: {};
            peek: {};
            pipe: {};
            target: | undefined
            | { "~@dxos/echo/Kind": Object; hue?: string; id: string; label: string };
            tryLoad: {};
            uri: URI;
        }[];
        updatedAt?: number;
        version?: string;
    }

    • Readonlyannotations: { readonly [key: string & Brand<"~@dxos/echo/AnnotationKey">]: unknown }

      Dictionary of annotations to this entity.

    • Optional ReadonlyconvergenceKey?: string

      Caller-supplied domain identity, unique within a space: two entities carrying the same convergence key are the same entity and are merged into one. Declared by assigning this field inside an update callback — Entity.update(x, (x) => { Entity.getMeta(x).convergenceKey = '…' }) — so it batches with the caller's other writes; there is deliberately no dedicated setter.

      Objects only: the merge engine ignores the field on relations and types (not merge subjects yet), and treats the empty string as no key — both are verified at detection, in the worker, and in the client executor rather than at write time, since the field replicates from peers that cannot be trusted to have validated it.

      Opaque to the storage engine — callers that need generations encode them in the string (e.g. com.example.seed@2), which yields distinct entities because the strings differ. Distinct from key/version above, which record the registry entry an instance was created from (provenance, not identity).

    • Optional ReadonlycreatedAt?: number

      Unix ms timestamp when this entity was created. Read-only; sourced from the system section of the automerge document — not stored in meta.

    • Optional Readonlykey?: string

      Fully-qualified registry key for the object (FQN format, e.g. com.example.type.foo). Identifies the canonical registry entry the object instance was created from.

    • Readonlykeys: readonly { id: string; source: string }[]

    • Readonlytags: readonly {
          "[RefTypeId]": {
              _T: {
                  "~@dxos/echo/Kind": Object;
                  hue?: string;
                  id: string;
                  label: string;
              };
          };
          atom: {
              "[NodeInspectSymbol]": {};
              "~effect/reactivity/Atom": "~effect/reactivity/Atom";
              equals: {};
              idleTTL?: number;
              initialValueTarget?: { readonly keepAlive: boolean; readonly lazy: boolean; readonly read: {}; readonly equals: {}; readonly refresh?: {} | undefined; readonly label?: readonly [name: string, stack: string] | undefined; readonly idleTTL?: number | undefined; ... 5 more ...; readonly [NodeInspectSymbol]: {}; };
              keepAlive: boolean;
              label?: readonly [string, string];
              lazy: boolean;
              pipe: {};
              read: {};
              refresh?: {};
              toJSON: {};
              toString: {};
          };
          encode: {};
          isAvailable: boolean;
          load: {};
          noInline: {};
          onResolved: {};
          peek: {};
          pipe: {};
          target: | undefined
          | { "~@dxos/echo/Kind": Object; hue?: string; id: string; label: string };
          tryLoad: {};
          uri: URI;
      }[]

      Tags applied to this entity, as references to Tag objects.

    • Optional ReadonlyupdatedAt?: number

      Unix ms timestamp of the last automerge change on this entity's document. Read-only; derived from the automerge change graph — not stored in meta.

    • Optional Readonlyversion?: string

      Semantic version of the registry entry the object was created from. Must be a valid semver string (e.g. 1.2.3).

    Example

    // Read-only access outside change callback
    const meta = Obj.getMeta(person);  // ReadonlyMeta
    
    // Mutable access inside change callback
    Obj.update(person, (obj) => {
      const meta = Obj.getMeta(obj);     // EntityMeta (mutable)
      meta.tags.push(Ref.make(tag));     // tags are refs to Tag objects
    });
    Copy

    Performance

    O(1); returns the live (memoized) meta proxy, not a copy.