velocious 1.0.502 → 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

@@ -43,6 +43,7 @@
  * @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] - 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.

package/src/sync/sync-client.js

@@ -661,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 {}