velocious 1.0.488 → 1.0.492

package/build/sync/query-scope.js

@@ -0,0 +1,84 @@
+// @ts-check
+
+import stableJsonStringify from "./stable-json.js"
+
+/**
+ * Serializes a model query into a transportable sync scope.
+ *
+ * Only plain attribute equality conditions are supported: the scope must be
+ * expressible as `{resourceType, conditions}` so servers can match it against
+ * their change feeds. Anything else (raw SQL, negations, joins, orders,
+ * limits, offsets, groups) fails loudly.
+ * @param {import("../database/query/model-class-query.js").default<?>} query - Model query declaring the sync scope.
+ * @returns {import("./sync-client-types.js").SerializedSyncScope} Serialized sync scope.
+ */
+export function serializedScopeFromQuery(query) {
+  if (query.getJoins().length > 0) throw new Error("sync(query) does not support joins")
+  if (query.getOrders().length > 0) throw new Error("sync(query) does not support orders")
+  if (query.getLimit() !== null && query.getLimit() !== undefined) throw new Error("sync(query) does not support limit")
+  if (query.getOffset() !== null && query.getOffset() !== undefined) throw new Error("sync(query) does not support offset")
+  if (query.getGroups().length > 0) throw new Error("sync(query) does not support groups")
+
+  const modelClass = query.getModelClass()
+  const conditions = /** @type {Record<string, ?>} */ ({})
+
+  for (const where of query.getWheres()) {
+    const whereHash = /** @type {{hash?: Record<string, ?>}} */ (where).hash
+
+    if (!whereHash || typeof whereHash !== "object" || Array.isArray(whereHash) || /** @type {{where?: ?}} */ (where).where) {
+      throw new Error(`sync(query) only supports plain attribute conditions, got: ${where.constructor.name}`)
+    }
+
+    for (const [attributeName, value] of Object.entries(whereHash)) {
+      const conditionValue = scalarConditionValue(attributeName, value)
+
+      if (attributeName in conditions && stableJsonStringify(conditions[attributeName]) !== stableJsonStringify(conditionValue)) {
+        throw new Error(`sync(query) got conflicting conditions for: ${attributeName}`)
+      }
+
+      conditions[attributeName] = conditionValue
+    }
+  }
+
+  return {conditions, resourceType: modelClass.getModelName()}
+}
+
+/**
+ * Returns a stable canonical key identifying a sync scope.
+ * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
+ * @returns {string} Stable scope key.
+ */
+export function scopeKey(scope) {
+  return `${scope.resourceType}:${stableJsonStringify(scope.conditions)}`
+}
+
+/**
+ * Validates one scope condition value as a scalar or array of scalars.
+ * @param {string} attributeName - Condition attribute name for error messages.
+ * @param {?} value - Condition value.
+ * @returns {?} Validated condition value.
+ */
+function scalarConditionValue(attributeName, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) validateScalar(attributeName, item)
+
+    return value
+  }
+
+  validateScalar(attributeName, value)
+
+  return value
+}
+
+/**
+ * Validates one scalar condition value.
+ * @param {string} attributeName - Condition attribute name for error messages.
+ * @param {?} value - Condition value.
+ * @returns {void}
+ */
+function validateScalar(attributeName, value) {
+  if (value === null) return
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return
+
+  throw new Error(`sync(query) condition values must be scalar, got ${typeof value} for: ${attributeName}`)
+}

package/build/sync/server-change-feed.js

@@ -2,6 +2,7 @@
 
 import {randomUUID} from "crypto"
 import TableData from "../database/table-data/index.js"
+import stableJsonStringify from "./stable-json.js"
 
 const DEFAULT_RETENTION_SIZE = 10000
 const DEFAULT_PAGE_SIZE = 100
@@ -464,31 +465,6 @@ function scopesEqual(changeScope, requestedScope) {
   return stableJsonStringify(changeScope || null) === stableJsonStringify(requestedScope)
 }
 
-/**
- * Stable JSON serialization for persisted sync scopes.
- * @param {?} value - JSON-compatible value.
- * @returns {string} - Stable JSON representation.
- */
-function stableJsonStringify(value) {
-  return JSON.stringify(stableJsonValue(value))
-}
-
-/**
- * Produces a recursively key-sorted JSON value.
- * @param {?} value - JSON-compatible value.
- * @returns {?} - Stable JSON-compatible value.
- */
-function stableJsonValue(value) {
-  if (Array.isArray(value)) return value.map((item) => stableJsonValue(item))
-  if (!value || typeof value !== "object") return value
-
-  return Object.keys(value).sort().reduce((memo, key) => {
-    memo[key] = stableJsonValue(value[key])
-
-    return memo
-  }, /** @type {Record<string, ?>} */ ({}))
-}
-
 /**
  * @typedef {object} ServerChangeFeedEntry
  * @property {string | null} actorDeviceId - Signed mutation actor device id when available.

package/build/sync/stable-json.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+/**
+ * Serializes a JSON-compatible value with recursively sorted object keys, so
+ * equal values always produce byte-identical strings (used for sync scope and
+ * change-feed identity comparisons).
+ * @param {?} value - JSON-compatible value.
+ * @returns {string} - Stable JSON string.
+ */
+export default function stableJsonStringify(value) {
+  return JSON.stringify(stableJsonValue(value))
+}
+
+/**
+ * Produces a recursively key-sorted JSON value.
+ * @param {?} value - JSON-compatible value.
+ * @returns {?} - Stable JSON-compatible value.
+ */
+function stableJsonValue(value) {
+  if (Array.isArray(value)) return value.map((item) => stableJsonValue(item))
+  if (!value || typeof value !== "object") return value
+
+  return Object.keys(value).sort().reduce((memo, key) => {
+    memo[key] = stableJsonValue(value[key])
+
+    return memo
+  }, /** @type {Record<string, ?>} */ ({}))
+}

package/build/sync/sync-api-client.js

@@ -1,6 +1,8 @@
 // @ts-check
 
-import {optionalInteger} from "typanic"
+import {optionalBoolean, optionalInteger} from "typanic"
+
+const syncTaskPromises = new Map()
 
 /** @typedef {import("./sync-api-client-types.js").SyncChangeApplyResult} SyncChangeApplyResult */
 /** @typedef {import("./sync-api-client-types.js").SyncChangeEnvelope} SyncChangeEnvelope */
@@ -18,6 +20,81 @@ import {optionalInteger} from "typanic"
  * persistence/auth hooks.
  */
 export default class SyncApiClient {
+  /**
+   * Serializes sync work with the same key so callers do not have to keep app-local locks.
+   * @param {string} key - Lock key.
+   * @param {() => Promise<void>} callback - Work to run once previous work finished.
+   * @returns {Promise<void>}
+   */
+  static async singleFlight(key, callback) {
+    while (syncTaskPromises.has(key)) {
+      try {
+        await syncTaskPromises.get(key)
+      } catch (_error) {
+        // The failed flight's own caller observes that rejection; callers queued
+        // behind it still run their own work so pending rows retry after the lock clears.
+      }
+    }
+
+    const promise = callback()
+    syncTaskPromises.set(key, promise)
+
+    try {
+      await promise
+    } finally {
+      if (syncTaskPromises.get(key) === promise) syncTaskPromises.delete(key)
+    }
+  }
+
+  /**
+   * Pulls backend sync changes with a framework-managed cursor row.
+   * @param {object} args - Pull args.
+   * @param {string} args.authenticationToken - Auth token to send with change requests.
+   * @param {number} [args.batchSize] - Max syncs per request.
+   * @param {?} args.cursorModel - Model that responds to findBy/findOrInitializeBy for cursor persistence.
+   * @param {string} args.cursorKey - Cursor option key.
+   * @param {(payload: SyncChangesRequest) => Promise<SyncChangesResponse>} args.postChanges - Posts one changes request.
+   * @param {Record<string, SyncResourceConfig>} args.resources - Resource policies.
+   * @param {(progress: {pages: number, syncedCount: number}) => void} [args.onProgress] - Progress callback.
+   * @returns {Promise<SyncChangesResult>} Pull result.
+   */
+  static async pullChangesWithCursor(args) {
+    return await this.pullChanges({
+      authenticationToken: args.authenticationToken,
+      batchSize: args.batchSize,
+      loadCursor: async () => await this.loadSyncCursor({cursorKey: args.cursorKey, cursorModel: args.cursorModel}),
+      saveCursor: async (cursor) => await this.saveSyncCursor({cursor, cursorKey: args.cursorKey, cursorModel: args.cursorModel}),
+      postChanges: args.postChanges,
+      applySync: this.resourceApplier(args.resources),
+      onProgress: args.onProgress
+    })
+  }
+
+  /**
+   * Loads a persisted sync cursor from a model row with a value column.
+   * @param {{cursorKey: string, cursorModel: ?}} args - Cursor args.
+   * @returns {Promise<string | null>} Persisted cursor payload.
+   */
+  static async loadSyncCursor({cursorKey, cursorModel}) {
+    const option = await cursorModel.findBy({key: cursorKey})
+
+    return option ? option.value() : null
+  }
+
+  /**
+   * Saves a persisted sync cursor to a model row with a value column.
+   * @param {{cursor: SyncCursor, cursorKey: string, cursorModel: ?}} args - Cursor args.
+   * @returns {Promise<void>}
+   */
+  static async saveSyncCursor({cursor, cursorKey, cursorModel}) {
+    if (!cursor) return
+
+    const option = await cursorModel.findOrInitializeBy({key: cursorKey})
+
+    option.assign({value: JSON.stringify(cursor)})
+    if (option.isChanged()) await option.save()
+  }
+
   /**
    * Pulls backend sync changes in stable pages, applies them locally, and stores
    * the acknowledged cursor. Apps provide only auth, persistence, transport, and
@@ -183,43 +260,49 @@ export default class SyncApiClient {
    * mechanics stay here; apps only declare which models/attributes/hooks are
    * allowed for each resource type.
    * @param {Record<string, SyncResourceConfig>} resources - Resource policy map.
+   * @param {(record: ?) => () => void} [onRecord] - Called with each record about to be written; returns a release callback invoked after the write (used for echo suppression).
    * @returns {(sync: SyncChangeEnvelope) => Promise<SyncChangeApplyResult>} Sync apply callback.
    */
-  static resourceApplier(resources) {
-    return async (sync) => await this.applyResourceSync({resources, sync})
+  static resourceApplier(resources, onRecord) {
+    return async (sync) => await this.applyResourceSync({onRecord, resources, sync})
   }
 
   /**
    * Applies one sync row using declarative resource policy.
-   * @param {{resources: Record<string, SyncResourceConfig>, sync: SyncChangeEnvelope}} args - Apply args.
+   * @param {{resources: Record<string, SyncResourceConfig>, sync: SyncChangeEnvelope, onRecord?: (record: ?) => () => void}} args - Apply args.
    * @returns {Promise<SyncChangeApplyResult>} Apply result.
    */
-  static async applyResourceSync({resources, sync}) {
+  static async applyResourceSync({onRecord, resources, sync}) {
     const resourceType = sync.resourceType()
     const resource = resourceType ? resources[resourceType] : undefined
 
     if (!resource || !resource.enabled) return {changed: false, resourceType}
 
     if (sync.syncType() === "delete") {
-      return {changed: await this.destroySyncedResource({resource, sync}), resourceType}
+      return {changed: await this.destroySyncedResource({onRecord, resource, sync}), resourceType}
     }
 
     const data = this.syncData(sync)
     const record = resource.findRecord ? await resource.findRecord({data, resourceId: sync.resourceId(), sync}) : await resource.modelClass.findOrInitializeBy({id: data.id ?? sync.resourceId()})
     const attributes = await resource.attributes({data, record, sync})
+    const releaseRecord = onRecord ? onRecord(record) : null
     let changed = false
 
-    record.assign(attributes)
+    try {
+      record.assign(attributes)
 
-    if (record.isChanged()) {
-      await record.save()
-      changed = true
-    }
+      if (record.isChanged()) {
+        await record.save()
+        changed = true
+      }
 
-    if (resource.afterApply) {
-      const hookChanged = await resource.afterApply({attributes, data, record, sync})
+      if (resource.afterApply) {
+        const hookChanged = await resource.afterApply({attributes, data, record, sync})
 
-      changed ||= hookChanged === true
+        changed ||= hookChanged === true
+      }
+    } finally {
+      if (releaseRecord) releaseRecord()
     }
 
     return {changed, resourceType}
@@ -227,16 +310,23 @@ export default class SyncApiClient {
 
   /**
    * Destroys a synced resource via its declared model policy.
-   * @param {{resource: SyncResourceConfig, sync: SyncChangeEnvelope}} args - Destroy args.
+   * @param {{resource: SyncResourceConfig, sync: SyncChangeEnvelope, onRecord?: (record: ?) => () => void}} args - Destroy args.
    * @returns {Promise<boolean>} Whether a local row was destroyed.
    */
-  static async destroySyncedResource({resource, sync}) {
+  static async destroySyncedResource({onRecord, resource, sync}) {
     const id = sync.resourceId()
     const record = resource.findRecordForDelete ? await resource.findRecordForDelete({resourceId: id, sync}) : await resource.modelClass.findBy({id})
 
     if (!record) return false
 
-    await record.destroy()
+    const releaseRecord = onRecord ? onRecord(record) : null
+
+    try {
+      await record.destroy()
+    } finally {
+      if (releaseRecord) releaseRecord()
+    }
+
     return true
   }
 
@@ -255,6 +345,230 @@ export default class SyncApiClient {
     throw new Error(`Sync ${sync.id()} has invalid data`)
   }
 
+  /**
+   * Drains pending sync records from a local Velocious model in stable order.
+   * @param {object} args - Replay args.
+   * @param {string} args.authenticationToken - Auth token to send with replay requests.
+   * @param {number} [args.batchSize] - Max syncs per request.
+   * @param {?} args.syncModel - Local Sync model class.
+   * @param {(payload: {authenticationToken: string, syncs: Array<Record<string, ?>>}) => Promise<SyncReplayResponse>} args.postReplay - Replay poster.
+   * @returns {Promise<void>}
+   */
+  static async replayLocalSyncs(args) {
+    const postedSnapshotsBySyncId = new Map()
+
+    await this.replayPending({
+      authenticationToken: args.authenticationToken,
+      batchSize: args.batchSize,
+      markSuccessful: async (sync) => {
+        const syncId = (/** @type {{id: () => string | number | null | undefined}} */ (sync)).id()
+        // Reload with the resource preloaded so rows relying on the resource-attributes
+        // fallback in localSyncData compare against the same snapshot they posted.
+        const currentSync = await args.syncModel.preload({resource: true}).where({id: syncId}).first()
+
+        if (!currentSync) return
+        // A row edited while its old payload was in flight stays pending, so the
+        // newer local change replays on the next drain instead of being lost.
+        if (this.localSyncReplaySnapshot(currentSync) !== postedSnapshotsBySyncId.get(String(syncId))) return
+
+        await currentSync.update({state: "success"})
+      },
+      pendingSyncs: async () => await args.syncModel.preload({resource: true}).where({state: "pending"}).order("created_at").toArray(),
+      postReplay: args.postReplay,
+      syncId: (sync) => (/** @type {{id: () => string | number | null | undefined}} */ (sync)).id(),
+      syncPayload: (sync) => {
+        postedSnapshotsBySyncId.set(String((/** @type {{id: () => string | number | null | undefined}} */ (sync)).id()), this.localSyncReplaySnapshot(sync))
+
+        return this.localSyncPayload(sync)
+      }
+    })
+  }
+
+  /**
+   * Serializes the replay-relevant state of a local sync row for in-flight comparisons.
+   * @param {?} sync - Local sync row.
+   * @returns {string} Stable snapshot of the row's replayed payload.
+   */
+  static localSyncReplaySnapshot(sync) {
+    return JSON.stringify({data: this.localSyncData(sync), syncType: sync.syncType()})
+  }
+
+  /**
+   * Builds one replay envelope from a local sync row.
+   * @param {?} sync - Local sync row.
+   * @returns {{clientUpdatedAt?: string, data: Record<string, unknown>, id: number, resourceId: string, resourceType: string, syncType: string}} Sync replay envelope.
+   */
+  static localSyncPayload(sync) {
+    const clientUpdatedAt = sync.updatedAt() || sync.createdAt()
+
+    return {
+      clientUpdatedAt: clientUpdatedAt ? clientUpdatedAt.toISOString() : undefined,
+      data: this.localSyncData(sync),
+      id: /** @type {number} */ (/** @type {unknown} */ (sync.id())),
+      resourceId: String(sync.resourceId()),
+      resourceType: sync.resourceType() || "",
+      syncType: sync.syncType()
+    }
+  }
+
+  /**
+   * Resolves one local sync row payload, falling back to preloaded resource attributes.
+   * @param {?} sync - Local sync row.
+   * @returns {Record<string, unknown>} Sync data.
+   */
+  static localSyncData(sync) {
+    let syncData = /** @type {string | Record<string, unknown>} */ (sync.data() || {})
+
+    if (typeof syncData === "string") {
+      try {
+        syncData = /** @type {Record<string, unknown>} */ (JSON.parse(syncData))
+      } catch (_error) {
+        syncData = {}
+      }
+    }
+
+    if (Object.keys(syncData).length > 0) return syncData
+
+    try {
+      return /** @type {Record<string, unknown>} */ (sync.resource().attributes())
+    } catch (_error) {
+      return {}
+    }
+  }
+
+  /**
+   * Queues a local sync row for a Velocious model resource.
+   * @param {object} args - Queue args.
+   * @param {?} args.resource - Resource being synced.
+   * @param {?} args.syncModel - Local Sync model class.
+   * @param {Record<string, unknown>} [args.data] - Explicit sync data.
+   * @param {string} [args.syncType] - Sync operation type.
+   * @param {string[]} [args.localOnlyAttributes] - Attributes to strip from queued payloads.
+   * @param {string[]} [args.booleanAttributes] - Attributes to coerce through sync boolean parsing.
+   * @param {(data: Record<string, unknown>) => Record<string, unknown>} [args.normalizeData] - App-specific data normalizer.
+   * @returns {Promise<?>} Local sync row.
+   */
+  static async queueLocalSync(args) {
+    const resourceRecordId = args.resource.id()
+    const modelClass = args.resource.constructor
+
+    if (typeof modelClass.getModelName !== "function") {
+      throw new Error("The resource model class must implement static getModelName() to queue sync data - class names are not stable across explicit model names and minified bundles")
+    }
+
+    const resourceType = modelClass.getModelName()
+    const syncData = this.queuedSyncData(args)
+    const syncType = args.syncType || "update"
+
+    if (!resourceRecordId) throw new Error("resource.id() is required to queue sync data")
+
+    const resourceId = String(resourceRecordId)
+    const existingSync = await args.syncModel.findBy({resourceId, resourceType})
+
+    if (existingSync) {
+      await existingSync.update({
+        data: syncData,
+        state: "pending",
+        syncType
+      })
+
+      return existingSync
+    }
+
+    return await args.syncModel.create({
+      data: syncData,
+      resourceId,
+      resourceType,
+      state: "pending",
+      syncType
+    })
+  }
+
+  /**
+   * Builds backend-safe queued sync data without mutating caller data.
+   * @param {{resource: ?, data?: Record<string, unknown>, localOnlyAttributes?: string[], booleanAttributes?: string[], normalizeData?: (data: Record<string, unknown>) => Record<string, unknown>}} args - Data args.
+   * @returns {Record<string, unknown>} Queued data.
+   */
+  static queuedSyncData(args) {
+    const inputData = args.data ?? /** @type {Record<string, unknown>} */ (args.resource.attributes())
+    const normalizedData = args.normalizeData ? args.normalizeData(inputData) : inputData
+    const syncData = {...normalizedData}
+
+    for (const attributeName of args.localOnlyAttributes || []) delete syncData[attributeName]
+    for (const attributeName of args.booleanAttributes || []) {
+      if (Object.hasOwn(syncData, attributeName)) syncData[attributeName] = this.optionalBooleanSyncValue(syncData[attributeName], attributeName)
+    }
+
+    return syncData
+  }
+
+  /**
+   * Builds a small app-facing local sync queue facade from declarative model config.
+   * @param {object} args - Queue config.
+   * @param {?} args.syncModel - Local Sync model class.
+   * @param {string} args.singleFlightKey - Key used to serialize backend replay.
+   * @param {() => Promise<void>} args.syncPending - Backend replay callback.
+   * @param {(resource: ?) => string[]} [args.localOnlyAttributes] - Resource-specific local-only attributes.
+   * @param {(resource: ?) => string[]} [args.booleanAttributes] - Resource-specific SQLite boolean attributes.
+   * @returns {{queue: (queueArgs: {resource: ?, data?: Record<string, unknown>, syncType?: string}) => Promise<?>, syncPending: () => Promise<void>}} Configured local sync queue.
+   */
+  static localSyncQueue(args) {
+    return {
+      queue: async (queueArgs) => await this.queueLocalSync({
+        ...queueArgs,
+        booleanAttributes: args.booleanAttributes ? args.booleanAttributes(queueArgs.resource) : [],
+        localOnlyAttributes: args.localOnlyAttributes ? args.localOnlyAttributes(queueArgs.resource) : [],
+        syncModel: args.syncModel
+      }),
+      syncPending: async () => await this.singleFlight(args.singleFlightKey, args.syncPending)
+    }
+  }
+
+  /**
+   * Parses booleans commonly used by SQLite/offline sync payloads.
+   * @param {unknown} value - Sync decision value.
+   * @param {string} [description] - Error context.
+   * @returns {boolean | null} Parsed boolean-like backend/local value.
+   */
+  static optionalBooleanSyncValue(value, description = "sync boolean") {
+    if (value == null) return null
+    if (value === 1) return true
+    if (value === 0) return false
+
+    return optionalBoolean(value, description)
+  }
+
+  /**
+   * Converts a boolean sync value to SQLite boolean storage.
+   * @param {boolean | null} value - Sync boolean value.
+   * @returns {0 | 1} SQLite-compatible boolean value.
+   */
+  static sqliteBooleanSyncValue(value) {
+    return value === true ? 1 : 0
+  }
+
+  /**
+   * Projects generic sync counters into app-specific result keys.
+   * @param {object} args - Result args.
+   * @param {SyncChangesResult} args.result - Generic Velocious sync result.
+   * @param {Record<string, {changedKey: string, countKey: string}>} args.resources - Resource result key map.
+   * @returns {Record<string, unknown>} Projected result.
+   */
+  static syncResultForResources({result, resources}) {
+    const syncResult = /** @type {Record<string, unknown>} */ ({
+      changed: result.changed,
+      pages: result.pages,
+      syncedCount: result.syncedCount
+    })
+
+    for (const [resourceType, keys] of Object.entries(resources)) {
+      syncResult[keys.countKey] = result.resourceCounts[resourceType] || 0
+      syncResult[keys.changedKey] = result.resourceChanged[resourceType] || false
+    }
+
+    return syncResult
+  }
+
   /**
    * Drains pending sync records in stable order and marks acknowledged rows.
    * @param {object} args - Replay args.

package/build/sync/sync-api-controller.js

@@ -3,6 +3,9 @@
 import Controller from "../controller.js"
 import FrontendModelBaseResource from "../frontend-model-resource/base-resource.js"
 
+/** Configurations whose sync.api routes have already been mounted. */
+const mountedConfigurations = new WeakSet()
+
 /**
  * Generic `/velocious/sync` transport controller.
  *
@@ -99,6 +102,23 @@ export default class SyncApiController extends Controller {
     })
   }
 
+  /**
+   * Auto-mounts the sync endpoints configured through `sync.api` on a configuration.
+   * No-op when `sync.api` is absent; guarded so repeated server boots with the
+   * same configuration register the routes only once.
+   * @param {import("../configuration.js").default} configuration - Configuration instance.
+   * @returns {void}
+   */
+  static mountFromConfiguration(configuration) {
+    const api = configuration.getSyncConfiguration().api
+
+    if (!api || mountedConfigurations.has(configuration)) return
+
+    mountedConfigurations.add(configuration)
+
+    this.mountInto({at: api.mountPath, configuration, syncResourceClass: api.resourceClass})
+  }
+
   /**
    * Normalizes a sync mount path.
    * @param {string} at - Mount path.

package/build/sync/sync-client-registry.js

@@ -0,0 +1,30 @@
+// @ts-check
+
+/**
+ * Registry for the app's current sync client.
+ *
+ * Kept dependency-free so client-bundled modules (like the query layer) can
+ * delegate to a configured sync client without importing the sync stack.
+ */
+
+/** @type {?} */
+let currentClient = null
+
+/**
+ * Registers the current sync client.
+ * @param {?} client - Configured sync client (or null to clear).
+ * @returns {void}
+ */
+export function setCurrentSyncClient(client) {
+  currentClient = client
+}
+
+/**
+ * Returns the current sync client.
+ * @returns {?} Current sync client.
+ */
+export function currentSyncClient() {
+  if (!currentClient) throw new Error("No sync client configured - create a SyncClient and call setCurrent() on it first")
+
+  return currentClient
+}

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

@@ -0,0 +1,41 @@
+// @ts-check
+
+/**
+ * Client-declared sync scope serialized from a model query.
+ * @typedef {object} SerializedSyncScope
+ * @property {Record<string, ?>} conditions - Plain attribute conditions from the query.
+ * @property {string} resourceType - Resource/model name the scope was declared for.
+ */
+
+/**
+ * Declarative per-resource sync policy.
+ * @typedef {object} SyncClientResourceConfig
+ * @property {?} 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 {(args: {operation: "create" | "update" | "destroy", record: ?}) => string} [syncType] - Maps a mutation operation to a sync type. 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 {boolean | {operations: Array<"create" | "update" | "destroy">}} [track] - Enables automatic mutation tracking through model lifecycle callbacks.
+ */
+
+/**
+ * Declarative sync client configuration.
+ * @typedef {object} SyncClientConfig
+ * @property {() => string | Promise<string>} authenticationToken - Resolves the auth token sent with sync requests.
+ * @property {number} [batchSize] - Max syncs per request.
+ * @property {import("../configuration.js").default} [configuration] - Configuration owning the scope-store database. Defaults to the current configuration.
+ * @property {() => boolean | Promise<boolean>} [isOnline] - Connectivity gate for pulls and replays. Defaults to always online.
+ * @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 {Record<string, SyncClientResourceConfig>} resources - Declarative resource policies keyed by resource/model name.
+ * @property {import("./sync-scope-store.js").default} [scopeStore] - Scope store override.
+ * @property {?} syncModel - Local pending-sync model class.
+ */
+
+export {}