velocious 1.0.489 → 1.0.493

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

@@ -0,0 +1,179 @@
+// @ts-check
+
+import {optionalFloat, optionalInteger, optionalString} from "typanic"
+
+import SyncApiClient from "./sync-api-client.js"
+
+/**
+ * Coercers for the declarative sync field types. All are present-key based:
+ * a field is only applied when its key exists in the mutation data.
+ * @type {Record<string, (value: ?, label: string) => ?>}
+ */
+const FIELD_TYPES = {
+  booleanOrNull: (value, label) => SyncApiClient.optionalBooleanSyncValue(value, label),
+  dateOrNull: (value, label) => optionalSyncDate(value, label),
+  floatOrNull: (value, label) => optionalFloat(value, label),
+  integerOrNull: (value, label) => optionalInteger(value, label),
+  raw: (value) => value,
+  stringOrNull: (value, label) => optionalString(value, label)
+}
+
+/**
+ * Parses an optional date value, failing loudly on invalid input.
+ * @param {?} value - Date, parseable string, or epoch number.
+ * @param {string} label - Field label for error messages.
+ * @returns {Date | null} Parsed date or null when absent.
+ */
+function optionalSyncDate(value, label) {
+  if (value === null || value === undefined) return null
+
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value
+
+  if (typeof value === "string" || typeof value === "number") {
+    const dateValue = new Date(value)
+
+    if (!Number.isNaN(dateValue.getTime())) return dateValue
+  }
+
+  throw new Error(`Expected ${label} to be a valid date or null`)
+}
+
+/**
+ * Declarative field-map upsert applier for sync replay mutations.
+ *
+ * Owns the generic mechanics every per-resource replay handler repeats:
+ * present-key filtering, per-field type coercion, unknown-key rejection, the
+ * find-or-create upsert, the delete branch, optional snapshot serialization,
+ * and the domain after-apply tail. Apps declare only the field map and hooks.
+ */
+export default class SyncReplayUpsertApplier {
+  /**
+   * Creates a declarative upsert applier.
+   * @param {object} args - Applier configuration.
+   * @param {?} args.modelClass - Model class receiving the mutations.
+   * @param {Record<string, string | {type: string, column?: string} | ((value: ?, label: string) => ?)>} args.fields - Data-key → field-type map: a named type, a {type, column} rename spec, "ignored" for accepted-but-dropped keys, or a custom coercer function.
+   * @param {(args: {data: Record<string, ?>, mutation: ?, context: Record<string, ?>}) => Promise<?>} [args.findRecord] - Custom record resolver. Defaults to findBy({id: mutation.resourceId}).
+   * @param {(args: {mutation: ?, context: Record<string, ?>}) => Promise<?>} [args.findRecordForDelete] - Custom delete resolver. Defaults to findRecord.
+   * @param {"error" | "ignore"} [args.restArgs] - Unknown data-key handling. Defaults to "error".
+   * @param {(args: {mappedAttributes: Record<string, ?>, mutation: ?, context: Record<string, ?>, record: ?}) => Promise<Record<string, ?> | void>} [args.afterApply] - Domain tail; its returned object merges into the apply result.
+   * @param {(args: {mutation: ?, context: Record<string, ?>, record: ?}) => Promise<Record<string, ?>> | Record<string, ?>} [args.serialize] - Snapshot serializer; result lands on applyResult.serializedData.
+   */
+  constructor({afterApply, fields, findRecord, findRecordForDelete, modelClass, restArgs = "error", serialize}) {
+    if (!modelClass) throw new Error("SyncReplayUpsertApplier requires a modelClass")
+    if (!fields || typeof fields !== "object") throw new Error("SyncReplayUpsertApplier requires a fields map")
+    if (restArgs !== "error" && restArgs !== "ignore") {
+      throw new Error(`SyncReplayUpsertApplier restArgs must be "error" or "ignore", got: ${String(restArgs)}`)
+    }
+
+    for (const [fieldName, fieldSpec] of Object.entries(fields)) {
+      if (typeof fieldSpec === "function") continue
+
+      const fieldType = typeof fieldSpec === "string" ? fieldSpec : fieldSpec.type
+
+      if (fieldType !== "ignored" && !(fieldType in FIELD_TYPES)) {
+        throw new Error(`Unknown sync field type: ${fieldType} for: ${fieldName}`)
+      }
+    }
+
+    this.afterApply = afterApply
+    this.fields = fields
+    this.findRecord = findRecord
+    this.findRecordForDelete = findRecordForDelete
+    this.modelClass = modelClass
+    this.restArgs = restArgs
+    this.serialize = serialize
+  }
+
+  /**
+   * Applies one normalized replay mutation to the declared model.
+   * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, mutation: ?}} args - Replay apply arguments.
+   * @returns {Promise<Record<string, ?>>} Apply result with the record, created/deleted flags, optional serializedData, and afterApply extras.
+   */
+  async apply({context, mutation}) {
+    if (mutation.syncType === "delete") return await this.applyDelete({context, mutation})
+
+    const mappedAttributes = this.mappedAttributes(mutation.data)
+    const record = this.findRecord
+      ? await this.findRecord({context, data: mutation.data, mutation})
+      : await this.modelClass.findBy({id: mutation.resourceId})
+    /** @type {Record<string, ?>} */
+    const result = {created: false, deleted: false, record: null}
+
+    if (record) {
+      record.assign(mappedAttributes)
+      await record.save()
+      result.record = record
+    } else {
+      result.record = await this.modelClass.create({id: mutation.resourceId, ...mappedAttributes})
+      result.created = true
+    }
+
+    if (this.serialize) result.serializedData = await this.serialize({context, mutation, record: result.record})
+
+    if (this.afterApply) {
+      const afterApplyResult = await this.afterApply({context, mappedAttributes, mutation, record: result.record})
+
+      if (afterApplyResult && typeof afterApplyResult === "object") Object.assign(result, afterApplyResult)
+    }
+
+    return result
+  }
+
+  /**
+   * Applies a delete mutation to the declared model.
+   * @param {{context: Record<string, ?>, mutation: ?}} args - Delete arguments.
+   * @returns {Promise<Record<string, ?>>} Apply result with the deleted flag.
+   */
+  async applyDelete({context, mutation}) {
+    const resolveRecord = this.findRecordForDelete || this.findRecord
+    const record = resolveRecord
+      ? await resolveRecord({context, data: mutation.data, mutation})
+      : await this.modelClass.findBy({id: mutation.resourceId})
+
+    if (!record) return {created: false, deleted: false, record: null}
+
+    await record.destroy()
+
+    return {created: false, deleted: true, record}
+  }
+
+  /**
+   * Maps present data keys through the declared field types.
+   * @param {Record<string, ?>} data - Normalized mutation data.
+   * @returns {Record<string, ?>} Coerced attributes keyed by column name.
+   */
+  mappedAttributes(data) {
+    /** @type {Record<string, ?>} */
+    const mappedAttributes = {}
+    /** @type {string[]} */
+    const unknownKeys = []
+
+    for (const [dataKey, value] of Object.entries(data)) {
+      const fieldSpec = this.fields[dataKey]
+
+      if (!fieldSpec) {
+        unknownKeys.push(dataKey)
+        continue
+      }
+
+      if (typeof fieldSpec === "function") {
+        mappedAttributes[dataKey] = fieldSpec(value, dataKey)
+        continue
+      }
+
+      const fieldType = typeof fieldSpec === "string" ? fieldSpec : fieldSpec.type
+
+      if (fieldType === "ignored") continue
+
+      const column = typeof fieldSpec === "string" ? dataKey : fieldSpec.column || dataKey
+
+      mappedAttributes[column] = FIELD_TYPES[fieldType](value, dataKey)
+    }
+
+    if (unknownKeys.length > 0 && this.restArgs === "error") {
+      throw new Error(`Unknown sync data keys: ${unknownKeys.join(", ")}`)
+    }
+
+    return mappedAttributes
+  }
+}

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

@@ -0,0 +1,143 @@
+// @ts-check
+
+import {forcedNonBlankStringParam} from "typanic"
+
+import FrontendModelBaseResource from "../frontend-model-resource/base-resource.js"
+import SyncModelChangeFeedService from "./sync-model-change-feed-service.js"
+
+/**
+ * Optional client-declared sync scope carried on a changes request.
+ * @typedef {object} SerializedChangesScope
+ * @property {Record<string, ?>} conditions - Plain attribute conditions from the client query.
+ * @property {string} resourceType - Client resource/model name the scope was declared for.
+ */
+
+/**
+ * Base resource for Velocious sync endpoints.
+ *
+ * Velocious owns the changes/replay orchestration (scope parsing, feed paging,
+ * replay delegation, response shape) while apps subclass and only declare
+ * authorization, feed scoping, and their replay service.
+ * @template {typeof import("../database/record/index.js").default} [TModelClass=typeof import("../database/record/index.js").default]
+ * @augments {FrontendModelBaseResource<TModelClass>}
+ */
+export default class SyncResourceBase extends FrontendModelBaseResource {
+  /**
+   * Returns a stable change-feed page after app authorization.
+   * @returns {Promise<Record<string, ?>>} Change-feed page result.
+   */
+  async changes() {
+    const params = this.params()
+    const scope = this.changesScope(params)
+
+    await this.authorizeChanges({params, scope})
+
+    return await this.changeFeedService({params, scope}).changes()
+  }
+
+  /**
+   * Replays client sync envelopes through the app replay service.
+   * @returns {Promise<Record<string, ?>>} Replay result with per-sync states.
+   */
+  async replay() {
+    const result = await this.buildReplayService().replay(this.params())
+
+    if (result.status === "error") return result
+
+    return {status: "success", syncs: result.syncs}
+  }
+
+  /**
+   * Parses the optional client-declared scope from request params.
+   * @param {Record<string, ?>} params - Request params.
+   * @returns {SerializedChangesScope | null} Parsed scope, or null when the client sent none.
+   */
+  changesScope(params) {
+    const scope = params.scope
+
+    if (scope === undefined || scope === null) return null
+
+    if (typeof scope !== "object" || Array.isArray(scope)) {
+      throw new Error(`Sync changes scope must be an object, got: ${String(scope)}`)
+    }
+
+    const scopeParams = /** @type {Record<string, ?>} */ (scope)
+    const resourceType = forcedNonBlankStringParam(scopeParams, "resourceType")
+    const conditions = scopeParams.conditions
+
+    if (!conditions || typeof conditions !== "object" || Array.isArray(conditions)) {
+      throw new Error(`Sync changes scope.conditions must be an object, got: ${String(conditions)}`)
+    }
+
+    return {conditions: /** @type {Record<string, ?>} */ (conditions), resourceType}
+  }
+
+  /**
+   * Builds the change-feed service serving this changes request.
+   * @param {{params: Record<string, ?>, scope: SerializedChangesScope | null}} args - Request params and parsed scope.
+   * @returns {{changes: () => Promise<Record<string, ?>>}} Change-feed service.
+   */
+  changeFeedService({params, scope}) {
+    return new SyncModelChangeFeedService({
+      modelClass: this.syncModelClass(),
+      params,
+      scopeQuery: ({query}) => this.scopeChangesQuery({params, query, scope})
+    })
+  }
+
+  /**
+   * Builds the app replay service handling this replay request.
+   * @returns {import("./sync-envelope-replay-service.js").default} Replay service instance.
+   */
+  buildReplayService() {
+    const ReplayServiceClass = this.replayServiceClass()
+
+    return new ReplayServiceClass(this.replayServiceArgs())
+  }
+
+  /**
+   * Returns constructor args for the app replay service.
+   * @returns {Record<string, ?>} Replay service constructor args.
+   */
+  replayServiceArgs() {
+    return {}
+  }
+
+  /**
+   * Returns the sync model class backing the change feed.
+   * @returns {typeof import("../database/record/index.js").default} Sync model class.
+   */
+  syncModelClass() {
+    const modelClass = /** @type {typeof SyncResourceBase} */ (this.constructor).ModelClass
+
+    if (!modelClass) throw new Error(`${this.constructor.name} must define static ModelClass`)
+
+    return modelClass
+  }
+
+  /**
+   * Authorizes the current context for reading the requested changes.
+   * @param {{params: Record<string, ?>, scope: SerializedChangesScope | null}} _args - Request params and parsed scope.
+   * @returns {Promise<void>} Resolves when access is allowed; throws otherwise.
+   */
+  async authorizeChanges(_args) {
+    throw new Error("SyncResourceBase#authorizeChanges must be implemented")
+  }
+
+  /**
+   * Applies app visibility scoping onto the change-feed query.
+   * @param {{params: Record<string, ?>, query: import("../database/query/model-class-query.js").default, scope: SerializedChangesScope | null}} _args - Request params, feed query, and parsed scope.
+   * @returns {void}
+   */
+  scopeChangesQuery(_args) {
+    throw new Error("SyncResourceBase#scopeChangesQuery must be implemented")
+  }
+
+  /**
+   * Returns the app replay service class handling replay mutations.
+   * @returns {typeof import("./sync-envelope-replay-service.js").default} Replay service class.
+   */
+  replayServiceClass() {
+    throw new Error("SyncResourceBase#replayServiceClass must be implemented")
+  }
+}

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

@@ -0,0 +1,327 @@
+// @ts-check
+
+import TableData from "../database/table-data/index.js"
+import UUID from "pure-uuid"
+
+import {scopeKey} from "./query-scope.js"
+import stableJsonStringify from "./stable-json.js"
+
+const TABLE_NAME = "velocious_sync_scopes"
+const SCOPE_DIGEST_PREFIX = "velocious-sync-scope:"
+
+/**
+ * Digests a serialized scope into a fixed-size deterministic key, so scope
+ * identities with long condition values fit an indexed string column.
+ * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
+ * @returns {string} Deterministic UUIDv5 digest of the canonical scope key.
+ */
+function scopeDigestForScope(scope) {
+  return new UUID(5, "ns:URL", `${SCOPE_DIGEST_PREFIX}${scopeKey(scope)}`).format()
+}
+
+/**
+ * @typedef {object} SyncScopeRow
+ * @property {Record<string, ?>} conditions - Scope attribute conditions.
+ * @property {string | null} cursorPayload - Persisted cursor JSON payload.
+ * @property {string} id - Scope row id.
+ * @property {string} resourceType - Scope resource/model name.
+ * @property {string} scopeDigest - Fixed-size deterministic digest of the canonical scope key.
+ * @property {string} state - Scope state ("active" or "removed").
+ */
+
+/**
+ * Framework-owned local persistence for declared sync scopes and their cursors.
+ *
+ * Backed by an auto-created `velocious_sync_scopes` table on the configured
+ * database, with a process-local memory fallback when no database is
+ * configured (mirroring the server change-feed store).
+ */
+export default class SyncScopeStore {
+  /**
+   * Creates a sync scope store.
+   * @param {object} args - Options.
+   * @param {import("../configuration.js").default} args.configuration - Configuration owning the database.
+   * @param {string} [args.databaseIdentifier] - Database identifier.
+   */
+  constructor({configuration, databaseIdentifier = "default"}) {
+    this.configuration = configuration
+    this.databaseIdentifier = databaseIdentifier
+    /** @type {Map<string, SyncScopeRow>} */
+    this._memoryScopes = new Map()
+    this._isReady = false
+    /** @type {Promise<void> | null} */
+    this._readyPromise = null
+  }
+
+  /**
+   * Ensures the backing table exists.
+   * @returns {Promise<void>} Resolves when ready.
+   */
+  async ensureReady() {
+    if (this._isReady) return
+
+    if (this._usesMemoryStorage()) {
+      this._isReady = true
+      return
+    }
+
+    if (this._readyPromise) return await this._readyPromise
+
+    this._readyPromise = this._withDb(async (db) => {
+      await this._ensureScopesTable(db)
+      this._isReady = true
+    })
+
+    try {
+      await this._readyPromise
+    } finally {
+      if (!this._isReady) this._readyPromise = null
+    }
+  }
+
+  /**
+   * Finds or creates the scope row for a serialized scope, reactivating removed scopes.
+   * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
+   * @returns {Promise<SyncScopeRow>} Persisted scope row.
+   */
+  async findOrCreateScope(scope) {
+    await this.ensureReady()
+
+    const digest = scopeDigestForScope(scope)
+
+    if (this._usesMemoryStorage()) {
+      const existingScope = this._memoryScopes.get(digest)
+
+      if (existingScope) {
+        if (existingScope.state !== "active") existingScope.state = "active"
+
+        return existingScope
+      }
+
+      const newScope = {
+        conditions: scope.conditions,
+        cursorPayload: null,
+        id: new UUID(4).format(),
+        resourceType: scope.resourceType,
+        scopeDigest: digest,
+        state: "active"
+      }
+
+      this._memoryScopes.set(digest, newScope)
+
+      return newScope
+    }
+
+    return await this._withDb(async (db) => {
+      const existingRow = await this._rowByScopeDigest(db, digest)
+
+      if (existingRow) {
+        if (existingRow.state !== "active") {
+          await db.update({conditions: {id: existingRow.id}, data: {state: "active", updated_at: new Date()}, tableName: TABLE_NAME})
+          existingRow.state = "active"
+        }
+
+        return existingRow
+      }
+
+      await db.insert({
+        tableName: TABLE_NAME,
+        data: {
+          conditions_json: stableJsonStringify(scope.conditions),
+          created_at: new Date(),
+          cursor_json: null,
+          id: new UUID(4).format(),
+          resource_type: scope.resourceType,
+          scope_digest: digest,
+          state: "active",
+          updated_at: new Date()
+        }
+      })
+
+      const createdRow = await this._rowByScopeDigest(db, digest)
+
+      if (!createdRow) throw new Error("Failed to persist sync scope")
+
+      return createdRow
+    })
+  }
+
+  /**
+   * Returns all active scope rows.
+   * @returns {Promise<SyncScopeRow[]>} Active scope rows.
+   */
+  async activeScopes() {
+    await this.ensureReady()
+
+    if (this._usesMemoryStorage()) {
+      return [...this._memoryScopes.values()].filter((scope) => scope.state === "active")
+    }
+
+    return await this._withDb(async (db) => {
+      const rows = /** @type {Array<Record<string, ?>>} */ (await db
+        .newQuery()
+        .from(TABLE_NAME)
+        .where({state: "active"})
+        .order("created_at ASC")
+        .results())
+
+      return rows.map((row) => this._normalizeScopeRow(row))
+    })
+  }
+
+  /**
+   * Loads the persisted cursor payload for a scope row.
+   * @param {SyncScopeRow} scopeRow - Scope row.
+   * @returns {Promise<string | null>} Cursor JSON payload.
+   */
+  async loadCursor(scopeRow) {
+    await this.ensureReady()
+
+    if (this._usesMemoryStorage()) {
+      return this._memoryScopes.get(scopeRow.scopeDigest)?.cursorPayload ?? null
+    }
+
+    return await this._withDb(async (db) => {
+      const row = await this._rowByScopeDigest(db, scopeRow.scopeDigest)
+
+      return row ? row.cursorPayload : null
+    })
+  }
+
+  /**
+   * Persists the acknowledged cursor for a scope row.
+   * @param {SyncScopeRow} scopeRow - Scope row.
+   * @param {import("./sync-api-client-types.js").SyncCursor} cursor - Acknowledged cursor.
+   * @returns {Promise<void>}
+   */
+  async saveCursor(scopeRow, cursor) {
+    if (!cursor) return
+
+    await this.ensureReady()
+
+    const cursorPayload = JSON.stringify(cursor)
+
+    if (this._usesMemoryStorage()) {
+      const memoryScope = this._memoryScopes.get(scopeRow.scopeDigest)
+
+      if (!memoryScope) throw new Error(`No sync scope found for: ${scopeRow.scopeDigest}`)
+
+      memoryScope.cursorPayload = cursorPayload
+      return
+    }
+
+    await this._withDb(async (db) => {
+      await db.update({
+        conditions: {scope_digest: scopeRow.scopeDigest},
+        data: {cursor_json: cursorPayload, updated_at: new Date()},
+        tableName: TABLE_NAME
+      })
+    })
+  }
+
+  /**
+   * Deactivates the scope row for a serialized scope.
+   * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
+   * @returns {Promise<void>}
+   */
+  async deactivate(scope) {
+    await this.ensureReady()
+
+    const digest = scopeDigestForScope(scope)
+
+    if (this._usesMemoryStorage()) {
+      const memoryScope = this._memoryScopes.get(digest)
+
+      if (memoryScope) memoryScope.state = "removed"
+
+      return
+    }
+
+    await this._withDb(async (db) => {
+      await db.update({conditions: {scope_digest: digest}, data: {state: "removed", updated_at: new Date()}, tableName: TABLE_NAME})
+    })
+  }
+
+  /**
+   * Whether the store runs without a configured database.
+   * @returns {boolean} Whether memory storage is used.
+   */
+  _usesMemoryStorage() {
+    try {
+      return !this.configuration.getDatabaseConfiguration()[this.databaseIdentifier]
+    } catch {
+      return true
+    }
+  }
+
+  /**
+   * Runs a callback with a database connection.
+   * @template Result
+   * @param {(db: import("../database/drivers/base.js").default) => Promise<Result>} callback - Database callback.
+   * @returns {Promise<Result>} Callback result.
+   */
+  async _withDb(callback) {
+    return await this.configuration.ensureConnections({name: "Sync scope store"}, async (dbs) => {
+      const db = dbs[this.databaseIdentifier]
+
+      if (!db) throw new Error(`No database connection available for identifier: ${this.databaseIdentifier}`)
+
+      return await callback(db)
+    })
+  }
+
+  /**
+   * Ensures the scopes table exists.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>}
+   */
+  async _ensureScopesTable(db) {
+    if (await db.tableExists(TABLE_NAME)) return
+
+    const table = new TableData(TABLE_NAME, {ifNotExists: true})
+
+    table.string("id", {null: false, primaryKey: true})
+    table.string("scope_digest", {index: true, null: false})
+    table.string("resource_type", {index: true, null: false})
+    table.text("conditions_json", {null: false})
+    table.text("cursor_json", {null: true})
+    table.string("state", {index: true, null: false})
+    table.datetime("created_at", {null: false})
+    table.datetime("updated_at", {null: false})
+
+    await db.createTable(table)
+  }
+
+  /**
+   * Resolves a scope row by its digest.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string} digest - Fixed-size scope digest.
+   * @returns {Promise<SyncScopeRow | null>} Scope row or null.
+   */
+  async _rowByScopeDigest(db, digest) {
+    const rows = /** @type {Array<Record<string, ?>>} */ (await db
+      .newQuery()
+      .from(TABLE_NAME)
+      .where({scope_digest: digest})
+      .limit(1)
+      .results())
+
+    return rows[0] ? this._normalizeScopeRow(rows[0]) : null
+  }
+
+  /**
+   * Normalizes a raw scope table row.
+   * @param {Record<string, ?>} row - Raw table row.
+   * @returns {SyncScopeRow} Normalized scope row.
+   */
+  _normalizeScopeRow(row) {
+    return {
+      conditions: /** @type {Record<string, ?>} */ (JSON.parse(String(row.conditions_json))),
+      cursorPayload: row.cursor_json === null || row.cursor_json === undefined ? null : String(row.cursor_json),
+      id: String(row.id),
+      resourceType: String(row.resource_type),
+      scopeDigest: String(row.scope_digest),
+      state: String(row.state)
+    }
+  }
+}