velocious 1.0.577 → 1.0.579

package/src/sync/sync-publisher.js

@@ -93,9 +93,9 @@ export default class SyncPublisher {
       resources[resourceConfig.resourceType] = resourceConfig
     }
 
-    /** @type {{actorForeignKeyColumn: string, broadcaster: import("./sync-publisher-types.js").SyncPublisherOptions["broadcaster"], configuration: Configuration, onError: import("./sync-publisher-types.js").SyncPublisherOptions["onError"], resources: Record<string, import("./sync-publisher-types.js").SyncPublisherResourceConfig>, syncModel: ?}} */
+    /** @type {{actorForeignKeyColumn: string, broadcaster: import("./sync-publisher-types.js").SyncPublisherOptions["broadcaster"], configuration: Configuration, onError: import("./sync-publisher-types.js").SyncPublisherOptions["onError"], resources: Record<string, import("./sync-publisher-types.js").SyncPublisherResourceConfig>, syncModel: ReturnType<typeof JSON.parse>}} */
     this.config = {actorForeignKeyColumn, broadcaster, configuration, onError, resources, syncModel: resolvedSyncModel}
-    /** @type {Array<{callback: (record: ?) => Promise<void>, callbackName: "afterCreate" | "afterUpdate" | "afterDestroy", modelClass: ?}>} */
+    /** @type {Array<{callback: (record: ReturnType<typeof JSON.parse>) => Promise<void>, callbackName: "afterCreate" | "afterUpdate" | "afterDestroy", modelClass: ReturnType<typeof JSON.parse>}>} */
     this._publishedCallbacks = []
     /** @type {Logger | null} */
     this._logger = null
@@ -183,7 +183,7 @@ export default class SyncPublisher {
    * publish failures are reported without rethrowing into the driver's
    * afterCommit chain (see reportAfterCommitError).
    * @param {{operation: "create" | "update" | "destroy", resourceConfig: import("./sync-publisher-types.js").SyncPublisherResourceConfig}} args - Operation and resource config.
-   * @returns {(record: ?) => Promise<void>} Lifecycle callback.
+   * @returns {(record: ReturnType<typeof JSON.parse>) => Promise<void>} Lifecycle callback.
    */
   publishedMutationCallback({operation, resourceConfig}) {
     return async (record) => {
@@ -193,7 +193,7 @@ export default class SyncPublisher {
       const resourceId = String(record.id())
       const syncType = operation === "destroy" ? "delete" : "update"
       const scopeValues = await this.publishedScopeValues({record, resourceConfig})
-      /** @type {Record<string, ?>} */
+      /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
       const attributes = {
         [this.config.actorForeignKeyColumn]: null,
         client_updated_at: new Date(),
@@ -241,7 +241,7 @@ export default class SyncPublisher {
    * the record's own id for scope-root models, or the deprecated resolver
    * function). The values are persisted onto the sync row's partition columns
    * and broadcast as the framework sync channel's scoping params.
-   * @param {{record: ?, resourceConfig: import("./sync-publisher-types.js").SyncPublisherResourceConfig}} args - Mutated record and resource config.
+   * @param {{record: ReturnType<typeof JSON.parse>, resourceConfig: import("./sync-publisher-types.js").SyncPublisherResourceConfig}} args - Mutated record and resource config.
    * @returns {Promise<{columns: Record<string, string | null>, params: Record<string, string | null>}>} Scope values keyed by sync-row column and by scope attribute.
    */
   async publishedScopeValues({record, resourceConfig}) {
@@ -251,7 +251,7 @@ export default class SyncPublisher {
     const params = {}
 
     for (const scopePlanEntry of resourceConfig.scopePlan) {
-      /** @type {?} */
+      /** @type {ReturnType<typeof JSON.parse>} */
       let rawValue
 
       if (scopePlanEntry.resolver) {
@@ -277,11 +277,11 @@ export default class SyncPublisher {
    * (id, server sequence, updated-at, and declared scope-partition attributes).
    * Uses the sync model's generated typed accessors and follows the
    * change-feed serializer's public field convention.
-   * @param {{data: Record<string, ?>, resourceConfig: import("./sync-publisher-types.js").SyncPublisherResourceConfig, resourceId: string, syncRow: ?, syncType: string}} args - Publish args.
-   * @returns {Record<string, ?>} Broadcast sync entry.
+   * @param {{data: Record<string, ReturnType<typeof JSON.parse>>, resourceConfig: import("./sync-publisher-types.js").SyncPublisherResourceConfig, resourceId: string, syncRow: ReturnType<typeof JSON.parse>, syncType: string}} args - Publish args.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Broadcast sync entry.
    */
   publishedSyncEntry({data, resourceConfig, resourceId, syncRow, syncType}) {
-    /** @type {Record<string, ?>} */
+    /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
     const entry = {
       data,
       id: syncRow.id(),
@@ -312,9 +312,9 @@ export default class SyncPublisher {
    * server-origin rows carry a null actor column (no device to echo the
    * change back to), so repeated server changes to one resource reuse and
    * re-sequence one feed row.
-   * @param {Record<string, ?>} attributes - Snapshotted sync row attributes.
-   * @param {?} syncModel - Operation-bound or static Sync model interface.
-   * @returns {Promise<?>} Upserted sync row.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} attributes - Snapshotted sync row attributes.
+   * @param {ReturnType<typeof JSON.parse>} syncModel - Operation-bound or static Sync model interface.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} Upserted sync row.
    */
   async upsertPublishedSyncRow(attributes, syncModel = this.config.syncModel) {
     const existingSync = await syncModel
@@ -386,7 +386,7 @@ export default class SyncPublisher {
  * Resolves a model class's active publish declaration from `static sync`.
  * Opted-out (`publish: false`) and undeclared models resolve to null; every
  * other declared value flows into loud declaration validation.
- * @param {?} modelClass - Registered model class.
+ * @param {ReturnType<typeof JSON.parse>} modelClass - Registered model class.
  * @returns {import("./sync-publisher-types.js").SyncPublishDeclaration | null} Active publish declaration, or null.
  */
 function publishDeclarationFor(modelClass) {
@@ -401,7 +401,7 @@ function publishDeclarationFor(modelClass) {
  * Builds one published resource config from a model's `static sync` publish
  * declaration. `publish: true` opts in with all defaults (attribute payload,
  * derived scope partition, created/updated operations).
- * @param {{modelClass: ?, publish: import("./sync-publisher-types.js").SyncPublishDeclaration | null, scopeAttributes: string[] | null, syncModel: ?}} args - Declaration args plus the sync model's declared scope attributes.
+ * @param {{modelClass: ReturnType<typeof JSON.parse>, publish: import("./sync-publisher-types.js").SyncPublishDeclaration | null, scopeAttributes: string[] | null, syncModel: ReturnType<typeof JSON.parse>}} args - Declaration args plus the sync model's declared scope attributes.
  * @returns {import("./sync-publisher-types.js").SyncPublisherResourceConfig} Derived resource config.
  */
 function resourceConfigFromPublishDeclaration({modelClass, publish, scopeAttributes: syncScopeAttributes, syncModel}) {
@@ -451,7 +451,7 @@ function resourceConfigFromPublishDeclaration({modelClass, publish, scopeAttribu
  * name map), or the record's own id when the model has no such attribute
  * (scope-root models). The deprecated `eventId` declaration forms map to a
  * fixed `eventId`/`event_id` plan for 1.0.503 compatibility.
- * @param {{eventId: import("./sync-publisher-types.js").SyncPublishDeclarationConfig["eventId"], modelClass: ?, modelName: string, scopeAttributes: Record<string, string> | undefined, syncModel: ?, syncScopeAttributes: string[] | null}} args - Declaration and sync-model scope args.
+ * @param {{eventId: import("./sync-publisher-types.js").SyncPublishDeclarationConfig["eventId"], modelClass: ReturnType<typeof JSON.parse>, modelName: string, scopeAttributes: Record<string, string> | undefined, syncModel: ReturnType<typeof JSON.parse>, syncScopeAttributes: string[] | null}} args - Declaration and sync-model scope args.
  * @returns {Array<import("./sync-publisher-types.js").SyncPublisherScopePlanEntry>} Derived scope plan.
  */
 function scopePlanFor({eventId, modelClass, modelName, scopeAttributes, syncModel, syncScopeAttributes}) {
@@ -512,7 +512,7 @@ function scopePlanFor({eventId, modelClass, modelName, scopeAttributes, syncMode
 
 /**
  * Resolves the sync-row column persisting a declared scope attribute.
- * @param {{scopeAttribute: string, syncModel: ?}} args - Scope attribute and sync model.
+ * @param {{scopeAttribute: string, syncModel: ReturnType<typeof JSON.parse>}} args - Scope attribute and sync model.
  * @returns {string} Sync-row column name.
  */
 function syncScopeColumnName({scopeAttribute, syncModel}) {
@@ -528,11 +528,11 @@ function syncScopeColumnName({scopeAttribute, syncModel}) {
 /**
  * Default publish serializer: the record's attributes with Date values
  * serialized to ISO strings.
- * @param {?} record - Mutated server model record.
- * @returns {Record<string, ?>} Serialized attributes payload.
+ * @param {ReturnType<typeof JSON.parse>} record - Mutated server model record.
+ * @returns {Record<string, ReturnType<typeof JSON.parse>>} Serialized attributes payload.
  */
 function defaultSerializedAttributes(record) {
-  /** @type {Record<string, ?>} */
+  /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
   const attributes = {...record.attributes()}
 
   for (const [attributeName, value] of Object.entries(attributes)) {

package/src/sync/sync-realtime-bridge.js

@@ -50,7 +50,7 @@ export default class SyncRealtimeBridge {
    * Subscribes the derived realtime channels (idempotent and single-flighted):
    * an active subscription is kept as-is and a concurrent subscribe awaits the
    * in-flight attempt. Call `unsubscribe()` first to change the context.
-   * @param {?} [context] - App context passed to the deprecated `sync.client.realtime.channels` callback (runtime scope values).
+   * @param {ReturnType<typeof JSON.parse>} [context] - App context passed to the deprecated `sync.client.realtime.channels` callback (runtime scope values).
    * @returns {Promise<void>}
    */
   async subscribe(context) {
@@ -72,7 +72,7 @@ export default class SyncRealtimeBridge {
    * Locally created resources are only promoted to the bridge once everything
    * is live; an unsubscribe arriving during any await marks this attempt stale
    * and it tears its own resources down instead of resubscribing.
-   * @param {?} context - App context passed to the channels callback.
+   * @param {ReturnType<typeof JSON.parse>} context - App context passed to the channels callback.
    * @returns {Promise<void>}
    */
   async _subscribe(context) {
@@ -251,7 +251,7 @@ export default class SyncRealtimeBridge {
    * `{resourceType, conditions}`), plus the deprecated legacy paths —
    * model-level static realtime declarations and the config channels callback.
    * Fails loudly when nothing is subscribable.
-   * @param {?} context - App context passed to the deprecated channels callback.
+   * @param {ReturnType<typeof JSON.parse>} context - App context passed to the deprecated channels callback.
    * @returns {Promise<Array<VelociousSyncRealtimeChannelDescriptor>>} Channel descriptors.
    */
   async channelDescriptors(context) {
@@ -301,8 +301,8 @@ export default class SyncRealtimeBridge {
    * The all-types (user) scope has no resource type and no conditions - it
    * covers everything the server authorizes for the caller - so there is
    * nothing to map.
-   * @param {{conditions: Record<string, ?>, resourceType: string | null}} scopeRow - Active scope row.
-   * @returns {Record<string, ?>} Attribute-named scope conditions.
+   * @param {{conditions: Record<string, ReturnType<typeof JSON.parse>>, resourceType: string | null}} scopeRow - Active scope row.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Attribute-named scope conditions.
    */
   attributeNamedConditions(scopeRow) {
     if (scopeRow.resourceType === null) return {}
@@ -314,7 +314,7 @@ export default class SyncRealtimeBridge {
     }
 
     const columnNameToAttributeName = resourceConfig.modelClass.getColumnNameToAttributeNameMap()
-    /** @type {Record<string, ?>} */
+    /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
     const conditions = {}
 
     for (const [conditionName, conditionValue] of Object.entries(scopeRow.conditions)) {
@@ -327,7 +327,7 @@ export default class SyncRealtimeBridge {
   /**
    * Chains one pushed message onto the serialized apply queue so changes apply
    * in arrival order; failures go to the sync client's error reporting.
-   * @param {{body: ?, resourceType: string | null}} args - Message args.
+   * @param {{body: ReturnType<typeof JSON.parse>, resourceType: string | null}} args - Message args.
    * @returns {void}
    */
   enqueueApply({body, resourceType}) {
@@ -344,7 +344,7 @@ export default class SyncRealtimeBridge {
    * Applies one pushed message through the derived resource applier: drops
    * own-device messages by echo origin, defaults the channel's resourceType onto
    * envelopes without one, and fails loudly on unknown resource types.
-   * @param {{body: ?, resourceType: string | null}} args - Message args.
+   * @param {{body: ReturnType<typeof JSON.parse>, resourceType: string | null}} args - Message args.
    * @returns {Promise<void>}
    */
   async applyMessage({body, resourceType}) {

package/src/sync/sync-replay-upsert-applier.js

@@ -7,7 +7,7 @@ import SyncApiClient from "./sync-api-client.js"
 /**
  * Coercers for the declarative sync field types. All are present-key based:
  * a field is only applied when its key exists in the mutation data.
- * @type {Record<string, (value: ?, label: string) => ?>}
+ * @type {Record<string, (value: ReturnType<typeof JSON.parse>, label: string) => ReturnType<typeof JSON.parse>>}
  */
 const FIELD_TYPES = {
   booleanOrNull: (value, label) => SyncApiClient.optionalBooleanSyncValue(value, label),
@@ -20,7 +20,7 @@ const FIELD_TYPES = {
 
 /**
  * Parses an optional date value, failing loudly on invalid input.
- * @param {?} value - Date, parseable string, or epoch number.
+ * @param {ReturnType<typeof JSON.parse>} value - Date, parseable string, or epoch number.
  * @param {string} label - Field label for error messages.
  * @returns {Date | null} Parsed date or null when absent.
  */
@@ -51,13 +51,13 @@ export default class SyncReplayUpsertApplier {
   /**
    * Creates a declarative upsert applier.
    * @param {object} args - Applier configuration.
-   * @param {?} args.modelClass - Model class receiving the mutations.
-   * @param {Record<string, string | {type: string, column?: string} | ((value: ?, label: string) => ?)>} args.fields - Data-key → field-type map: a named type, a {type, column} rename spec, "ignored" for accepted-but-dropped keys, or a custom coercer function.
-   * @param {(args: {data: Record<string, ?>, mutation: ?, context: Record<string, ?>}) => Promise<?>} [args.findRecord] - Custom record resolver. Defaults to findBy({id: mutation.resourceId}).
-   * @param {(args: {mutation: ?, context: Record<string, ?>}) => Promise<?>} [args.findRecordForDelete] - Custom delete resolver. Defaults to findRecord.
+   * @param {ReturnType<typeof JSON.parse>} args.modelClass - Model class receiving the mutations.
+   * @param {Record<string, string | {type: string, column?: string} | ((value: ReturnType<typeof JSON.parse>, label: string) => ReturnType<typeof JSON.parse>)>} args.fields - Data-key → field-type map: a named type, a {type, column} rename spec, "ignored" for accepted-but-dropped keys, or a custom coercer function.
+   * @param {(args: {data: Record<string, ReturnType<typeof JSON.parse>>, mutation: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>}) => Promise<ReturnType<typeof JSON.parse>>} [args.findRecord] - Custom record resolver. Defaults to findBy({id: mutation.resourceId}).
+   * @param {(args: {mutation: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>}) => Promise<ReturnType<typeof JSON.parse>>} [args.findRecordForDelete] - Custom delete resolver. Defaults to findRecord.
    * @param {"error" | "ignore"} [args.restArgs] - Unknown data-key handling. Defaults to "error".
-   * @param {(args: {mappedAttributes: Record<string, ?>, mutation: ?, context: Record<string, ?>, record: ?}) => Promise<Record<string, ?> | void>} [args.afterApply] - Domain tail; its returned object merges into the apply result.
-   * @param {(args: {mutation: ?, context: Record<string, ?>, record: ?}) => Promise<Record<string, ?>> | Record<string, ?>} [args.serialize] - Snapshot serializer; result lands on applyResult.serializedData.
+   * @param {(args: {mappedAttributes: Record<string, ReturnType<typeof JSON.parse>>, mutation: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>, record: ReturnType<typeof JSON.parse>}) => Promise<Record<string, ReturnType<typeof JSON.parse>> | void>} [args.afterApply] - Domain tail; its returned object merges into the apply result.
+   * @param {(args: {mutation: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>, record: ReturnType<typeof JSON.parse>}) => Promise<Record<string, ReturnType<typeof JSON.parse>>> | Record<string, ReturnType<typeof JSON.parse>>} [args.serialize] - Snapshot serializer; result lands on applyResult.serializedData.
    */
   constructor({afterApply, fields, findRecord, findRecordForDelete, modelClass, restArgs = "error", serialize}) {
     if (!modelClass) throw new Error("SyncReplayUpsertApplier requires a modelClass")
@@ -87,8 +87,8 @@ export default class SyncReplayUpsertApplier {
 
   /**
    * Applies one normalized replay mutation to the declared model.
-   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, mutation: ?}} args - Replay apply arguments.
-   * @returns {Promise<Record<string, ?>>} Apply result with the record, created/deleted flags, optional serializedData, and afterApply extras.
+   * @param {{actor: ReturnType<typeof JSON.parse>, context: Record<string, ReturnType<typeof JSON.parse>>, existingSync: ReturnType<typeof JSON.parse>, mutation: ReturnType<typeof JSON.parse>}} args - Replay apply arguments.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} Apply result with the record, created/deleted flags, optional serializedData, and afterApply extras.
    */
   async apply({context, mutation}) {
     if (mutation.syncType === "delete") return await this.applyDelete({context, mutation})
@@ -97,7 +97,7 @@ export default class SyncReplayUpsertApplier {
     const record = this.findRecord
       ? await this.findRecord({context, data: mutation.data, mutation})
       : await this.modelClass.findBy({id: mutation.resourceId})
-    /** @type {Record<string, ?>} */
+    /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
     const result = {created: false, deleted: false, record: null}
 
     if (record) {
@@ -122,8 +122,8 @@ export default class SyncReplayUpsertApplier {
 
   /**
    * Applies a delete mutation to the declared model.
-   * @param {{context: Record<string, ?>, mutation: ?}} args - Delete arguments.
-   * @returns {Promise<Record<string, ?>>} Apply result with the deleted flag.
+   * @param {{context: Record<string, ReturnType<typeof JSON.parse>>, mutation: ReturnType<typeof JSON.parse>}} args - Delete arguments.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} Apply result with the deleted flag.
    */
   async applyDelete({context, mutation}) {
     const resolveRecord = this.findRecordForDelete || this.findRecord
@@ -140,11 +140,11 @@ export default class SyncReplayUpsertApplier {
 
   /**
    * Maps present data keys through the declared field types.
-   * @param {Record<string, ?>} data - Normalized mutation data.
-   * @returns {Record<string, ?>} Coerced attributes keyed by column name.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} data - Normalized mutation data.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Coerced attributes keyed by column name.
    */
   mappedAttributes(data) {
-    /** @type {Record<string, ?>} */
+    /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
     const mappedAttributes = {}
     /** @type {string[]} */
     const unknownKeys = []

package/src/sync/sync-resource-base.js

@@ -10,7 +10,7 @@ import VelociousError from "../velocious-error.js"
 /**
  * Optional client-declared sync scope carried on a changes request.
  * @typedef {object} SerializedChangesScope
- * @property {Record<string, ?>} conditions - Plain attribute conditions from the client query.
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} conditions - Plain attribute conditions from the client query.
  * @property {string | null} resourceType - Client resource/model name the scope was declared for, or null for the all-types (user) scope: one scope covering every resource type this resource authorizes for the caller, so a sync authorizes once however many types it serves.
  * @property {string[] | null} resourceTypes - For the all-types scope, the resource types the client can apply. A cheap delivery/type filter only - it narrows, never widens, what the app's authorization already allows. Null for a type-declared scope.
  */
@@ -23,7 +23,7 @@ import VelociousError from "../velocious-error.js"
  * `resourceType` normalized to strings. Apps authorizing by exact-row
  * identity read the extra fields; overrides that only read
  * `resourceId`/`resourceType` keep working unchanged.
- * @typedef {Record<string, ?> & {resourceId: string, resourceType: string}} ChangeDeliverableSyncEntry
+ * @typedef {Record<string, ReturnType<typeof JSON.parse>> & {resourceId: string, resourceType: string}} ChangeDeliverableSyncEntry
  */
 const QUICK_SEARCH_COLUMN = "quickSearch"
 
@@ -108,7 +108,7 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
 
   /**
    * Returns a stable change-feed page after app authorization.
-   * @returns {Promise<Record<string, ?>>} Change-feed page result.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} Change-feed page result.
    */
   async changes() {
     const params = this.params()
@@ -121,7 +121,7 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
 
   /**
    * Replays client sync envelopes through the app replay service.
-   * @returns {Promise<Record<string, ?>>} Replay result with per-sync states.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} Replay result with per-sync states.
    */
   async replay() {
     const result = await this.buildReplayService().replay(this.params())
@@ -133,7 +133,7 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
 
   /**
    * Parses the optional client-declared scope from request params.
-   * @param {Record<string, ?>} params - Request params.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Request params.
    * @returns {SerializedChangesScope | null} Parsed scope, or null when the client sent none.
    */
   changesScope(params) {
@@ -145,7 +145,7 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
       throw new Error(`Sync changes scope must be an object, got: ${String(scope)}`)
     }
 
-    const scopeParams = /** @type {Record<string, ?>} */ (scope)
+    const scopeParams = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (scope)
     const resourceType = scopeParams.resourceType === null || scopeParams.resourceType === undefined
       ? null
       : forcedNonBlankString(scopeParams.resourceType, "resourceType")
@@ -156,12 +156,12 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
       throw new Error(`Sync changes scope.conditions must be an object, got: ${String(conditions)}`)
     }
 
-    return {conditions: /** @type {Record<string, ?>} */ (conditions), resourceType, resourceTypes}
+    return {conditions: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (conditions), resourceType, resourceTypes}
   }
 
   /**
    * Parses the optional resource-type list an all-types scope declares.
-   * @param {?} value - Raw `scope.resourceTypes` param.
+   * @param {ReturnType<typeof JSON.parse>} value - Raw `scope.resourceTypes` param.
    * @returns {string[] | null} Declared resource types, or null when the client sent none.
    */
   changesScopeResourceTypes(value) {
@@ -174,8 +174,8 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
 
   /**
    * Builds the change-feed service serving this changes request.
-   * @param {{params: Record<string, ?>, scope: SerializedChangesScope | null}} args - Request params and parsed scope.
-   * @returns {{changes: () => Promise<Record<string, ?>>}} Change-feed service.
+   * @param {{params: Record<string, ReturnType<typeof JSON.parse>>, scope: SerializedChangesScope | null}} args - Request params and parsed scope.
+   * @returns {{changes: () => Promise<Record<string, ReturnType<typeof JSON.parse>>>}} Change-feed service.
    */
   changeFeedService({params, scope}) {
     return new SyncModelChangeFeedService({
@@ -206,7 +206,7 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
 
   /**
    * Returns constructor args for the app replay service.
-   * @returns {Record<string, ?>} Replay service constructor args.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Replay service constructor args.
    */
   replayServiceArgs() {
     return {}
@@ -226,7 +226,7 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
 
   /**
    * Authorizes the current context for reading the requested changes.
-   * @param {{params: Record<string, ?>, scope: SerializedChangesScope | null}} _args - Request params and parsed scope.
+   * @param {{params: Record<string, ReturnType<typeof JSON.parse>>, scope: SerializedChangesScope | null}} _args - Request params and parsed scope.
    * @returns {Promise<void>} Resolves when access is allowed; throws otherwise.
    */
   async authorizeChanges(_args) {
@@ -235,7 +235,7 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
 
   /**
    * Applies app visibility scoping onto the change-feed query.
-   * @param {{params: Record<string, ?>, query: import("../database/query/model-class-query.js").default, scope: SerializedChangesScope | null}} _args - Request params, feed query, and parsed scope.
+   * @param {{params: Record<string, ReturnType<typeof JSON.parse>>, query: import("../database/query/model-class-query.js").default, scope: SerializedChangesScope | null}} _args - Request params, feed query, and parsed scope.
    * @returns {void}
    */
   scopeChangesQuery(_args) {
@@ -258,7 +258,7 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
    * can authorize concurrent targeted and shared broadcasts for the same
    * resource identity independently by their exact-row identity. The channel
    * never mutates the published entry; normalization happens on a copy.
-   * @param {{params: Record<string, ?>, scope: SerializedChangesScope | null, sync: ChangeDeliverableSyncEntry}} args - Request params, subscription scope, and the published sync entry.
+   * @param {{params: Record<string, ReturnType<typeof JSON.parse>>, scope: SerializedChangesScope | null, sync: ChangeDeliverableSyncEntry}} args - Request params, subscription scope, and the published sync entry.
    * @returns {Promise<boolean>} Whether the change may be delivered to this subscription.
    */
   async changeDeliverable({params, scope, sync}) {

package/src/sync/sync-scope-attributes.js

@@ -10,7 +10,7 @@
  * published sync row and broadcasts them as the framework sync channel's
  * scoping params, and the change feed serializes them onto every changes row
  * under their own names. Velocious itself has no built-in partition name.
- * @param {?} syncModel - Sync/change model class.
+ * @param {ReturnType<typeof JSON.parse>} syncModel - Sync/change model class.
  * @returns {string[] | null} Declared scope attributes, or null when the model declares none.
  */
 export function declaredSyncScopeAttributes(syncModel) {

package/src/sync/sync-scope-store.js

@@ -8,7 +8,7 @@ import stableJsonStringify from "./stable-json.js"
 
 /**
  * @typedef {object} SyncScopeRow
- * @property {Record<string, ?>} conditions - Scope attribute conditions.
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} conditions - Scope attribute conditions.
  * @property {string | null} cursorPayload - Persisted cursor JSON payload.
  * @property {string} id - Scope row id.
  * @property {string | null} resourceType - Scope resource/model name, or null for the all-types (user) scope.
@@ -159,7 +159,7 @@ export default class SyncScopeStore {
     }
 
     return await this._withDb(async (db) => {
-      const rows = /** @type {Array<Record<string, ?>>} */ (await db
+      const rows = /** @type {Array<Record<string, ReturnType<typeof JSON.parse>>>} */ (await db
         .newQuery()
         .from(TABLE_NAME)
         .where({state: "active"})
@@ -300,7 +300,7 @@ export default class SyncScopeStore {
    * @returns {Promise<SyncScopeRow | null>} Scope row or null.
    */
   async _rowByScopeDigest(db, digest) {
-    const rows = /** @type {Array<Record<string, ?>>} */ (await db
+    const rows = /** @type {Array<Record<string, ReturnType<typeof JSON.parse>>>} */ (await db
       .newQuery()
       .from(TABLE_NAME)
       .where({scope_digest: digest})
@@ -312,12 +312,12 @@ export default class SyncScopeStore {
 
   /**
    * Normalizes a raw scope table row.
-   * @param {Record<string, ?>} row - Raw table row.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} row - Raw table row.
    * @returns {SyncScopeRow} Normalized scope row.
    */
   _normalizeScopeRow(row) {
     return {
-      conditions: /** @type {Record<string, ?>} */ (JSON.parse(String(row.conditions_json))),
+      conditions: /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (JSON.parse(String(row.conditions_json))),
       cursorPayload: row.cursor_json === null || row.cursor_json === undefined ? null : String(row.cursor_json),
       id: String(row.id),
       resourceType: String(row.resource_type) === "" ? null : String(row.resource_type),

package/src/sync/sync-websocket-channel.js

@@ -126,7 +126,7 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
     if (!scope) return false
 
     const scopingParams = broadcastParams && typeof broadcastParams === "object" && !Array.isArray(broadcastParams)
-      ? /** @type {Record<string, ?>} */ (broadcastParams)
+      ? /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (broadcastParams)
       : {}
 
     if (!Object.hasOwn(scopingParams, "resourceType")) return false
@@ -198,12 +198,12 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
   async _userScopeDeliverableBody(body) {
     if (!body || typeof body !== "object" || Array.isArray(body)) return null
 
-    const envelope = /** @type {Record<string, ?>} */ (body)
+    const envelope = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (body)
     const scope = /** @type {import("./sync-resource-base.js").SerializedChangesScope} */ (this._scope)
-    /** @type {Array<Record<string, ?>>} */
+    /** @type {Array<Record<string, ReturnType<typeof JSON.parse>>>} */
     const syncs = Array.isArray(envelope.syncs) ? envelope.syncs : [envelope]
     const configuration = this.session.configuration
-    /** @type {Array<Record<string, ?>>} */
+    /** @type {Array<Record<string, ReturnType<typeof JSON.parse>>>} */
     const deliverableSyncs = []
 
     // Broadcast fan-out runs through `withoutCurrentConnectionContexts` (see
@@ -246,7 +246,7 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
 
   /**
    * Returns the authorized scope for debug snapshots.
-   * @returns {Record<string, ?>} Debug-safe subscription details.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} Debug-safe subscription details.
    */
   debugSnapshot() {
     return {scope: this._scope, userScope: this._isUserScope()}

package/src/tenants/default-tenant-database-provisioning.js

@@ -64,7 +64,7 @@ function maintenanceConnection(databaseConfiguration, configuration) {
 
 /**
  * Creates the tenant database for one tenant.
- * @param {{configuration: import("../configuration.js").default, databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, identifier?: string, tenant: ?}} args - Provisioning arguments.
+ * @param {{configuration: import("../configuration.js").default, databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, identifier?: string, tenant: ReturnType<typeof JSON.parse>}} args - Provisioning arguments.
  * @returns {Promise<void>} - Resolves once the tenant database exists.
  */
 export async function createTenantDatabase({configuration, databaseConfiguration, identifier, tenant}) {

package/src/tenants/tenant-aggregator.js

@@ -13,7 +13,7 @@ import Current from "../current.js"
 /**
  * @typedef {object} SubqueryContext
  * @property {(tableName: string) => string} table - Quotes a table for this tenant. In a cross-database `UNION ALL` it returns a `database`.`table` qualified identifier; when each tenant runs on its own connection it returns the plain quoted table name. Use it for every table the subquery reads so the same subquery works on both execution paths.
- * @property {((value: ?) => string) & {list: (values: Array<?>) => string}} quote - Quotes a value for the active connection. `quote.list(values)` quotes and comma-joins an array for `IN (...)` clauses.
+ * @property {((value: ReturnType<typeof JSON.parse>) => string) & {list: (values: Array<ReturnType<typeof JSON.parse>>) => string}} quote - Quotes a value for the active connection. `quote.list(values)` quotes and comma-joins an array for `IN (...)` clauses.
  * @property {object} tenant - The tenant descriptor this subquery is being built for.
  * @property {import("../database/drivers/base.js").default} connection - The driver the query will run on.
  */
@@ -22,7 +22,7 @@ import Current from "../current.js"
  * @typedef {object} TenantAggregateOptions
  * @property {string} identifier - Database identifier whose tenants are aggregated (for example `"projectTenant"`).
  * @property {object[]} [tenants] - Explicit tenant descriptors to aggregate. Defaults to every tenant the identifier's provider `listTenants` returns.
- * @property {(tenant: ?) => boolean} [filter] - Optional filter applied to the resolved tenant list.
+ * @property {(tenant: ReturnType<typeof JSON.parse>) => boolean} [filter] - Optional filter applied to the resolved tenant list.
  * @property {string[]} [keyColumns] - Columns the aggregate is grouped by (for example `["docker_server_id"]`). Empty means a single grand-total row.
  * @property {Record<string, AggregateSpec>} aggregates - Output column name to aggregate. `"SUM"` is shorthand for `{op: "SUM", column: <output name>}`; use `{op: "COUNT", column: "*"}` for `COUNT(*)`.
  * @property {AbortSignal} [signal] - Signal passed to each aggregate database query.
@@ -61,14 +61,14 @@ export default class TenantAggregator {
 
   /**
    * Resolves the tenant list, runs the aggregate per server, and merges everything.
-   * @returns {Promise<Array<Record<string, ?>>>} - One merged row per distinct key-column combination.
+   * @returns {Promise<Array<Record<string, ReturnType<typeof JSON.parse>>>>} - One merged row per distinct key-column combination.
    */
   async run() {
     const resolvedTenants = await this._resolveTenants()
 
     if (resolvedTenants.length === 0) return []
 
-    /** @type {Array<Record<string, ?>>} */
+    /** @type {Array<Record<string, ReturnType<typeof JSON.parse>>>} */
     const rows = []
 
     for (const group of this._groupByServer(resolvedTenants)) {
@@ -157,7 +157,7 @@ export default class TenantAggregator {
    * connection scope that is released before the fan-out runs, so a `max: 1` tenant pool is never
    * asked for a second connection while the first is still held (which would deadlock).
    * @param {ResolvedTenant[]} group - Tenants sharing one server.
-   * @returns {Promise<Array<Record<string, ?>>>} - Rows produced for this server.
+   * @returns {Promise<Array<Record<string, ReturnType<typeof JSON.parse>>>>} - Rows produced for this server.
    */
   async _runForServer(group) {
     const [firstTenant] = group
@@ -174,7 +174,7 @@ export default class TenantAggregator {
       })
     }
 
-    /** @type {Array<Record<string, ?>>} */
+    /** @type {Array<Record<string, ReturnType<typeof JSON.parse>>>} */
     const rows = []
 
     for (const resolvedTenant of group) {
@@ -244,11 +244,11 @@ export default class TenantAggregator {
    * treated as "no contribution" and skipped, not coerced to `0` — otherwise an empty tenant would
    * drag a `MAX` of negatives or a `MIN` of positives to `0`. A key whose every tenant contributed
    * `NULL` stays `NULL`, matching SQL aggregate semantics over no rows.
-   * @param {Array<Record<string, ?>>} rows - Rows collected from all servers/tenants.
-   * @returns {Array<Record<string, ?>>} - One merged row per distinct key-column combination.
+   * @param {Array<Record<string, ReturnType<typeof JSON.parse>>>} rows - Rows collected from all servers/tenants.
+   * @returns {Array<Record<string, ReturnType<typeof JSON.parse>>>} - One merged row per distinct key-column combination.
    */
   _mergeRows(rows) {
-    /** @type {Map<string, Record<string, ?>>} */
+    /** @type {Map<string, Record<string, ReturnType<typeof JSON.parse>>>} */
     const merged = new Map()
 
     for (const row of rows) {
@@ -303,7 +303,7 @@ export default class TenantAggregator {
    * `bigint`) as strings; an integer beyond `Number.MAX_SAFE_INTEGER` cannot be represented exactly
    * as a JS number, so cross-server merging would corrupt the result — throw instead. (Fractional
    * `DECIMAL`/`NUMERIC` values are still subject to normal floating-point representation.)
-   * @param {?} rawValue - Value returned by the driver for an aggregate column.
+   * @param {ReturnType<typeof JSON.parse>} rawValue - Value returned by the driver for an aggregate column.
    * @returns {number} - The value as a number.
    */
   _toExactNumber(rawValue) {
@@ -319,12 +319,12 @@ export default class TenantAggregator {
   /**
    * Builds the value quoter passed to subqueries, with a `.list` helper for `IN (...)` clauses.
    * @param {import("../database/drivers/base.js").default} connection - Driver whose quoting is used.
-   * @returns {((value: ?) => string) & {list: (values: Array<?>) => string}} - Value quoter with a `.list` helper.
+   * @returns {((value: ReturnType<typeof JSON.parse>) => string) & {list: (values: Array<ReturnType<typeof JSON.parse>>) => string}} - Value quoter with a `.list` helper.
    */
   _buildQuote(connection) {
     return Object.assign(
-      (/** @type {?} */ value) => String(connection.quote(value)),
-      {list: (/** @type {Array<?>} */ values) => values.map((value) => String(connection.quote(value))).join(", ")}
+      (/** @type {ReturnType<typeof JSON.parse>} */ value) => String(connection.quote(value)),
+      {list: (/** @type {Array<ReturnType<typeof JSON.parse>>} */ values) => values.map((value) => String(connection.quote(value))).join(", ")}
     )
   }