@mblaney/holster 2.2.3 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mblaney/holster",
-  "version": "2.2.3",
+  "version": "2.3.1",
   "description": "Holster is a service that allows synchronising data between devices using Node, Deno, Bun or the browser.",
   "type": "module",
   "main": "index.js",

package/src/holster.js

@@ -73,17 +73,31 @@ const Holster = opt => {
     const data = await new Promise(res => {
       const _ctxid = utils.text.random()
       allctx.set(_ctxid, {chain: [{item: null, soul: id}], user: ctxUser})
-      api(_ctxid).next(
-        null,
-        res,
-        retries === 0 ? utils.obj.put(_opt, "fast", true) : _opt,
-      )
+      api(_ctxid).next(null, res, _opt)
     })
     if (data !== null || retries >= 5) return data
     await new Promise(resolve => setTimeout(resolve, 50))
     return readRelTarget(id, ctxUser, _opt, retries + 1)
   }
 
+  // Wraps a not-yet-terminal chain object (api(ctxid), returned wherever no
+  // callback was given to resolve it yet) with a .then, so awaiting it
+  // resolves the same way a callback given right here would - mirrors
+  // readRelTarget's own api(ctxid).next(null, cb) idiom, which resolves the
+  // current chain without pushing a new key onto it. There's no separate
+  // error channel on this path (get/next's own callback only ever receives
+  // a value, never an error), so reject is simply never called - a
+  // rejection-less promise is still a valid one. Deliberately only applied
+  // at these specific "chain not yet resolved" return points, not to
+  // api()'s own bare object (see holster.user(), which Object.assigns that
+  // onto the long-lived user object) - that object has no chain to resolve
+  // at all, and giving user itself a .then would make a bare `await user`
+  // (or passing it to Promise.all, etc) silently try to resolve one.
+  const awaitable = chainApi => ({
+    ...chainApi,
+    then: resolve => chainApi.next(null, resolve),
+  })
+
   const api = ctxid => {
     const get = (lex, soul, ack, _opt) => {
       wire.get(
@@ -412,7 +426,7 @@ const Holster = opt => {
         // to be objects.
         ctxid = utils.text.random()
         allctx.set(ctxid, {chain: [{item: String(key), soul: "root"}], cb: cb})
-        if (!cb) return api(ctxid)
+        if (!cb) return awaitable(api(ctxid))
 
         const _done = done(ctxid)
         // When there's a callback need to resolve the context first.
@@ -467,7 +481,7 @@ const Holster = opt => {
         // Push the key to the context as it needs a soul lookup.
         // (null is used to call the api with updated context)
         if (key !== null) ctx.chain.push({item: String(key), soul: null})
-        if (!ctx.cb) return api(ctxid)
+        if (!ctx.cb) return awaitable(api(ctxid))
 
         // When there's a callback need to resolve the context first.
         const {soul} = resolve({get: lex, _opt: _opt}, _ack)
@@ -478,6 +492,25 @@ const Holster = opt => {
           cb = set
           set = false
         }
+        // Unlike get/next (see awaitable above), put's own callback always
+        // receives an error channel - an error string, or undefined on
+        // success - so a promise here can reject, not just resolve.
+        if (!cb) {
+          const promise = new Promise((resolve, reject) => {
+            api(ctxid).put(data, set, err =>
+              err ? reject(new Error(err)) : resolve(),
+            )
+          })
+          // A caller using the old fire-and-forget idiom (put(data) with
+          // no callback, result never touched) shouldn't crash the
+          // process on an unhandled rejection if something genuinely
+          // fails now that this returns a promise - doesn't suppress the
+          // rejection for a caller that does await/catch it, since a
+          // promise can have more than one handler attached (same
+          // pattern as createRel's own promise above).
+          promise.catch(() => {})
+          return promise
+        }
         const ack = ctxid => {
           return data => {
             if (cb) {
@@ -619,13 +652,14 @@ const Holster = opt => {
 
                   const _ctxid = utils.text.random()
                   const chain = [{item: item, soul: soul}]
-                  // Pass on the previous ctx's callback and user flag here.
-                  allctx.set(_ctxid, {
-                    chain: chain,
-                    user: ctx.user,
-                    cb: ctx.cb,
-                  })
-                  api(_ctxid).put(data)
+                  allctx.set(_ctxid, {chain: chain, user: ctx.user})
+                  // Pass on the previous ctx's own callback (if any)
+                  // positionally rather than pre-registering it via
+                  // allctx - otherwise it's invisible to put's own "no cb
+                  // given" check above, which would then wrap this retry
+                  // in a brand new promise competing with (and never
+                  // actually calling) the real one.
+                  api(_ctxid).put(data, ctx.cb)
                 })
                 return
               }
@@ -952,7 +986,7 @@ const Holster = opt => {
             ctxid = utils.text.random()
             const chain = [{item: String(key), soul: "~" + pub}]
             allctx.set(ctxid, {chain: chain, user: user.is, cb: cb})
-            if (!cb) return api(ctxid)
+            if (!cb) return awaitable(api(ctxid))
 
             // When there's a callback need to resolve the context first.
             const _done = done(ctxid)

package/src/wire.js

@@ -534,12 +534,12 @@ const Wire = opt => {
       return
     }
 
-    store.get(lex, (err, ack) => {
-      if (ack) {
+    store.get(lex, (err, stored) => {
+      if (stored) {
         // Populate in-memory graph from store data before sending the server
         // request, so stale server responses with older state are correctly
         // rejected by ham.mix.
-        for (const [soul, node] of Object.entries(ack)) {
+        for (const [soul, node] of Object.entries(stored)) {
           if (!node) continue
           if (!graph[soul]) {
             graph[soul] = {...node}
@@ -567,40 +567,44 @@ const Wire = opt => {
           }
         }
         // Full-node fetch: the graph is now complete for this soul.
-        if (!lex["."] && ack[lex["#"]]) hasNode.add(lex["#"])
-        // Only serve from store if the requested property is present.
-        const node = ack[lex["#"]]
-        const hasProperty =
-          node &&
-          Object.keys(node).some(
-            key => key !== "_" && utils.match(lex["."], key),
-          )
-        if (hasProperty) {
-          // Public keys are immutable once written — never need a wire check.
-          if (!isNode && lex["."] !== utils.userPublicKey) {
-            if (!lex["."] || typeof lex["."] === "string") {
-              const checkKey = lex["#"] + (lex["."] ? "." + lex["."] : "")
-              const now = Date.now()
-              const lastCheck = recentChecks.get(checkKey)
-              if (!lastCheck || now - lastCheck > recentCheckTTL) {
-                recentChecks.set(checkKey, now)
-                const sendResult = send(request)
-                if (sendResult && sendResult.err) {
-                  cb({err: sendResult.err})
-                  return
-                }
-              }
-            } else {
+        if (!lex["."] && stored[lex["#"]]) hasNode.add(lex["#"])
+      }
+
+      // Answered from the graph rather than the raw store result: the merge
+      // above keeps any newer in-memory values, so a local put that store
+      // hasn't finished persisting yet is still included, while everything
+      // already on disk fills in the rest of the node.
+      const ack = {...stored, ...Get(lex, graph, true)}
+      // Only serve locally if the requested property is present.
+      const node = ack[lex["#"]]
+      const hasProperty =
+        node &&
+        Object.keys(node).some(key => key !== "_" && utils.match(lex["."], key))
+      if (hasProperty) {
+        // Public keys are immutable once written - never need a wire check.
+        if (!isNode && lex["."] !== utils.userPublicKey) {
+          if (!lex["."] || typeof lex["."] === "string") {
+            const checkKey = lex["#"] + (lex["."] ? "." + lex["."] : "")
+            const now = Date.now()
+            const lastCheck = recentChecks.get(checkKey)
+            if (!lastCheck || now - lastCheck > recentCheckTTL) {
+              recentChecks.set(checkKey, now)
               const sendResult = send(request)
               if (sendResult && sendResult.err) {
                 cb({err: sendResult.err})
                 return
               }
             }
+          } else {
+            const sendResult = send(request)
+            if (sendResult && sendResult.err) {
+              cb({err: sendResult.err})
+              return
+            }
           }
-          cb(err ? {put: ack, err: err} : {put: ack})
-          return
         }
+        cb(err ? {put: ack, err: err} : {put: ack})
+        return
       }
 
       // Data wasn't found locally, log errors and call back after a timeout.
@@ -678,17 +682,6 @@ const Wire = opt => {
           return
         }
 
-        // Ham.mix has already merged this locally-authored update into
-        // graph[soul], synchronously, before store.put below even starts
-        // persisting it - mark it as fully known now rather than waiting
-        // for a future disk fetch to do so, so a read landing in that
-        // window doesn't get forced through a disk round-trip that could
-        // itself race ahead of this same write and find nothing, even
-        // though the correct answer was already sitting in memory.
-        for (const soul of Object.keys(update.now)) {
-          hasNode.add(soul)
-        }
-
         if (opt.userLimit) {
           for (const [soul, node] of Object.entries(update.now)) {
             const pub = node[utils.userPublicKey]

package/ts/src/get.ts

@@ -59,9 +59,10 @@ const Get = (lex: Lex, graph: Graph, fast?: boolean): Graph | undefined => {
     // return undefined to ensure we get all matching properties from store.
     if (!fast) return undefined
 
+    let found = false
     for (const key of Object.keys(graph[soul]!)) {
       // Always include userPublicKey for verification, regardless of filter
-      if (key === userPublicKey || match(lex["."], key)) {
+      if (key !== "_" && (key === userPublicKey || match(lex["."], key))) {
         node[key] = graph[soul]![key]!
         node._[">"][key] = graph[soul]!._[">"][key]!
         const state = graph[soul]!._[">"][key]!
@@ -69,8 +70,10 @@ const Get = (lex: Lex, graph: Graph, fast?: boolean): Graph | undefined => {
         if (sigs && sigs[state]) {
           signatures[state.toString()] = sigs[state]!
         }
+        found = true
       }
     }
+    if (!found) return undefined
   }
 
   if (Object.keys(signatures).length > 0) {

package/ts/src/holster.ts

@@ -28,34 +28,54 @@ export interface HolsterAPI {
   get: {
     (
       key: string | null,
-      lex?: LexWithDot,
-      cb?: (data: unknown) => void,
+      lex: LexWithDot,
+      cb: (data: unknown) => void,
       _opt?: WireOptions,
     ): HolsterAPI
     (
       key: string | null,
-      cb?: (data: unknown) => void,
+      cb: (data: unknown) => void,
       _opt?: WireOptions,
     ): HolsterAPI
+    (
+      key: string | null,
+      lex?: LexWithDot,
+      _opt?: WireOptions,
+    ): AwaitableHolsterAPI
   }
   next: {
     (
       key: string | null,
-      lex?: LexWithDot,
-      cb?: (data: unknown) => void,
+      lex: LexWithDot,
+      cb: (data: unknown) => void,
       _opt?: WireOptions,
     ): HolsterAPI
     (
       key: string | null,
-      cb?: (data: unknown) => void,
+      cb: (data: unknown) => void,
       _opt?: WireOptions,
     ): HolsterAPI
+    (
+      key: string | null,
+      lex?: LexWithDot,
+      _opt?: WireOptions,
+    ): AwaitableHolsterAPI
+  }
+  put: {
+    (
+      data: GraphValue | Record<string, GraphValue>,
+      set: boolean,
+      cb: (data?: string | null) => void,
+    ): void
+    (
+      data: GraphValue | Record<string, GraphValue>,
+      cb: (data?: string | null) => void,
+    ): void
+    (
+      data: GraphValue | Record<string, GraphValue>,
+      set?: boolean,
+    ): Promise<void>
   }
-  put: (
-    data: GraphValue | Record<string, GraphValue>,
-    set?: boolean | ((data?: string | null) => void),
-    cb?: (data?: string | null) => void,
-  ) => HolsterAPI | void
   on: {
     (
       lex: LexWithDot,
@@ -71,6 +91,23 @@ export interface HolsterAPI {
   SEA: typeof SEA
 }
 
+// Deliberately not the built-in PromiseLike<T> - that also requires a
+// return value and an onrejected param awaitable's own then() never uses
+// (there's no separate error channel on this path, see awaitable's own
+// comment). TS's Awaited<T> only needs a callable then(onfulfilled, ...)
+// to recognize something as thenable - this minimal shape is enough for
+// `await` to work and to correctly infer the resolved type as unknown.
+interface Thenable {
+  then: (resolve: (data: unknown) => void) => void
+}
+
+// A chain object (api(ctxid), returned wherever no callback was given to
+// resolve it yet) with a .then added, so `await`-ing it resolves the same
+// way a callback given right here would (see awaitable in holster.ts).
+// Only the "no callback given" get/next overloads above return this -
+// the "has a real callback" ones genuinely don't have a .then.
+export type AwaitableHolsterAPI = HolsterAPI & Thenable
+
 const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
   let options: HolsterOptions
   if (typeof opt === "string") options = {peers: [opt]}
@@ -145,17 +182,32 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
     const data = await new Promise<unknown>(res => {
       const _ctxid = utils.text.random()
       allctx.set(_ctxid, {chain: [{item: null, soul: id}], user: ctxUser})
-      api(_ctxid).next(
-        null as never,
-        res as never,
-        (retries === 0 ? utils.obj.put(opt, "fast", true) : opt) as never,
-      )
+      api(_ctxid).next(null as never, res as never, opt as never)
     })
     if (data !== null || retries >= 5) return data
     await new Promise(resolve => setTimeout(resolve, 50))
     return readRelTarget(id, ctxUser, opt, retries + 1)
   }
 
+  // Wraps a not-yet-terminal chain object (api(ctxid), returned wherever no
+  // callback was given to resolve it yet) with a .then, so awaiting it
+  // resolves the same way a callback given right here would - mirrors
+  // readRelTarget's own api(ctxid).next(null, cb) idiom, which resolves the
+  // current chain without pushing a new key onto it. There's no separate
+  // error channel on this path (get/next's own callback only ever receives
+  // a value, never an error), so reject is simply never called - a
+  // rejection-less promise is still a valid one. Deliberately only applied
+  // at these specific "chain not yet resolved" return points, not to
+  // api()'s own bare object (see holster.user(), which Object.assigns that
+  // onto the long-lived user object) - that object has no chain to resolve
+  // at all, and giving user itself a .then would make a bare `await user`
+  // (or passing it to Promise.all, etc) silently try to resolve one.
+  const awaitable = (chainApi: HolsterAPI): AwaitableHolsterAPI => ({
+    ...chainApi,
+    then: (resolve: (data: unknown) => void) =>
+      chainApi.next(null, resolve as never),
+  })
+
   const api = (initCtxid?: string): HolsterAPI => {
     let ctxid = initCtxid
     const get = (
@@ -559,7 +611,7 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
           chain: [{item: String(key), soul: "root"}],
           cb: callback,
         })
-        if (!callback) return api(ctxid)
+        if (!callback) return awaitable(api(ctxid))
 
         const _done = done(ctxid)
         const result = resolve({get: lexFilter, _opt: opts}, _done)
@@ -624,7 +676,7 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
         }
 
         if (key !== null) ctx.chain.push({item: String(key), soul: null})
-        if (!ctx.cb) return api(ctxid)
+        if (!ctx.cb) return awaitable(api(ctxid))
 
         const result = resolve({get: lexFilter, _opt: opts}, _ack)
         if (result) get(lexFilter as never, result.soul!, _ack, opts)
@@ -635,7 +687,7 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
         data: GraphValue | Record<string, GraphValue>,
         set?: boolean | ((data?: string | null) => void),
         cb?: (data?: string | null) => void,
-      ): HolsterAPI | void {
+      ): void | Promise<void> {
         let isSet = false
         let callback: ((data?: string | null) => void) | undefined
 
@@ -647,6 +699,26 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
           callback = cb
         }
 
+        // Unlike get/next (see awaitable above), put's own callback always
+        // receives an error channel - an error string, or undefined on
+        // success - so a promise here can reject, not just resolve.
+        if (!callback) {
+          const promise = new Promise<void>((promiseResolve, reject) => {
+            api(ctxid).put(data, isSet, err =>
+              err ? reject(new Error(err)) : promiseResolve(),
+            )
+          })
+          // A caller using the old fire-and-forget idiom (put(data) with
+          // no callback, result never touched) shouldn't crash the
+          // process on an unhandled rejection if something genuinely
+          // fails now that this returns a promise - doesn't suppress the
+          // rejection for a caller that does await/catch it, since a
+          // promise can have more than one handler attached (same
+          // pattern as createRel's own promise above).
+          promise.catch(() => {})
+          return promise
+        }
+
         const ack = (ctxid: string) => {
           return (data?: string | null): void => {
             if (callback) {
@@ -797,12 +869,14 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
 
                   const _ctxid = utils.text.random()
                   const chain: ChainItem[] = [{item: item!, soul: soul}]
-                  allctx.set(_ctxid, {
-                    chain: chain,
-                    user: ctx.user,
-                    cb: ctx.cb,
-                  })
-                  api(_ctxid).put(data)
+                  allctx.set(_ctxid, {chain: chain, user: ctx.user})
+                  // Pass on the previous ctx's own callback (if any)
+                  // positionally rather than pre-registering it via
+                  // allctx - otherwise it's invisible to put's own "no cb
+                  // given" check above, which would then wrap this retry
+                  // in a brand new promise competing with (and never
+                  // actually calling) the real one.
+                  api(_ctxid).put(data, ctx.cb as never)
                 })
                 return
               }
@@ -864,7 +938,7 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
           )
         }
         attemptRead()
-      },
+      } as HolsterAPI["put"],
 
       on: function (
         lex: LexWithDot | ((data: unknown) => void),
@@ -1199,7 +1273,7 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
               user: user.is,
               cb: callback as never,
             })
-            if (!callback) return api(ctxid)
+            if (!callback) return awaitable(api(ctxid))
 
             const _done = done(ctxid)
             const resolved = resolve({get: lexFilter, _opt: opts}, _done)

package/ts/src/user.ts

@@ -12,7 +12,7 @@ import type {
   LexFilter,
   WireOptions,
 } from "./schemas.ts"
-import type {HolsterAPI} from "./holster.ts"
+import type {HolsterAPI, AwaitableHolsterAPI} from "./holster.ts"
 
 type WireInterface = ReturnType<typeof Wire>
 
@@ -42,12 +42,24 @@ export interface UserInterface {
     password: string,
     cb?: (err?: string | null) => void,
   ) => void
-  get?(
-    keys: string | string[],
-    lex?: LexFilter | ((data: unknown) => void),
-    cb?: ((data: unknown) => void) | WireOptions,
-    _opt?: WireOptions,
-  ): HolsterAPI
+  get?: {
+    (
+      keys: string | string[],
+      lex: LexFilter,
+      cb: (data: unknown) => void,
+      _opt?: WireOptions,
+    ): HolsterAPI
+    (
+      keys: string | string[],
+      cb: (data: unknown) => void,
+      _opt?: WireOptions,
+    ): HolsterAPI
+    (
+      keys: string | string[],
+      lex?: LexFilter,
+      _opt?: WireOptions,
+    ): AwaitableHolsterAPI
+  }
 }
 
 /**

package/ts/src/wire.ts

@@ -593,12 +593,12 @@ const Wire = (opt: HolsterOptions): WireAPI => {
       return
     }
 
-    store.get(lex, (err, ack) => {
-      if (ack) {
+    store.get(lex, (err, stored) => {
+      if (stored) {
         // Populate in-memory graph from store data before sending the server
         // request, so stale server responses with older state are correctly
         // rejected by ham.mix.
-        for (const [soul, node] of Object.entries(ack)) {
+        for (const [soul, node] of Object.entries(stored)) {
           if (!node) continue
           if (!graph[soul]) {
             graph[soul] = {...node} as unknown as Graph[string]
@@ -622,40 +622,44 @@ const Wire = (opt: HolsterOptions): WireAPI => {
           }
         }
         // Full-node fetch: the graph is now complete for this soul.
-        if (!lex["."] && ack[lex["#"]]) hasNode.add(lex["#"])
-        // Only serve from store if the requested property is present.
-        const node = ack[lex["#"]]
-        const hasProperty =
-          node &&
-          Object.keys(node).some(
-            key => key !== "_" && utils.match(lex["."], key),
-          )
-        if (hasProperty) {
-          // Public keys are immutable once written — never need a wire check.
-          if (!isNode && lex["."] !== utils.userPublicKey) {
-            if (!lex["."] || typeof lex["."] === "string") {
-              const checkKey = lex["#"] + (lex["."] ? "." + lex["."] : "")
-              const now = Date.now()
-              const lastCheck = recentChecks.get(checkKey)
-              if (!lastCheck || now - lastCheck > recentCheckTTL) {
-                recentChecks.set(checkKey, now)
-                const sendResult = send(request)
-                if (sendResult && sendResult.err) {
-                  cb({err: sendResult.err})
-                  return
-                }
-              }
-            } else {
+        if (!lex["."] && stored[lex["#"]]) hasNode.add(lex["#"])
+      }
+
+      // Answered from the graph rather than the raw store result: the merge
+      // above keeps any newer in-memory values, so a local put that store
+      // hasn't finished persisting yet is still included, while everything
+      // already on disk fills in the rest of the node.
+      const ack = {...stored, ...Get(lex, graph, true)}
+      // Only serve locally if the requested property is present.
+      const node = ack[lex["#"]]
+      const hasProperty =
+        node &&
+        Object.keys(node).some(key => key !== "_" && utils.match(lex["."], key))
+      if (hasProperty) {
+        // Public keys are immutable once written - never need a wire check.
+        if (!isNode && lex["."] !== utils.userPublicKey) {
+          if (!lex["."] || typeof lex["."] === "string") {
+            const checkKey = lex["#"] + (lex["."] ? "." + lex["."] : "")
+            const now = Date.now()
+            const lastCheck = recentChecks.get(checkKey)
+            if (!lastCheck || now - lastCheck > recentCheckTTL) {
+              recentChecks.set(checkKey, now)
               const sendResult = send(request)
               if (sendResult && sendResult.err) {
                 cb({err: sendResult.err})
                 return
               }
             }
+          } else {
+            const sendResult = send(request)
+            if (sendResult && sendResult.err) {
+              cb({err: sendResult.err})
+              return
+            }
           }
-          cb(err ? {put: ack, err: err} : {put: ack})
-          return
         }
+        cb(err ? {put: ack, err: err} : {put: ack})
+        return
       }
 
       if (err) console.log(err)
@@ -725,17 +729,6 @@ const Wire = (opt: HolsterOptions): WireAPI => {
           return
         }
 
-        // Ham.mix has already merged this locally-authored update into
-        // graph[soul], synchronously, before store.put below even starts
-        // persisting it - mark it as fully known now rather than waiting
-        // for a future disk fetch to do so, so a read landing in that
-        // window doesn't get forced through a disk round-trip that could
-        // itself race ahead of this same write and find nothing, even
-        // though the correct answer was already sitting in memory.
-        for (const soul of Object.keys(update.now)) {
-          hasNode.add(soul)
-        }
-
         if (options.userLimit) {
           for (const [soul, node] of Object.entries(update.now)) {
             const pub = node![utils.userPublicKey] as string | undefined