@mblaney/holster 2.0.2 → 2.1.1

package/ts/src/index.ts

@@ -1,35 +1,34 @@
 /**
  * Holster TypeScript Entry Point
- * 
+ *
  * This is the main entry point for the TypeScript version of Holster.
  * It exports all the main modules and types.
  */
 
 // Main API
-export { default as Holster, type HolsterAPI } from "./holster.ts"
+export {default as Holster, type HolsterAPI} from "./holster.ts"
 
 // Core modules
-export { default as Wire, type WireAPI } from "./wire.ts"
-export { default as User, type UserInterface } from "./user.ts"
-export { default as SEA } from "./sea.ts"
-export { default as Store, type StoreInterface } from "./store.ts"
+export {default as Wire, type WireAPI} from "./wire.ts"
+export {default as User, type UserInterface} from "./user.ts"
+export {default as SEA} from "./sea.ts"
+export {default as Store, type StoreInterface} from "./store.ts"
 
 // Data structure modules
-export { default as Ham } from "./ham.ts"
-export { default as Get } from "./get.ts"
-export { default as Radisk } from "./radisk.ts"
-export { default as Radix } from "./radix.ts"
-export { default as Dup, type DupInterface } from "./dup.ts"
+export {default as Ham} from "./ham.ts"
+export {default as Get} from "./get.ts"
+export {default as Radisk} from "./radisk.ts"
+export {default as Radix} from "./radix.ts"
+export {default as Dup, type DupInterface} from "./dup.ts"
 
 // Utilities
 export * as utils from "./utils.ts"
 export * as seaUtils from "./sea-utils.ts"
-export { default as SafeBuffer } from "./buffer.ts"
-export { default as SeaArray } from "./array.ts"
+export {default as SafeBuffer} from "./buffer.ts"
+export {default as SeaArray} from "./array.ts"
 
 // Types and Schemas
 export * from "./schemas.ts"
 
 // Default export
-export { default } from "./holster.ts"
-
+export {default} from "./holster.ts"

package/ts/src/radisk.ts

@@ -4,9 +4,14 @@
  */
 
 import Radix from "./radix.ts"
-import type { RadixFunction } from "./schemas.ts"
+import type {RadixFunction} from "./schemas.ts"
 import * as utils from "./utils.ts"
-import type { EncodedValue, RadiskOptions, GraphValue, Relation } from "./schemas.ts"
+import type {
+  EncodedValue,
+  RadiskOptions,
+  GraphValue,
+  Relation,
+} from "./schemas.ts"
 
 // ASCII character for end of text
 const etx = String.fromCharCode(3)
@@ -18,8 +23,18 @@ const unit = String.fromCharCode(31)
 export interface RadiskInterface extends RadixFunction {
   // Override call signature to support both get (with callback) and put (with value and optional callback)
   // Accepts GraphValue (raw values) OR EncodedValue (tuples) - see src/radisk.js and tests
-  (key?: string, value?: GraphValue | EncodedValue | ((err?: string | null, value?: EncodedValue | Record<string, EncodedValue>) => void), cb?: (err?: string | null) => void): void
-  
+  (
+    key?: string,
+    value?:
+      | GraphValue
+      | EncodedValue
+      | ((
+          err?: string | null,
+          value?: EncodedValue | Record<string, EncodedValue>,
+        ) => void),
+    cb?: (err?: string | null) => void,
+  ): void
+
   batch: RadixFunction & {
     acks: Array<(err?: string | null) => void>
     ed: number
@@ -32,9 +47,22 @@ export interface RadiskInterface extends RadixFunction {
     more?: boolean
   }
   save: (rad: RadixFunction, cb: (err?: string | null) => void) => void
-  write: (file: string, rad: RadixFunction, cb: (err?: string | null) => void) => void
-  read: (key: string, cb: (err?: string | null, value?: EncodedValue | Record<string, EncodedValue>) => void) => void
-  parse: (file: string, cb: (err?: string | null, disk?: RadixFunction) => void) => void
+  write: (
+    file: string,
+    rad: RadixFunction,
+    cb: (err?: string | null) => void,
+  ) => void
+  read: (
+    key: string,
+    cb: (
+      err?: string | null,
+      value?: EncodedValue | Record<string, EncodedValue>,
+    ) => void,
+  ) => void
+  parse: (
+    file: string,
+    cb: (err?: string | null, disk?: RadixFunction) => void,
+  ) => void
 }
 
 /**
@@ -48,7 +76,12 @@ const Radisk = (opt: RadiskOptions) => {
 
   const pendingReads = new Map<
     string,
-    Array<(err?: string | null, result?: EncodedValue | Record<string, EncodedValue>) => void>
+    Array<
+      (
+        err?: string | null,
+        result?: EncodedValue | Record<string, EncodedValue>,
+      ) => void
+    >
   >()
 
   let lastMemoryCheck = 0
@@ -67,22 +100,27 @@ const Radisk = (opt: RadiskOptions) => {
   }
 
   if (!options.store) {
-    throw new Error("Radisk needs `store` interface with `{get: fn, put: fn, list: fn}`")
+    throw new Error(
+      "Radisk needs `store` interface with `{get: fn, put: fn, list: fn}`",
+    )
   }
   if (!options.store.get) {
     throw new Error("Radisk needs `store.get` interface with `(file, cb)`")
   }
   if (!options.store.put) {
-    throw new Error("Radisk needs `store.put` interface with `(file, data, cb)`")
+    throw new Error(
+      "Radisk needs `store.put` interface with `(file, data, cb)`",
+    )
   }
   if (!options.store.list) {
-    throw new Error("Radisk needs a streaming `store.list` interface with `(cb)`")
+    throw new Error(
+      "Radisk needs a streaming `store.list` interface with `(cb)`",
+    )
   }
 
   // After validation, store is guaranteed to be defined
   const store = options.store
 
-
   const checkMemoryUsage = (): void => {
     if (typeof process === "undefined" || !process.memoryUsage) return
 
@@ -98,21 +136,31 @@ const Radisk = (opt: RadiskOptions) => {
     if (heapUsageRatio > HEAP_CLEANUP_THRESHOLD) {
       const cacheSize = cache.size
       console.log(
-        `[RADISK-MEMORY] High memory usage: ${Math.round(heapUsageRatio * 100)}% of heap limit. Clearing ${cacheSize} cached files.`
+        `[RADISK-MEMORY] High memory usage: ${Math.round(heapUsageRatio * 100)}% of heap limit. Clearing ${cacheSize} cached files.`,
       )
       cache.clear()
-      if ((global as { gc?: () => void }).gc) {
-        (global as { gc: () => void }).gc()
+      if ((global as {gc?: () => void}).gc) {
+        ;(global as {gc: () => void}).gc()
       }
       lastMemoryCheck = now + MEMORY_CHECK_INTERVAL
     } else if (heapUsageRatio > HEAP_WARNING_THRESHOLD) {
       console.log(
-        `[RADISK-MEMORY] Memory warning: ${Math.round(heapUsageRatio * 100)}% of heap limit used. Cache size: ${cache.size} files.`
+        `[RADISK-MEMORY] Memory warning: ${Math.round(heapUsageRatio * 100)}% of heap limit used. Cache size: ${cache.size} files.`,
       )
     }
   }
 
-  const radisk = ((key?: string, value?: GraphValue | EncodedValue | ((err?: string | null, value?: EncodedValue | Record<string, EncodedValue>) => void), cb?: (err?: string | null) => void) => {
+  const radisk = ((
+    key?: string,
+    value?:
+      | GraphValue
+      | EncodedValue
+      | ((
+          err?: string | null,
+          value?: EncodedValue | Record<string, EncodedValue>,
+        ) => void),
+    cb?: (err?: string | null) => void,
+  ) => {
     if (typeof key !== "string") return undefined
 
     if (typeof value === "function") {
@@ -261,7 +309,7 @@ const Radisk = (opt: RadiskOptions) => {
       done: false,
       count: 0,
       sub: undefined as RadixFunction | undefined,
-      halfKey: "",   // soul ID at the ~options.size/2 mark for a balanced split
+      halfKey: "", // soul ID at the ~options.size/2 mark for a balanced split
       halfOffset: 0, // write.text.length before that entry
       each: (
         value: EncodedValue,
@@ -289,8 +337,7 @@ const Radisk = (opt: RadiskOptions) => {
         ) {
           const fullKey = pre.join("") + k
           const endIdx = fullKey.indexOf(enq)
-          write.halfKey =
-            endIdx === -1 ? fullKey : fullKey.substring(0, endIdx)
+          write.halfKey = endIdx === -1 ? fullKey : fullKey.substring(0, endIdx)
           write.halfOffset = write.text.length
         }
 
@@ -342,20 +389,35 @@ const Radisk = (opt: RadiskOptions) => {
     const soul = endIdx === -1 ? key : key.substring(0, endIdx)
 
     const findFile = (files: string[]): string | null => {
-      let lo = 0, hi = files.length - 1, result: string | null = null
+      let lo = 0,
+        hi = files.length - 1,
+        result: string | null = null
       while (lo <= hi) {
         const mid = (lo + hi) >> 1
         const f = files[mid]!
-        if (f <= soul) { result = f; lo = mid + 1 }
-        else { hi = mid - 1 }
+        if (f <= soul) {
+          result = f
+          lo = mid + 1
+        } else {
+          hi = mid - 1
+        }
       }
       return result
     }
 
     const read = (file: string | null): void => {
-      if (!file) { cb("no file found", undefined); return }
+      if (!file) {
+        cb("no file found", undefined)
+        return
+      }
       if (options.cache && cache.has(file)) {
-        return cb(undefined, cache.get(file)!(key) as EncodedValue | Record<string, EncodedValue> | undefined)
+        return cb(
+          undefined,
+          cache.get(file)!(key) as
+            | EncodedValue
+            | Record<string, EncodedValue>
+            | undefined,
+        )
       }
       radisk.parse(file, (err, disk) => {
         if (err) options.log(err)
@@ -363,17 +425,32 @@ const Radisk = (opt: RadiskOptions) => {
           cache.set(file, disk)
           checkMemoryUsage()
         }
-        cb(err, disk ? disk(key) as EncodedValue | Record<string, EncodedValue> | undefined : undefined)
+        cb(
+          err,
+          disk
+            ? (disk(key) as
+                | EncodedValue
+                | Record<string, EncodedValue>
+                | undefined)
+            : undefined,
+        )
       })
     }
 
     const now = Date.now()
-    if (options.cache && fileListCache && now - fileListCacheTime < FILE_LIST_CACHE_TTL) {
+    if (
+      options.cache &&
+      fileListCache &&
+      now - fileListCacheTime < FILE_LIST_CACHE_TTL
+    ) {
       read(findFile(fileListCache))
     } else {
       const files: string[] = []
       store.list((file?: string) => {
-        if (file) { files.push(file); return }
+        if (file) {
+          files.push(file)
+          return
+        }
         files.sort()
         if (options.cache) {
           fileListCache = files
@@ -387,7 +464,10 @@ const Radisk = (opt: RadiskOptions) => {
   radisk.parse = (file, cb) => {
     const parse = {
       disk: Radix(),
-      read: (err?: string | null, data?: string | EncodedValue | Record<string, unknown>): void => {
+      read: (
+        err?: string | null,
+        data?: string | EncodedValue | Record<string, unknown>,
+      ): void => {
         if (err) return cb(err)
         if (!data) return cb(null, parse.disk)
 
@@ -398,7 +478,12 @@ const Radisk = (opt: RadiskOptions) => {
           let key: string | undefined
           let value: EncodedValue | undefined
           const tmpVal = tmp[1]
-          const i = typeof tmpVal === "number" ? tmpVal : (typeof tmpVal === "string" ? parseInt(tmpVal, 10) : 0)
+          const i =
+            typeof tmpVal === "number"
+              ? tmpVal
+              : typeof tmpVal === "string"
+                ? parseInt(tmpVal, 10)
+                : 0
           tmp = parse.split(tmp[2]) || ("" as never)
           if (tmp[0] === "#") {
             const tmpKey = tmp[1]
@@ -425,16 +510,14 @@ const Radisk = (opt: RadiskOptions) => {
         }
         cb(null, parse.disk)
       },
-      split: (
-        data: string
-      ): [string, unknown, string] | undefined => {
+      split: (data: string): [string, unknown, string] | undefined => {
         if (!data) return undefined
 
         const i = data.indexOf(unit)
         if (i === -1) return undefined
 
         const a = data.slice(0, i)
-        const o: { i?: number } = {}
+        const o: {i?: number} = {}
         return [a, Radisk.decode(data.slice(i), o), data.slice(i + o.i!)]
       },
     }
@@ -452,7 +535,7 @@ Radisk.encode = (input: EncodedValue | GraphValue): string => {
   let state = ""
   let sig = ""
   let data: GraphValue
-  
+
   if (Array.isArray(input) && (input.length === 2 || input.length === 3)) {
     // input is EncodedValue - extract the GraphValue and metadata
     state = etx + input[1]
@@ -492,7 +575,10 @@ Radisk.encode = (input: EncodedValue | GraphValue): string => {
 /**
  * Decode value from storage
  */
-Radisk.decode = (data: string, obj?: { i?: number }): EncodedValue | GraphValue | Relation | null | undefined => {
+Radisk.decode = (
+  data: string,
+  obj?: {i?: number},
+): EncodedValue | GraphValue | Relation | null | undefined => {
   let i = -1
   let n = 0
   let current: string | undefined = undefined
@@ -574,4 +660,3 @@ Radisk.decode = (data: string, obj?: { i?: number }): EncodedValue | GraphValue
 }
 
 export default Radisk
-

package/ts/src/radix.ts

@@ -4,7 +4,7 @@
  */
 
 import * as utils from "./utils.ts"
-import type { EncodedValue, RadixFunction } from "./schemas.ts"
+import type {EncodedValue, RadixFunction} from "./schemas.ts"
 
 // ASCII character for group separator
 const group = String.fromCharCode(29)
@@ -34,10 +34,11 @@ const Radix = (): RadixFunction => {
   const radix = ((
     keys?: string,
     value?: EncodedValue,
-    tree?: RadixTree
+    tree?: RadixTree,
   ): RadixNode | EncodedValue | undefined | Record<string, EncodedValue> => {
     if (!tree) {
-      if (!(radix as Record<string, unknown>)[group]) (radix as Record<string, unknown>)[group] = {}
+      if (!(radix as Record<string, unknown>)[group])
+        (radix as Record<string, unknown>)[group] = {}
       tree = (radix as Record<string, RadixTree>)[group]!
     }
     if (!keys) return tree
@@ -57,32 +58,35 @@ const Radix = (): RadixFunction => {
 
     if (!found) {
       // If not found from the provided keys try matching with an existing key
-      const result = utils.obj.map(tree!, (hasValue: RadixValue, hasKey: string) => {
-        let j = 0
-        let matchingKey = ""
-        while (hasKey[j] === keys[j]) {
-          matchingKey += hasKey[j]
-          j++
-        }
-        if (matchingKey) {
-          if (noValue) {
-            // matchingKey has to be as long as the original keys when reading
-            if (j <= max) return undefined
-
-            tmp[hasKey.slice(j)] = hasValue
-            return hasValue
+      const result = utils.obj.map(
+        tree!,
+        (hasValue: RadixValue, hasKey: string) => {
+          let j = 0
+          let matchingKey = ""
+          while (hasKey[j] === keys[j]) {
+            matchingKey += hasKey[j]
+            j++
           }
-
-          const replace: RadixTree = {
-            [hasKey.slice(j)]: hasValue,
-            [keys.slice(j)]: { [record]: value! },
+          if (matchingKey) {
+            if (noValue) {
+              // matchingKey has to be as long as the original keys when reading
+              if (j <= max) return undefined
+
+              tmp[hasKey.slice(j)] = hasValue
+              return hasValue
+            }
+
+            const replace: RadixTree = {
+              [hasKey.slice(j)]: hasValue,
+              [keys.slice(j)]: {[record]: value!},
+            }
+            tree![matchingKey] = {[group]: replace}
+            delete tree![hasKey]
+            return true
           }
-          tree![matchingKey] = { [group]: replace }
-          delete tree![hasKey]
-          return true
-        }
-        return undefined
-      })
+          return undefined
+        },
+      )
 
       if (!result) {
         if (noValue) return undefined
@@ -96,7 +100,9 @@ const Radix = (): RadixFunction => {
       // If no value use the key provided to return a whole group or record
       if (noValue) {
         // If an individual record isn't found then return the whole group
-        return typeof found[record] === "undefined" ? found[group] : found[record]
+        return typeof found[record] === "undefined"
+          ? found[group]
+          : found[record]
       }
       // Otherwise create a new record at the provided key for value
       found[record] = value!
@@ -120,22 +126,33 @@ const Radix = (): RadixFunction => {
  */
 Radix.map = function map(
   radix: RadixFunction | RadixNode,
-  cb: (value: EncodedValue, fullKey: string, key: string, pre: string[]) => unknown,
+  cb: (
+    value: EncodedValue,
+    fullKey: string,
+    key: string,
+    pre: string[],
+  ) => unknown,
   opt?: boolean,
-  pre: string[] = []
+  pre: string[] = [],
 ): unknown {
-  const tree = ((radix as Record<string, RadixTree>)[group] || radix) as RadixTree
+  const tree = ((radix as Record<string, RadixTree>)[group] ||
+    radix) as RadixTree
   const keys = Object.keys(tree).sort()
 
   for (let i = 0; i < keys.length; i++) {
     const key = keys[i]!
     const found = tree[key]
     if (!found) continue
-    
+
     const recordValue = found[record]
 
     if (typeof recordValue !== "undefined") {
-      const result = cb(recordValue as EncodedValue, pre.join("") + key, key, pre)
+      const result = cb(
+        recordValue as EncodedValue,
+        pre.join("") + key,
+        key,
+        pre,
+      )
       if (typeof result !== "undefined") return result
     } else if (opt) {
       cb(undefined as never, pre.join(""), key, pre)
@@ -154,4 +171,3 @@ Radix.map = function map(
 }
 
 export default Radix
-

package/ts/src/schemas.ts

@@ -1,4 +1,4 @@
-import { z } from "zod"
+import {z} from "zod"
 
 // ============================================================================
 // Core Primitive Types
@@ -48,7 +48,7 @@ export const GraphValueSchema: z.ZodType<GraphValue> = z.lazy(() =>
     z.null(),
     RelationSchema,
     z.record(z.string(), GraphValueSchema),
-  ])
+  ]),
 )
 
 export type GraphValue =
@@ -57,7 +57,7 @@ export type GraphValue =
   | boolean
   | null
   | Relation
-  | { [key: string]: GraphValue }
+  | {[key: string]: GraphValue}
 
 /**
  * State vector - tracks timestamps for each property
@@ -91,9 +91,11 @@ export const USER_SIGNATURE = "_holster_user_signature"
  * Graph node - contains metadata and properties
  * Note: Using manual type to properly handle the index signature with special _ key
  */
-export const GraphNodeSchema = z.object({
-  _: GraphMetadataSchema,
-}).and(z.record(z.string(), GraphValueSchema))
+export const GraphNodeSchema = z
+  .object({
+    _: GraphMetadataSchema,
+  })
+  .and(z.record(z.string(), GraphValueSchema))
 
 export type GraphNode = {
   _: GraphMetadata
@@ -141,9 +143,7 @@ export const LexFilterSchema = z.union([
 export type LexFilter = z.infer<typeof LexFilterSchema>
 
 // LexFilter with optional "." property for nested queries
-export type LexWithDot =
-  | LexFilter
-  | { ".": LexFilter }
+export type LexWithDot = LexFilter | {".": LexFilter}
 
 /**
  * Lex query object
@@ -294,8 +294,18 @@ export const FileSystemInterfaceSchema = z.object({
 // FileSystemInterface: Flexible to support both string-based and EncodedValue storage
 // In-memory stores use strings, disk stores use EncodedValue/RadixNode
 export interface FileSystemInterface {
-  get: (file: string, cb: (err?: string | null, data?: string | EncodedValue | Record<string, unknown>) => void) => void
-  put: (file: string, data: string | EncodedValue | Record<string, unknown>, cb: (err?: string | null) => void) => void
+  get: (
+    file: string,
+    cb: (
+      err?: string | null,
+      data?: string | EncodedValue | Record<string, unknown>,
+    ) => void,
+  ) => void
+  put: (
+    file: string,
+    data: string | EncodedValue | Record<string, unknown>,
+    cb: (err?: string | null) => void,
+  ) => void
   list: (cb: (file?: string) => void) => void
 }
 
@@ -405,6 +415,9 @@ export const HolsterOptionsSchema = z
     maxConnections: z.number().optional(),
     maxMessageSize: z.number().optional(),
     maxQueueLength: z.number().optional(),
+    userLimit: z.boolean().optional(),
+    defaultLimit: z.number().optional(),
+    maxGraphSize: z.number().optional(),
   })
   .passthrough()
 export type HolsterOptions = z.infer<typeof HolsterOptionsSchema>
@@ -462,20 +475,28 @@ export type RadixValue = GraphValue | EncodedValue | RadixNode
  */
 export type RadixFunction = {
   // Main call signature: synchronous get/put operations
-  (keys?: string, value?: GraphValue | EncodedValue, tree?: RadixNode): 
-    RadixNode | EncodedValue | undefined | Record<string, EncodedValue>
-  
+  (
+    keys?: string,
+    value?: GraphValue | EncodedValue,
+    tree?: RadixNode,
+  ): RadixNode | EncodedValue | undefined | Record<string, EncodedValue>
+
   // Callback form: async operations
   (key?: string, value?: RadixValue, cb?: (err?: string) => void): void
-  
+
   // Static map method for iterating over radix tree values
   map: (
-    radix: RadixFunction | RadixNode, 
-    cb: (value: EncodedValue, fullKey: string, key: string, pre: string[]) => unknown,
+    radix: RadixFunction | RadixNode,
+    cb: (
+      value: EncodedValue,
+      fullKey: string,
+      key: string,
+      pre: string[],
+    ) => unknown,
     opt?: boolean,
-    pre?: string[]
+    pre?: string[],
   ) => unknown
-  
+
   // Dynamic properties for internal state (e.g., group separator key)
   [key: string]: unknown
 }
@@ -506,10 +527,9 @@ export type Dup = z.infer<typeof DupSchema> & {
 // ============================================================================
 
 // Export RadiskInterface from radisk module for test usage
-export type { RadiskInterface } from "./radisk.ts"
+export type {RadiskInterface} from "./radisk.ts"
 
 // Export other interfaces for test usage
-export type { WireAPI as WireInterface } from "./wire.ts"
-export type { UserInterface } from "./user.ts"
-export type { StoreInterface } from "./store.ts"
-
+export type {WireAPI as WireInterface} from "./wire.ts"
+export type {UserInterface} from "./user.ts"
+export type {StoreInterface} from "./store.ts"

package/ts/src/sea-utils.ts

@@ -4,7 +4,7 @@
  */
 
 import SafeBuffer from "./buffer.ts"
-import type { JWK } from "./schemas.ts"
+import type {JWK} from "./schemas.ts"
 
 const isNode = typeof process !== "undefined" && process.versions?.node != null
 
@@ -64,23 +64,20 @@ export const jwk = (pub: string, priv?: string): JWK => {
  */
 export const sha256 = async (data: unknown): Promise<SeaArray> => {
   const hash = await subtle.digest(
-    { name: "SHA-256" },
-    new TextEncoder().encode(stringify(data))
+    {name: "SHA-256"},
+    new TextEncoder().encode(stringify(data)),
   )
   return SafeBuffer.from(new Uint8Array(hash))
 }
 
 /**
- * Derive AES key from password and salt  
+ * Derive AES key from password and salt
  */
-export const aeskey = async (
-  key: string,
-  salt: SeaArray
-) => {
+export const aeskey = async (key: string, salt: SeaArray) => {
   const combined = key + salt.toString("utf8")
   const hashResult = await sha256(combined)
   const jwkKey = keyToJwk(hashResult)
-  return await subtle.importKey("jwk", jwkKey, { name: "AES-GCM" }, false, [
+  return await subtle.importKey("jwk", jwkKey, {name: "AES-GCM"}, false, [
     "encrypt",
     "decrypt",
   ])
@@ -95,9 +92,8 @@ const keyToJwk = (key: SeaArray): JWK => {
     .replace(/\+/g, "-")
     .replace(/\//g, "_")
     .replace(/=/g, "")
-  return { kty: "oct", k: k, ext: false, alg: "A256GCM" }
+  return {kty: "oct", k: k, ext: false, alg: "A256GCM"}
 }
 
 // Re-export SeaArray type for convenience
 import type SeaArray from "./array.ts"
-