reactive-helpers

Appearance

use/listInstance ​

Classes ​

ListInstanceError ​

Defines a custom error class specific to list instance operations, encapsulating details about errors that occur during list manipulation and processing.

Extends ​

  • Error

Constructors ​

Constructor ​

new ListInstanceError(message, code): ListInstanceError

Creates an instance of ListInstanceError.

Parameters ​
message ​

string

The error message.

code ​

string

The error code.

Returns ​

ListInstanceError

Overrides ​

Error.constructor

Properties ​

code ​

code: string

name ​

name: string

Inherited from ​

Error.name

Interfaces ​

ClearListOptions ​

Options to control which reactive state is reset when clearing the list.

Properties ​

keepColumnTotals? ​

optional keepColumnTotals?: boolean

When true, keep the current column totals.

keepError? ​

optional keepError?: boolean

When true, keep the current error state.

keepPagination? ​

optional keepPagination?: boolean

When true, keep the current pagination information.

ListInstanceMyFunctions ​

Defines the methods provided by the list instance for managing objects in the list.

Properties ​

addListObject ​

addListObject: (object) => void

Adds an object to the list.

Parameters ​
object ​

ExistingCrudObject

Returns ​

void

bulkDelete ​

bulkDelete: (args?) => MaybeCancellablePromise<boolean>

Deletes objects from the list by pk, returning a promise to a boolean indicating success. The promise carries a cancel method when the handler's promise did.

Parameters ​
args? ​

object & AdditionalListArgs

Returns ​

MaybeCancellablePromise<boolean>

clearList ​

clearList: (options?) => void

Clears the list objects and optionally keeps pagination, totals, or error state.

Parameters ​
options? ​

ClearListOptions

Returns ​

void

deleteListObject ​

deleteListObject: (objectId) => void

Deletes an object from the list by pk.

Parameters ​
objectId ​

PkInput

Returns ​

void

executeAction ​

executeAction: (args) => MaybeCancellablePromise<any>

Initiates an action on all objects in the list, returning the response, or null if the action failed. The promise carries a cancel method when the handler's promise did.

Parameters ​
args ​

object & AdditionalListArgs

Returns ​

MaybeCancellablePromise<any>

getFakePk ​

getFakePk: () => string

Generates a unique fake pk for use within the list.

Returns ​

string

list ​

list: (args?) => MaybeCancellablePromise<boolean>

Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.

Parameters ​
args? ​

AdditionalListArgs

Returns ​

MaybeCancellablePromise<boolean>

pushObjects ​

pushObjects: PushObjectsFn

Customizable callback for handling new objects per page.

setColumnTotals ​

setColumnTotals: (total) => void

The method to update column totals.

Parameters ​
total ​

ColumnTotals

Returns ​

void

setPaginateInfo ​

setPaginateInfo: (info) => void

The method to update pagination information.

Parameters ​
info ​

PaginateInfo

Returns ​

void

updateListObject ​

updateListObject: (object) => void

Updates an object in the list.

Parameters ​
object ​

ExistingCrudObject

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.

ListInstanceOptions ​

The configuration options used to create a list instance.

Properties ​

handlers? ​

optional handlers?: object

Default implementation are used as set by setListCrud.

bulkDelete? ​

optional bulkDelete?: CrudBulkDeleteFn

Provide the implementation for the bulkDelete function.

executeAction? ​

optional executeAction?: CrudExecuteActionFn

Provide the implementation for the executeAction function.

list? ​

optional list?: CrudListFn

Provide the implementation for the list function.

subscribe? ​

optional subscribe?: CrudListSubscribeFn

Provide the implementation for the subscribe function.

props ​

props: object

The props for the list instance.

params ​

params: any

The arguments passed to the server.

pkKey ​

pkKey: string

The primary key field for the list objects.

target ​

target: any

Implementation specific arguments.

ListInstanceProps ​

The reactive arguments for the list instance.

Properties ​

params ​

params: any

The arguments passed to the server.

pkKey ​

pkKey: string

The primary key field for the list objects.

target ​

target: any

Implementation specific arguments.

ListInstanceRawMyState ​

The raw state object for the list instance, defining the reactive properties and their types.

Properties ​

columnTotals ​

columnTotals: ShallowReactive<ColumnTotals>

Column totals for the list.

crud ​

crud: object

CRUD handlers and their configurations for the list.

args ​

args: Reactive<{ } | TargetArgs>

The arguments to be passed to the crud handlers.

bulkDelete ​

bulkDelete: CrudBulkDeleteFn

The bulk delete function.

executeAction ​

executeAction: CrudExecuteActionFn

The execute action function.

list ​

list: CrudListFn

The list function.

subscribe ​

subscribe: CrudListSubscribeFn

The subscribe function.

objects ​

objects: ObjectsByPk

The list objects stored by their pks.

objectsInOrder ​

objectsInOrder: ComputedRef<readonly ExistingCrudObject[]>

The objects in the order specified by the list.

objectsMap ​

objectsMap: ObjectsMap

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

ListInstanceRawStateCrud ​

The raw CRUD handlers and target args stored in a list instance's reactive state.

Properties ​

args ​

args: Reactive<{ } | TargetArgs>

The arguments to be passed to the crud handlers.

bulkDelete ​

bulkDelete: CrudBulkDeleteFn

The bulk delete function.

executeAction ​

executeAction: CrudExecuteActionFn

The execute action function.

list ​

list: CrudListFn

The list function.

subscribe ​

subscribe: CrudListSubscribeFn

The subscribe function.

PaginateInfo ​

Pagination details for a list, including total records, total pages, per-page count, and current page.

Properties ​

page? ​

optional page?: number

The page you are giving us results for.

perPage? ​

optional perPage?: number

The per page.

totalPages? ​

optional totalPages?: number

The total pages.

totalRecords? ​

optional totalRecords?: number

The total records.

Type Aliases ​

ColumnTotals ​

ColumnTotals = object

A map of column names to their aggregate total values for a list.

Type Parameters ​

Index Signature ​

[key: string]: string | number

ListInstance ​

ListInstance = ListInstanceStateMixIn & ListInstanceFunctions

The list instance, combining state management and functional operations for managing a list of objects.

Type Parameters ​

ListInstanceFunctions ​

ListInstanceFunctions = ListInstanceMyFunctions & Pick<LoadingErrorStatus, "clearError">

The methods contributed by the list instance, including its CRUD operations plus clearError.

Type Parameters ​

ListInstanceRawState ​

ListInstanceRawState = ListInstanceRawMyState & Pick<LoadingErrorStatus, "loading" | "error" | "errored">

The raw, pre-unwrapped state of a list instance, combining its own state with loading and error status.

Type Parameters ​

ListInstanceState ​

ListInstanceState = UnwrapNestedRefs

Defines the reactive state used by the list instance.

Type Parameters ​

ListInstanceStateMixIn ​

ListInstanceStateMixIn = object

Helper type to facilitate the combination of state and functions into a single type.

Type Parameters ​

Type Declaration ​

state ​

state: ListInstanceState

ListOrder ​

ListOrder = ComputedRef

The read-only order of the objects in the list. Change presentation order through useListSort rather than by writing to it.

Type Parameters ​

ObjectsByPk ​

ObjectsByPk = object

The objects by pk. The collection itself is read-only; mutate it through the list's own methods. Each object it holds stays reactive and writable.

Type Parameters ​

Index Signature ​

[pk: string]: ExistingCrudObject

ObjectsInOrder ​

ObjectsInOrder = ComputedRef

The objects in order, based on .order & .objects. The array is read-only; each object in it stays reactive and writable.

Type Parameters ​

ObjectsMap ​

ObjectsMap = ReadonlyMap<Pk, Reactive>

A read-only Map of primary keys to the list's reactive existing objects. Mutate it through the list's own methods. Each object it holds stays reactive and writable.

Type Parameters ​

PushObjectsFn ​

PushObjectsFn = (newObjects) => void

Signature for the function that pushes a page of newly received objects into the list.

Type Parameters ​

Parameters ​

newObjects ​

ExistingCrudObject[]

Returns ​

void

Functions ​

useListInstance() ​

useListInstance(options): ListInstance

Creates and manages a reactive list of objects, providing utilities to add, update, delete, and fetch objects according to the specified CRUD operations.

Parameters ​

options ​

ListInstanceOptions

Specifies the configuration options for creating a list instance, including properties for CRUD operations and UI behaviours like page persistence.

Returns ​

ListInstance

The list instance.

Example ​

vue
<script setup>
import { useListInstance } 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 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"),
    },
});
const listInstance = useListInstance({ props: listInstanceProps });
watch(toRef(props, "someListFilter"), (newValue, oldValue) => {
    if (newValue !== oldValue && !isEmpty(newValue)) {
        listInstance.list();
    }
}, {
   immediate: true,
   deep: true,
});
</script>
<template>
    <ul>
        <!-- reactive list of objects, re-retrieving the list as someListFilter changes. -->
        <li v-for="obj in listInstance.state.objectsInOrder">
            {{ obj }}
        </li>
    </ul>
</template>

Throws ​

If the props are missing.

useListInstances() ​

useListInstances(listInstanceArgs): object

Creates and manages multiple list instances.

Parameters ​

listInstanceArgs ​

The arguments for each list instance.

Returns ​

object

An object of list instances.

References ​

ClearListFn ​

Renames and re-exports ClearObjectsFn

SetColumnTotalsFn ​

Renames and re-exports SetColumnTotals

SetPaginateInfoFn ​

Renames and re-exports SetPaginateInfo