reactive-helpers

Appearance

use/listRelated ​

Classes ​

ListRelatedError ​

Defines a custom error class specific to list related rules, encapsulating details about rules that cannot be resolved as configured.

Extends ​

  • Error

Constructors ​

Constructor ​

new ListRelatedError(message, code): ListRelatedError

Creates an instance of ListRelatedError.

Parameters ​
message ​

string

The error message.

code ​

string

The error code.

Returns ​

ListRelatedError

Overrides ​

Error.constructor

Properties ​

code ​

code: string

name ​

name: string

Inherited from ​

Error.name

Interfaces ​

ListRelatedOptions ​

The options for the list related composition function.

Properties ​

parentState ​

parentState: object

The parent state object.

columnTotals ​

columnTotals: ShallowReactive<ColumnTotals>

Column totals for the list.

crud ​

crud: object

CRUD handlers and their configurations for the list.

crud.args ​

args: Reactive<{ } | TargetArgs>

The arguments to be passed to the crud handlers.

crud.bulkDelete ​

bulkDelete: CrudBulkDeleteFn

The bulk delete function.

crud.executeAction ​

executeAction: CrudExecuteActionFn

The execute action function.

crud.list ​

list: CrudListFn

The list function.

crud.subscribe ​

subscribe: CrudListSubscribeFn

The subscribe function.

error ​

error: Error

The error that occurred.

errored ​

errored: boolean

Whether an error has occurred.

intendToList? ​

optional intendToList?: boolean

If this is true, the list should be fetched, or re-fetched if arguments change.

intendToSubscribe? ​

optional intendToSubscribe?: boolean

If this is true, the subscription should start or restart if arguments change.

loading ​

loading: boolean

Whether the component is loading.

objects ​

objects: ObjectsByPk

The list objects stored by their pks.

objectsInOrder ​

objectsInOrder: readonly ExistingCrudObject[]

The objects in the order specified by the list.

objectsMap ​

objectsMap: object

The map of objects stored by their pks.

objectsVersion ​

objectsVersion: number

Increments when this layer's set of object keys changes. Each layer that narrows membership publishes its own, so the value belongs to the state reporting it and is not comparable with another layer's. Watch it rather than reading it, and prefer watchMembershipChanged, which carries the same signal without exposing how it is counted.

order ​

order: readonly string[]

The order of objects in the list.

paginateInfo ​

paginateInfo: ShallowReactive<PaginateInfo>

Pagination information for the list.

params ​

params: any

Arguments passed to the server for listing operations.

pkKey ​

pkKey: string

The primary key field for the list objects.

subscribed? ​

optional subscribed?: boolean

Whether the subscription is active.

relatedObjectsRules ​

relatedObjectsRules: Ref<ListRelatedRules, ListRelatedRules>

The rules for the related objects.

ListRelatedProperties ​

The properties for the list related composition function.

Properties ​

parentState ​

parentState: object

The parent state object.

columnTotals ​

columnTotals: ShallowReactive<ColumnTotals>

Column totals for the list.

crud ​

crud: object

CRUD handlers and their configurations for the list.

crud.args ​

args: Reactive<{ } | TargetArgs>

The arguments to be passed to the crud handlers.

crud.bulkDelete ​

bulkDelete: CrudBulkDeleteFn

The bulk delete function.

crud.executeAction ​

executeAction: CrudExecuteActionFn

The execute action function.

crud.list ​

list: CrudListFn

The list function.

crud.subscribe ​

subscribe: CrudListSubscribeFn

The subscribe function.

error ​

error: Error

The error that occurred.

errored ​

errored: boolean

Whether an error has occurred.

intendToList? ​

optional intendToList?: boolean

If this is true, the list should be fetched, or re-fetched if arguments change.

intendToSubscribe? ​

optional intendToSubscribe?: boolean

If this is true, the subscription should start or restart if arguments change.

loading ​

loading: boolean

Whether the component is loading.

objects ​

objects: ObjectsByPk

The list objects stored by their pks.

objectsInOrder ​

objectsInOrder: readonly ExistingCrudObject[]

The objects in the order specified by the list.

objectsMap ​

objectsMap: object

The map of objects stored by their pks.

objectsVersion ​

objectsVersion: number

Increments when this layer's set of object keys changes. Each layer that narrows membership publishes its own, so the value belongs to the state reporting it and is not comparable with another layer's. Watch it rather than reading it, and prefer watchMembershipChanged, which carries the same signal without exposing how it is counted.

order ​

order: readonly string[]

The order of objects in the list.

paginateInfo ​

paginateInfo: ShallowReactive<PaginateInfo>

Pagination information for the list.

params ​

params: any

Arguments passed to the server for listing operations.

pkKey ​

pkKey: string

The primary key field for the list objects.

subscribed? ​

optional subscribed?: boolean

Whether the subscription is active.

state ​

state: object

The state for the list related property.

columnTotals ​

columnTotals: ShallowReactive<ColumnTotals>

Column totals for the list.

crud ​

crud: object

CRUD handlers and their configurations for the list.

crud.args ​

args: Reactive<{ } | TargetArgs>

The arguments to be passed to the crud handlers.

crud.bulkDelete ​

bulkDelete: CrudBulkDeleteFn

The bulk delete function.

crud.executeAction ​

executeAction: CrudExecuteActionFn

The execute action function.

crud.list ​

list: CrudListFn

The list function.

crud.subscribe ​

subscribe: CrudListSubscribeFn

The subscribe function.

error ​

error: Error

The error that occurred.

errored ​

errored: boolean

Whether an error has occurred.

fkForPkAndRule ​

fkForPkAndRule: object

The foreign key for each object pk and rule, crucial for navigating complex data relationships. Each entry is backed by a computed that the reactive proxy unwraps on read.

Index Signature ​

[pk: string]: object

intendToList? ​

optional intendToList?: boolean

If this is true, the list should be fetched, or re-fetched if arguments change.

intendToSubscribe? ​

optional intendToSubscribe?: boolean

If this is true, the subscription should start or restart if arguments change.

loading ​

loading: boolean

Whether the component is loading.

objAndKeyForPkAndRule ​

objAndKeyForPkAndRule: object

Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation. Reads through the reactive state unwrap the computed to the tuple itself, so .value is not used.

Index Signature ​

[pk: string]: object

objects ​

objects: ObjectsByPk

The list objects stored by their pks.

objectsInOrder ​

objectsInOrder: readonly ExistingCrudObject[]

The objects in the order specified by the list.

objectsMap ​

objectsMap: object

The map of objects stored by their pks.

objectsVersion ​

objectsVersion: number

Increments when this layer's set of object keys changes. Each layer that narrows membership publishes its own, so the value belongs to the state reporting it and is not comparable with another layer's. Watch it rather than reading it, and prefer watchMembershipChanged, which carries the same signal without exposing how it is counted.

order ​

order: readonly string[]

The order of objects in the list.

paginateInfo ​

paginateInfo: ShallowReactive<PaginateInfo>

Pagination information for the list.

params ​

params: any

Arguments passed to the server for listing operations.

pkKey ​

pkKey: string

The primary key field for the list objects.

relatedObjects ​

relatedObjects: object

The related objects, by object pk and then rule name. Each entry is backed by a computed, but it is read through a reactive proxy that unwraps it, so reads yield the related object (or array of related objects) and never carry a .value.

Index Signature ​

[pk: string]: object

relatedObjectsParentStateObjectsWatchRunning ​

relatedObjectsParentStateObjectsWatchRunning: boolean

Flags whether the watch on parent state objects is currently active, ensuring updates trigger as needed.

relatedObjectsRules ​

relatedObjectsRules: ListRelatedRules

Defines the rules for establishing relationships, such as foreign key links and sorting orders.

relatedObjectsWatchRunning ​

relatedObjectsWatchRunning: boolean

Indicates if watches on the related objects themselves are active, managing updates efficiently.

relatedRunning ​

relatedRunning: boolean

Signals whether any computations related to object relationships are currently in progress.

running ​

running: boolean

General flag that indicates if the list-related logic is processing, used to manage UI feedback or prevent concurrent operations.

subscribed? ​

optional subscribed?: boolean

Whether the subscription is active.

stop ​

stop: () => void

Stops all effects of the list related property.

Returns ​

void

watchMembershipChanged ​

watchMembershipChanged: WatchMembershipChanged

Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.

ListRelatedRawState ​

Represents the internal state used by the list related composition function. It manages and computes the relationships between objects based on specified rules, providing real-time updates to related objects as the parent state changes.

Properties ​

fkForPkAndRule ​

fkForPkAndRule: object

The foreign key for each object pk and rule, crucial for navigating complex data relationships. Each entry is backed by a computed that the reactive proxy unwraps on read.

Index Signature ​

[pk: string]: object

objAndKeyForPkAndRule ​

objAndKeyForPkAndRule: object

Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation. Reads through the reactive state unwrap the computed to the tuple itself, so .value is not used.

Index Signature ​

[pk: string]: object

relatedObjects ​

relatedObjects: object

The related objects, by object pk and then rule name. Each entry is backed by a computed, but it is read through a reactive proxy that unwraps it, so reads yield the related object (or array of related objects) and never carry a .value.

Index Signature ​

[pk: string]: object

relatedObjectsParentStateObjectsWatchRunning ​

relatedObjectsParentStateObjectsWatchRunning: boolean

Flags whether the watch on parent state objects is currently active, ensuring updates trigger as needed.

relatedObjectsRules ​

relatedObjectsRules: ListRelatedRules

Defines the rules for establishing relationships, such as foreign key links and sorting orders.

relatedObjectsWatchRunning ​

relatedObjectsWatchRunning: boolean

Indicates if watches on the related objects themselves are active, managing updates efficiently.

relatedRunning ​

relatedRunning: boolean

Signals whether any computations related to object relationships are currently in progress.

running ​

running: Ref<boolean, boolean>

General flag that indicates if the list-related logic is processing, used to manage UI feedback or prevent concurrent operations.

ListRelatedRule ​

The rule for defining relationships for objects in a list.

Properties ​

fkKey? ​

optional fkKey?: string

Specifies the foreign key on each row used to link objects across lists. Defaults to the rule's own key when omitted.

objects ​

objects: ObjectsByPk

The objects that can be related based on the foreign key.

order? ​

optional order?: string[]

Specifies the order in which related objects should be sorted, if applicable.

pkKey? ​

optional pkKey?: string

Deprecated alias for fkKey, removed in v24. The option never named a primary key. A rule setting both uses fkKey.

Type Aliases ​

ListRelated ​

ListRelated = ListRelatedProperties

An instance of useListRelated.

Type Parameters ​

ListRelatedParentRawState ​

ListRelatedParentRawState = ListInstanceRawState & Partial<ListSubscriptionRawState>

The raw state properties for a parent of a list related property.

Type Parameters ​

ListRelatedParentState ​

ListRelatedParentState = UnwrapNestedRefs

The type for a parentState object.

Type Parameters ​

ListRelatedRules ​

ListRelatedRules = object

The rules for defining relationships among objects in a list.

Type Parameters ​

Index Signature ​

[rule: string]: ListRelatedRule

ListRelatedState ​

ListRelatedState = UnwrapNestedRefs

The state for a list related property.

Type Parameters ​

Functions ​

useListRelated() ​

useListRelated(options): ListRelatedProperties

Initializes and returns an instance of a related objects manager. This function sets up reactive states and computations that dynamically adjust as the parent list's state changes. It uses defined rules for object relationships to compute and update related objects in real-time, ensuring that changes in the parent state are reflected in the relationships defined by the rules.

Parameters ​

options ​

ListRelatedOptions

The configuration options including the parent state and rules for related objects.

Returns ​

ListRelatedProperties

  • A reactive instance that manages related objects, providing real-time updates and maintaining the integrity of object relationships as per the specified rules.

Example ​

vue
<script setup>
import { useListInstance, useListRelated } from "@arrai-innovations/reactive-helpers";
import { reactive, toRef } from "vue";

const props = defineProps({
    someListFilter: {
        type: String,
        default: "",
        description: "The filter to apply to the list.",
    },
    objects: {
        type: Object,
        default: () => ({}),
        description: "The objects to relate to.",
    },
    order: {
         type: Array,
         default: () => [],
         description: "The order of the list.",
    },
});

const listInstanceProps = reactive({
    target: {
        // whatever arguments are required for your configured list crud function to get the right endpoint
    },
    params: {
        // whatever arguments are required for your configured list function to get the right list
        someListFilter: toRef(props, "someListFilter"),
    },
    pkKey: 'id',
    intendToList: false,
});
listInstanceProps.intendToList = computed(()=> !!props.someListFilter);
const listInstance = useListInstance({ props: listInstanceProps });
const listRelatedProps = reactive({
    parentState: listInstance.state, // reactive-to-reactive so no need for toRef
    relatedObjectsRules: {
        someRule: {
            // this can point to a key or an array of keys to relate to
            fkKey: "dot.separated.key.to.the.foreign.key.on.a.listInstance.object",
            objects: toRef(props, "objects"),
            order: toRef(props, "order"),
        },
    },
});
const listRelated = useListRelated(listRelatedProps);
</script>
<template>
    <ul>
        <!-- reactive list of objects, re-retrieving the list as someListFilter changes. -->
        <li v-for="obj in listInstance.state.objectsInOrder">
            {{ obj }}
            <div>
                <!-- the related object or objects based on the rule -->
                {{ listRelated.state.relatedObjects[obj.id].someRule }}
            </div>
        </li>
    </ul>
</template>

useListRelateds() ​

useListRelateds(listRelatedArgs): object

Creates and manages multiple instances of list-related properties, linking each to corresponding parent instances based on provided configuration.

Parameters ​

listRelatedArgs ​

The options for the list related properties.

Returns ​

object

  • The instances of the list related properties.