velocious 1.0.501 → 1.0.503

package/src/sync/sync-change-fanout.js

@@ -0,0 +1,58 @@
+// @ts-check
+
+/**
+ * One declarative broadcast delivered through an injected broadcaster. The
+ * replay service resolves it with replay args ({actor, applyResult, mutation,
+ * ...}) and the sync publisher with publish args
+ * ({@link import("./sync-publisher-types.js").SyncPublishBroadcastArgs}).
+ * @template [Args=Record<string, ?>]
+ * @typedef {object} DeclaredBroadcast
+ * @property {string | ((args: Args) => string)} channel - Channel name or resolver.
+ * @property {(args: Args) => Record<string, ?>} broadcastParams - Channel routing params.
+ * @property {(args: Args) => ?} body - Broadcast body.
+ * @property {(args: Args) => boolean} [when] - Optional gate; skipped when it returns false.
+ */
+
+/**
+ * Upserts one sync/change row through the shared sync-model contract: an
+ * existing row for the resource identity is reassigned and re-sequenced
+ * through `advanceServerSequence()` (the change-feed sequence contract) so
+ * feed cursors pick the change up again; otherwise a new row is created
+ * (creates allocate their sequence through the model's own hooks). Shared by
+ * the replay service's model-backed persistence and the server sync
+ * publisher.
+ * @param {{attributes: Record<string, ?>, existingSync: ?, syncModel: ?}} args - Row attributes, existing row for the resource identity, and the sync model.
+ * @returns {Promise<?>} Upserted sync row.
+ */
+export async function upsertSyncRow({attributes, existingSync, syncModel}) {
+  if (existingSync) {
+    existingSync.assign(attributes)
+    await existingSync.advanceServerSequence()
+    await existingSync.save()
+
+    return existingSync
+  }
+
+  return await syncModel.create(attributes)
+}
+
+/**
+ * Delivers declarative broadcasts through an injected broadcaster: each
+ * broadcast's `when` gate is checked, then channel/params/body are resolved
+ * from the caller's args. Shared by the replay service's default
+ * afterReplayMutation and the server sync publisher.
+ * @template Args
+ * @param {{args: Args, broadcaster: (broadcast: {channel: string, params: Record<string, ?>, body: ?}) => Promise<void>, broadcasts: Array<DeclaredBroadcast<Args>>}} deliveryArgs - Broadcast resolver args, broadcaster, and declared broadcasts.
+ * @returns {Promise<void>}
+ */
+export async function deliverDeclaredBroadcasts({args, broadcaster, broadcasts}) {
+  for (const broadcast of broadcasts) {
+    if (broadcast.when && !broadcast.when(args)) continue
+
+    await broadcaster({
+      body: broadcast.body(args),
+      channel: typeof broadcast.channel === "function" ? broadcast.channel(args) : broadcast.channel,
+      params: broadcast.broadcastParams(args)
+    })
+  }
+}

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

@@ -28,7 +28,7 @@
  * @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 {boolean | {operations: Array<"create" | "update" | "destroy">}} [track] - Enables automatic mutation tracking through model lifecycle callbacks.
+ * @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] - Static realtime channel this resource subscribes through `subscribeRealtime(...)`.
  */
 
@@ -43,8 +43,9 @@
  * @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 {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} [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 {boolean | Array<"create" | "update" | "destroy"> | {operations: Array<"create" | "update" | "destroy">}} [track] - Enables automatic mutation tracking; an array is shorthand for {operations}.
+ * @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 {ModelSyncRealtimeDeclaration} [realtime] - Static realtime channel this resource subscribes through `subscribeRealtime(...)`; use the `sync.client.realtime.channels` callback for channels needing runtime params.
  */

package/src/sync/sync-client.js

@@ -2,6 +2,7 @@
 
 import Configuration from "../configuration.js"
 import {isBooleanColumnType} from "../database/column-types.js"
+import Logger from "../logger.js"
 import restArgsError from "../utils/rest-args-error.js"
 
 import {serializedScopeFromQuery} from "./query-scope.js"
@@ -15,6 +16,14 @@ let clientCounter = 0
 /** @type {{create: "afterCreate", update: "afterUpdate", destroy: "afterDestroy"}} */
 const TRACKED_CALLBACK_NAMES = {create: "afterCreate", destroy: "afterDestroy", update: "afterUpdate"}
 
+/**
+ * Operations tracked by default for models declaring `static sync` without a
+ * `track` key: local creates and updates queue automatically. Destroys are not
+ * tracked by default because a local destroy is often cache eviction rather
+ * than a server delete; opt in with `track: true` or an operations list.
+ * @type {Array<"create" | "update" | "destroy">} */
+const DEFAULT_TRACKED_OPERATIONS = ["create", "update"]
+
 /** Attribute names treated as client-local sync bookkeeping when deriving localOnlyAttributes. */
 const LOCAL_BOOKKEEPING_ATTRIBUTE_NAMES = ["createdAt", "updatedAt", "lastSyncChangeAt"]
 
@@ -105,13 +114,18 @@ export default class SyncClient {
     this._trackedCallbacks = []
     /** @type {WeakSet<object>} */
     this._remoteApplyRecords = new WeakSet()
+    this._withoutTrackingDepth = 0
+    /** @type {Logger | {error: (...messages: Array<?>) => Promise<void>} | null} */
+    this._logger = null
     this._started = false
   }
 
   /**
-   * Registers automatic mutation tracking for every resource with `track` enabled:
-   * local model creates/updates/destroys queue pending sync rows and schedule an
-   * immediate replay attempt, without app-side queue calls.
+   * Registers automatic mutation tracking for every declared resource (on by
+   * default: local creates and updates queue pending sync rows once their
+   * transaction commits and schedule an immediate replay attempt, without
+   * app-side queue calls). `track: false` resources are skipped; `track: true`
+   * adds destroys; an operations list narrows the tracked operations.
    * @returns {Promise<void>}
    */
   async start() {
@@ -147,13 +161,17 @@ export default class SyncClient {
 
   /**
    * Resolves and validates the tracked operations for a resource config.
+   * Tracking is on by default: models declaring `static sync` without a `track`
+   * key queue local creates and updates automatically; `track: false` opts a
+   * model out (for models written by non-user flows).
    * @param {{resourceConfig: import("./sync-client-types.js").SyncClientResourceConfig, resourceType: string}} args - Resource config and name.
    * @returns {Array<"create" | "update" | "destroy">} Tracked operations.
    */
   trackedOperations({resourceConfig, resourceType}) {
     const track = resourceConfig.track
 
-    if (track === undefined || track === false) return []
+    if (track === false) return []
+    if (track === undefined) return DEFAULT_TRACKED_OPERATIONS
     if (track === true) return ["create", "update", "destroy"]
 
     if (!track || typeof track !== "object" || !Array.isArray(track.operations) || track.operations.length === 0) {
@@ -170,25 +188,76 @@ export default class SyncClient {
   }
 
   /**
-   * Builds the lifecycle callback queueing one tracked mutation.
+   * Builds the lifecycle callback queueing one tracked mutation. The queued
+   * payload and sync type are snapshotted at mutation-callback time, so
+   * afterSave hooks assigning unsaved attributes (or any later drift on the
+   * record) cannot change what gets queued vs what was committed. Queueing is
+   * deferred through the model connection's afterCommit hook so it only runs
+   * once the mutation's transaction has committed (immediately when no
+   * transaction is open) - queued syncs never reference rolled-back rows.
+   * 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.
    */
   trackedMutationCallback({operation, resourceConfig}) {
     return async (record) => {
-      if (this.isRemoteApply(record)) return
+      if (this.isTrackingSuppressed(record)) return
 
-      await SyncApiClient.queueLocalSync({
+      const data = SyncApiClient.queuedSyncData({
         booleanAttributes: resourceConfig.booleanAttributes || [],
         data: resourceConfig.trackedData ? resourceConfig.trackedData({operation, record}) : undefined,
         localOnlyAttributes: resourceConfig.localOnlyAttributes || [],
-        resource: record,
-        syncModel: this.config.syncModel,
-        syncType: this.defaultSyncType({operation, record, resourceConfig})
+        resource: record
+      })
+      const syncType = this.defaultSyncType({operation, record, resourceConfig})
+
+      await resourceConfig.modelClass.connection().afterCommit(async () => {
+        try {
+          await SyncApiClient.queueLocalSync({
+            data,
+            resource: record,
+            syncModel: this.config.syncModel,
+            syncType
+          })
+        } catch (error) {
+          await this.reportAfterCommitError(/** @type {Error} */ (error))
+
+          return
+        }
+
+        this.scheduleReplay()
       })
+    }
+  }
+
+  /**
+   * Reports a post-commit tracked-queueing failure. The transaction has already
+   * committed when afterCommit callbacks run, so rethrowing here would poison
+   * the driver's awaited afterCommit chain (breaking unrelated callbacks) -
+   * instead the failure goes to the configured sync.client.onError hook, or is
+   * logged loudly through the client's logger when none is configured.
+   * @param {Error} error - Post-commit queueing failure.
+   * @returns {Promise<void>}
+   */
+  async reportAfterCommitError(error) {
+    if (this.config.onError) {
+      this.config.onError(error)
 
-      this.scheduleReplay()
+      return
     }
+
+    await this.logger().error("SyncClient failed to queue a tracked mutation after commit", error)
+  }
+
+  /**
+   * Returns the lazily built client logger.
+   * @returns {Logger | {error: (...messages: Array<?>) => Promise<void>}} Client logger.
+   */
+  logger() {
+    this._logger ||= new Logger("SyncClient", {configuration: this.config.configuration})
+
+    return this._logger
   }
 
   /**
@@ -200,6 +269,54 @@ export default class SyncClient {
     return this._remoteApplyRecords.has(record)
   }
 
+  /**
+   * Whether tracked mutation queueing is currently suppressed for a record:
+   * 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.
+   * @returns {boolean} Whether tracked queueing is suppressed for the record.
+   */
+  isTrackingSuppressed(record) {
+    return this._withoutTrackingDepth > 0 || this.isRemoteApply(record)
+  }
+
+  /**
+   * Runs a callback with tracked mutation queueing suppressed on this client -
+   * for code applying server-originated data outside the derived pull/realtime
+   * appliers (legacy pull paths, importers, sign-in backfills), so their writes
+   * are not echoed back to the server as device changes. Suppression covers the
+   * whole async duration of the callback (nested calls stack) and is
+   * client-wide while it runs: mutations from concurrently running tasks are
+   * also suppressed for that window, so prefer `markRemoteApply(record)` when
+   * writes from other flows can interleave.
+   * @template T
+   * @param {() => Promise<T> | T} callback - Work whose model writes should not queue tracked syncs.
+   * @returns {Promise<T>} The callback result.
+   */
+  async withoutTracking(callback) {
+    this._withoutTrackingDepth++
+
+    try {
+      return await callback()
+    } finally {
+      this._withoutTrackingDepth--
+    }
+  }
+
+  /**
+   * 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.
+   * @returns {() => void} Release callback re-enabling tracking for the record.
+   */
+  markRemoteApply(record) {
+    this._remoteApplyRecords.add(record)
+
+    return () => this._remoteApplyRecords.delete(record)
+  }
+
   /**
    * Registers this client as the app's current sync client.
    * @returns {void}
@@ -319,11 +436,7 @@ export default class SyncClient {
    */
   remoteApplySync({source = "pulled change"} = {}) {
     const pullResourceConfigs = this.pullResourceConfigs()
-    const applier = SyncApiClient.resourceApplier(pullResourceConfigs, (record) => {
-      this._remoteApplyRecords.add(record)
-
-      return () => this._remoteApplyRecords.delete(record)
-    })
+    const applier = SyncApiClient.resourceApplier(pullResourceConfigs, (record) => this.markRemoteApply(record))
 
     return async (sync) => {
       const resourceType = sync.resourceType()
@@ -548,11 +661,16 @@ function resourceConfigFromSyncDeclaration({declaration, modelClass, resourceTyp
     throw new Error(`${resourceType} static sync must be true or a sync declaration object, got: ${String(declaration)}`)
   }
 
-  const {afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, realtime, syncType, track, trackedData, ...restDeclaration} = normalizedDeclaration
+  const {afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, publish, realtime, syncType, track, trackedData, ...restDeclaration} = normalizedDeclaration
   const unknownKeys = Object.keys(restDeclaration)
 
+  // `publish` is the server-side half of the shared `static sync` declaration
+  // (consumed by SyncPublisher on the backend) - the client derives nothing
+  // from it, but models declared once for both sides must stay valid here.
+  void publish
+
   if (unknownKeys.length > 0) {
-    throw new Error(`${resourceType} static sync received unknown keys: ${unknownKeys.join(", ")} (supported: afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, realtime, syncType, track, trackedData)`)
+    throw new Error(`${resourceType} static sync received unknown keys: ${unknownKeys.join(", ")} (supported: afterApply, attributes, booleanAttributes, findRecord, findRecordForDelete, localOnlyAttributes, publish, realtime, syncType, track, trackedData)`)
   }
   if (syncType !== undefined && typeof syncType !== "function" && syncType !== "upsert") {
     throw new Error(`${resourceType} static sync syncType must be a function or the string "upsert", got: ${String(syncType)}`)

package/src/sync/sync-envelope-replay-service.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import {deliverDeclaredBroadcasts, upsertSyncRow} from "./sync-change-fanout.js"
+import {markServerApply} from "./sync-publish-suppression.js"
 import {resolveFrontendModelResourceClass} from "../frontend-models/resource-definition.js"
 import SyncReplayUpsertApplier from "./sync-replay-upsert-applier.js"
 import {ValidationError} from "../database/record/index.js"
@@ -485,7 +487,11 @@ export default class SyncEnvelopeReplayService {
   }
 
   /**
-   * Applies a routed delete mutation.
+   * Applies a routed delete mutation. The record is marked as a server apply
+   * for the duration of the replay-owned destroy - an active SyncPublisher
+   * never publishes the replayed delete a second time (the replay owns its
+   * own persist and broadcasts), while later server-side writes to the same
+   * instance publish normally again.
    * @param {object} args - Options.
    * @param {import("./sync-envelope-replay-service.js").SyncReplayMutation} args.mutation - Normalized replay mutation.
    * @param {import("../frontend-model-resource/base-resource.js").default} args.resource - Routed resource instance.
@@ -496,7 +502,13 @@ export default class SyncEnvelopeReplayService {
 
     if (!record) return {created: false, deleted: false, record: null}
 
-    await record.destroy()
+    const releaseServerApply = markServerApply(record)
+
+    try {
+      await record.destroy()
+    } finally {
+      releaseServerApply()
+    }
 
     return {created: false, deleted: true, record}
   }
@@ -506,8 +518,12 @@ export default class SyncEnvelopeReplayService {
    * assigned and saved onto the found record (the record layer owns value
    * casting and validation), and missing records are created with the
    * client-generated primary key plus a save-then-check membership check.
-   * Model validation failures become client-safe per-sync failures carrying
-   * the translated validation message.
+   * Written records are marked as server applies for the duration of the
+   * replay-owned write - an active SyncPublisher never publishes the replayed
+   * mutation a second time (the replay owns its own persist and broadcasts),
+   * while later server-side writes to the same instance publish normally
+   * again. Model validation failures become client-safe per-sync failures
+   * carrying the translated validation message.
    * @param {object} args - Options.
    * @param {Record<string, ?>} args.context - Replay context.
    * @param {import("./sync-envelope-replay-service.js").SyncReplayMutation} args.mutation - Normalized replay mutation.
@@ -523,8 +539,14 @@ export default class SyncEnvelopeReplayService {
     let created = false
 
     if (existingRecord) {
-      existingRecord.assign(attributes)
-      await this.saveRoutedReplayRecord(existingRecord)
+      const releaseServerApply = markServerApply(existingRecord)
+
+      try {
+        existingRecord.assign(attributes)
+        await this.saveRoutedReplayRecord(existingRecord)
+      } finally {
+        releaseServerApply()
+      }
     } else {
       record = await this.createRoutedReplayRecord({attributes, mutation, resource})
       created = true
@@ -588,7 +610,10 @@ export default class SyncEnvelopeReplayService {
   }
 
   /**
-   * Creates the routed record with the client-generated primary key, then
+   * Creates the routed record with the client-generated primary key (marked
+   * as a server apply for the duration of the create - including the
+   * membership-check compensation destroy - so an active SyncPublisher never
+   * publishes the replayed create a second time), then
    * verifies create-scope membership when an ability is configured: records
    * outside the ability's create scope are destroyed again and fail the sync
    * with the resource-declared reason. A record that already exists outside
@@ -611,33 +636,39 @@ export default class SyncEnvelopeReplayService {
       })
     }
 
-    /** @type {import("../database/record/index.js").default} */
-    let record
+    await ModelClass.ensureInitialized()
+
+    const record = new ModelClass({[primaryKey]: mutation.resourceId, ...attributes})
+    const releaseServerApply = markServerApply(record)
 
     try {
-      record = await ModelClass.create({[primaryKey]: mutation.resourceId, ...attributes})
-    } catch (error) {
-      throw this.routedReplaySaveError(error)
-    }
+      try {
+        await record.save()
+      } catch (error) {
+        throw this.routedReplaySaveError(error)
+      }
 
-    const ability = resource.ability
+      const ability = resource.ability
 
-    if (ability) {
-      const memberIds = await ModelClass
-        .accessibleFor(resource.syncAbilityAction("create"), ability)
-        .where({[primaryKey]: record.id()})
-        .pluck(primaryKey)
+      if (ability) {
+        const memberIds = await ModelClass
+          .accessibleFor(resource.syncAbilityAction("create"), ability)
+          .where({[primaryKey]: record.id()})
+          .pluck(primaryKey)
 
-      if (memberIds.length === 0) {
-        await record.destroy()
+        if (memberIds.length === 0) {
+          await record.destroy()
 
-        throw VelociousError.safe(`Sync create denied for: ${mutation.resourceType}.`, {
-          code: resource.syncAuthorizationFailureReason({action: "create", mutation}) || "access-denied"
-        })
+          throw VelociousError.safe(`Sync create denied for: ${mutation.resourceType}.`, {
+            code: resource.syncAuthorizationFailureReason({action: "create", mutation}) || "access-denied"
+          })
+        }
       }
-    }
 
-    return record
+      return record
+    } finally {
+      releaseServerApply()
+    }
   }
 
   /**
@@ -709,13 +740,9 @@ export default class SyncEnvelopeReplayService {
       const existingClientUpdatedAt = this.existingReplaySyncClientUpdatedAt(existingSync)
 
       if (existingClientUpdatedAt && mutation.clientUpdatedAt <= existingClientUpdatedAt) return
-
-      existingSync.assign(attributes)
-      await existingSync.advanceServerSequence()
-      await existingSync.save()
-    } else {
-      await this.syncModel.create(attributes)
     }
+
+    await upsertSyncRow({attributes, existingSync, syncModel: this.syncModel})
   }
 
   /**
@@ -748,15 +775,7 @@ export default class SyncEnvelopeReplayService {
     // would fan out stale side effects (or crash on the default null applyResult).
     if (!args.shouldApply) return
 
-    for (const broadcast of this.broadcasts) {
-      if (broadcast.when && !broadcast.when(args)) continue
-
-      await this.broadcaster({
-        body: broadcast.body(args),
-        channel: typeof broadcast.channel === "function" ? broadcast.channel(args) : broadcast.channel,
-        params: broadcast.broadcastParams(args)
-      })
-    }
+    await deliverDeclaredBroadcasts({args, broadcaster: this.broadcaster, broadcasts: this.broadcasts})
   }
 }
 

package/src/sync/sync-publish-suppression.js

@@ -0,0 +1,59 @@
+// @ts-check
+
+/**
+ * Records currently being written from an already-synced source (sync replay
+ * applies, importers applying device-origin data). Module-scoped so the
+ * framework's replay apply can mark records without holding a publisher
+ * instance.
+ * @type {WeakSet<object>}
+ */
+const serverApplyRecords = new WeakSet()
+
+let withoutPublishingDepth = 0
+
+/**
+ * Marks one record as being written from an already-synced source so server
+ * publish callbacks skip it (record-precise suppression). The framework's
+ * routed sync replay apply uses this internally around every applied write, so
+ * replayed device mutations never publish a second, server-origin sync change.
+ * @param {?} record - Server model record about to be written.
+ * @returns {() => void} Release callback re-enabling publishing for the record.
+ */
+export function markServerApply(record) {
+  serverApplyRecords.add(record)
+
+  return () => serverApplyRecords.delete(record)
+}
+
+/**
+ * Runs a callback with server publish callbacks suppressed - for code applying
+ * already-synced data outside the framework's replay apply (importers,
+ * backfills applying device-origin rows). Suppression covers the whole async
+ * duration of the callback (nested calls stack) and is process-wide while it
+ * runs: mutations from concurrently running requests are also suppressed for
+ * that window, so prefer `markServerApply(record)` when other flows can
+ * interleave.
+ * @template T
+ * @param {() => Promise<T> | T} callback - Work whose model writes should not publish sync changes.
+ * @returns {Promise<T>} The callback result.
+ */
+export async function withoutPublishing(callback) {
+  withoutPublishingDepth++
+
+  try {
+    return await callback()
+  } finally {
+    withoutPublishingDepth--
+  }
+}
+
+/**
+ * Whether server publishing is currently suppressed for a record: either the
+ * record was marked as a server apply (`markServerApply`) or a
+ * `withoutPublishing` callback is running.
+ * @param {?} record - Server model record being written.
+ * @returns {boolean} Whether publishing is suppressed for the record.
+ */
+export function isPublishingSuppressed(record) {
+  return withoutPublishingDepth > 0 || serverApplyRecords.has(record)
+}

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

@@ -0,0 +1,64 @@
+// @ts-check
+
+/**
+ * Args resolved against a publish declaration's broadcasts after a published
+ * server-side mutation commits.
+ * @typedef {object} SyncPublishBroadcastArgs
+ * @property {Record<string, ?>} data - Payload snapshotted through the declaration's `serialize(record)` at mutation time.
+ * @property {"create" | "update" | "destroy"} operation - Mutation operation that published.
+ * @property {?} record - Mutated server model record.
+ * @property {string} resourceId - Published resource id.
+ * @property {string} resourceType - Published resource type.
+ * @property {?} syncRow - Upserted sync/change row.
+ * @property {string} syncType - Published sync type ("update" for creates/updates, "delete" for destroys).
+ */
+
+/**
+ * One declarative broadcast fanned out after a published server-side mutation
+ * commits — same shape the replay service's injected broadcaster consumes.
+ * @typedef {object} SyncPublishBroadcast
+ * @property {string | ((args: SyncPublishBroadcastArgs) => string)} channel - Channel name or resolver.
+ * @property {(args: SyncPublishBroadcastArgs) => Record<string, ?>} broadcastParams - Channel routing params.
+ * @property {(args: SyncPublishBroadcastArgs) => ?} body - Broadcast body.
+ * @property {(args: SyncPublishBroadcastArgs) => boolean} [when] - Optional gate; skipped when it returns false.
+ */
+
+/**
+ * Server-side publish declaration on a model's `static sync`, consumed by
+ * `SyncPublisher.fromConfiguration(...)`. Publishing is on for models
+ * declaring it (server-side creates and updates write to the sync change
+ * feed and broadcast automatically once their transaction commits);
+ * `publish: false` opts a model out explicitly.
+ * @typedef {object} SyncPublishDeclarationConfig
+ * @property {(record: ?) => Record<string, ?> | Promise<Record<string, ?>>} serialize - Builds the published payload snapshot from the mutated record (snapshotted at mutation time).
+ * @property {(record: ?) => string | number | null | Promise<string | number | null>} [eventId] - Resolves the event scope persisted to the sync row's event_id column.
+ * @property {SyncPublishBroadcast[]} [broadcasts] - Declarative broadcasts fanned out after the sync row is upserted.
+ * @property {Array<"create" | "update" | "destroy">} [operations] - Published operations. Defaults to creates and updates; destroys are opt-in because a server destroy is often cleanup rather than a synced delete.
+ * @property {string} [resourceType] - Published resource type. Defaults to the model name.
+ */
+
+/** @typedef {false | SyncPublishDeclarationConfig} SyncPublishDeclaration */
+
+/**
+ * Options for building a sync publisher. Published resources are derived from
+ * the configuration's registered models (`static sync` publish declarations).
+ * @typedef {object} SyncPublisherOptions
+ * @property {string} [actorForeignKeyColumn] - Sync model column linking rows to a device actor. Published server-origin rows set it to null (no device to echo). Defaults to "authentication_token_id".
+ * @property {(broadcast: {channel: string, params: Record<string, ?>, body: ?}) => Promise<void>} [broadcaster] - Delivers declared broadcasts. Defaults to the configuration's channel broadcast.
+ * @property {import("../configuration.js").default} [configuration] - Configuration owning the registered models. Defaults to the current configuration.
+ * @property {(error: Error) => void} [onError] - Reports post-commit publish failures. Defaults to loud logging.
+ * @property {?} [syncModel] - Sync/change model override. Defaults to the registered "Sync" model.
+ */
+
+/**
+ * Internal derived publish policy for one resource — not an app-facing API.
+ * @typedef {object} SyncPublisherResourceConfig
+ * @property {SyncPublishBroadcast[] | undefined} broadcasts - Declared broadcasts.
+ * @property {SyncPublishDeclarationConfig["eventId"] | undefined} eventId - Event scope resolver.
+ * @property {?} modelClass - Server model class for this resource.
+ * @property {Array<"create" | "update" | "destroy">} operations - Published operations.
+ * @property {string} resourceType - Published resource type.
+ * @property {SyncPublishDeclarationConfig["serialize"]} serialize - Payload snapshot builder.
+ */
+
+export {}