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: ExistingCrudObject[]

The objects in the order specified by the list.

objectsMap ​

objectsMap: Map<string, ExistingCrudObject> & Omit<ObjectsMap, keyof Map<any, any>>

The map of objects stored by their pks.

objectsVersion ​

objectsVersion: number

Increments when the set of object keys changes.

order ​

order: 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.

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.