@audiotool/nexus - v0.0.12
    Preparing search index...

    Interface EntityQuery<T>

    Provides facilities to query the nexus document.

    Once the query is built, execute it by calling get().

    There are two ways to get access to an entity query.

    • by creating a transaction and accessing the field {@link TransactionBuilder.entities}
    • by accessing the field {@link NexusDocument.queryEntitiesWithoutLock}

    Example usage:

    const nexus = new NexusDocument()
    await nexus.modify(t => {
      // all entities of the nexus document
      const allEntities = t.entities.get()

      // all connections pointing to a tb303
      const tb303Entity = ...
      const connections = t.entities
           .ofTypes("desktopAudioCable", "desktopNoteCable")
           .pointingToEntity(tbt303Entity.id)
           .get()
    })

    // the returned values are typed; `connections` is of type
    // NexusEntity<'desktopAudioCable' | 'desktopNoteCable'>[]
    // so we can access shared fields of the entity:
    const fromSocket = connections[0]?.fields.fromSocket

    If the results of a query are used to create a transaction, the entities of the TransactionBuilder should be used. Transactions are created asynchronously, so the result of the query can become out of date once the transaction lock is acquired, and transaction errors can occur.

    Entity queries can technically be "recycled", meaning that you can type:

    const t = await nexus.createTransaction()
    const query = t.entities.pointingTo.entities(bassline3)
    const audioConnsToBassline3 = query.ofTypes("desktopAudioCable").get()
    const noteConnsToBassline3 = query.ofTypes("desktopNoteCable").get()
    t.send()

    However, note that queries created this way will throw if they're used outside of a transaction.

    To query the document without awaiting the transaction lock, you can use

    nexus.queryEntitiesWithoutLock.ofTypes("desktopAudioCable").get()
    interface EntityQuery<T extends EntityTypeKey = EntityTypeKey> {
        get pointedToBy(): ReferenceQuery<T>;
        get pointingTo(): ReferenceQuery<T>;
        fields(): FieldQuery<NexusField>;
        get(): NexusEntityUnion<T>[];
        getEntity(uuid: string): undefined | NexusEntityUnion<T>;
        getEntityAs<E extends keyof EntityTypes>(
            uuid: string,
            ...types: E[],
        ): undefined | NexusEntityUnion<E>;
        getOne(): undefined | NexusEntityUnion<T>;
        has(uuidOrEntity: string | NexusEntity<keyof EntityTypes>): boolean;
        mustGetEntity(uuid: string): NexusEntityUnion<T>;
        mustGetEntityAs<E extends keyof EntityTypes>(
            uuid: string,
            ...types: E[],
        ): NexusEntityUnion<E>;
        notOfTypes<Q extends (keyof EntityTypes)[]>(
            ...types: Q,
        ): EntityQuery<Exclude<T, Q[number]>>;
        ofTargetTypes(
            ...targetTypes: (
                | "Groove"
                | "Sample"
                | "MicroTuning"
                | "Listenable"
                | "AutomatableParameter"
                | "AudioInput"
                | "AudioOutput"
                | "NotesInput"
                | "NotesOutput"
                | "AutomationCollection"
                | "AudioTrack"
                | "AudioTrackPlayer"
                | "PatternTrack"
                | "PatternTrackPlayer"
                | "NoteCollection"
                | "NoteTrack"
                | "NoteTrackPlayer"
                | "AutomationTrack"
                | "Waveshaper"
                | "Centroid"
                | "RasselbockPatternSlot"
                | "TonematrixPatternSlot"
                | "Beatbox8PatternSlot"
                | "Beatbox9PatternSlot"
                | "BasslinePatternSlot"
                | "MachinistePatternSlot"
                | "MatrixArpeggiatorPatternSlot"
                | "MixerStripGroup"
                | "MixerStripGroupChild"
                | "MixerSideChainInput"
                | "MixerSideChainOutput"
                | "MixerAuxSend"
                | "MixerAuxReceive"
            )[],
        ): EntityQuery<T>;
        ofTypes<Q extends (keyof EntityTypes)[]>(
            ...types: Q,
        ): EntityQuery<Q[number] & T>;
        withIds(...uuids: string[]): EntityQuery<T>;
    }

    Type Parameters

    Index

    Accessors

    pointedToBy pointingTo

    Methods

    fields get getEntity getEntityAs getOne has mustGetEntity mustGetEntityAs notOfTypes ofTargetTypes ofTypes withIds

    Accessors

    • get pointedToBy(): ReferenceQuery<T>

      Only keep entities that are themselves, or have fields that are, pointed to by:

      • entityOfType: some field of entities of a set of types
      • locations: specific locations
      • entities: some field of specific entities

      Passing an empty list to any of these methods will result in an empty query result.

      Use e.g. as:

      nexus.entities.pointedToBy.entitiesOfType("tb303").get()

      Returns ReferenceQuery<T>

    • get pointingTo(): ReferenceQuery<T>

      Only keep entities that have some fields that point to:

      • entityOfType: some field of entities of a set of types
      • locations: specific locations
      • entities: some field of specific entities

      Passing an empty list to any of these methods will result in an empty query result.

      Use e.g. like:

      nexus.entities.pointingTo.entitiesOfType("tb303").get()

      Returns ReferenceQuery<T>

    Methods

    • Returns the first entity returned by get(), if any.

      Since the order of entities in get() is undefined, which of the selected entity this method returns is also undefined. This method is intended to be used if it's known that the query will return at most one entity.

      Returns undefined | NexusEntityUnion<T>

    • Only keep entities whose messages are marked with a target type appearing in targetTypes. Target types of fields of entities are ignored.

      Parameters

      • ...targetTypes: (
            | "Groove"
            | "Sample"
            | "MicroTuning"
            | "Listenable"
            | "AutomatableParameter"
            | "AudioInput"
            | "AudioOutput"
            | "NotesInput"
            | "NotesOutput"
            | "AutomationCollection"
            | "AudioTrack"
            | "AudioTrackPlayer"
            | "PatternTrack"
            | "PatternTrackPlayer"
            | "NoteCollection"
            | "NoteTrack"
            | "NoteTrackPlayer"
            | "AutomationTrack"
            | "Waveshaper"
            | "Centroid"
            | "RasselbockPatternSlot"
            | "TonematrixPatternSlot"
            | "Beatbox8PatternSlot"
            | "Beatbox9PatternSlot"
            | "BasslinePatternSlot"
            | "MachinistePatternSlot"
            | "MatrixArpeggiatorPatternSlot"
            | "MixerStripGroup"
            | "MixerStripGroupChild"
            | "MixerSideChainInput"
            | "MixerSideChainOutput"
            | "MixerAuxSend"
            | "MixerAuxReceive"
        )[]

      Returns EntityQuery<T>

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods