velocious 1.0.646 → 1.0.647

package/src/frontend-models/base.js

@@ -21,6 +21,9 @@ import {forcedNonBlankString} from "typanic"
 import {modelPrimaryKeyCacheKey, modelPrimaryKeyConditions, readModelPrimaryKeyValue, scalarModelPrimaryKey, scalarModelPrimaryKeyValue} from "../utils/model-primary-key.js"
 import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQueryData, setPayloadAssociationCount, setPayloadComputedAbility, setPayloadQueryData} from "../record-payload-values.js"
 
+/** @typedef {string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue} FrontendModelEventPrimaryKeyValue */
+/** @typedef {import("./query.js").FrontendModelEventOptions} FrontendModelEventOptions */
+
 /**
  * Frontend model relationship helper type. Returned by `getRelationshipByName`,
  * which generated models immediately cast to their concrete relationship type
@@ -32,11 +35,14 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  */
 /**
  * Defines this typedef.
- * @typedef {{callback: (payload: {id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue, model: FrontendModelBase}) => void, eventFilterKey: string | null, eventFilterPayload: import("./query.js").FrontendModelEventFilterPayload | null, projectionPayload: import("./query.js").FrontendModelProjectionPayload}} FrontendModelModelEventCallbackEntry
+ * @template {import("../utils/model-primary-key.js").ModelPrimaryKeyValue} [PrimaryKeyValue=import("../utils/model-primary-key.js").ModelPrimaryKeyValue]
+ * @template {FrontendModelBase} [Model=FrontendModelBase]
+ * @typedef {{callback: (payload: {id: PrimaryKeyValue, model: Model}) => void, eventFilterKey: string | null, eventFilterPayload: import("./query.js").FrontendModelEventFilterPayload | null, projectionPayload: import("./query.js").FrontendModelProjectionPayload}} FrontendModelModelEventCallbackEntry
  */
 /**
  * Defines this typedef.
- * @typedef {{callback: (payload: {id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue}) => void}} FrontendModelDestroyEventCallbackEntry
+ * @template {import("../utils/model-primary-key.js").ModelPrimaryKeyValue} [PrimaryKeyValue=import("../utils/model-primary-key.js").ModelPrimaryKeyValue]
+ * @typedef {{callback: (payload: {id: PrimaryKeyValue}) => void}} FrontendModelDestroyEventCallbackEntry
  */
 /**
  * FrontendModelCommandType type.
@@ -111,16 +117,22 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  * invariance. Defaulting to `any` lets any subclass satisfy the constraint while
  * the methods' own `@template T` still captures the precise calling class for
  * their return types.
- * @template {FrontendModelBase} [T=FrontendModelBase<any, any, any>]
+ * @template {FrontendModelBase} [T=FrontendModelBase<any, any, any, any, any>]
  * @template {object} [Attributes=any]
  * @template {object} [CreateAttributes=any]
  * @typedef {{new (): T, create(attributes?: CreateAttributes): Promise<T>} & Omit<typeof FrontendModelBase, "create" | "prototype">} FrontendModelClass
  */
+/** @typedef {Omit<FrontendModelClass<FrontendModelBase<any, any, any, any, string>>, "onDestroy"> & {onDestroy: (callback: (payload: {id: string}) => void, options?: import("./query.js").FrontendModelEventOptions) => Promise<() => void>}} FrontendModelScalarEventClass */
 /**
  * Create attributes accepted by a frontend model instance.
  * @template {FrontendModelBase} T
  * @typedef {T extends FrontendModelBase<Record<string, FrontendModelAttributeValue>, infer CreateAttributes, infer _UpdateAttributes> ? CreateAttributes : Record<string, FrontendModelAttributeValue>} FrontendModelCreateAttributesFor
  */
+/**
+ * Lifecycle event identity exposed by a concrete frontend model.
+ * @template {FrontendModelBase} T
+ * @typedef {T extends FrontendModelBase<any, any, any, any, infer EventPrimaryKeyValue> ? EventPrimaryKeyValue : FrontendModelEventPrimaryKeyValue} FrontendModelEventPrimaryKeyValueFor
+ */
 /**
  * Loaded instance type for relationship helper generics. Older generated
  * frontend models passed model classes into relationship helpers, while newer
@@ -1432,7 +1444,7 @@ function frontendModelMatchedEventFilterKeys(body) {
 
 /**
  * Runs frontend model event entry matches.
- * @param {FrontendModelModelEventCallbackEntry} entry - Callback entry.
+ * @param {FrontendModelModelEventCallbackEntry<any, any>} entry - Callback entry.
  * @param {Set<string>} matchedEventFilterKeys - Backend matched filter keys.
  * @returns {boolean} Whether the callback should receive the event.
  */
@@ -1478,19 +1490,19 @@ class FrontendModelEventSubscription {
     this.requestContext = requestContext
     /**
      * Narrows the runtime value to the documented type.
-     * @type {Set<FrontendModelModelEventCallbackEntry>} */
+     * @type {Set<FrontendModelModelEventCallbackEntry<any, any>>} */
     this.classCreateCallbacks = new Set()
     /**
      * Narrows the runtime value to the documented type.
-     * @type {Set<FrontendModelModelEventCallbackEntry>} */
+     * @type {Set<FrontendModelModelEventCallbackEntry<any, any>>} */
     this.classUpdateCallbacks = new Set()
     /**
      * Narrows the runtime value to the documented type.
-     * @type {Set<FrontendModelDestroyEventCallbackEntry>} */
+     * @type {Set<FrontendModelDestroyEventCallbackEntry<never>>} */
     this.classDestroyCallbacks = new Set()
     /**
      * Narrows the runtime value to the documented type.
-     * @type {Map<string, {instance: FrontendModelBase, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}>} */
+     * @type {Map<string, {instance: FrontendModelBase, updateCallbacks: Set<FrontendModelModelEventCallbackEntry<any, any>>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry<any>>}>} */
     this.instanceListeners = new Map()
     /**
      * Narrows the runtime value to the documented type.
@@ -1573,7 +1585,7 @@ class FrontendModelEventSubscription {
 
   /**
    * Runs register class callback.
-   * @template {FrontendModelModelEventCallbackEntry | FrontendModelDestroyEventCallbackEntry} T
+   * @template {FrontendModelModelEventCallbackEntry<any, any> | FrontendModelDestroyEventCallbackEntry<never>} T
    * @param {Set<T>} callbacks - Callback set for the event type.
    * @param {T} entry - Callback entry.
    * @returns {Promise<() => void>} - Unsubscribe callback.
@@ -1687,7 +1699,9 @@ class FrontendModelEventSubscription {
         deleteFrontendModelInstanceListener(this, listener)
       }
       for (const entry of this.classDestroyCallbacks) {
-        try { entry.callback({id: identity}) } catch (error) { console.error(error) }
+        try {
+          /** @type {(payload: {id: import("../utils/model-primary-key.js").ModelPrimaryKeyValue}) => void} */ (entry.callback)({id: identity})
+        } catch (error) { console.error(error) }
       }
       return
     }
@@ -1833,7 +1847,7 @@ function frontendModelEventRequestContext(requestContext) {
  * @param {FrontendModelEventSubscription} sub - Event subscription bucket.
  * @param {string} id - Model id.
  * @param {FrontendModelBase} instance - Listener instance.
- * @returns {{instance: FrontendModelBase, updateCallbacks: Set<FrontendModelModelEventCallbackEntry>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry>}} - Instance listener bucket.
+ * @returns {{instance: FrontendModelBase, updateCallbacks: Set<FrontendModelModelEventCallbackEntry<any, any>>, destroyCallbacks: Set<FrontendModelDestroyEventCallbackEntry<any>>}} - Instance listener bucket.
  */
 function ensureFrontendModelInstanceListener(sub, id, instance) {
   let listener = sub.instanceListeners.get(id)
@@ -2411,6 +2425,8 @@ function assertDefinedFindByConditionValue(value, keyPath) {
  * @template {object} [Attributes=any]
  * @template {object} [CreateAttributes=any]
  * @template {object} [UpdateAttributes=any]
+ * @template {import("../utils/model-primary-key.js").ModelPrimaryKeyValue} [PrimaryKeyValue=import("../utils/model-primary-key.js").ModelPrimaryKeyValue]
+ * @template {import("../utils/model-primary-key.js").ModelPrimaryKeyValue} [EventPrimaryKeyValue=PrimaryKeyValue]
  */
 export default class FrontendModelBase {
   /**
@@ -2968,13 +2984,13 @@ export default class FrontendModelBase {
 
   /**
    * Runs primary key value.
-   * @returns {import("../utils/model-primary-key.js").ModelPrimaryKeyValue} - Primary key value.
+   * @returns {PrimaryKeyValue} - Primary key value.
    */
   primaryKeyValue() {
     const ModelClass = frontendModelClassFor(this)
     const primaryKey = ModelClass.primaryKey()
 
-    return readModelPrimaryKeyValue(primaryKey, (attributeName) => {
+    return /** @type {PrimaryKeyValue} */ (readModelPrimaryKeyValue(primaryKey, (attributeName) => {
       const value = this.readAttribute(attributeName)
 
       if (value === undefined || value === null) {
@@ -2982,7 +2998,7 @@ export default class FrontendModelBase {
       }
 
       return value
-    })
+    }))
   }
 
   /**
@@ -2996,13 +3012,13 @@ export default class FrontendModelBase {
 
   /**
    * Returns the identity represented by the last persisted frontend attributes.
-   * @returns {import("../utils/model-primary-key.js").ModelPrimaryKeyValue} - Persisted primary-key value.
+   * @returns {PrimaryKeyValue} - Persisted primary-key value.
    */
   persistedPrimaryKeyValue() {
     const ModelClass = frontendModelClassFor(this)
     const primaryKey = ModelClass.primaryKey()
 
-    return readModelPrimaryKeyValue(primaryKey, (attributeName) => {
+    return /** @type {PrimaryKeyValue} */ (readModelPrimaryKeyValue(primaryKey, (attributeName) => {
       const value = this._persistedAttributes[attributeName]
 
       if (value === undefined || value === null) {
@@ -3010,7 +3026,7 @@ export default class FrontendModelBase {
       }
 
       return value
-    })
+    }))
   }
 
   /**
@@ -3951,8 +3967,9 @@ export default class FrontendModelBase {
    * accepted, future `create` events for this model are delivered
    * without re-checking per-record visibility. Query options can still
    * narrow which events reach this callback.
-   * @this {FrontendModelClass}
-   * @param {(payload: {id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue, model: FrontendModelBase}) => void} callback - Event callback.
+   * @template {FrontendModelClass} T
+   * @this {T}
+   * @param {(payload: {id: FrontendModelEventPrimaryKeyValueFor<InstanceType<T>>, model: InstanceType<T>}) => void} callback - Event callback.
    * @param {import("./query.js").FrontendModelEventOptions} [options] - Event query or record projection options.
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
@@ -3966,8 +3983,9 @@ export default class FrontendModelBase {
 
   /**
    * Class-level hook fired when any record of this model is updated.
-   * @this {FrontendModelClass}
-   * @param {(payload: {id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue, model: FrontendModelBase}) => void} callback - Event callback.
+   * @template {FrontendModelClass} T
+   * @this {T}
+   * @param {(payload: {id: FrontendModelEventPrimaryKeyValueFor<InstanceType<T>>, model: InstanceType<T>}) => void} callback - Event callback.
    * @param {import("./query.js").FrontendModelEventOptions} [options] - Event query or record projection options.
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
@@ -3979,10 +3997,17 @@ export default class FrontendModelBase {
     return await sub.registerClassCallback(sub.classUpdateCallbacks, entry)
   }
 
+  /**
+   * @template {FrontendModelClass} T
+   * @overload
+   * @param {T} this - Concrete frontend model class.
+   * @param {(payload: {id: FrontendModelEventPrimaryKeyValueFor<InstanceType<T>>}) => void} callback - Event callback.
+   * @param {import("./query.js").FrontendModelEventOptions} [options] - Accepted for API symmetry; destroy events carry ids only.
+   * @returns {Promise<() => void>} - Unsubscribe callback.
+   */
   /**
    * Class-level hook fired when any record of this model is destroyed.
-   * @this {FrontendModelClass}
-   * @param {(payload: {id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue}) => void} callback - Event callback.
+   * @param {(payload: {id: never}) => void} callback - Event callback erased at the overload implementation boundary.
    * @param {import("./query.js").FrontendModelEventOptions} [options] - Accepted for API symmetry; destroy events carry ids only.
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
@@ -3991,6 +4016,7 @@ export default class FrontendModelBase {
 
     const {requestContext} = frontendModelEventOptionsPayload(this, options)
     const sub = ensureFrontendModelEventSubscription(this, frontendModelEventRequestContext(requestContext))
+    /** @type {FrontendModelDestroyEventCallbackEntry<never>} */
     const entry = {callback}
 
     return await sub.registerClassCallback(sub.classDestroyCallbacks, entry)
@@ -4001,7 +4027,7 @@ export default class FrontendModelBase {
    * instance's attributes are auto-merged with the broadcast payload
    * before the callback runs, so callers can read fresh values via
    * `this.someAttr()` without re-fetching.
-   * @param {(payload: {id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue, model: FrontendModelBase}) => void} callback - Event callback.
+   * @param {(payload: {id: EventPrimaryKeyValue, model: FrontendModelBase<Attributes, CreateAttributes, UpdateAttributes, PrimaryKeyValue, EventPrimaryKeyValue>}) => void} callback - Event callback.
    * @param {import("./query.js").FrontendModelEventOptions} [options] - Event query or record projection options.
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */
@@ -4030,7 +4056,7 @@ export default class FrontendModelBase {
 
   /**
    * Instance-level hook fired when THIS record is destroyed.
-   * @param {(payload: {id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue}) => void} callback - Event callback.
+   * @param {(payload: {id: EventPrimaryKeyValue}) => void} callback - Event callback.
    * @param {import("./query.js").FrontendModelEventOptions} [options] - Accepted for API symmetry; destroy events carry ids only.
    * @returns {Promise<() => void>} - Unsubscribe callback.
    */

package/src/frontend-models/event-hook-models.js

@@ -2,7 +2,7 @@
 
 /**
  * FrontendModelInstance type.
- * @typedef {import("./base.js").default} FrontendModelInstance */
+ * @typedef {InstanceType<import("./base.js").FrontendModelClass>} FrontendModelInstance */
 
 /**
  * Model dependency ids.

package/src/frontend-models/use-destroyed-event.js

@@ -13,13 +13,13 @@ import useModelClassEvent from "./use-model-class-event.js"
  * @typedef {import("./base.js").FrontendModelClass} FrontendModelClass */
 /**
  * FrontendModelInstance type.
- * @typedef {import("./base.js").default} FrontendModelInstance */
+ * @typedef {InstanceType<FrontendModelClass>} FrontendModelInstance */
 /**
  * FrontendModelClassDestroyEventPayload type.
  * @typedef {import("./use-model-class-event.js").FrontendModelDestroyEventPayload} FrontendModelClassDestroyEventPayload */
 /**
  * Defines this typedef.
- * @typedef {{id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue}} FrontendModelInstanceDestroyEventPayload */
+ * @typedef {{id: import("./base.js").FrontendModelEventPrimaryKeyValue}} FrontendModelInstanceDestroyEventPayload */
 /**
  * FrontendModelDestroyEventPayload type.
  * @typedef {FrontendModelClassDestroyEventPayload | FrontendModelInstanceDestroyEventPayload} FrontendModelDestroyEventPayload */

package/src/frontend-models/use-model-class-event.js

@@ -17,10 +17,10 @@ import {frontendModelRemoteRequestContextKey} from "./remote-request-context.js"
  * @typedef {"create" | "update" | "destroy"} FrontendModelClassEventName */
 /**
  * Defines this typedef.
- * @typedef {{id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue, model: FrontendModelInstance}} FrontendModelCreateUpdateEventPayload */
+ * @typedef {{id: import("./base.js").FrontendModelEventPrimaryKeyValue, model: FrontendModelInstance}} FrontendModelCreateUpdateEventPayload */
 /**
  * Defines this typedef.
- * @typedef {{id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue}} FrontendModelDestroyEventPayload */
+ * @typedef {{id: import("./base.js").FrontendModelEventPrimaryKeyValue}} FrontendModelDestroyEventPayload */
 /**
  * FrontendModelClassEventPayload type.
  * @typedef {FrontendModelCreateUpdateEventPayload | FrontendModelDestroyEventPayload} FrontendModelClassEventPayload */

package/src/frontend-models/use-updated-event.js

@@ -13,13 +13,13 @@ import useModelClassEvent from "./use-model-class-event.js"
  * @typedef {import("./base.js").FrontendModelClass} FrontendModelClass */
 /**
  * FrontendModelInstance type.
- * @typedef {import("./base.js").default} FrontendModelInstance */
+ * @typedef {InstanceType<FrontendModelClass>} FrontendModelInstance */
 /**
  * FrontendModelClassUpdateEventPayload type.
  * @typedef {import("./use-model-class-event.js").FrontendModelCreateUpdateEventPayload} FrontendModelClassUpdateEventPayload */
 /**
  * Defines this typedef.
- * @typedef {{id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue, model: FrontendModelInstance}} FrontendModelInstanceUpdateEventPayload */
+ * @typedef {{id: import("./base.js").FrontendModelEventPrimaryKeyValue, model: FrontendModelInstance}} FrontendModelInstanceUpdateEventPayload */
 /**
  * FrontendModelUpdateEventPayload type.
  * @typedef {FrontendModelClassUpdateEventPayload | FrontendModelInstanceUpdateEventPayload} FrontendModelUpdateEventPayload */

package/src/testing/browser-frontend-model-event-hook-scenarios.js

@@ -13,19 +13,23 @@ import wait from "awaitery/build/wait.js"
 /**
  * FrontendModelResourceConfig type.
  * @typedef {import("../frontend-models/base.js").FrontendModelResourceConfig} FrontendModelResourceConfig */
+/**
+ * FrontendModelClass type.
+ * @typedef {import("../frontend-models/base.js").FrontendModelClass} FrontendModelClass */
 /**
  * Defines this typedef.
- * @typedef {{id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue, model: FrontendModelBase}} FrontendModelHookTestCreateUpdatePayload */
+ * @typedef {{id: import("../frontend-models/base.js").FrontendModelEventPrimaryKeyValue, model: FrontendModelBase}} FrontendModelHookTestCreateUpdatePayload */
 /**
  * Defines this typedef.
- * @typedef {{id: string | import("../utils/model-primary-key.js").CompositeModelPrimaryKeyValue}} FrontendModelHookTestDestroyPayload */
+ * @typedef {{id: import("../frontend-models/base.js").FrontendModelEventPrimaryKeyValue}} FrontendModelHookTestDestroyPayload */
+/** @typedef {(payload: never) => void} ErasedFrontendModelHookCallback */
 /**
  * FakeSubscriptions type.
  * @typedef {object} FakeSubscriptions
- * @property {Set<(payload: FrontendModelHookTestCreateUpdatePayload) => void>} create - Create callbacks.
- * @property {Set<(payload: FrontendModelHookTestDestroyPayload) => void>} destroy - Destroy callbacks.
+ * @property {Set<ErasedFrontendModelHookCallback>} create - Heterogeneous create callbacks owned by the fake transport.
+ * @property {Set<ErasedFrontendModelHookCallback>} destroy - Heterogeneous destroy callbacks owned by the fake transport.
  * @property {{create: import("../frontend-models/query.js").FrontendModelEventOptionsObject[], destroy: import("../frontend-models/query.js").FrontendModelEventOptionsObject[], update: import("../frontend-models/query.js").FrontendModelEventOptionsObject[]}} options - Subscription options.
- * @property {Set<(payload: FrontendModelHookTestCreateUpdatePayload) => void>} update - Update callbacks.
+ * @property {Set<ErasedFrontendModelHookCallback>} update - Heterogeneous update callbacks owned by the fake transport.
  */
 
 /**
@@ -122,7 +126,9 @@ function buildFakeModelClass() {
 
     /**
      * Runs on create.
-     * @param {(payload: FrontendModelHookTestCreateUpdatePayload) => void} callback - Event callback.
+     * @template {FrontendModelClass} T
+     * @this {T}
+     * @param {(payload: {id: import("../frontend-models/base.js").FrontendModelEventPrimaryKeyValueFor<InstanceType<T>>, model: InstanceType<T>}) => void} callback - Event callback.
      * @param {import("../frontend-models/query.js").FrontendModelEventOptionsObject} [options] - Event query or projection options.
      * @returns {Promise<() => void>} - Unsubscribe callback.
      */
@@ -135,7 +141,7 @@ function buildFakeModelClass() {
 
     /**
      * Runs on destroy.
-     * @param {(payload: FrontendModelHookTestDestroyPayload) => void} callback - Event callback.
+     * @param {ErasedFrontendModelHookCallback} callback - Event callback stored by the heterogeneous fake transport.
      * @param {import("../frontend-models/query.js").FrontendModelEventOptionsObject} [options] - Event query or projection options.
      * @returns {Promise<() => void>} - Unsubscribe callback.
      */
@@ -148,7 +154,9 @@ function buildFakeModelClass() {
 
     /**
      * Runs on update.
-     * @param {(payload: FrontendModelHookTestCreateUpdatePayload) => void} callback - Event callback.
+     * @template {FrontendModelClass} T
+     * @this {T}
+     * @param {(payload: {id: import("../frontend-models/base.js").FrontendModelEventPrimaryKeyValueFor<InstanceType<T>>, model: InstanceType<T>}) => void} callback - Event callback.
      * @param {import("../frontend-models/query.js").FrontendModelEventOptionsObject} [options] - Event query or projection options.
      * @returns {Promise<() => void>} - Unsubscribe callback.
      */
@@ -173,7 +181,7 @@ function buildFakeModelClass() {
 function emitEvent(subscriptions, eventName, payload) {
   if (eventName === "destroy") {
     for (const callback of subscriptions.destroy) {
-      callback({id: payload.id})
+      /** @type {(event: FrontendModelHookTestDestroyPayload) => void} */ (callback)({id: payload.id})
     }
 
     return
@@ -184,7 +192,7 @@ function emitEvent(subscriptions, eventName, payload) {
   }
 
   for (const callback of subscriptions[eventName]) {
-    callback(payload)
+    /** @type {(event: FrontendModelHookTestCreateUpdatePayload) => void} */ (callback)(payload)
   }
 }