velocious 1.0.577 → 1.0.579

package/src/sync/sync-client-types.js

@@ -3,7 +3,7 @@
 /**
  * Client-declared sync scope serialized from a model query.
  * @typedef {object} SerializedSyncScope
- * @property {Record<string, ?>} conditions - Plain attribute conditions from the query.
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} conditions - Plain attribute conditions from the query.
  * @property {string | null} resourceType - Resource/model name the scope was declared for, or null for the all-types (user) scope covering every type the server authorizes for the caller.
  * @property {string} [owner] - Local partition key: the authenticated identity that declared the scope. Used only to partition the local scope/cursor store (never sent to the server as scope conditions), so a user scope's empty-conditions cursor does not leak across accounts on a shared device.
  */
@@ -14,21 +14,21 @@
  * @deprecated Declared pull scopes subscribe the framework sync channel automatically; keep this only for legacy app channels.
  * @typedef {object} ModelSyncRealtimeDeclaration
  * @property {string} channel - Server channel name to subscribe.
- * @property {Record<string, ?>} [params] - Static subscribe params. The framework injects `authenticationToken` automatically.
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} [params] - Static subscribe params. The framework injects `authenticationToken` automatically.
  */
 
 /**
  * Declarative per-resource sync policy.
  * @typedef {object} SyncClientResourceConfig
- * @property {?} modelClass - Local model class for this resource.
+ * @property {ReturnType<typeof JSON.parse>} modelClass - Local model class for this resource.
  * @property {import("./sync-api-client-types.js").SyncResourceConfig["attributes"]} [attributes] - Pull-apply attribute mapper. Required for resources that receive pulled changes.
  * @property {import("./sync-api-client-types.js").SyncResourceConfig["findRecord"]} [findRecord] - Custom pull-apply record resolver.
  * @property {import("./sync-api-client-types.js").SyncResourceConfig["findRecordForDelete"]} [findRecordForDelete] - Custom pull-apply delete resolver.
  * @property {import("./sync-api-client-types.js").SyncResourceConfig["afterApply"]} [afterApply] - Post-apply hook.
  * @property {string[]} [booleanAttributes] - Attributes coerced through sync boolean parsing when queueing.
  * @property {string[]} [localOnlyAttributes] - Attributes stripped from queued payloads.
- * @property {"upsert" | ((args: {operation: "create" | "update" | "destroy", record: ?}) => string)} [syncType] - Maps a mutation operation to a sync type. The "upsert" flag queues creates and updates as "update" rows (the server upserts by resource id) and destroys as "delete". Defaults to the operation name with destroy mapped to "delete".
- * @property {(args: {operation: "create" | "update" | "destroy", record: ?}) => Record<string, ?>} [trackedData] - Custom queued-payload builder for tracked mutations.
+ * @property {"upsert" | ((args: {operation: "create" | "update" | "destroy", record: ReturnType<typeof JSON.parse>}) => string)} [syncType] - Maps a mutation operation to a sync type. The "upsert" flag queues creates and updates as "update" rows (the server upserts by resource id) and destroys as "delete". Defaults to the operation name with destroy mapped to "delete".
+ * @property {(args: {operation: "create" | "update" | "destroy", record: ReturnType<typeof JSON.parse>}) => Record<string, ReturnType<typeof JSON.parse>>} [trackedData] - Custom queued-payload builder for tracked mutations.
  * @property {boolean | {operations: Array<"create" | "update" | "destroy">}} [track] - Automatic mutation tracking policy. On by default (creates and updates queue automatically); `false` opts the resource out, `true` adds destroys, `{operations}` narrows the tracked operations.
  * @property {ModelSyncRealtimeDeclaration} [realtime] - Deprecated: static legacy realtime channel this resource subscribes through `subscribeRealtime(...)`. Declared pull scopes subscribe the framework sync channel automatically.
  */
@@ -46,9 +46,9 @@
  * @property {import("./sync-api-client-types.js").SyncResourceConfig["findRecordForDelete"]} [findRecordForDelete] - Custom pull-apply delete resolver.
  * @property {string[]} [localOnlyAttributes] - Extra local-only attributes merged with the derived primary key, createdAt/updatedAt, and sync bookkeeping attributes.
  * @property {import("./sync-publisher-types.js").SyncPublishDeclaration<TModel>} [publish] - Server-side publish declaration consumed by `SyncPublisher.fromConfiguration(...)` on the backend; ignored by the client.
- * @property {"upsert" | ((args: {operation: "create" | "update" | "destroy", record: ?}) => string)} [syncType] - Sync type flag or mapper (see SyncClientResourceConfig).
+ * @property {"upsert" | ((args: {operation: "create" | "update" | "destroy", record: ReturnType<typeof JSON.parse>}) => string)} [syncType] - Sync type flag or mapper (see SyncClientResourceConfig).
  * @property {boolean | Array<"create" | "update" | "destroy"> | {operations: Array<"create" | "update" | "destroy">}} [track] - Automatic mutation tracking policy; an array is shorthand for {operations}. On by default (creates and updates queue automatically); `false` opts the model out (for models written by non-user flows), `true` adds destroys.
- * @property {(args: {operation: "create" | "update" | "destroy", record: ?}) => Record<string, ?>} [trackedData] - Custom queued-payload builder for tracked mutations.
+ * @property {(args: {operation: "create" | "update" | "destroy", record: ReturnType<typeof JSON.parse>}) => Record<string, ReturnType<typeof JSON.parse>>} [trackedData] - Custom queued-payload builder for tracked mutations.
  * @property {ModelSyncRealtimeDeclaration} [realtime] - Deprecated: static legacy realtime channel this resource subscribes through `subscribeRealtime(...)`. Declared pull scopes subscribe the framework sync channel automatically.
  */
 
@@ -74,7 +74,7 @@
  * @property {import("../configuration.js").default} [configuration] - Configuration owning the registered models, the `sync.client` block, and the scope-store database. Defaults to the current configuration.
  * @property {(args: {scope: SerializedSyncScope}) => string | null | Promise<string | null>} [legacyCursor] - Seeds a newly declared scope's cursor (e.g. from a pre-scope cursor store) so devices don't re-pull everything.
  * @property {import("./sync-scope-store.js").default} [scopeStore] - Scope store override (tests).
- * @property {?} [syncModel] - Pending-sync model override. Defaults to the registered "Sync" model.
+ * @property {ReturnType<typeof JSON.parse>} [syncModel] - Pending-sync model override. Defaults to the registered "Sync" model.
  */
 
 /**
@@ -88,10 +88,10 @@
  * @property {(args: {scope: SerializedSyncScope}) => string | null | Promise<string | null>} [legacyCursor] - Seeds a newly declared scope's cursor (e.g. from a pre-scope cursor store) so devices don't re-pull everything.
  * @property {(error: Error) => void} [onError] - Reports background replay/pull failures. Defaults to rethrowing.
  * @property {(payload: import("./sync-api-client-types.js").SyncChangesRequest & {scope: SerializedSyncScope}) => Promise<import("./sync-api-client-types.js").SyncChangesResponse>} postChanges - Posts one changes request.
- * @property {(payload: {authenticationToken: string, syncs: Array<Record<string, ?>>}) => Promise<import("./sync-api-client-types.js").SyncReplayResponse>} postReplay - Posts one replay request.
+ * @property {(payload: {authenticationToken: string, syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}) => Promise<import("./sync-api-client-types.js").SyncReplayResponse>} postReplay - Posts one replay request.
  * @property {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration} [realtime] - Realtime push configuration consumed by `subscribeRealtime(...)`.
  * @property {Record<string, SyncClientResourceConfig>} resources - Derived resource policies keyed by resource/model name.
- * @property {?} syncModel - Local pending-sync model class.
+ * @property {ReturnType<typeof JSON.parse>} syncModel - Local pending-sync model class.
  * @property {SyncClientSharedConnection} [websocketClient] - Shared app-lifetime websocket client instance (the low-level shared-connection form).
  * @property {string | (() => string | null | undefined)} [websocketUrl] - Shared app-lifetime websocket URL the framework builds a client from.
  */

package/src/sync/sync-client.js

@@ -119,12 +119,12 @@ export default class SyncClient {
     this._scheduledReplay = null
     /** @type {Record<string, import("./sync-api-client-types.js").SyncResourceConfig> | null} */
     this._pullResourceConfigs = null
-    /** @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._trackedCallbacks = []
     /** @type {WeakSet<object>} */
     this._remoteApplyRecords = new WeakSet()
     this._withoutTrackingDepth = 0
-    /** @type {Logger | {error: (...messages: Array<?>) => Promise<void>} | null} */
+    /** @type {Logger | {error: (...messages: Array<ReturnType<typeof JSON.parse>>) => Promise<void>} | null} */
     this._logger = null
     this._started = false
   }
@@ -207,7 +207,7 @@ export default class SyncClient {
    * Post-commit queue failures are reported without rethrowing into the
    * driver's afterCommit chain (see reportAfterCommitError).
    * @param {{operation: "create" | "update" | "destroy", resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig}} args - Operation and resource config.
-   * @returns {(record: ?) => Promise<void>} Lifecycle callback.
+   * @returns {(record: ReturnType<typeof JSON.parse>) => Promise<void>} Lifecycle callback.
    */
   trackedMutationCallback({operation, resourceConfig}) {
     return async (record) => {
@@ -265,7 +265,7 @@ export default class SyncClient {
 
   /**
    * Returns the lazily built client logger.
-   * @returns {Logger | {error: (...messages: Array<?>) => Promise<void>}} Client logger.
+   * @returns {Logger | {error: (...messages: Array<ReturnType<typeof JSON.parse>>) => Promise<void>}} Client logger.
    */
   logger() {
     this._logger ||= new Logger("SyncClient", {configuration: this.config.configuration})
@@ -275,7 +275,7 @@ export default class SyncClient {
 
   /**
    * Whether a record is currently being written by pull-apply (echo suppression).
-   * @param {?} record - Local model record.
+   * @param {ReturnType<typeof JSON.parse>} record - Local model record.
    * @returns {boolean} Whether the record write originates from a remote change.
    */
   isRemoteApply(record) {
@@ -287,7 +287,7 @@ export default class SyncClient {
    * either the record was marked as a remote apply (`markRemoteApply`, used by
    * pull and realtime applies) or a `withoutTracking` callback is running on
    * this client.
-   * @param {?} record - Local model record.
+   * @param {ReturnType<typeof JSON.parse>} record - Local model record.
    * @returns {boolean} Whether tracked queueing is suppressed for the record.
    */
   isTrackingSuppressed(record) {
@@ -321,7 +321,7 @@ export default class SyncClient {
    * Marks one record as being written from server-originated data so tracked
    * mutation queueing skips it (record-precise suppression). The derived pull
    * and realtime appliers use this internally around every applied write.
-   * @param {?} record - Local model record about to be written.
+   * @param {ReturnType<typeof JSON.parse>} record - Local model record about to be written.
    * @returns {() => void} Release callback re-enabling tracking for the record.
    */
   markRemoteApply(record) {
@@ -359,7 +359,7 @@ export default class SyncClient {
 
   /**
    * Declares (or re-activates) a sync scope from a model query and pulls it when online.
-   * @param {import("../database/query/model-class-query.js").default<?>} query - Query declaring the sync scope.
+   * @param {import("../database/query/model-class-query.js").default<ReturnType<typeof JSON.parse>>} query - Query declaring the sync scope.
    * @param {object} [options] - Sync options.
    * @param {(progress: import("./sync-api-client-types.js").SyncPullProgress) => void} [options.onProgress] - Called per applied page of the pull this declaration triggers, so the initial import of a newly declared scope can drive a "syncedCount of total" progress bar. See `pull()`.
    * @returns {Promise<{scope: import("./sync-client-types.js").SerializedSyncScope, pulled: import("./sync-api-client-types.js").SyncChangesResult | null}>} Declared scope and pull result (null while offline).
@@ -381,7 +381,7 @@ export default class SyncClient {
 
   /**
    * Deactivates the sync scope declared by a model query.
-   * @param {import("../database/query/model-class-query.js").default<?>} query - Query whose scope should stop syncing.
+   * @param {import("../database/query/model-class-query.js").default<ReturnType<typeof JSON.parse>>} query - Query whose scope should stop syncing.
    * @returns {Promise<void>}
    */
   async unsync(query) {
@@ -514,7 +514,7 @@ export default class SyncClient {
   /**
    * Subscribes the derived realtime channels so pushed websocket changes apply
    * through the same derived applier as pulls (idempotent, single-flighted).
-   * @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 subscribeRealtime(context) {
@@ -655,8 +655,8 @@ export default class SyncClient {
   /**
    * Queues a local model change as a pending sync row and schedules an immediate
    * replay attempt (kept pending while offline or when the backend rejects it).
-   * @param {{resource: ?, data?: Record<string, ?>, syncType?: string}} args - Queue args.
-   * @returns {Promise<?>} Pending local sync row.
+   * @param {{resource: ReturnType<typeof JSON.parse>, data?: Record<string, ReturnType<typeof JSON.parse>>, syncType?: string}} args - Queue args.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} Pending local sync row.
    */
   async queue({data, resource, syncType}) {
     const resourceConfig = this.resourceConfigFor(resource)
@@ -751,7 +751,7 @@ export default class SyncClient {
 
   /**
    * Resolves the declared resource config for a local record.
-   * @param {?} resource - Local model record.
+   * @param {ReturnType<typeof JSON.parse>} resource - Local model record.
    * @returns {import("./sync-client-types.js").SyncClientResourceConfig} Declared resource config.
    */
   resourceConfigFor(resource) {
@@ -773,7 +773,7 @@ export default class SyncClient {
    * Resolves the sync type for a mutation through the resource config. The
    * "upsert" flag queues creates and updates as "update" rows (the server
    * upserts by resource id) and destroys as "delete" rows.
-   * @param {{operation: "create" | "update" | "destroy", record: ?, resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig}} args - Mutation args.
+   * @param {{operation: "create" | "update" | "destroy", record: ReturnType<typeof JSON.parse>, resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig}} args - Mutation args.
    * @returns {string} Sync type.
    */
   defaultSyncType({operation, record, resourceConfig}) {
@@ -809,7 +809,7 @@ export default class SyncClient {
 /**
  * Builds one resource config from a model's `static sync` declaration plus its
  * derived column metadata.
- * @param {{declaration: import("./sync-client-types.js").ModelSyncDeclaration, modelClass: ?, resourceType: string}} args - Declaration args.
+ * @param {{declaration: import("./sync-client-types.js").ModelSyncDeclaration, modelClass: ReturnType<typeof JSON.parse>, resourceType: string}} args - Declaration args.
  * @returns {import("./sync-client-types.js").SyncClientResourceConfig} Derived resource config.
  */
 function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceType}) {
@@ -855,7 +855,7 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
  * Derives boolean and local-only attribute names from a model's column metadata:
  * booleans from boolean column types; local-only from the primary key,
  * createdAt/updatedAt, and sync bookkeeping columns.
- * @param {{modelClass: ?, resourceType: string}} args - Derivation args.
+ * @param {{modelClass: ReturnType<typeof JSON.parse>, resourceType: string}} args - Derivation args.
  * @returns {{booleanAttributes: string[], localOnlyAttributes: string[]}} Derived attribute names.
  */
 function derivedSyncAttributes({modelClass, resourceType}) {
@@ -921,7 +921,7 @@ function normalizedTrack(track) {
 /**
  * Builds a framework-owned sync endpoint POSTer over the configured transport.
  * @param {{path: string, transport: import("../configuration-types.js").VelociousSyncClientTransport}} args - Poster args.
- * @returns {(payload: Record<string, ?>) => Promise<?>} Sync endpoint POSTer.
+ * @returns {(payload: Record<string, ReturnType<typeof JSON.parse>>) => Promise<ReturnType<typeof JSON.parse>>} Sync endpoint POSTer.
  */
 function transportPoster({path, transport}) {
   return async (payload) => {
@@ -955,7 +955,7 @@ export function syncClient(configuration = Configuration.current()) {
 
 /**
  * Declares a sync scope on the current sync client.
- * @param {import("../database/query/model-class-query.js").default<?>} query - Query declaring the sync scope.
+ * @param {import("../database/query/model-class-query.js").default<ReturnType<typeof JSON.parse>>} query - Query declaring the sync scope.
  * @returns {Promise<{scope: import("./sync-client-types.js").SerializedSyncScope, pulled: import("./sync-api-client-types.js").SyncChangesResult | null}>} Declared scope and pull result.
  */
 export async function sync(query) {