@mblaney/holster 2.2.2 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mblaney/holster",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "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

@@ -84,6 +84,24 @@ const Holster = opt => {
     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 +430,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 +485,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 +496,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 +656,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 +990,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

@@ -497,7 +497,15 @@ const Wire = opt => {
     })
 
     if (ack) {
-      if (!isNode) {
+      // Put requests only need a local answer - skip the wire round-trip
+      // (matches the same check below, once store.get is reached instead
+      // of this fast graph path). Without this, check()'s own bare
+      // full-node lookup - always {put: true} - re-sends on the wire every
+      // time it's called once the soul's been through store.get once (see
+      // hasNode above), and since its own reply re-enters put() and calls
+      // check() again, this becomes a self-sustaining loop: a get every
+      // ~recentCheckTTL, forever, per soul, for every soul ever fetched.
+      if (!isNode && !_opt.put) {
         // Client: send request on the wire to check for updates,
         // since it may have missed puts while disconnected.
         // Skip if the same lex was checked recently to avoid flooding.

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]}
@@ -156,6 +193,25 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
     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 +615,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 +680,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 +691,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 +703,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 +873,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 +942,7 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
           )
         }
         attemptRead()
-      },
+      } as HolsterAPI["put"],
 
       on: function (
         lex: LexWithDot | ((data: unknown) => void),
@@ -1199,7 +1277,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

@@ -556,7 +556,15 @@ const Wire = (opt: HolsterOptions): WireAPI => {
     })
 
     if (ack) {
-      if (!isNode) {
+      // Put requests only need a local answer - skip the wire round-trip
+      // (matches the same check below, once store.get is reached instead
+      // of this fast graph path). Without this, check()'s own bare
+      // full-node lookup - always {put: true} - re-sends on the wire every
+      // time it's called once the soul's been through store.get once (see
+      // hasNode above), and since its own reply re-enters put() and calls
+      // check() again, this becomes a self-sustaining loop: a get every
+      // ~recentCheckTTL, forever, per soul, for every soul ever fetched.
+      if (!isNode && !opts.put) {
         // Client: send request on the wire to check for updates,
         // since it may have missed puts while disconnected.
         // Skip if the same lex was checked recently to avoid flooding.