@knowlearning/agents 0.9.188 → 0.9.190

package/agents/attach-synced.js

@@ -0,0 +1,83 @@
+import { applyPatch } from 'fast-json-patch'
+import { standardJSONPatch } from '@knowlearning/patch-proxy'
+
+// Wraps a state promise with a .synced(callback?) method that applies external
+// patches to the live proxy in-place.
+//
+// Usage:
+//   const promise = attachSynced(watchers, (ctx, resolve) => {
+//     const p = new Promise(async (...) => {
+//       const proxy = new PatchProxy(data, patch => {
+//         if (ctx.applyingExternalUpdate) return
+//         // ... interact
+//       })
+//       resolve(proxy, qualifiedKey)
+//       resolvePromise(proxy)
+//     })
+//     return p
+//   })
+export default function attachSynced(watchers, init) {
+  const ctx = { applyingExternalUpdate: false }
+  let shouldSync = false
+  let syncCallbacks = []
+  let syncRegistered = false
+  let resolvedProxy = null
+  let resolvedKey = null
+
+  function registerSyncWatcher() {
+    if (syncRegistered) return
+    syncRegistered = true
+    if (!watchers[resolvedKey]) watchers[resolvedKey] = []
+    watchers[resolvedKey].push(({ patch, state, ii }) => {
+      if (!patch) return
+      const pending = ctx.pendingInteractions?.size
+        ? Promise.all(ctx.pendingInteractions)
+        : Promise.resolve()
+      pending.then(() => {
+        const isOwn = ctx.ownInteractions?.has(ii)
+        const echoBatch = isOwn ? ctx.ownInteractionBatches?.get(ii) : null
+        if (isOwn) {
+          ctx.ownInteractions.delete(ii)
+          if (echoBatch) ctx.ownInteractionBatches.delete(ii)
+        } else {
+          ctx.applyingExternalUpdate = true
+          applyPatch(resolvedProxy, standardJSONPatch(patch))
+          ctx.applyingExternalUpdate = false
+        }
+        if (echoBatch) {
+          echoBatch.state = state
+          if (echoBatch.remaining !== undefined) echoBatch.remaining -= 1
+          if ((echoBatch.remaining === undefined || echoBatch.remaining === 0) && !echoBatch.resolved) {
+            echoBatch.resolved = true
+            syncCallbacks.forEach(cb => cb(echoBatch.state, patch))
+            echoBatch.resolve()
+          }
+          return
+        }
+        syncCallbacks.forEach(cb => cb(state, patch))
+        if (isOwn && ctx.echoResolvers?.length) {
+          ctx.echoResolvers.shift()()
+        }
+      })
+    })
+  }
+
+  function resolve(proxy, key) {
+    resolvedProxy = proxy
+    resolvedKey = key
+    if (shouldSync) registerSyncWatcher()
+  }
+
+  const promise = init(ctx, resolve)
+
+  promise.synced = function(callback) {
+    shouldSync = true
+    ctx.syncActive = true
+    if (!ctx.echoResolvers) ctx.echoResolvers = []
+    if (callback) syncCallbacks.push(callback)
+    if (resolvedProxy) registerSyncWatcher()
+    return promise
+  }
+
+  return promise
+}

package/agents/embedded.js

@@ -1,5 +1,6 @@
 import { validate as isUUID, v1 as uuid } from 'uuid'
 import PatchProxy from '@knowlearning/patch-proxy'
+import attachSynced from './attach-synced.js'
 import watchImplementation from './watch.js'
 import sync from './sync.js'
 
@@ -10,6 +11,7 @@ export default function EmbeddedAgent(postMessage) {
   const responses = {}
   const watchers = {}
   const sentUpdates = {}
+  const pendingEchoCallbacks = new Set()
 
   const [ watch, removeWatcher ] = watchImplementation({ metadata, state, watchers, synced, sentUpdates, environment })
 
@@ -96,18 +98,63 @@ export default function EmbeddedAgent(postMessage) {
     return send({ type: 'patch', root, scopes })
   }
 
-  async function state(scope, user, domain) {
-    if (scope === undefined) {
-      const { context } = await environment()
-      scope = JSON.stringify(context)
-    }
-    const startState = await send({ type: 'state', scope, user, domain })
-    return new PatchProxy(startState, patch => {
-      //  TODO: reject updates if user is not owner
-      const activePatch = structuredClone(patch)
-      activePatch.forEach(entry => entry.path.unshift('active'))
-      interact(scope, activePatch)
-    })
+  function state(scope, user, domain) {
+    return attachSynced(watchers, (ctx, resolveSync) => (async () => {
+      if (scope === undefined) {
+        const { context } = await environment()
+        scope = JSON.stringify(context)
+      }
+      const startState = await send({ type: 'state', scope, user, domain })
+      const { auth, domain: rootDomain } = await environment()
+      const d = !domain || domain === rootDomain ? '' : domain
+      const u = !user || auth.user === user ? '' : user
+      const key = isUUID(scope) ? scope : `${d}/${u}/${scope}`
+      if (!ctx.ownInteractions) ctx.ownInteractions = new Set()
+      if (!ctx.ownInteractionBatches) ctx.ownInteractionBatches = new Map()
+      if (!ctx.pendingInteractions) ctx.pendingInteractions = new Set()
+      if (!ctx.echoResolvers) ctx.echoResolvers = []
+      let currentEchoBatch = null
+      const proxy = new PatchProxy(startState, patch => {
+        //  TODO: reject updates if user is not owner
+        if (ctx.applyingExternalUpdate) return
+        const activePatch = structuredClone(patch)
+        activePatch.forEach(entry => entry.path.unshift('active'))
+        let echoBatch
+        if (ctx.syncActive) {
+          if (!currentEchoBatch) {
+            let resolveEcho
+            const echoPromise = new Promise(r => resolveEcho = r)
+            echoBatch = currentEchoBatch = { remaining: 0, resolve: resolveEcho, resolved: false }
+            pendingEchoCallbacks.add(echoPromise)
+            echoPromise.then(() => pendingEchoCallbacks.delete(echoPromise))
+            Promise.resolve().then(() => { currentEchoBatch = null })
+          }
+          else echoBatch = currentEchoBatch
+          echoBatch.remaining += 1
+        }
+        const interactPromise = interact(scope, activePatch)
+        const p = interactPromise.then(
+          r => {
+            ctx.ownInteractions.add(r.ii)
+            if (echoBatch) ctx.ownInteractionBatches.set(r.ii, echoBatch)
+            ctx.pendingInteractions.delete(p)
+          },
+          () => {
+            if (echoBatch) {
+              echoBatch.remaining -= 1
+              if (echoBatch.remaining === 0 && !echoBatch.resolved) {
+                echoBatch.resolved = true
+                echoBatch.resolve()
+              }
+            }
+            ctx.pendingInteractions.delete(p)
+          }
+        )
+        ctx.pendingInteractions.add(p)
+      })
+      resolveSync(proxy, key)
+      return proxy
+    })())
   }
 
   function reset(scope) {
@@ -203,7 +250,11 @@ export default function EmbeddedAgent(postMessage) {
   function logout() { return send({ type: 'logout' }) }
   function disconnect() { return send({ type: 'disconnect' }) }
   function reconnect() { return send({ type: 'reconnect' }) }
-  function synced() { return send({ type: 'synced' }) }
+  async function synced() {
+    const echoSnapshot = [...pendingEchoCallbacks]
+    await send({ type: 'synced' })
+    if (echoSnapshot.length) await Promise.all(echoSnapshot)
+  }
   function close(info) { return send({ type: 'close', info }) }
   function guarantee(script, namespaces, context) { return send({ type: 'guarantee', script, namespaces, context }) }
   function response(id=lastRequestId) { return send({ type: 'response', id }) }

package/agents/generic/index.js

@@ -17,6 +17,7 @@ export default function Agent({ Connection, domain, token, sid, uuid, fetch, app
   const watchers = {}
   const keyToSubscriptionId = {}
   const lastInteractionResponse = {}
+  const pendingEchoCallbacks = new Set()
 
   log('INITIALIZING AGENT CONNECTION')
   const [
@@ -47,6 +48,7 @@ export default function Agent({ Connection, domain, token, sid, uuid, fetch, app
     interact,
     fetch,
     synced,
+    pendingEchoCallbacks,
     metadata,
     log
   }
@@ -204,6 +206,12 @@ export default function Agent({ Connection, domain, token, sid, uuid, fetch, app
     }
   }
 
+  async function syncedWithEchoCallbacks() {
+    const echoSnapshot = [...pendingEchoCallbacks]
+    await synced()
+    if (echoSnapshot.length) await Promise.all(echoSnapshot)
+  }
+
   function response() {
     return lastMessageResponse()
   }
@@ -224,7 +232,7 @@ export default function Agent({ Connection, domain, token, sid, uuid, fetch, app
     reset,
     metadata,
     query,
-    synced,
+    synced: syncedWithEchoCallbacks,
     disconnect,
     reconnect,
     debug,

package/agents/generic/state.js

@@ -1,11 +1,12 @@
 import { v4 as uuid, validate as isUUID } from 'uuid'
 import PatchProxy from '@knowlearning/patch-proxy'
+import attachSynced from '../attach-synced.js'
 
-export default function(scope='[]', user, domain, { keyToSubscriptionId, watchers, states, create, environment, lastMessageResponse, lastInteractionResponse, interact, log }) {
+export default function(scope='[]', user, domain, { keyToSubscriptionId, watchers, states, create, environment, lastMessageResponse, lastInteractionResponse, interact, pendingEchoCallbacks, log }) {
   let resolveMetadataPromise
   let metadataPromise = new Promise(resolve => resolveMetadataPromise = resolve)
 
-  const statePromise = new Promise(async (resolveState, rejectState) => {
+  const statePromise = attachSynced(watchers, (ctx, resolveSync) => new Promise(async (resolveState, rejectState) => {
     const { auth: { user: u }, domain: d, session } = await environment()
 
     const qualifiedScope = isUUID(scope) ? scope : `${!domain || domain === d ? '' : domain}/${!user || user === u ? '' : user}/${scope}`
@@ -35,17 +36,52 @@ export default function(scope='[]', user, domain, { keyToSubscriptionId, watcher
       const active = data.active
       delete data.active
       resolveMetadataPromise(data)
-      resolveState(new PatchProxy(active || {}, patch => {
+      if (!ctx.ownInteractions) ctx.ownInteractions = new Set()
+      if (!ctx.ownInteractionBatches) ctx.ownInteractionBatches = new Map()
+      if (!ctx.pendingInteractions) ctx.pendingInteractions = new Set()
+      if (!ctx.echoResolvers) ctx.echoResolvers = []
+      let currentEchoBatch = null
+      const proxy = new PatchProxy(active || {}, patch => {
+        if (ctx.applyingExternalUpdate) return
         const activePatch = structuredClone(patch)
         activePatch.forEach(entry => entry.path.unshift('active'))
-        interact(scope, activePatch)
-      }))
+        let echoBatch
+        if (ctx.syncActive && pendingEchoCallbacks) {
+          if (!currentEchoBatch) {
+            let resolveEcho
+            const echoPromise = new Promise(r => resolveEcho = r)
+            echoBatch = currentEchoBatch = { resolve: resolveEcho, resolved: false }
+            pendingEchoCallbacks.add(echoPromise)
+            echoPromise.then(() => pendingEchoCallbacks.delete(echoPromise))
+            Promise.resolve().then(() => { currentEchoBatch = null })
+          }
+          else echoBatch = currentEchoBatch
+        }
+        const interactPromise = interact(scope, activePatch)
+        const p = interactPromise.then(
+          r => {
+            ctx.ownInteractions.add(r.ii)
+            if (echoBatch) ctx.ownInteractionBatches.set(r.ii, echoBatch)
+            ctx.pendingInteractions.delete(p)
+          },
+          () => {
+            if (echoBatch && !echoBatch.resolved) {
+              echoBatch.resolved = true
+              echoBatch.resolve()
+            }
+            ctx.pendingInteractions.delete(p)
+          }
+        )
+        ctx.pendingInteractions.add(p)
+      })
+      resolveSync(proxy, qualifiedScope)
+      resolveState(proxy)
     }
     catch (error) {
       rejectState(error)
     }
-  })
+  }))
 
   statePromise.metadata = metadataPromise
   return statePromise
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowlearning/agents",
-  "version": "0.9.188",
+  "version": "0.9.190",
   "description": "API for embedding applications in KnowLearning systems.",
   "main": "node.js",
   "browser": "browser.js",

package/types.d.ts

@@ -27,11 +27,16 @@ export interface AgentUploadInfo {
   accept?: string;
 }
 
+export interface SyncedStatePromise extends Promise<object> {
+  synced(callback?: (state: object, patch: object[]) => void): SyncedStatePromise;
+  metadata: Promise<object>;
+}
+
 export interface Agent {
   login(provider: string): void;
   logout(): void;
   uuid(): string;
-  state(id: string, user?: string, domain?: string): Promise<object>;
+  state(id: string, user?: string, domain?: string): SyncedStatePromise;
   metadata(id: string, user?: string, domain?: string): Promise<object>;
   watch(id: string, callback: (update: { state: object }) => void, user?: string, domain?: string): void;
   upload(info?: AgentUploadInfo): Promise<string>;