@knowlearning/agents 0.9.187 → 0.9.189

package/agents/attach-synced.js

@@ -0,0 +1,56 @@
+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 }) => {
+      if (!patch) return
+      ctx.applyingExternalUpdate = true
+      applyPatch(resolvedProxy, standardJSONPatch(patch))
+      ctx.applyingExternalUpdate = false
+      syncCallbacks.forEach(cb => cb(resolvedProxy, patch))
+    })
+  }
+
+  function resolve(proxy, key) {
+    resolvedProxy = proxy
+    resolvedKey = key
+    if (shouldSync) registerSyncWatcher()
+  }
+
+  const promise = init(ctx, resolve)
+
+  promise.synced = function(callback) {
+    shouldSync = true
+    if (callback) syncCallbacks.push(callback)
+    if (resolvedProxy) registerSyncWatcher()
+    return promise
+  }
+
+  return promise
+}

package/agents/embedded.js

@@ -1,6 +1,8 @@
 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'
 
 export default function EmbeddedAgent(postMessage) {
   let messageIndex = 0
@@ -95,18 +97,27 @@ 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}`
+      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'))
+        interact(scope, activePatch)
+      })
+      resolveSync(proxy, key)
+      return proxy
+    })())
   }
 
   function reset(scope) {
@@ -227,6 +238,7 @@ export default function EmbeddedAgent(postMessage) {
     synced,
     close,
     response,
+    sync,
     query
   }
 }

package/agents/generic/index.js

@@ -4,6 +4,7 @@ import messageQueue from './message-queue.js'
 import stateImplementation from './state.js'
 import watchImplementation from '../watch.js'
 import downloadImplementation from '../download.js'
+import sync from '../sync.js'
 
 // TODO: consider using something better than name as mechanism
 //       for resoling default scope in context
@@ -229,6 +230,7 @@ export default function Agent({ Connection, domain, token, sid, uuid, fetch, app
     debug,
     guarantee,
     response,
+    sync,
     on
   }
 }

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 }) {
   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,20 @@ export default function(scope='[]', user, domain, { keyToSubscriptionId, watcher
       const active = data.active
       delete data.active
       resolveMetadataPromise(data)
-      resolveState(new PatchProxy(active || {}, patch => {
+      const proxy = new PatchProxy(active || {}, patch => {
+        if (ctx.applyingExternalUpdate) return
         const activePatch = structuredClone(patch)
         activePatch.forEach(entry => entry.path.unshift('active'))
         interact(scope, activePatch)
-      }))
+      })
+      resolveSync(proxy, qualifiedScope)
+      resolveState(proxy)
     }
     catch (error) {
       rejectState(error)
     }
-  })
+  }))
 
   statePromise.metadata = metadataPromise
   return statePromise
-}
+}

package/agents/sync.js

@@ -0,0 +1,7 @@
+import { compare, applyPatch } from 'fast-json-patch'
+
+export default function sync(state, target) {
+  const patch = compare(state, target)
+  applyPatch(state, patch, true, true)
+  return { patch }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowlearning/agents",
-  "version": "0.9.187",
+  "version": "0.9.189",
   "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>;