reactive-helpers

Appearance

use/listSubscription ​

Classes ​

ListSubscriptionError ​

Custom error class for list subscription errors.

Extends ​

  • Error

Constructors ​

Constructor ​

new ListSubscriptionError(message, code): ListSubscriptionError

Creates a new ListSubscriptionError.

Parameters ​
message ​

string

The error message.

code ​

string

The error code.

Returns ​

ListSubscriptionError

Overrides ​

Error.constructor

Properties ​

code ​

code: string

name ​

name: string

Inherited from ​

Error.name

Interfaces ​

ListSubscriptionMyState ​

The raw state of a list subscription.

Properties ​

intendToList ​

intendToList: boolean | Ref<boolean, boolean>

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

intendToSubscribe ​

intendToSubscribe: boolean | Ref<boolean, boolean>

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

subscribed ​

subscribed: Ref<boolean, boolean>

Whether the subscription is active.

ListSubscriptionOwnOptions ​

The options specific to a list subscription, namely an optional pre-built list instance to reuse.

Properties ​

listInstance? ​

optional listInstance?: ListInstance

A list instance to use instead of creating one.

ListSubscriptionProperties ​

The properties of a list subscription.

Properties ​

listInstance ​

listInstance: ListInstance

The list instance used by the subscription.

listIntent ​

listIntent: CancellableIntent

The CancellableIntent instance managing if the list should be (re)fetched.

state ​

state: object

The reactive state of the list subscription.

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 ​

intendToList: boolean

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

intendToSubscribe ​

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 ​

subscribed: boolean

Whether the subscription is active.

subscribeIntent ​

subscribeIntent: CancellableIntent

The CancellableIntent instance managing if the subscription should be (un)subscribed.

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.

Type Aliases ​

ListInstanceStateRefs ​

ListInstanceStateRefs = ToRefs

The list instance's reactive state converted to individual Vue refs.

Type Parameters ​

ListSubscription ​

ListSubscription = ListSubscriptionFunctions & ListSubscriptionProperties

An instance of a list subscription, returned by useListSubscription.

Type Parameters ​

ListSubscriptionContext ​

ListSubscriptionContext = object

The context (state, list instance, and loading/error status) bound to the shared list subscription functions.

Type Parameters ​

Type Declaration ​

listInstance ​

listInstance: ListInstance

loadingError ​

loadingError: LoadingErrorStatus

state ​

state: ListSubscriptionState

ListSubscriptionFunctions ​

ListSubscriptionFunctions = Pick<LoadingErrorStatus, "clearError"> & object

The methods available on a list subscription.

Type Declaration ​

stop ​

stop: () => void

Returns ​

void

Type Parameters ​

ListSubscriptionOptions ​

ListSubscriptionOptions = ListInstanceOptions & ListSubscriptionOwnOptions

Defines the settings required to establish a list subscription, detailing how list instances should handle updates and subscriptions based on the given properties.

Type Parameters ​

ListSubscriptionRawState ​

ListSubscriptionRawState = ListSubscriptionMyState & Pick<LoadingErrorStatus, "loading" | "error" | "errored"> & ListInstanceStateRefs

The raw state of a list subscription, including the state from the list instance.

Type Parameters ​

ListSubscriptionState ​

ListSubscriptionState = Reactive

A reactive object that manages a list of objects, as returned by useListInstance.

Type Parameters ​

Functions ​

useListSubscription() ​

useListSubscription(options): ListSubscription

A composition function that creates a reactive object that manages a list of objects, as returned by useListInstance, causing the list to be re-fetched as needed and listening for updates to the list.

Parameters ​

options ​

ListSubscriptionOptions

The options for the list subscription.

Returns ​

ListSubscription

  • Returns a robust list subscription object that manages a list instance with capabilities to subscribe and unsubscribe to data sources, alongside handling real-time data updates.

Example ​

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

const props = defineProps({
    // whatever props are required for your configured list instance
    someListFilter: {
        type: String,
        default: "",
    },
});

const listSubscriptionProps = 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"),
    },
    intendToList: false,
    intendToSubscribe: false,
});
listSubscriptionProps.intendToList = listSubscriptionProps.intendToSubscribe = computed(()=> !!props.someListFilter);
const listSubscription = useListSubscription({ props: listSubscriptionProps });
</script>
<template>
    <ul>
        <!-- reactive list of objects, responding to updates via configured subscription function. -->
        <li v-for="obj in listSubscription.state.objectsInOrder">
            {{ obj }}
        </li>
    </ul>
</template>

Throws ​

  • If the list instance is not set and no props are passed.

useListSubscriptions() ​

useListSubscriptions(listSubscriptionArgs): object

A Vue composition function that creates multiple list subscriptions, and returns them as an object.

Parameters ​

listSubscriptionArgs ​

Each desired list instance options, keyed by an instance name.

Returns ​

object

  • Each list instance, keyed by the instance name.