@arrai-innovations/reactive-helpers 21.0.1 → 21.1.2

package/types/use/proxyLoading.d.ts

@@ -1,15 +1,25 @@
 /**
- * @typedef {Pick<import('./loading.js').LoadingStatus, "loading">} ReadonlyLoadingStatus
- * @typedef {import("vue").Ref<ReadonlyLoadingStatus>} RefLoadingStatus
- * @typedef {ReadonlyLoadingStatus | RefLoadingStatus} WatchableLoading
+ * @typedef {import('./loading.js').LoadingProperties | import("vue").Reactive<import('./loading.js').LoadingProperties>} WatchableLoading
+ * @typedef {import('vue').MaybeRef<WatchableLoading>} MaybeRefWatchableLoading
+ * @typedef {import('./loading.js').LoadingProperties} ReadonlyLoadingStatus
  */
 /**
  * A composable function for aggregating loading state across multiple sources.
  *
- * @param {WatchableLoading[]} loadings - The loading states to monitor.
+ * @param {import('vue').MaybeRef<MaybeRefWatchableLoading[]>} loadings - The loading states to monitor.
  * @returns {ReadonlyLoadingStatus} An object containing the aggregated loading field.
  */
-export function useProxyLoading(loadings: WatchableLoading[]): ReadonlyLoadingStatus;
-export type ReadonlyLoadingStatus = Pick<import("./loading.js").LoadingStatus, "loading">;
-export type RefLoadingStatus = import("vue").Ref<ReadonlyLoadingStatus>;
-export type WatchableLoading = ReadonlyLoadingStatus | RefLoadingStatus;
+export function useProxyLoading(loadings: import("vue").MaybeRef<MaybeRefWatchableLoading[]>): ReadonlyLoadingStatus;
+/**
+ * Adapt an object with reactive loading state into a WatchableLoading shape.
+ * Accepts either an object with a `state` property or an object that already exposes `loading`.
+ *
+ * @param {import('vue').MaybeRef<{ state: WatchableLoading } | WatchableLoading>} source - The source object to adapt.
+ * @returns {WatchableLoading} - The adapted WatchableLoading object.
+ */
+export function asWatchableLoading(source: import("vue").MaybeRef<{
+    state: WatchableLoading;
+} | WatchableLoading>): WatchableLoading;
+export type WatchableLoading = import("./loading.js").LoadingProperties | import("vue").Reactive<import("./loading.js").LoadingProperties>;
+export type MaybeRefWatchableLoading = import("vue").MaybeRef<WatchableLoading>;
+export type ReadonlyLoadingStatus = import("./loading.js").LoadingProperties;

package/types/use/proxyLoadingError.d.ts

@@ -1,13 +1,28 @@
 /**
  * @typedef {import('./proxyLoading.js').WatchableLoading & import('./proxyError.js').WatchableError} WatchableLoadingError
- * @typedef {import('./proxyLoading.js').ReadonlyLoadingStatus & import('./proxyError.js').ReadonlyErrorStatus} ProxyLoadingError
+ * @typedef {import('vue').MaybeRef<WatchableLoadingError>} MaybeRefWatchableLoadingError
+ * @typedef {import('./loading.js').LoadingProperties & import('./error.js').ReadonlyErrorStatus} ProxyLoadingError
  */
 /**
- * A composable function combining aggregated loading and error state.
+ * A composable function combining aggregated loading and error state. Use `asWatchableLoadingError` to convert <List|Object><Instance|Subscription> to WatchableLoadingError.
  *
- * @param {WatchableLoadingError[]} loadingErrors - The loading and error states to monitor.
+ * @param {import('vue').MaybeRef<MaybeRefWatchableLoadingError[]>} loadingErrors - The loading and error states to monitor.
  * @returns {ProxyLoadingError} - An object containing aggregated reactive fields and actions for both loading and error state.
  */
-export function useProxyLoadingError(loadingErrors: WatchableLoadingError[]): ProxyLoadingError;
+export function useProxyLoadingError(loadingErrors: import("vue").MaybeRef<MaybeRefWatchableLoadingError[]>): ProxyLoadingError;
+/**
+ * @typedef {{ state: import('vue').Reactive<import('./error.js').ErrorProperties> } & import('./error.js').ErrorReadOnlyFunctions} SeparateStateLoadingError
+ */
+/**
+ * Adapt an object that exposes loading/error state and clearError into a WatchableLoadingError shape.
+ *
+ * @param {import('vue').MaybeRef<SeparateStateLoadingError | WatchableLoadingError>} source - The source object to adapt.
+ * @returns {WatchableLoadingError} - The adapted WatchableLoadingError object.
+ */
+export function asWatchableLoadingError(source: import("vue").MaybeRef<SeparateStateLoadingError | WatchableLoadingError>): WatchableLoadingError;
 export type WatchableLoadingError = import("./proxyLoading.js").WatchableLoading & import("./proxyError.js").WatchableError;
-export type ProxyLoadingError = import("./proxyLoading.js").ReadonlyLoadingStatus & import("./proxyError.js").ReadonlyErrorStatus;
+export type MaybeRefWatchableLoadingError = import("vue").MaybeRef<WatchableLoadingError>;
+export type ProxyLoadingError = import("./loading.js").LoadingProperties & import("./error.js").ReadonlyErrorStatus;
+export type SeparateStateLoadingError = {
+    state: import("vue").Reactive<import("./error.js").ErrorProperties>;
+} & import("./error.js").ErrorReadOnlyFunctions;

package/types/utils/isReactiveTyped.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @template {object} T
+ * @param {T | import('vue').Reactive<T>} v - The value to check.
+ * @returns {v is import('vue').Reactive<T>} - True if the value is reactive, false otherwise.
+ */
+export function isReactiveTyped<T extends unknown>(v: T | import("vue").Reactive<T>): v is import("vue").Reactive<T>;

package/types/utils/refIfReactive.d.ts

@@ -1 +1,2 @@
-export function refIfReactive<T, K extends keyof T>(source: (T & object) | undefined | null, property: K, defaultValue?: T[K]): import("vue").ComputedRef<T[K]> | import("vue").Ref<T[K]>;
+export function refIfReactive<T, K extends keyof T>(source: (T & object) | undefined | null, property: K, defaultValue?: T[K] | undefined): import("vue").ComputedRef<T[K] | undefined> | import("vue").Ref<T[K] | undefined>;
+export function pkRefIfReactive(source: object | undefined | null, property?: string, defaultValue?: import("../config/commonCrud.js").Pk | null): import("vue").ComputedRef<import("../config/commonCrud.js").Pk | undefined>;

package/types/utils/toRefsIfReactive.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @template {object} T
+ * @overload
+ * @param {import('vue').Reactive<T>} source - The source reactive object.
+ * @returns {import('vue').ToRefs<T>} - The refs of the reactive object.
+ */
+export function toRefsIfReactive<T extends unknown>(source: import("vue").Reactive<T>): import("vue").ToRefs<T>;
+/**
+ * @template {object} T
+ * @overload
+ * @param {T} source - The source object.
+ * @returns {T} - The original object.
+ */
+export function toRefsIfReactive<T extends unknown>(source: T): T;

package/use/cancellableIntent.js

@@ -34,7 +34,7 @@ export class CancellableIntentError extends Error {
  */
 
 /**
- * @typedef {object} CancellableIntentRawState - The raw state of the cancellable intent.
+ * @typedef {object} CancellableIntentMyState - The raw state of the cancellable intent.
  * @property {import('vue').ComputedRef<boolean>|undefined} active - Whether there are active intents.
  * @property {import('vue').ComputedRef<boolean>|undefined} resolving - Whether there are resolving intents.
  * @property {boolean} clearActiveOnResolved - Whether to clear the active state when the promise resolves.
@@ -44,10 +44,11 @@ export class CancellableIntentError extends Error {
  */
 
 /**
- * @typedef {import("vue").Reactive<
- *     CancellableIntentRawState &
- *     Pick<import('./error.js').ErrorStatus, 'error' | 'errored'>
- * >} CancellableIntentState - The state of the cancellable intent.
+ * @typedef {CancellableIntentMyState & import('./error.js').ErrorProperties} CancellableIntentRawState - The raw state of the cancellable intent.
+ */
+
+/**
+ * @typedef {import("vue").Reactive<CancellableIntentRawState>} CancellableIntentState - The state of the cancellable intent.
  */
 
 /**
@@ -63,7 +64,7 @@ export class CancellableIntentError extends Error {
  */
 
 /**
- * @typedef {(runTracking: CommonRunTracking) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<void>} AwaitableWithCancel - A function that returns a promise that can be cancelled.
+ * @typedef {(runTracking: CommonRunTracking) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<unknown>} AwaitableWithCancel - A function that returns a promise that can be cancelled. The return value of the promise is not used.
  */
 
 /**
@@ -95,7 +96,7 @@ export class CancellableIntentError extends Error {
  */
 
 /**
- * @typedef {MyCancellableIntent & Pick<import('./error.js').ErrorStatus, "clearError">} CancellableIntent - The instance of the cancellable intent.
+ * @typedef {MyCancellableIntent & import('./error.js').ErrorReadOnlyFunctions} CancellableIntent - The instance of the cancellable intent.
  */
 
 /**

package/use/error.js

@@ -9,15 +9,34 @@ import { readonly, ref } from "vue";
  */
 
 /**
- * The error state API.
- *
- * @typedef {object} ErrorStatus
+ * @typedef {object} ErrorProperties
  * @property {ErrorReadonlyRef} error - The error that occurred.
  * @property {ErroredReadonlyRef} errored - Whether an error has occurred.
+ */
+
+/**
+ * @typedef {object} ErrorFunctions
  * @property {(error: Error) => void} setError - Set the error state.
  * @property {ClearErrorFn} clearError - Clear the error state.
  */
 
+/**
+ * Proxies can still clear errors but cannot set them directly.
+ *
+ * @typedef {object} ErrorReadOnlyFunctions
+ * @property {ClearErrorFn} clearError - Clear the error state.
+ */
+
+/**
+ * @typedef {ErrorProperties & ErrorReadOnlyFunctions} ReadonlyErrorStatus
+ */
+
+/**
+ * The error state API.
+ *
+ * @typedef {ErrorProperties & ErrorFunctions} ErrorStatus
+ */
+
 /**
  * A composable function for managing error state.
  *

package/use/listCalculated.js

@@ -35,7 +35,7 @@ import { computed, effectScope, nextTick, reactive, ref, toRef, toRefs, unref, w
  * The raw state for a list calculated.
  *
  * @typedef {object} ListCalculatedRawState - The raw state for a list calculated property.
- * @property {{[pk: string]: {[rule: string]: import('vue').ComputedRef<any>}}} calculatedObjects - The calculated objects.
+ * @property {{[pk: import('../config/commonCrud.js').Pk]: {[rule: string]: import('vue').ComputedRef<any>}}} calculatedObjects - The calculated objects.
  * @property {ListCalculatedRules} calculatedObjectsRules - The rules for the calculated objects.
  * @property {boolean} calculatedObjectsParentStateObjectsWatchRunning - Whether the parent state objects watch is running.
  * @property {boolean} calculatedObjectsWatchRunning - Whether the calculated objects watch is running.

package/use/listInstance.js

@@ -59,7 +59,7 @@ export class ListInstanceError extends Error {
 /**
  * The objects by pk.
  *
- * @typedef {{[pk: string]: import('../use/objectInstance.js').ExistingCrudObject}} ObjectsByPk
+ * @typedef {{[pk: import('../config/commonCrud.js').Pk]: import('../use/objectInstance.js').ExistingCrudObject}} ObjectsByPk
  */
 
 /**
@@ -71,7 +71,7 @@ export class ListInstanceError extends Error {
 /**
  * The order of the objects in the list.
  *
- * @typedef {import('vue').ComputedRef<string[]>} ListOrder
+ * @typedef {import('vue').ComputedRef<import('../config/commonCrud.js').Pk[]>} ListOrder
  */
 
 /**
@@ -84,7 +84,7 @@ export class ListInstanceError extends Error {
  */
 
 /**
- * @typedef {Map<string, import('vue').Reactive<import('../use/objectInstance.js').ExistingCrudObject>>} ObjectsMap
+ * @typedef {Map<import('../config/commonCrud.js').Pk, import('vue').Reactive<import('../use/objectInstance.js').ExistingCrudObject>>} ObjectsMap
  */
 
 /**
@@ -156,13 +156,13 @@ export class ListInstanceError extends Error {
  * @property {PushObjectsFn} pushObjects - Customizable callback for handling new objects per page.
  * @property {(object: import('../use/objectInstance.js').ExistingCrudObject) => void} addListObject - Adds an object to the list.
  * @property {(object: import('../use/objectInstance.js').ExistingCrudObject) => void} updateListObject - Updates an object in the list.
- * @property {(objectId: string) => void} deleteListObject - Deletes an object from the list by pk.
+ * @property {(objectId: import('../config/commonCrud.js').PkInput) => void} deleteListObject - Deletes an object from the list by pk.
  * @property {(options?: ClearListOptions) => void} clearList - Clears the list objects and optionally keeps pagination, totals,
  *  or error state.
- * @property {() => string} getFakePk - Generates a unique fake pk for use within the list.
- * @property {() => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} list - Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
- * @property {(args: {pks?: string[]}) => Promise<boolean>} bulkDelete - Deletes objects from the list by pk, returning a promise to a boolean indicating success.
- * @property {() => Promise<object|string|false>} executeAction - Initiates an action on all objects in the list, returning the response, or false if the action failed.
+ * @property {() => import('../config/commonCrud.js').Pk} getFakePk - Generates a unique fake pk for use within the list.
+ * @property {(args?: import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<boolean|never>} list - Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
+ * @property {(args?: {pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => Promise<boolean>} bulkDelete - Deletes objects from the list by pk, returning a promise to a boolean indicating success.
+ * @property {(args: {action: string, pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => Promise<object|string|boolean|null>} executeAction - Initiates an action on all objects in the list, returning the response, or null if the action failed.
  * @property {(info: PaginateInfo) => void} setPaginateInfo - The method to update pagination information.
  * @property {(total: ColumnTotals) => void} setColumnTotals - The method to update column totals.
  */
@@ -262,7 +262,7 @@ export function useListInstance({ props, handlers = {} }) {
 
     const [_objectsProxy, _objectsMapProxy] = es.run(() => {
         // ### do not use this directly, because we proxy `set` to make sure that values are reactive ###
-        /** @type {import('vue').Reactive<Map<string, import('../use/objectInstance.js').ExistingCrudObject>>} */
+        /** @type {import('vue').Reactive<Map<import('../config/commonCrud.js').Pk, import('../use/objectInstance.js').ExistingCrudObject>>} */
         const _objectsMap = shallowReactive(new Map()); // maps are ordered, if you don't clear lists, you need to insert pages in order.
 
         // ### this is a proxy to make the map behave like an object for reactivity ###
@@ -417,8 +417,7 @@ export function useListInstance({ props, handlers = {} }) {
         setColumnTotals: (total) => {
             assignReactiveObject(state.columnTotals, total || {});
         },
-        list: (args) => {
-            const { runId, isCurrentRun } = args || {};
+        list: (args = {}) => {
             // this function cannot be async, or the resulting promise will lose its .cancel() method
             if (promises.list) {
                 // if a retrieve is already in progress, return the existing promise
@@ -433,6 +432,7 @@ export function useListInstance({ props, handlers = {} }) {
             let listPromise = null;
             try {
                 const listCrudArgs = {
+                    ...args,
                     target: state.crud.args,
                     pkKey: state.pkKey,
                     params: state.params,
@@ -442,10 +442,6 @@ export function useListInstance({ props, handlers = {} }) {
                     setPaginateInfo: self.setPaginateInfo,
                     setColumnTotals: self.setColumnTotals,
                 };
-                if (runId) {
-                    listCrudArgs.runId = runId;
-                    listCrudArgs.isCurrentRun = isCurrentRun;
-                }
                 listPromise = state.crud.list(listCrudArgs);
             } catch (e) {
                 loadingError.setError(e);
@@ -475,7 +471,7 @@ export function useListInstance({ props, handlers = {} }) {
             );
             return promises.list;
         },
-        bulkDelete: ({ pks } = {}) => {
+        bulkDelete: ({ pks, ...additionalArgs } = {}) => {
             if (state.loading) {
                 return Promise.reject(new ListInstanceError("already loading.", "already-loading"));
             }
@@ -486,6 +482,7 @@ export function useListInstance({ props, handlers = {} }) {
             loadingError.clearError();
             return state.crud
                 .bulkDelete({
+                    ...additionalArgs,
                     target: state.crud.args,
                     pks,
                     pkKey: state.pkKey,
@@ -503,7 +500,7 @@ export function useListInstance({ props, handlers = {} }) {
                     loadingError.clearLoading();
                 });
         },
-        executeAction: ({ pks, action }) => {
+        executeAction: ({ pks, action, ...additionalArgs }) => {
             if (state.loading) {
                 return Promise.reject(new ListInstanceError("already loading.", "already-loading"));
             }
@@ -514,8 +511,9 @@ export function useListInstance({ props, handlers = {} }) {
             loadingError.clearError();
             return state.crud
                 .executeAction({
-                    action,
+                    ...additionalArgs,
                     target: state.crud.args,
+                    action,
                     pks,
                     pkKey: state.pkKey,
                 })
@@ -532,36 +530,39 @@ export function useListInstance({ props, handlers = {} }) {
                 });
         },
         addListObject: (object) => {
+            const pk = String(object[state.pkKey]);
             if (!object[state.pkKey]) {
                 throw new ListInstanceError(
                     `addListObject: object missing pk(${state.pkKey}).\n${inspect(object)}`,
                     "missing-pk"
                 );
             }
-            if (object[state.pkKey] in state.objects) {
+            if (pk in state.objects) {
                 throw new ListInstanceError(
-                    `addListObject: list already has object for pk(${state.pkKey}): ${inspect(object[state.pkKey])}`,
+                    `addListObject: list already has object for pk(${state.pkKey}): ${inspect(pk)}`,
                     "duplicate-pk"
                 );
             }
-            state.objects[object[state.pkKey]] = object;
+            state.objects[pk] = object;
         },
         updateListObject: (object) => {
+            const pk = String(object[state.pkKey]);
             if (!object[state.pkKey]) {
                 throw new ListInstanceError(
                     `updateListObject: object missing pk(${state.pkKey}).\n${inspect(object)}`,
                     "missing-pk"
                 );
             }
-            if (!(object[state.pkKey] in state.objects)) {
+            if (!(pk in state.objects)) {
                 throw new ListInstanceError(
-                    `updateListObject: list missing object for update by pk(${state.pkKey}): ${inspect(object[state.pkKey])}`,
+                    `updateListObject: list missing object for update by pk(${state.pkKey}): ${inspect(pk)}`,
                     "missing-object"
                 );
             }
-            assignReactiveObject(state.objects[object[state.pkKey]], object);
+            assignReactiveObject(state.objects[pk], object);
         },
-        deleteListObject: (pk) => {
+        deleteListObject: (pkInput) => {
+            const pk = String(pkInput);
             if (!(pk in state.objects)) {
                 throw new ListInstanceError(
                     `deleteListObject: list missing object for removal by pk(${state.pkKey}): ${inspect(pk)}`,
@@ -588,7 +589,8 @@ export function useListInstance({ props, handlers = {} }) {
         getFakePk: () => getFakePk(state.objects, state.pkKey),
         pushObjects: (newObjects) => {
             newObjects.forEach((newObject) => {
-                if (newObject[state.pkKey] in state.objects) {
+                const pk = String(newObject[state.pkKey]);
+                if (pk in state.objects) {
                     self.updateListObject.call(this, newObject);
                 } else {
                     self.addListObject.call(this, newObject);

package/use/listRelated.js

@@ -41,18 +41,18 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
  *
  * @typedef {object} ListRelatedRawState
  * @property {{
- *     [pk: string]: {
+ *     [pk: import('../config/commonCrud.js').Pk]: {
  *         [rule: string]: import('vue').ComputedRef<any>,
  *     },
  * }} relatedObjects - Stores computed references to related objects, allowing for dynamic access based on object pk and specific rules.
  * @property {ListRelatedRules} relatedObjectsRules - Defines the rules for establishing relationships, such as foreign key links and sorting orders.
  * @property {{
- *     [pk: string]: {
+ *     [pk: import('../config/commonCrud.js').Pk]: {
  *         [rule: string]: import('vue').ComputedRef<[object, string]>,
  *     },
  * }} objAndKeyForPkAndRule - Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation.
  * @property {{
- *     [pk: string]: {
+ *     [pk: import('../config/commonCrud.js').Pk]: {
  *         [rule: string]: import('vue').ComputedRef<any>,
  *     },
  * }} fkForPkAndRule - Maintains computed references to the foreign keys for each object pk and rule, crucial for navigating complex data relationships.

package/use/listSubscription.js

@@ -5,8 +5,8 @@ import inspect from "browser-util-inspect";
 import cloneDeep from "lodash-es/cloneDeep.js";
 import isEmpty from "lodash-es/isEmpty.js";
 import isObject from "lodash-es/isObject.js";
-import { reactive, toRef, toRefs } from "vue";
-import { useProxyLoadingError } from "./proxyLoadingError.js";
+import { reactive, readonly, ref, toRef, toRefs } from "vue";
+import { asWatchableLoadingError, useProxyLoadingError } from "./proxyLoadingError.js";
 import { refIfReactive } from "../utils/refIfReactive.js";
 
 /**
@@ -89,12 +89,16 @@ export class ListSubscriptionError extends Error {
  * @typedef {ListSubscriptionFunctions & ListSubscriptionProperties} ListSubscription
  */
 
+/**
+ * @typedef {object} ListSubscriptionOwnOptions
+ * @property {import("./listInstance.js").ListInstance} [listInstance] - A list instance to use instead of creating one.
+ */
+
 /**
  * Defines the settings required to establish a list subscription, detailing how list instances should handle updates
  *  and subscriptions based on the given properties.
  *
- * @typedef {object & import("./listInstance.js").ListInstanceOptions} ListSubscriptionOptions
- * @property {import("./listInstance.js").ListInstance} listInstance - A list instance to use instead of creating one.
+ * @typedef {import("./listInstance.js").ListInstanceOptions & ListSubscriptionOwnOptions} ListSubscriptionOptions
  */
 
 /**
@@ -182,7 +186,7 @@ export function useListSubscription({ listInstance, props, handlers }) {
     const parentState = listInstance.state;
 
     const loadingError = useLoadingError();
-    const proxyLoadingError = useProxyLoadingError([loadingError, parentState]);
+    const proxyLoadingError = useProxyLoadingError([loadingError, asWatchableLoadingError(listInstance)]);
     // stand alone in order to avoid circular dependency between state & intents.
     const intendToList = refIfReactive(props, "intendToList", false);
     const intendToSubscribe = refIfReactive(props, "intendToSubscribe", false);
@@ -208,95 +212,109 @@ export function useListSubscription({ listInstance, props, handlers }) {
     const subscribeIntent = useCancellableIntent({
         awaitableWithCancel: ({ runId, isCurrentRun }) => {
             // this function cannot be async, or the resulting promise will lose its .cancel() method
+            const isCancelled = ref(false);
             loadingError.setLoading();
             let subscribePromise, catchPromise;
             try {
-                subscribePromise = parentState.crud.subscribe({
-                    runId,
-                    isCurrentRun,
-                    target: cloneDeep(parentState.crud.args),
-                    pkKey: parentState.pkKey,
-                    params: cloneDeep(parentState.params),
-                    applyObjectEvent: (
-                        /** @type {import('./objectInstance.js').ExistingCrudObject} */ data,
-                        /** @type {"create"|"update"|"delete"} */ action
-                    ) => {
-                        if (!data || (isObject(data) && isEmpty(data))) {
-                            throw new ListSubscriptionError(
-                                `got update with no data (${inspect(data)}), action: ${action}`,
-                                "empty-data"
-                            );
-                        }
-                        switch (action) {
-                            case "delete":
-                                try {
-                                    listInstance.deleteListObject(data);
-                                } catch (err) {
-                                    if (err.name === "ListInstanceError" && err.code === "missing-object") {
-                                        console.warn(
-                                            `deleteFromSubscription: delete for pk(${listInstance.state.pkKey}) not in objects (${inspect(data)}).`
+                subscribePromise = /** @type {import('../utils/cancellablePromise.js').CancellablePromise<void>} */ (
+                    parentState.crud.subscribe({
+                        runId,
+                        isCurrentRun,
+                        target: cloneDeep(parentState.crud.args),
+                        pkKey: parentState.pkKey,
+                        params: cloneDeep(parentState.params),
+                        applyObjectEvent: (
+                            /** @type {import('./objectInstance.js').ExistingCrudObject} */ data,
+                            /** @type {"create"|"update"|"delete"} */ action
+                        ) => {
+                            if (!data || (isObject(data) && isEmpty(data))) {
+                                throw new ListSubscriptionError(
+                                    `got update with no data (${inspect(data)}), action: ${action}`,
+                                    "empty-data"
+                                );
+                            }
+                            switch (action) {
+                                case "delete":
+                                    try {
+                                        const pkValue = isObject(data) ? data[parentState.pkKey] : data;
+                                        listInstance.deleteListObject(pkValue);
+                                    } catch (err) {
+                                        if (err.name === "ListInstanceError" && err.code === "missing-object") {
+                                            console.warn(
+                                                `deleteFromSubscription: delete for pk(${parentState.pkKey}) not in objects (${inspect(data)}).`
+                                            );
+                                            return;
+                                        }
+                                        throw err;
+                                    }
+                                    break;
+                                case "create":
+                                    if (!data[parentState.pkKey]) {
+                                        throw new ListSubscriptionError(
+                                            `addFromSubscription: data missing pk(${parentState.pkKey}).\n${inspect(data)}`,
+                                            "missing-pk"
                                         );
-                                        return;
                                     }
-                                    throw err;
-                                }
-                                break;
-                            case "create":
-                                if (!data[listInstance.state.pkKey]) {
-                                    throw new ListSubscriptionError(
-                                        `addFromSubscription: data missing pk(${listInstance.state.pkKey}).\n${inspect(data)}`,
-                                        "missing-pk"
-                                    );
-                                }
-                                try {
-                                    listInstance.addListObject(data);
-                                } catch (err) {
-                                    if (err.name === "ListInstanceError" && err.code === "duplicate-pk") {
-                                        console.warn(
-                                            `addFromSubscription: add for pk(${listInstance.state.pkKey}) already in objects (${data[listInstance.state.pkKey]}).`
+                                    try {
+                                        listInstance.addListObject(data);
+                                    } catch (err) {
+                                        if (err.name === "ListInstanceError" && err.code === "duplicate-pk") {
+                                            console.warn(
+                                                `addFromSubscription: add for pk(${parentState.pkKey}) already in objects (${data[parentState.pkKey]}).`
+                                            );
+                                            return;
+                                        }
+                                        throw err;
+                                    }
+                                    break;
+                                case "update":
+                                    if (!data[parentState.pkKey]) {
+                                        throw new ListSubscriptionError(
+                                            `updateFromSubscription: data missing pk(${parentState.pkKey}).\n${inspect(data)}`,
+                                            "missing-pk"
                                         );
-                                        return;
                                     }
-                                    throw err;
-                                }
-                                break;
-                            case "update":
-                                if (!data[listInstance.state.pkKey]) {
+                                    try {
+                                        listInstance.updateListObject(data);
+                                    } catch (err) {
+                                        if (err.name === "ListInstanceError" && err.code === "missing-object") {
+                                            console.warn(
+                                                `updateFromSubscription: update for pk(${parentState.pkKey}) not in objects (${data[parentState.pkKey]}).`
+                                            );
+                                            return;
+                                        }
+                                        throw err;
+                                    }
+                                    break;
+                                default:
                                     throw new ListSubscriptionError(
-                                        `updateFromSubscription: data missing pk(${listInstance.state.pkKey}).\n${inspect(data)}`,
-                                        "missing-pk"
+                                        `got update for unknown action: ${action}\n${inspect(data)}`,
+                                        "unknown-action"
                                     );
-                                }
-                                try {
-                                    listInstance.updateListObject(data);
-                                } catch (err) {
-                                    if (err.name === "ListInstanceError" && err.code === "missing-object") {
-                                        console.warn(
-                                            `updateFromSubscription: update for pk(${listInstance.state.pkKey}) not in objects (${data[listInstance.state.pkKey]}).`
-                                        );
-                                        return;
-                                    }
-                                    throw err;
-                                }
-                                break;
-                            default:
-                                throw new ListSubscriptionError(
-                                    `got update for unknown action: ${action}\n${inspect(data)}`,
-                                    "unknown-action"
-                                );
-                        }
-                    },
-                });
-                // catching makes a new promise, we need to make sure the cancel method lives on.
-                catchPromise = subscribePromise
-                    .catch((/** @type {Error} */ err) => {
-                        console.error(err);
-                        loadingError.setError(err);
+                            }
+                        },
+                        isCancelled: readonly(isCancelled),
                     })
-                    .finally(() => {
-                        loadingError.clearLoading();
-                    });
-                catchPromise.cancel = subscribePromise.cancel.bind(subscribePromise);
+                );
+                // catching makes a new promise, we need to make sure the cancel method lives on.
+                catchPromise = /** @type {import('../utils/cancellablePromise.js').CancellablePromise<void>} */ (
+                    subscribePromise
+                        .catch((/** @type {Error} */ err) => {
+                            console.error(err);
+                            loadingError.setError(err);
+                        })
+                        .finally(() => {
+                            loadingError.clearLoading();
+                        })
+                );
+                if (subscribePromise.cancel) {
+                    const originalCancel = subscribePromise.cancel.bind(subscribePromise);
+                    const cancelWithFlag = async (/** @type {any} */ reason) => {
+                        isCancelled.value = true;
+                        return originalCancel(reason);
+                    };
+                    catchPromise.cancel = cancelWithFlag;
+                }
                 return catchPromise;
             } catch (err) {
                 console.error(err);