velocious 1.0.430 → 1.0.431

package/src/frontend-models/transport-serialization.js

@@ -0,0 +1,369 @@
+// @ts-check
+
+import {resolveFrontendModelClass} from "./model-registry.js"
+import isPlainObject from "../utils/plain-object.js"
+
+const TYPE_KEY = "__velocious_type"
+const TYPE_DATE = "date"
+const TYPE_UNDEFINED = "undefined"
+const TYPE_BIGINT = "bigint"
+const TYPE_NUMBER = "number"
+const TYPE_FRONTEND_MODEL = "frontend_model"
+const NUMBER_NAN = "NaN"
+const NUMBER_POSITIVE_INFINITY = "Infinity"
+const NUMBER_NEGATIVE_INFINITY = "-Infinity"
+const PRELOADED_RELATIONSHIPS_KEY = "__preloadedRelationships"
+
+/**
+ * Assign a key to a plain object without triggering the `__proto__` setter.
+ * Uses `Object.defineProperty` so that keys like `__proto__` are stored as
+ * own data properties instead of mutating the object's prototype chain. This
+ * lets callers receive a regular `{}` object (with `Object.prototype` and a
+ * normal `constructor.name`) while still preventing prototype pollution.
+ * @param {Record<string, ?>} target - Target object.
+ * @param {string} key - Property key.
+ * @param {?} value - Property value.
+ * @returns {void}
+ */
+export function assignSafeProperty(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true
+  })
+}
+
+/**
+ * Runs is undefined marker.
+ * @param {?} value - Candidate value.
+ * @returns {boolean} - Whether value is encoded undefined marker.
+ */
+function isUndefinedMarker(value) {
+  if (!isPlainObject(value)) return false
+
+  const keys = Object.keys(value)
+
+  return keys.length === 1 && Object.prototype.hasOwnProperty.call(value, TYPE_KEY) && value[TYPE_KEY] === TYPE_UNDEFINED
+}
+
+/**
+ * Check whether a value is a typed marker object with a string `value` field.
+ * @param {?} value - Candidate marker.
+ * @param {string} markerType - Expected marker type value.
+ * @param {(stringValue: string) => boolean} valueMatches - Additional string value predicate.
+ * @returns {boolean} - Whether value matches the marker shape.
+ */
+function isStringValueMarker(value, markerType, valueMatches) {
+  if (!isPlainObject(value)) return false
+
+  const keys = Object.keys(value)
+
+  return (
+    keys.length === 2
+    && Object.prototype.hasOwnProperty.call(value, TYPE_KEY)
+    && Object.prototype.hasOwnProperty.call(value, "value")
+    && value[TYPE_KEY] === markerType
+    && typeof value.value === "string"
+    && valueMatches(value.value)
+  )
+}
+
+/**
+ * Runs is date marker.
+ * @param {?} value - Candidate value.
+ * @returns {boolean} - Whether value is encoded date marker.
+ */
+function isDateMarker(value) {
+  return isStringValueMarker(value, TYPE_DATE, () => true)
+}
+
+/**
+ * Runs is big int marker.
+ * @param {?} value - Candidate value.
+ * @returns {boolean} - Whether value is encoded bigint marker.
+ */
+function isBigIntMarker(value) {
+  return isStringValueMarker(value, TYPE_BIGINT, (stringValue) => /^-?\d+$/.test(stringValue))
+}
+
+/**
+ * Runs is non finite number marker.
+ * @param {?} value - Candidate value.
+ * @returns {boolean} - Whether value is encoded non-finite number marker.
+ */
+function isNonFiniteNumberMarker(value) {
+  if (!isPlainObject(value)) return false
+
+  const keys = Object.keys(value)
+  const markerValue = value.value
+
+  return (
+    keys.length === 2
+    && Object.prototype.hasOwnProperty.call(value, TYPE_KEY)
+    && Object.prototype.hasOwnProperty.call(value, "value")
+    && value[TYPE_KEY] === TYPE_NUMBER
+    && (markerValue === NUMBER_NAN || markerValue === NUMBER_POSITIVE_INFINITY || markerValue === NUMBER_NEGATIVE_INFINITY)
+  )
+}
+
+/**
+ * Runs is frontend model marker.
+ * @param {?} value - Candidate value.
+ * @returns {value is {__velocious_type: "frontend_model", attributes: Record<string, ?>, modelName: string, preloadedRelationships?: Record<string, ?>}} - Whether value is encoded frontend-model marker.
+ */
+function isFrontendModelMarker(value) {
+  if (!isPlainObject(value)) return false
+
+  const modelName = value.modelName
+  const attributes = value.attributes
+  const preloadedRelationships = value.preloadedRelationships
+
+  return (
+    Object.prototype.hasOwnProperty.call(value, TYPE_KEY)
+    && value[TYPE_KEY] === TYPE_FRONTEND_MODEL
+    && typeof modelName === "string"
+    && modelName.length > 0
+    && isPlainObject(attributes)
+    && (preloadedRelationships === undefined || isPlainObject(preloadedRelationships))
+  )
+}
+
+/**
+ * Runs the isBackendModelInstance helper.
+ * @param {?} value - Candidate value.
+ * @returns {value is {attributes: () => Record<string, ?>, constructor: {getModelName?: () => string, name?: string}, getModelClass: () => {getRelationshipsMap: () => Record<string, ?>}, getRelationshipByName: (relationshipName: string) => {getPreloaded: () => boolean, loaded: () => ?}}} - Whether value looks like a backend model instance.
+ */
+export function isBackendModelInstance(value) {
+  if (!value || typeof value !== "object") return false
+
+  const candidate = /**
+                     * Narrows the runtime value to the documented type.
+                      @type {Record<string, ?>} */ (value)
+
+  return (
+    typeof candidate.attributes === "function"
+    && typeof candidate.getModelClass === "function"
+    && typeof candidate.getRelationshipByName === "function"
+  )
+}
+
+/**
+ * Runs serialize frontend model transport value internal.
+ * @param {?} value - Value to serialize.
+ * @param {WeakSet<object>} seenModels - Models already visited in the current recursion path.
+ * @returns {?} - Serialized value with transport markers.
+ */
+function serializeFrontendModelTransportValueInternal(value, seenModels) {
+  if (value === undefined) {
+    return {[TYPE_KEY]: TYPE_UNDEFINED}
+  }
+
+  if (value instanceof Date) {
+    return {
+      [TYPE_KEY]: TYPE_DATE,
+      value: value.toISOString()
+    }
+  }
+
+  if (typeof value === "bigint") {
+    return {
+      [TYPE_KEY]: TYPE_BIGINT,
+      value: value.toString()
+    }
+  }
+
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    const markerValue = Number.isNaN(value)
+      ? NUMBER_NAN
+      : (value > 0 ? NUMBER_POSITIVE_INFINITY : NUMBER_NEGATIVE_INFINITY)
+
+    return {
+      [TYPE_KEY]: TYPE_NUMBER,
+      value: markerValue
+    }
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializeFrontendModelTransportValueInternal(entry, seenModels))
+  }
+
+  if (isBackendModelInstance(value)) {
+    const modelAttributes = value.attributes()
+    const modelClass = value.constructor
+    const modelName = typeof modelClass.getModelName === "function" ? modelClass.getModelName() : modelClass.name
+
+    /**
+     * Serialized model.
+      @type {Record<string, ?>} */
+    const serializedModel = {
+      [TYPE_KEY]: TYPE_FRONTEND_MODEL,
+      attributes: /**
+                   * Narrows the runtime value to the documented type.
+                    @type {Record<string, ?>} */ (serializeFrontendModelTransportValueInternal(modelAttributes, seenModels)),
+      modelName
+    }
+
+    if (seenModels.has(value)) {
+      return serializedModel
+    }
+
+    seenModels.add(value)
+
+    /**
+     * Preloaded relationships.
+      @type {Record<string, ?>} */
+    const preloadedRelationships = {}
+    const relationshipsMap = value.getModelClass().getRelationshipsMap()
+
+    for (const relationshipName of Object.keys(relationshipsMap)) {
+      const relationship = value.getRelationshipByName(relationshipName)
+
+      if (!relationship.getPreloaded()) continue
+
+      const loadedRelationship = relationship.loaded()
+
+      assignSafeProperty(preloadedRelationships, relationshipName, serializeFrontendModelTransportValueInternal(
+        loadedRelationship == undefined ? null : loadedRelationship,
+        seenModels
+      ))
+    }
+
+    seenModels.delete(value)
+
+    if (Object.keys(preloadedRelationships).length > 0) {
+      serializedModel.preloadedRelationships = preloadedRelationships
+    }
+
+    return serializedModel
+  }
+
+  if (isPlainObject(value)) {
+    /**
+     * Serialized.
+      @type {Record<string, ?>} */
+    const serialized = {}
+
+    for (const [key, nestedValue] of Object.entries(value)) {
+      assignSafeProperty(serialized, key, serializeFrontendModelTransportValueInternal(nestedValue, seenModels))
+    }
+
+    return serialized
+  }
+
+  return value
+}
+
+/**
+ * Runs deserialize frontend model marker.
+ * @param {{attributes: Record<string, ?>, modelName: string, preloadedRelationships?: Record<string, ?>}} marker - Encoded frontend-model marker.
+ * @returns {?} - Hydrated frontend model or plain object fallback.
+ */
+function deserializeFrontendModelMarker(marker) {
+  const attributes = /**
+                      * Narrows the runtime value to the documented type.
+                       @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(marker.attributes))
+  const preloadedRelationships = isPlainObject(marker.preloadedRelationships)
+    ? /**
+       * Narrows the runtime value to the documented type.
+        @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(marker.preloadedRelationships))
+    : {}
+  const modelClass = resolveFrontendModelClass(marker.modelName)
+
+  if (!modelClass || typeof modelClass.instantiateFromResponse !== "function") {
+    if (Object.keys(preloadedRelationships).length < 1) {
+      return attributes
+    }
+
+    return {
+      ...attributes,
+      [PRELOADED_RELATIONSHIPS_KEY]: preloadedRelationships
+    }
+  }
+
+  // Route hydration through `instantiateFromResponse` so
+  // `__abilities` / `__queryData` / `__associationCounts` /
+  // `__preloadedRelationships` baked into the marker's attributes blob (e.g.
+  // by `resource.serialize` in custom-command auto-serialization) get
+  // extracted and applied. Legacy markers that used a separate top-level
+  // `preloadedRelationships` field merge them under the standard key first
+  // so `modelDataFromResponse` picks them up.
+  const responseAttributes = Object.keys(preloadedRelationships).length > 0
+    ? {
+      ...attributes,
+      [PRELOADED_RELATIONSHIPS_KEY]: preloadedRelationships
+    }
+    : attributes
+
+  return modelClass.instantiateFromResponse(responseAttributes)
+}
+
+/**
+ * Runs the serializeFrontendModelTransportValue helper.
+ * @param {?} value - Value to serialize.
+ * @returns {?} - Serialized value with transport markers.
+ */
+export function serializeFrontendModelTransportValue(value) {
+  return serializeFrontendModelTransportValueInternal(value, new WeakSet())
+}
+
+/**
+ * Runs the deserializeFrontendModelTransportValue helper.
+ * @param {?} value - Value to deserialize.
+ * @returns {?} - Deserialized value with transport markers restored.
+ */
+export function deserializeFrontendModelTransportValue(value) {
+  if (isUndefinedMarker(value)) {
+    return undefined
+  }
+
+  if (isDateMarker(value)) {
+    const dateValue = /**
+                       * Narrows the runtime value to the documented type.
+                        @type {{value: string}} */ (value).value
+
+    return new Date(dateValue)
+  }
+
+  if (isBigIntMarker(value)) {
+    const bigintValue = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {{value: string}} */ (value).value
+
+    return BigInt(bigintValue)
+  }
+
+  if (isNonFiniteNumberMarker(value)) {
+    const numberValue = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {{value: string}} */ (value).value
+
+    if (numberValue === NUMBER_NAN) return Number.NaN
+    if (numberValue === NUMBER_POSITIVE_INFINITY) return Number.POSITIVE_INFINITY
+
+    return Number.NEGATIVE_INFINITY
+  }
+
+  if (isFrontendModelMarker(value)) {
+    return deserializeFrontendModelMarker(value)
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => deserializeFrontendModelTransportValue(entry))
+  }
+
+  if (isPlainObject(value)) {
+    /**
+     * Deserialized.
+      @type {Record<string, ?>} */
+    const deserialized = {}
+
+    for (const [key, nestedValue] of Object.entries(value)) {
+      assignSafeProperty(deserialized, key, deserializeFrontendModelTransportValue(nestedValue))
+    }
+
+    return deserialized
+  }
+
+  return value
+}

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

@@ -0,0 +1,21 @@
+// @ts-check
+
+import useModelClassEvent from "./use-model-class-event.js"
+
+/** @typedef {typeof import("./base.js").default} FrontendModelClass */
+/** @typedef {import("./use-model-class-event.js").FrontendModelCreateUpdateEventPayload} FrontendModelCreateEventPayload */
+/** @typedef {import("./use-model-class-event.js").UseModelClassEventOptions} UseCreatedEventOptions */
+/** @typedef {(payload: FrontendModelCreateEventPayload) => void} FrontendModelCreateEventCallback */
+
+/**
+ * React hook for frontend-model class create events.
+ * @param {FrontendModelClass | null | undefined} modelClass - Frontend model class.
+ * @param {FrontendModelCreateEventCallback} callback - Event callback.
+ * @param {UseCreatedEventOptions} [options] - Hook options.
+ * @returns {void}
+ */
+export default function useCreatedEvent(modelClass, callback, options = {}) {
+  useModelClassEvent(modelClass, "create", (payload) => {
+    callback(/** @type {FrontendModelCreateEventPayload} */ (payload))
+  }, options)
+}

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

@@ -0,0 +1,148 @@
+// @ts-check
+
+import debounceFunction from "debounce"
+import {useEffect, useMemo, useRef} from "react"
+
+import clearPendingDebouncedCallback from "./clear-pending-debounced-callback.js"
+import {modelsDependencyKey, modelsFromInput} from "./event-hook-models.js"
+import useModelClassEvent from "./use-model-class-event.js"
+
+/**
+ * FrontendModelClass type.
+  @typedef {typeof import("./base.js").default} FrontendModelClass */
+/**
+ * FrontendModelInstance type.
+  @typedef {import("./base.js").default} FrontendModelInstance */
+/**
+ * FrontendModelClassDestroyEventPayload type.
+  @typedef {import("./use-model-class-event.js").FrontendModelDestroyEventPayload} FrontendModelClassDestroyEventPayload */
+/**
+ * Defines this typedef.
+  @typedef {{id: string}} FrontendModelInstanceDestroyEventPayload */
+/**
+ * FrontendModelDestroyEventPayload type.
+  @typedef {FrontendModelClassDestroyEventPayload | FrontendModelInstanceDestroyEventPayload} FrontendModelDestroyEventPayload */
+/**
+ * UseDestroyedEventOptions type.
+  @typedef {import("./use-model-class-event.js").UseModelClassEventOptions} UseDestroyedEventOptions */
+/**
+ * FrontendModelDestroyEventCallback type.
+  @typedef {(payload: FrontendModelDestroyEventPayload) => void} FrontendModelDestroyEventCallback */
+
+/**
+ * Runs assert no unknown options.
+ * @param {Record<string, import("./query.js").FrontendModelTransportValue | (() => void) | undefined>} restOptions - Unknown options object.
+ * @returns {void}
+ */
+function assertNoUnknownOptions(restOptions) {
+  const unknownOptionNames = Object.keys(restOptions)
+
+  if (unknownOptionNames.length === 0) return
+
+  throw new Error(`Unknown options given to useDestroyedEvent: ${unknownOptionNames.join(", ")}`)
+}
+
+/**
+ * Runs event query dependency payload.
+ * @param {import("./query.js").default<FrontendModelClass> | undefined} query - Event query option.
+ * @returns {import("./query.js").FrontendModelEventOptionsPayload | null} Stable dependency payload.
+ */
+function eventQueryDependencyPayload(query) {
+  if (!query) return null
+
+  return query.eventOptionsPayload()
+}
+
+/**
+ * React hook for frontend-model destroy events. Pass a model class for class-level
+ * destroy events, or a model / model array for instance-level destroy events.
+ * @param {FrontendModelClass | FrontendModelInstance | FrontendModelInstance[] | null | undefined} modelClassOrModels - Model class, model, or models.
+ * @param {FrontendModelDestroyEventCallback} callback - Event callback.
+ * @param {UseDestroyedEventOptions} [options] - Hook options.
+ * @returns {void}
+ */
+export default function useDestroyedEvent(modelClassOrModels, callback, options = {}) {
+  const {active = true, abilities, debounce = false, onConnected, preload, query, queryData, select, selectsExtra, withCount, ...restOptions} = options
+  assertNoUnknownOptions(restOptions)
+
+  const classModel = typeof modelClassOrModels === "function" ? modelClassOrModels : null
+  const instanceModels = typeof modelClassOrModels === "function" ? null : modelClassOrModels
+  const projectionOptions = {abilities, preload, query, queryData, select, selectsExtra, withCount}
+
+  useModelClassEvent(classModel, "destroy", callback, {active: active && Boolean(classModel), debounce, onConnected, ...projectionOptions})
+  useInstanceDestroyedEvent(instanceModels, callback, {active: active && !classModel, debounce, onConnected, ...projectionOptions})
+}
+
+/**
+ * Runs use instance destroyed event.
+ * @param {FrontendModelInstance | FrontendModelInstance[] | null | undefined} modelOrModels - Model or models.
+ * @param {FrontendModelDestroyEventCallback} callback - Event callback.
+ * @param {UseDestroyedEventOptions} options - Hook options.
+ * @returns {void}
+ */
+function useInstanceDestroyedEvent(modelOrModels, callback, options) {
+  const {active = true, abilities, debounce = false, onConnected, preload, query, queryData, select, selectsExtra, withCount} = options
+  const projectionKey = JSON.stringify({abilities, preload, query: eventQueryDependencyPayload(query), queryData, select, selectsExtra, withCount})
+  const projectionOptionsRef = useRef({abilities, preload, query, queryData, select, selectsExtra, withCount})
+  const callbackRef = useRef(callback)
+  const activeRef = useRef(active)
+  projectionOptionsRef.current = {abilities, preload, query, queryData, select, selectsExtra, withCount}
+  callbackRef.current = callback
+  activeRef.current = active
+
+  const modelsKey = modelsDependencyKey(modelOrModels)
+  const eventCallback = useMemo(() => {
+    const wrappedCallback = (/**
+                              * Narrows the runtime value to the documented type.
+                               @type {FrontendModelInstanceDestroyEventPayload} */ payload) => {
+      if (activeRef.current) callbackRef.current(payload)
+    }
+
+    if (typeof debounce === "number") return debounceFunction(wrappedCallback, debounce)
+    if (debounce) return debounceFunction(wrappedCallback)
+
+    return wrappedCallback
+  }, [debounce])
+
+  useEffect(() => {
+    if (!active) return undefined
+
+    const models = modelsFromInput(modelOrModels)
+    if (models.length < 1) return undefined
+
+    let closed = false
+    /**
+     * Unsubscribe callbacks.
+      @type {Array<() => void>} */
+    const unsubscribeCallbacks = []
+    const subscriptionCallback = (/**
+                                   * Narrows the runtime value to the documented type.
+                                    @type {FrontendModelInstanceDestroyEventPayload} */ payload) => {
+      if (!closed) eventCallback(payload)
+    }
+
+    void (async () => {
+      for (const model of models) {
+        const unsubscribe = await model.onDestroy(subscriptionCallback, projectionOptionsRef.current)
+
+        if (closed) {
+          unsubscribe()
+        } else {
+          unsubscribeCallbacks.push(unsubscribe)
+        }
+      }
+
+      if (!closed && onConnected) onConnected()
+    })()
+
+    return () => {
+      closed = true
+
+      for (const unsubscribe of unsubscribeCallbacks) {
+        unsubscribe()
+      }
+
+      clearPendingDebouncedCallback(eventCallback)
+    }
+  }, [active, eventCallback, modelsKey, onConnected, projectionKey])
+}

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

@@ -0,0 +1,164 @@
+// @ts-check
+
+import debounceFunction from "debounce"
+import {useEffect, useMemo, useRef} from "react"
+
+import clearPendingDebouncedCallback from "./clear-pending-debounced-callback.js"
+
+/**
+ * FrontendModelClass type.
+  @typedef {typeof import("./base.js").default} FrontendModelClass */
+/**
+ * FrontendModelInstance type.
+  @typedef {InstanceType<FrontendModelClass>} FrontendModelInstance */
+/**
+ * FrontendModelClassEventName type.
+  @typedef {"create" | "update" | "destroy"} FrontendModelClassEventName */
+/**
+ * Defines this typedef.
+  @typedef {{id: string, model: FrontendModelInstance}} FrontendModelCreateUpdateEventPayload */
+/**
+ * Defines this typedef.
+  @typedef {{id: string}} FrontendModelDestroyEventPayload */
+/**
+ * FrontendModelClassEventPayload type.
+  @typedef {FrontendModelCreateUpdateEventPayload | FrontendModelDestroyEventPayload} FrontendModelClassEventPayload */
+/**
+ * FrontendModelClassEventCallback type.
+  @typedef {(payload: FrontendModelClassEventPayload) => void} FrontendModelClassEventCallback */
+/**
+ * Defines this typedef.
+  @typedef {{active?: boolean, debounce?: boolean | number, onConnected?: () => void} & import("./query.js").FrontendModelEventOptionsObject} UseModelClassEventOptions */
+
+/**
+ * Runs assert no unknown options.
+ * @param {Record<string, import("./query.js").FrontendModelTransportValue | (() => void) | undefined>} restOptions - Unknown options object.
+ * @returns {void}
+ */
+function assertNoUnknownOptions(restOptions) {
+  const unknownOptionNames = Object.keys(restOptions)
+
+  if (unknownOptionNames.length > 0) {
+    throw new Error(`Unknown options given to useModelClassEvent: ${unknownOptionNames.join(", ")}`)
+  }
+}
+
+/**
+ * Runs event query dependency payload.
+ * @param {import("./query.js").default<FrontendModelClass> | undefined} query - Event query option.
+ * @returns {import("./query.js").FrontendModelEventOptionsPayload | null} Stable dependency payload.
+ */
+function eventQueryDependencyPayload(query) {
+  if (!query) return null
+
+  return query.eventOptionsPayload()
+}
+
+/**
+ * Runs normalize event names.
+ * @param {FrontendModelClassEventName | FrontendModelClassEventName[]} eventOrEvents - Event name or names.
+ * @returns {FrontendModelClassEventName[]} - Normalized event names.
+ */
+function normalizeEventNames(eventOrEvents) {
+  return Array.isArray(eventOrEvents) ? eventOrEvents : [eventOrEvents]
+}
+
+/**
+ * Runs event names dependency key.
+ * @param {FrontendModelClassEventName[]} eventNames - Event names.
+ * @returns {string} - Stable dependency key.
+ */
+function eventNamesDependencyKey(eventNames) {
+  return eventNames.join("|")
+}
+
+/**
+ * Runs subscribe to model class event.
+ * @param {FrontendModelClass} modelClass - Frontend model class.
+ * @param {FrontendModelClassEventName} eventName - Event name.
+ * @param {FrontendModelClassEventCallback} callback - Event callback.
+ * @param {import("./query.js").FrontendModelEventOptionsObject} options - Event query or record projection options.
+ * @returns {Promise<() => void>} - Unsubscribe callback.
+ */
+async function subscribeToModelClassEvent(modelClass, eventName, callback, options) {
+  if (eventName === "create") return await modelClass.onCreate(callback, options)
+  if (eventName === "update") return await modelClass.onUpdate(callback, options)
+  if (eventName === "destroy") return await modelClass.onDestroy(callback, options)
+
+  throw new Error(`Unsupported frontend model class event: ${eventName}`)
+}
+
+/**
+ * React hook for frontend-model class lifecycle events.
+ * @param {FrontendModelClass | null | undefined} modelClass - Frontend model class.
+ * @param {FrontendModelClassEventName | FrontendModelClassEventName[]} eventOrEvents - Event name or names.
+ * @param {FrontendModelClassEventCallback} callback - Event callback.
+ * @param {UseModelClassEventOptions} [options] - Hook options.
+ * @returns {void}
+ */
+export default function useModelClassEvent(modelClass, eventOrEvents, callback, options = {}) {
+  const {active = true, abilities, debounce = false, onConnected, preload, query, queryData, select, selectsExtra, withCount, ...restOptions} = options
+  assertNoUnknownOptions(restOptions)
+
+  const projectionKey = JSON.stringify({abilities, preload, query: eventQueryDependencyPayload(query), queryData, select, selectsExtra, withCount})
+  const projectionOptionsRef = useRef({abilities, preload, query, queryData, select, selectsExtra, withCount})
+  const callbackRef = useRef(callback)
+  const activeRef = useRef(active)
+  projectionOptionsRef.current = {abilities, preload, query, queryData, select, selectsExtra, withCount}
+  callbackRef.current = callback
+  activeRef.current = active
+
+  const eventNames = normalizeEventNames(eventOrEvents)
+  const eventsKey = eventNamesDependencyKey(eventNames)
+  const eventCallback = useMemo(() => {
+    const wrappedCallback = (/**
+                              * Narrows the runtime value to the documented type.
+                               @type {FrontendModelClassEventPayload} */ payload) => {
+      if (activeRef.current) callbackRef.current(payload)
+    }
+
+    if (typeof debounce === "number") return debounceFunction(wrappedCallback, debounce)
+    if (debounce) return debounceFunction(wrappedCallback)
+
+    return wrappedCallback
+  }, [debounce])
+
+  useEffect(() => {
+    if (!active || !modelClass) return undefined
+
+    let closed = false
+    /**
+     * Unsubscribe callbacks.
+      @type {Array<() => void>} */
+    const unsubscribeCallbacks = []
+    const subscriptionCallback = (/**
+                                   * Narrows the runtime value to the documented type.
+                                    @type {FrontendModelClassEventPayload} */ payload) => {
+      if (!closed) eventCallback(payload)
+    }
+
+    void (async () => {
+      for (const eventName of eventNames) {
+        const unsubscribe = await subscribeToModelClassEvent(modelClass, eventName, subscriptionCallback, projectionOptionsRef.current)
+
+        if (closed) {
+          unsubscribe()
+        } else {
+          unsubscribeCallbacks.push(unsubscribe)
+        }
+      }
+
+      if (!closed && onConnected) onConnected()
+    })()
+
+    return () => {
+      closed = true
+
+      for (const unsubscribe of unsubscribeCallbacks) {
+        unsubscribe()
+      }
+
+      clearPendingDebouncedCallback(eventCallback)
+    }
+  }, [active, eventsKey, eventCallback, modelClass, onConnected, projectionKey])
+}