@mblaney/holster 2.1.4 → 2.2.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@mblaney/holster",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "description": "Holster is a service that allows synchronising data between devices using Node, Deno, Bun or the browser.",
   "type": "module",
   "main": "index.js",
   "scripts": {
-    "test": "node --test",
+    "test": "node --test test/*.test.js test/system/*.test.js",
     "test:ts": "node --test --import tsx/esm ts/test/*.test.ts ts/test/system/*.test.ts",
     "build": "esbuild src/holster.js --bundle --format=esm --sourcemap \"--external:node:*\" \"--external:ws\" --minify --outdir=build",
     "build:ts": "esbuild ts/src/holster.ts --bundle --format=esm --sourcemap \"--external:node:*\" \"--external:ws\" --minify --outdir=dist",

package/src/holster.js

@@ -2,6 +2,7 @@ import * as utils from "./utils.js"
 import Wire from "./wire.js"
 import User from "./user.js"
 import SEA from "./sea.js"
+import {attachNested} from "./nested.js"
 
 const Holster = opt => {
   if (typeof opt === "string") opt = {peers: [opt]}
@@ -14,6 +15,12 @@ const Holster = opt => {
   const map = new Map()
   // Allow concurrent calls to the api by storing each context.
   const allctx = new Map()
+  // Tracks on(..., {nested: true}) subscriptions, keyed by the caller's
+  // own callback (the same reference off() will be called with) - see
+  // attachNested in nested.js. The actual top-level/child listeners it
+  // creates use their own, separate contexts, so off() just needs to
+  // call the detach function this stores to tear the whole thing down.
+  const nested = new Map()
   // Serializes concurrent creation of a missing rel for the same
   // soul+item, so only the first caller creates it and the rest reuse
   // its result rather than each minting a competing soul. Map<soul,
@@ -680,6 +687,23 @@ const Holster = opt => {
         // Get the context to check if it has user info
         const ctx = allctx.get(ctxid)
 
+        if (_opt && _opt.nested) {
+          // attachNested calls this once for the top level and again for
+          // every discovered child, each needing its own independent
+          // context - a single shared _ctxid would accumulate .next()
+          // calls onto the same path instead of giving sibling paths.
+          const factory = () => {
+            const _ctxid = utils.text.random()
+            allctx.set(_ctxid, {
+              chain: [{item: item, soul: soul}],
+              user: ctx ? ctx.user : null,
+            })
+            return api(_ctxid)
+          }
+          nested.set(cb, attachNested(factory, cb, _get, _opt))
+          return
+        }
+
         // Flag that this context is set from on and shouldn't be removed.
         allctx.set(ctxid, {
           chain: [{item: item, soul: soul}],
@@ -837,6 +861,12 @@ const Holster = opt => {
           return
         }
 
+        if (nested.has(cb)) {
+          nested.get(cb)()
+          nested.delete(cb)
+          return
+        }
+
         // Resolve the current context before removing event listener.
         const {item, soul} = resolve({off: true}, cb)
         if (!soul) return

package/src/nested.js

@@ -0,0 +1,89 @@
+// Backs on(cb, _get, {nested: true}) - see holster.js. A plain on() only
+// resolves the node it's given; it never re-checks a child whose own
+// value is an object (which always has its own soul, since only scalars
+// live directly on a node) once that child's content changes in place -
+// nothing on the parent's own soul changes when that happens, so a
+// listener on the parent alone never sees it. get()'s own read-resolution
+// (holster.js) already recursively resolves every such child into plain
+// data for a one-time read - this doesn't repeat that; it adds a live
+// subscription for each child that resolution already exposed, so a
+// later change to it reaches the caller too.
+//
+// Pure and holster-internals-free: chain is a factory - () =>
+// user.get([host, "shared"]).next("domains").next(code) - not a
+// pre-built chained object, since a fresh, independent instance is
+// needed per discovered child (reusing one chained object across
+// multiple .next() calls would push them onto the same path instead of
+// giving sibling paths).
+export function attachNested(chain, cb, _get, _opt) {
+  // Stripped before being used on any .on() call this function makes
+  // itself (top-level or child) - otherwise a caller-provided {nested:
+  // true} would re-trigger holster.js's own nested check on re-entry,
+  // before the normal rel-resolution logic that actually finds the right
+  // soul ever runs.
+  const opt = {..._opt}
+  delete opt.nested
+
+  const childListeners = new Map() // key -> {api, handler}
+  let latest = null
+
+  const notify = () => cb(latest === null ? null : {...latest})
+
+  const topLevelHandler = data => {
+    if (data === null || typeof data !== "object") {
+      latest = data
+      notify()
+      return
+    }
+
+    if (!latest || typeof latest !== "object") latest = {}
+    for (const [key, value] of Object.entries(data)) {
+      if (key === "_") continue
+      latest[key] = value
+
+      if (
+        value !== null &&
+        typeof value === "object" &&
+        !childListeners.has(key)
+      ) {
+        const childApi = chain().next(key)
+        const handler = childData => {
+          if (childData === null) {
+            delete latest[key]
+            childListeners.delete(key)
+          } else {
+            latest[key] = childData
+          }
+          notify()
+        }
+        childListeners.set(key, {api: childApi, handler})
+        // false, not true - the current value is already in data above,
+        // so this only needs to watch for future changes, not trigger a
+        // redundant immediate re-read.
+        childApi.on(handler, false, opt)
+      }
+    }
+
+    for (const key of [...childListeners.keys()]) {
+      if (!(key in data)) {
+        const {api: childApi, handler} = childListeners.get(key)
+        childApi.off(handler)
+        childListeners.delete(key)
+        delete latest[key]
+      }
+    }
+
+    notify()
+  }
+
+  const topLevelApi = chain()
+  topLevelApi.on(topLevelHandler, _get, opt)
+
+  return () => {
+    topLevelApi.off(topLevelHandler)
+    for (const {api: childApi, handler} of childListeners.values()) {
+      childApi.off(handler)
+    }
+    childListeners.clear()
+  }
+}

package/src/wire.js

@@ -452,14 +452,18 @@ const Wire = opt => {
           continue
         }
         const limit = userLimits.get(pub) ?? defaultLimit
-        if ((userStorage.get(pub) ?? 0) >= limit) continue
-        toStore[soul] = node
+        const current = userStorage.get(pub) ?? 0
         const oldBytes = oldGraphBytes[soul] ?? 0
         const newBytes = graph[soul] ? JSON.stringify(graph[soul]).length : 0
-        userStorage.set(
-          pub,
-          Math.max(0, (userStorage.get(pub) ?? 0) - oldBytes + newBytes),
-        )
+        const updated = Math.max(0, current - oldBytes + newBytes)
+        // A write that doesn't grow this user's total usage (e.g. a
+        // delete) is always let through, even past the limit - otherwise
+        // a user already over quota could never delete anything to get
+        // back under it. Only a write that both grows usage and pushes
+        // the total past the limit is rejected.
+        if (updated > current && updated > limit) continue
+        toStore[soul] = node
+        userStorage.set(pub, updated)
         saveUserStorage()
       }
       if (Object.keys(toStore).length > 0) {
@@ -683,16 +687,22 @@ const Wire = opt => {
             if (!pub) continue
             const limit = userLimits.get(pub) ?? defaultLimit
             const current = userStorage.get(pub) ?? 0
-            if (current >= limit) {
-              if (cb) cb("storage limit exceeded")
-              return
-            }
-
             const oldBytes = oldGraphBytes[soul] ?? 0
             const newBytes = graph[soul]
               ? JSON.stringify(graph[soul]).length
               : 0
-            userStorage.set(pub, Math.max(0, current - oldBytes + newBytes))
+            const updated = Math.max(0, current - oldBytes + newBytes)
+            // A write that doesn't grow this user's total usage (e.g. a
+            // delete) is always let through, even past the limit - otherwise
+            // a user already over quota could never delete anything to get
+            // back under it. Only a write that both grows usage and pushes
+            // the total past the limit is rejected.
+            if (updated > current && updated > limit) {
+              if (cb) cb("storage limit exceeded")
+              return
+            }
+
+            userStorage.set(pub, updated)
             saveUserStorage()
           }
         }

package/ts/src/holster.ts

@@ -7,6 +7,7 @@ import * as utils from "./utils.ts"
 import Wire, {type WireAPI} from "./wire.ts"
 import User, {type UserInterface} from "./user.ts"
 import SEA from "./sea.ts"
+import {attachNested} from "./nested.ts"
 import type {
   HolsterOptions,
   ChainItem,
@@ -55,12 +56,15 @@ export interface HolsterAPI {
     set?: boolean | ((data?: string | null) => void),
     cb?: (data?: string | null) => void,
   ) => HolsterAPI | void
-  on: (
-    lex: LexWithDot | ((data: unknown) => void),
-    cb?: ((data: unknown) => void) | boolean,
-    _get?: boolean,
-    _opt?: WireOptions,
-  ) => void
+  on: {
+    (
+      lex: LexWithDot,
+      cb: (data: unknown) => void,
+      _get?: boolean,
+      _opt?: WireOptions,
+    ): void
+    (cb: (data: unknown) => void, _get?: boolean, _opt?: WireOptions): void
+  }
   off: (cb?: (data: unknown) => void) => HolsterAPI | void
   user: () => UserInterface & HolsterAPI
   wire: WireAPI
@@ -78,6 +82,12 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
   const user = User(options, wire as never)
   const map = new Map<(data: unknown) => void, () => void>()
   const allctx = new Map<string, ApiContext>()
+  // Tracks on(..., {nested: true}) subscriptions, keyed by the caller's
+  // own callback (the same reference off() will be called with) - see
+  // attachNested in nested.ts. The actual top-level/child listeners it
+  // creates use their own, separate contexts, so off() just needs to
+  // call the detach function this stores to tear the whole thing down.
+  const nested = new Map<(data: unknown) => void, () => void>()
   // Serializes concurrent creation of a missing rel for the same
   // soul+item, so only the first caller creates it and the rest reuse
   // its result rather than each minting a competing soul. Map<soul,
@@ -884,6 +894,23 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
 
         const ctx = allctx.get(ctxid)
 
+        if (opts && opts.nested) {
+          // attachNested calls this once for the top level and again for
+          // every discovered child, each needing its own independent
+          // context - a single shared _ctxid would accumulate .next()
+          // calls onto the same path instead of giving sibling paths.
+          const factory = (): HolsterAPI => {
+            const _ctxid = utils.text.random()
+            allctx.set(_ctxid, {
+              chain: [{item: item, soul: soul}],
+              user: ctx ? ctx.user : null,
+            })
+            return api(_ctxid)
+          }
+          nested.set(callback, attachNested(factory, callback, _get, opts))
+          return
+        }
+
         allctx.set(ctxid, {
           chain: [{item: item, soul: soul}],
           on: true,
@@ -1043,7 +1070,7 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
               : options.secure,
           },
         )
-      },
+      } as HolsterAPI["on"],
 
       off: function (cb?: (data: unknown) => void): HolsterAPI | void {
         if (!ctxid) {
@@ -1052,6 +1079,12 @@ const Holster = (opt?: HolsterOptions | string | string[]): HolsterAPI => {
           return
         }
 
+        if (cb && nested.has(cb)) {
+          nested.get(cb)!()
+          nested.delete(cb)
+          return
+        }
+
         const resolved = resolve({off: true}, cb)
         if (!resolved) return
 

package/ts/src/nested.ts

@@ -0,0 +1,101 @@
+import type {HolsterAPI} from "./holster.ts"
+import type {WireOptions} from "./schemas.ts"
+
+// Backs on(cb, _get, {nested: true}) - see holster.ts. A plain on() only
+// resolves the node it's given; it never re-checks a child whose own
+// value is an object (which always has its own soul, since only scalars
+// live directly on a node) once that child's content changes in place -
+// nothing on the parent's own soul changes when that happens, so a
+// listener on the parent alone never sees it. get()'s own read-resolution
+// (holster.ts) already recursively resolves every such child into plain
+// data for a one-time read - this doesn't repeat that; it adds a live
+// subscription for each child that resolution already exposed, so a
+// later change to it reaches the caller too.
+//
+// Pure and holster-internals-free: chain is a factory - () =>
+// user.get([host, "shared"]).next("domains").next(code) - not a
+// pre-built chained object, since a fresh, independent instance is
+// needed per discovered child (reusing one chained object across
+// multiple .next() calls would push them onto the same path instead of
+// giving sibling paths).
+export function attachNested(
+  chain: () => HolsterAPI,
+  cb: (data: unknown) => void,
+  _get?: boolean,
+  _opt?: WireOptions,
+): () => void {
+  // Stripped before being used on any .on() call this function makes
+  // itself (top-level or child) - otherwise a caller-provided {nested:
+  // true} would re-trigger holster.ts's own nested check on re-entry,
+  // before the normal rel-resolution logic that actually finds the right
+  // soul ever runs.
+  const opt: WireOptions = {..._opt}
+  delete opt.nested
+
+  const childListeners = new Map<
+    string,
+    {api: HolsterAPI; handler: (data: unknown) => void}
+  >()
+  let latest: Record<string, unknown> | null = null
+
+  const notify = () => cb(latest === null ? null : {...latest})
+
+  const topLevelHandler = (data: unknown) => {
+    if (data === null || typeof data !== "object") {
+      latest = data as Record<string, unknown> | null
+      notify()
+      return
+    }
+
+    if (!latest || typeof latest !== "object") latest = {}
+    const node = data as Record<string, unknown>
+    for (const [key, value] of Object.entries(node)) {
+      if (key === "_") continue
+      latest[key] = value
+
+      if (
+        value !== null &&
+        typeof value === "object" &&
+        !childListeners.has(key)
+      ) {
+        const childApi = chain().next(key)
+        const handler = (childData: unknown) => {
+          if (childData === null) {
+            delete latest![key]
+            childListeners.delete(key)
+          } else {
+            latest![key] = childData
+          }
+          notify()
+        }
+        childListeners.set(key, {api: childApi, handler})
+        // false, not true - the current value is already in data above,
+        // so this only needs to watch for future changes, not trigger a
+        // redundant immediate re-read.
+        childApi.on(handler, false, opt)
+      }
+    }
+
+    for (const key of [...childListeners.keys()]) {
+      if (!(key in node)) {
+        const entry = childListeners.get(key)!
+        entry.api.off(entry.handler)
+        childListeners.delete(key)
+        delete latest[key]
+      }
+    }
+
+    notify()
+  }
+
+  const topLevelApi = chain()
+  topLevelApi.on(topLevelHandler, _get, opt)
+
+  return () => {
+    topLevelApi.off(topLevelHandler)
+    for (const {api: childApi, handler} of childListeners.values()) {
+      childApi.off(handler)
+    }
+    childListeners.clear()
+  }
+}

package/ts/src/schemas.ts

@@ -185,6 +185,7 @@ export const WireOptionsSchema = z
     secure: z.boolean().optional(),
     fast: z.boolean().optional(),
     put: z.boolean().optional(),
+    nested: z.boolean().optional(),
   })
   .optional()
 export type WireOptions = z.infer<typeof WireOptionsSchema>

package/ts/src/wire.ts

@@ -509,14 +509,18 @@ const Wire = (opt: HolsterOptions): WireAPI => {
           continue
         }
         const limit = userLimits.get(pub) ?? defaultLimit
-        if ((userStorage.get(pub) ?? 0) >= limit) continue
-        toStore[soul] = node
+        const current = userStorage.get(pub) ?? 0
         const oldBytes = oldGraphBytes[soul] ?? 0
         const newBytes = graph[soul] ? JSON.stringify(graph[soul]).length : 0
-        userStorage.set(
-          pub,
-          Math.max(0, (userStorage.get(pub) ?? 0) - oldBytes + newBytes),
-        )
+        const updated = Math.max(0, current - oldBytes + newBytes)
+        // A write that doesn't grow this user's total usage (e.g. a
+        // delete) is always let through, even past the limit - otherwise
+        // a user already over quota could never delete anything to get
+        // back under it. Only a write that both grows usage and pushes
+        // the total past the limit is rejected.
+        if (updated > current && updated > limit) continue
+        toStore[soul] = node
+        userStorage.set(pub, updated)
         saveUserStorage()
       }
       if (Object.keys(toStore).length > 0) {
@@ -730,15 +734,21 @@ const Wire = (opt: HolsterOptions): WireAPI => {
             if (!pub) continue
             const limit = userLimits.get(pub) ?? defaultLimit
             const current = userStorage.get(pub) ?? 0
-            if (current >= limit) {
-              if (cb) cb("storage limit exceeded")
-              return
-            }
             const oldBytes = oldGraphBytes[soul] ?? 0
             const newBytes = graph[soul]
               ? JSON.stringify(graph[soul]).length
               : 0
-            userStorage.set(pub, Math.max(0, current - oldBytes + newBytes))
+            const updated = Math.max(0, current - oldBytes + newBytes)
+            // A write that doesn't grow this user's total usage (e.g. a
+            // delete) is always let through, even past the limit -
+            // otherwise a user already over quota could never delete
+            // anything to get back under it. Only a write that both grows
+            // usage and pushes the total past the limit is rejected.
+            if (updated > current && updated > limit) {
+              if (cb) cb("storage limit exceeded")
+              return
+            }
+            userStorage.set(pub, updated)
             saveUserStorage()
           }
         }