@nxtedition/deepstream.io-client-js 28.1.22 → 28.1.24

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run test:types:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/deepstream.io-client-js",
-  "version": "28.1.22",
+  "version": "28.1.24",
   "description": "the javascript client for deepstream.io",
   "homepage": "http://deepstream.io",
   "type": "module",
@@ -21,7 +21,8 @@
   "scripts": {
     "prepublishOnly": "pinst --disable",
     "postpublish": "pinst --enable",
-    "prepare": "husky"
+    "prepare": "husky",
+    "test:types": "tsd"
   },
   "lint-staged": {
     "*.{js,jsx,md,ts}": [
@@ -60,6 +61,7 @@
     "pinst": "^3.0.0",
     "prettier": "^3.3.3",
     "rxjs": "^7.8.1",
+    "tsd": "^0.33.0",
     "type-fest": "^4.33.0",
     "typescript": "^5.6.3",
     "typescript-eslint": "^8.12.2"

package/src/client.d.ts

@@ -1,14 +1,28 @@
-import type Record from './record/record.js'
-import type RecordHandler, { RecordStats } from './record/record-handler.js'
-import type EventHandler, { EventStats } from './event/event-handler.js'
-import type RpcHandler, { RpcStats, RpcMethodDef } from './rpc/rpc-handler.js'
+import type DsRecord from './record/record.js'
+import type { Paths, Get } from './record/record.js'
+import type RecordHandler from './record/record-handler.js'
+import type { RecordStats, ProvideOptions, SyncOptions } from './record/record-handler.js'
+import type EventHandler from './event/event-handler.js'
+import type { EventStats } from './event/event-handler.js'
+import type RpcHandler from './rpc/rpc-handler.js'
+import type { RpcStats, RpcMethodDef } from './rpc/rpc-handler.js'
 
-export default function <Records, Methods>(
-  url: string,
-  options?: unknown,
-): DeepstreamClient<Records, Methods>
+export default function <
+  Records extends Record<string, unknown> = Record<string, unknown>,
+  Methods extends Record<string, RpcMethodDef> = Record<string, RpcMethodDef>,
+>(url: string, options?: unknown): DeepstreamClient<Records, Methods>
 
-export type { Record, RecordHandler, EventHandler, RpcHandler }
+export type {
+  DsRecord,
+  RecordHandler,
+  EventHandler,
+  RpcHandler,
+  RpcMethodDef,
+  ProvideOptions,
+  SyncOptions,
+  Paths,
+  Get,
+}
 
 type RecordStateConstants = Readonly<{
   VOID: 0
@@ -28,8 +42,8 @@ type ConnectionStateConstants = Readonly<{
   ERROR: 'ERROR'
   RECONNECTING: 'RECONNECTING'
 }>
-type ConnectionStateKey = keyof typeof ConnectionStateConstants
-type ConnectionStateName = (typeof ConnectionStateConstants)[ConnectionStateKey]
+type ConnectionStateKey = keyof ConnectionStateConstants
+type ConnectionStateName = ConnectionStateConstants[ConnectionStateKey]
 
 type EventConstants = Readonly<{
   CONNECTION_ERROR: 'connectionError'
@@ -61,12 +75,12 @@ type EventConstants = Readonly<{
   RECORD_NOT_FOUND: 'RECORD_NOT_FOUND'
   NOT_SUBSCRIBED: 'NOT_SUBSCRIBED'
 }>
-type EventKey = keyof typeof EventConstants
-type EventName = (typeof EventConstants)[EventKey]
+type EventKey = keyof EventConstants
+type EventName = EventConstants[EventKey]
 
 export interface DeepstreamClient<
-  Records = Record<string, unknown>,
-  Methods = Record<string, RpcMethodDef>,
+  Records extends Record<string, unknown> = Record<string, unknown>,
+  Methods extends Record<string, RpcMethodDef> = Record<string, RpcMethodDef>,
 > {
   nuid: () => string
   event: EventHandler
@@ -92,13 +106,3 @@ export interface DeepstreamClient<
     EVENT: EventConstants
   }
 }
-
-export interface ProvideOptions {
-  recursive?: boolean
-  stringify?: ((input: unknown) => string) | null
-}
-
-export interface SyncOptions {
-  signal?: AbortSignal
-  timeout?: number
-}

package/src/client.test-d.ts

@@ -0,0 +1,105 @@
+import make from './client.js'
+import { expectAssignable, expectError } from 'tsd'
+
+interface Records extends Record<string, unknown> {
+  o: {
+    o0?: {
+      o1?: {
+        o2?: {
+          o3?: string
+        }
+      }
+    }
+  }
+  n: {
+    n0: {
+      n1: {
+        n2: {
+          n3: string
+        }
+      }
+    }
+  }
+  c: Circular
+  m: {
+    m1: string
+    m2: string
+    m3?: string
+  }
+  p: {
+    p1: string
+    p2?: string
+    p3: { p4: string }
+  }
+  [x: `${string}:domain`]: {
+    d1: string
+    d2: {
+      d3: string
+    }
+  }
+}
+
+interface Circular {
+  a: {
+    b0: Circular
+    b1: string
+  }
+}
+
+const ds = make<Records>('')
+
+expectAssignable<{ n0?: { n1: { n2: { n3: string } } } } | undefined>(await ds.record.get('n'))
+expectAssignable<{ n1: { n2: { n3: string } } } | undefined>(await ds.record.get('n', 'n0'))
+
+// set withouth path
+ds.record.set('n', {}) // empty should always work
+ds.record.set('n', { n0: { n1: { n2: { n3: 'test' } } } })
+expectError(ds.record.set('n', { n0: {} })) // nested props are required
+
+// set with path
+ds.record.set('n', 'n0.n1', { n2: { n3: 'test' } })
+ds.record.set('n', 'n0', { n1: { n2: { n3: 'test' } } })
+ds.record.set('n', 'n0.n1', { n2: { n3: 'test' } })
+ds.record.set('n', 'n0.n1.n2', { n3: 'test' })
+ds.record.set('n', 'n0.n1.n2.n3', 'test')
+ds.record.set('o', 'o0.o1.o2.o3', 'test')
+ds.record.set('o', 'o0', {})
+ds.record.set('o', 'o0.o1', {})
+ds.record.set('o', 'o0.o1.o2', {})
+ds.record.set('o', 'o0.o1', { o2: {} })
+ds.record.set('o', 'o0.o1', { o2: { o3: 'test' } })
+ds.record.set('c', 'a.b1', 'test')
+ds.record.set('x:domain', 'd1', 'test')
+const id = 'id'
+ds.record.set(`${id}:domain`, 'd2.d3', 'test')
+
+expectAssignable<string>(await ds.record.get(`${id}:domain`, 'd2.d3'))
+
+// errors
+expectError(ds.record.set('o', 'o0.o1', { o2: { o3: 0 } }))
+expectError(ds.record.set('o', 'o0.o1', { o3: 0 }))
+expectError(ds.record.set('n', 'x1', {}))
+expectError(ds.record.set('n', 'n0.x2', 22))
+expectError(ds.record.set('n', 'n1.x2', {}))
+expectError(ds.record.set('n', 'n1.n2.n3', { n4: 22 }))
+
+expectAssignable<string>(await ds.record.get('p', 'p1'))
+expectAssignable<string | undefined>(await ds.record.get('p', 'p2'))
+expectAssignable<unknown>(await ds.record.get('p', 'x1'))
+
+// Circular
+expectAssignable<string | undefined>(await ds.record.get('c', 'a.b1'))
+
+// ============
+//
+
+// getRecord
+const daRec = ds.record.getRecord('o')
+daRec.set({ o0: {} })
+
+daRec.update('o0', (x) => ({ ...x, o1: {} }))
+expectError(daRec.update((x) => 'x'))
+expectError(daRec.update('o0', (x) => ({ ...x, o1: '22' })))
+
+ds.record.set('foo', { num: [22, true] })
+ds.record.set('foo', { num: ['22'] })

package/src/record/record-handler.d.ts

@@ -1,10 +1,10 @@
 import type { Observable } from 'rxjs'
-import type Record, { EmptyObject, GettablePossibleEmpty, SettablePossibleEmpty } from './record.js'
+import type DsRecord from './record.js'
+import type { EmptyObject, Get, Paths } from './record.js'
 
-type Paths<T> = keyof T
-type Get<Data, Path extends string> = Path extends keyof Data ? Data[Path] : unknown
-
-export default class RecordHandler<Records> {
+export default class RecordHandler<
+  Lookup extends Record<string, unknown> = Record<string, unknown>,
+> {
   VOID: 0
   CLIENT: 1
   SERVER: 2
@@ -20,13 +20,13 @@ export default class RecordHandler<Records> {
   connected: boolean
   stats: RecordStats
 
-  getRecord: <Name extends keyof Records, Data extends Records[Name] = Records[Name]>(
+  getRecord<Name extends string, Data = Name extends keyof Lookup ? Lookup[Name] : unknown>(
     name: Name,
-  ) => Record<Data>
+  ): DsRecord<Data>
 
-  provide: <Data>(
+  provide: (
     pattern: string,
-    callback: (key: string) => Data,
+    callback: (key: string) => unknown,
     optionsOrRecursive?: ProvideOptions | boolean,
   ) => void | (() => void)
 
@@ -34,115 +34,107 @@ export default class RecordHandler<Records> {
 
   set: {
     // without path:
-    <Name extends keyof Records>(name: Name, data: SettablePossibleEmpty<Records[Name]>): void
+    <Name extends string>(name: Name, data: Lookup[Name] | EmptyObject): void
 
     // with path:
-    <Name extends keyof Records, Data extends Records[Name], Path extends Paths<Data>>(
+    <Name extends string, Path extends string | string[]>(
       name: Name,
       path: Path,
-      data: Get<Data, Path>,
+      data: Path extends Paths<Lookup[Name]> ? Get<Lookup[Name], Path> : never,
     ): void
   }
 
   update: {
     // without path:
-    <Name extends keyof Records, Data extends Records[Name]>(
+    <Name extends string>(
       name: Name,
-      updater: (data: Readonly<GettablePossibleEmpty<Data>>) => SettablePossibleEmpty<Data>,
+      updater: (data: Lookup[Name]) => Lookup[Name] | EmptyObject,
     ): Promise<void>
 
     // with path:
-    <Name extends keyof Records, Data extends Records[Name], Path extends Paths<Data>>(
+    <Name extends string, Path extends string | string[]>(
       name: Name,
       path: Path,
-      updater: (data: Readonly<Get<Data, Path>> | undefined) => Get<Data, Path>,
+      updater: (data: Get<Lookup[Name], Path>) => Get<Lookup[Name], Path>,
     ): Promise<void>
   }
 
   observe: {
     // without path:
-    <Name extends keyof Records, Data extends Records[Name]>(
-      name: Name,
-    ): Observable<GettablePossibleEmpty<Data>>
+    <Name extends string>(name: Name): Observable<Lookup[Name]>
 
     // with path:
-    <Name extends keyof Records, Data extends Records[Name], Path extends Paths<Data> & string>(
+    <Name extends string, Path extends string | string[]>(
       name: Name,
       path: Path,
-    ): Observable<Get<Data, Path> | undefined>
+    ): Observable<Get<Lookup[Name], Path>>
 
     // with state:
-    <Name extends keyof Records, Data extends Records[Name]>(
-      name: Name,
-      state: number,
-    ): Observable<GettablePossibleEmpty<Data>>
+    <Name extends string>(name: Name, state: number): Observable<Lookup[Name]>
 
     // with path and state:
-    <Name extends keyof Records, Data extends Records[Name], Path extends Paths<Data> & string>(
+    <Name extends string, Path extends string | string[]>(
       name: Name,
       path: Path,
       state: number,
-    ): Observable<Get<Data, Path> | undefined>
+    ): Observable<Get<Lookup[Name], Path>>
   }
 
   get: {
     // without path:
-    <Name extends keyof Records, Data extends Records[Name]>(
-      name: Name,
-      state?: number,
-    ): Promise<GettablePossibleEmpty<Data>>
+    <Name extends string>(name: Name, state?: number): Promise<Lookup[Name]>
 
     // with path:
-    <Name extends keyof Records, Data extends Records[Name], Path extends Paths<Data> & string>(
+    <Name extends string, Path extends string | string[]>(
       name: Name,
-      path?: Path,
+      path: Path,
       state?: number,
-    ): Promise<Get<Data, Path> | undefined>
+    ): Promise<Get<Lookup[Name], Path>>
   }
 
   observe2: {
     // without path:
-    <Name extends keyof Records, Data extends Records[Name]>(
+    <Name extends string>(
       name: Name,
     ): Observable<{
-      name: Name
+      name: string
       version: string
       state: number
-      data: GettablePossibleEmpty<Data>
+      data: Lookup[Name]
     }>
 
     // with path:
-    <Name extends keyof Records, Data extends Records[Name], Path extends Paths<Data> & string>(
+    <Name extends string, Path extends string | string[]>(
       name: Name,
       path: Path,
     ): Observable<{
-      name: Name
+      name: string
       version: string
       state: number
-      data: Get<Data, Path> | undefined
+      data: Get<Lookup[Name], Path>
     }>
 
     // with state:
-    <Name extends keyof Records, Data extends Records[Name]>(
+    <Name extends string>(
       name: Name,
       state: number,
     ): Observable<{
-      name: Name
+      name: string
       version: string
       state: number
-      data: GettablePossibleEmpty<Data>
+      data: Lookup[Name]
     }>
 
     // with path and state:
-    <Name extends keyof Records, Data extends Records[Name], Path extends Paths<Data> & string>(
+    <Name extends string, Path extends string | string[]>(
       name: Name,
       path: Path,
       state: number,
     ): Observable<{
-      name: Name
+      name: string
       version: string
       state: number
-      data: Get<Data, Path> | undefined
+      data: Get<Lookup[Name], Path>
     }>
   }
 }
@@ -156,3 +148,13 @@ export interface RecordStats {
   patching: number
   subscriptions: number
 }
+
+export interface ProvideOptions {
+  recursive?: boolean
+  stringify?: ((input: unknown) => string) | null
+}
+
+export interface SyncOptions {
+  signal?: AbortSignal
+  timeout?: number
+}

package/src/record/record-handler.js

@@ -163,13 +163,16 @@ class RecordHandler {
   }
 
   _onUpdating(rec, value) {
+    const callbacks = this._updating.get(rec)
+
     if (value) {
+      invariant(!callbacks, 'updating callbacks must not exist')
       this._stats.updating += 1
       this._updating.set(rec, [])
     } else {
-      this._stats.updating -= 1
+      invariant(callbacks, 'updating callbacks must exist')
 
-      const callbacks = this._updating.get(rec)
+      this._stats.updating -= 1
       this._updating.delete(rec)
       for (const callback of callbacks) {
         callback()
@@ -273,63 +276,31 @@ class RecordHandler {
     // TODO (perf): Slow implementation...
 
     const signal = opts?.signal
-    const timeout = opts?.timeout ?? 2 * 60e3
+    const timeout = opts?.timeout
 
-    const disposers = []
+    let disposers
     try {
       const signalPromise = signal
         ? new Promise((resolve, reject) => {
             const onAbort = () => reject(signal.reason ?? new utils.AbortError())
             signal.addEventListener('abort', onAbort)
+            disposers ??= []
             disposers.push(() => signal.removeEventListener('abort', onAbort))
           })
         : null
 
       signalPromise?.catch(noop)
 
-      if (this._putting.size) {
-        const promises = []
-
-        {
-          const puttingPromises = []
-          for (const callbacks of this._putting.values()) {
-            puttingPromises.push(new Promise((resolve) => callbacks.push(resolve)))
-          }
-          promises.push(puttingPromises)
-        }
-
-        if (timeout) {
-          promises.push(
-            new Promise((resolve) => {
-              const patchingTimeout = timers.setTimeout(() => {
-                this._client._$onError(
-                  C.TOPIC.RECORD,
-                  C.EVENT.TIMEOUT,
-                  new Error('sync putting timeout'),
-                )
-                resolve(null)
-              }, timeout)
-              disposers.push(() => timers.clearTimeout(patchingTimeout))
-            }),
-          )
-        }
-
-        if (signalPromise) {
-          promises.push(signalPromise)
-        }
-
-        await Promise.race(promises)
-      }
-
       if (this._patching.size) {
-        const promises = []
+        let promises
 
         {
           const patchingPromises = []
           for (const callbacks of this._patching.values()) {
             patchingPromises.push(new Promise((resolve) => callbacks.push(resolve)))
           }
-          promises.push(patchingPromises)
+          promises ??= []
+          promises.push(Promise.all(patchingPromises))
         }
 
         if (timeout) {
@@ -343,30 +314,36 @@ class RecordHandler {
                 )
                 resolve(null)
               }, timeout)
+              disposers ??= []
               disposers.push(() => timers.clearTimeout(patchingTimeout))
             }),
           )
         }
 
         if (signalPromise) {
+          promises ??= []
           promises.push(signalPromise)
         }
 
-        await Promise.race(promises)
+        if (promises) {
+          await Promise.race(promises)
+        }
       }
 
       if (this._updating.size) {
-        const promises = []
+        let promises
 
         {
           const updatingPromises = []
           for (const callbacks of this._updating.values()) {
             updatingPromises.push(new Promise((resolve) => callbacks.push(resolve)))
           }
-          promises.push(updatingPromises)
+          promises ??= []
+          promises.push(Promise.all(updatingPromises))
         }
 
         if (timeout) {
+          promises ??= []
           promises.push(
             new Promise((resolve) => {
               const updatingTimeout = timers.setTimeout(() => {
@@ -377,50 +354,57 @@ class RecordHandler {
                 )
                 resolve(null)
               }, timeout)
+              disposers ??= []
               disposers.push(() => timers.clearTimeout(updatingTimeout))
             }),
           )
         }
 
-        await Promise.race(promises)
+        if (promises) {
+          await Promise.race(promises)
+        }
       }
 
       {
-        const promises = []
+        const syncPromise = new Promise((resolve) => this._sync(resolve))
 
-        promises.push(
-          new Promise((resolve) => {
-            const token = xuid()
-            this._syncEmitter.once(token, resolve)
-            this._connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SYNC, [token])
-          }),
-        )
+        let promises
 
         if (timeout) {
+          promises ??= []
           promises.push(
             new Promise((resolve, reject) => {
               const serverTimeout = timers.setTimeout(() => {
                 reject(new Error('sync server timeout'))
               }, timeout)
+              disposers ??= []
               disposers.push(() => timers.clearTimeout(serverTimeout))
             }),
           )
         }
 
         if (signalPromise) {
+          promises ??= []
           promises.push(signalPromise)
         }
 
-        await Promise.race(promises)
+        if (promises) {
+          promises.push(syncPromise)
+          await Promise.race(promises)
+        } else {
+          await syncPromise
+        }
       }
     } finally {
-      for (const disposer of disposers) {
-        disposer()
+      if (disposers) {
+        for (const disposer of disposers) {
+          disposer()
+        }
       }
     }
   }
 
-  _sync(callback, opaque) {
+  _sync(callback, type, opaque) {
     this._syncQueue.push(callback, opaque)
 
     if (this._syncQueue.length > 2) {
@@ -437,7 +421,7 @@ class RecordHandler {
           queue[n](queue[n + 1])
         }
       })
-      this._connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SYNC, [token, 'WEAK'])
+      this._connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SYNC, type ? [token, type] : [token])
     }, 1)
   }
 
@@ -476,9 +460,7 @@ class RecordHandler {
     this._connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.PUT, update)
 
     this._putting.set(update, [])
-    this._sync((update) => {
-      this._putting.delete(update)
-    }, update)
+    this._sync((update) => this._putting.delete(update), 'WEAK', update)
   }
 
   /**
@@ -545,7 +527,7 @@ class RecordHandler {
           rec.subscribe(onUpdateFast, opaque)
 
           if (!opaque.synced) {
-            this._sync(onSyncFast, opaque)
+            this._sync(onSyncFast, 'WEAK', opaque)
           }
         }
       })
@@ -736,13 +718,14 @@ class RecordHandler {
 
     if (connected) {
       this._connected = Date.now()
-      for (const token of this._syncEmitter.eventNames()) {
-        this._connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SYNC, [token])
-      }
 
       for (const update of this._putting.keys()) {
         this._connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.PUT, update)
       }
+
+      for (const token of this._syncEmitter.eventNames()) {
+        this._connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SYNC, [token])
+      }
     } else {
       this._connected = 0
     }

package/src/record/record.d.ts

@@ -1,10 +1,6 @@
 import type RecordHandler from './record-handler.js'
-import type { EmptyObject, SingleKeyObject } from 'type-fest'
-
-type Paths<T> = keyof T
-type Get<Data, Path extends string> = Path extends keyof Data ? Data[Path] : unknown
-
-export type { EmptyObject } from 'type-fest'
+import type { Get, EmptyObject, SingleKeyObject } from 'type-fest'
+export type { Get, Paths, EmptyObject } from 'type-fest'
 
 // When getting, for convenience, we say the data might be partial under some
 // circumstances.
@@ -45,12 +41,12 @@ export interface UpdateOptions {
   signal?: AbortSignal
 }
 
-export default class Record<Data> {
+export default class Record<Data = unknown> {
   constructor(name: string, handler: RecordHandler)
 
   readonly name: string
   readonly version: string
-  readonly data: GettablePossibleEmpty<Data>
+  readonly data: Data
   readonly state: number
   readonly refs: number
 
@@ -61,29 +57,16 @@ export default class Record<Data> {
 
   get: {
     // with path
-    <Path extends Paths<Data>, DataAtPath extends Get<Data, Path> = Get<Data, Path>>(
-      path: Path,
-    ): DataAtPath | undefined
+    <P extends string | string[]>(path: P): Get<Data, P>
     // without path
-    (): GettablePossibleEmpty<Data>
-    // implementation
-    <Path extends Paths<Data>, DataAtPath extends Get<Data, Path> = Get<Data, Path>>(
-      path?: Path,
-    ): Path extends undefined ? GettablePossibleEmpty<Data> : DataAtPath | undefined
+    (): Data
   }
 
   set: {
     // with path
-    <Path extends Paths<Data>, DataAtPath extends Get<Data, Path>>(
-      path: Path,
-      dataAtPath: DataAtPath,
-    ): void
+    <P extends string | string[]>(path: P, dataAtPath: Get<Data, P>): void
     // without path
     (data: SettablePossibleEmpty<Data>): void
-    // implementation
-    <Path extends Paths<Data>, DataAtPath extends Get<Data, Path>>(
-      ...args: [pathOrData: Path | SettablePossibleEmpty<Data>, value?: DataAtPath]
-    ): void
   }
 
   when: {
@@ -93,18 +76,17 @@ export default class Record<Data> {
     (state: number, options: WhenOptions): Promise<Record<Data>>
   }
 
-  update<
-    Path extends Paths<Data>,
-    PathOrUpdater extends
-      | Path
-      | ((data: Readonly<GettablePossibleEmpty<Data>>) => SettablePossibleEmpty<Data>),
-  >(
-    ...args: PathOrUpdater extends Path
-      ? [
-          path: Path,
-          updater: (dataAtPath: Readonly<Get<Data, Path>> | undefined) => Get<Data, Path>,
-          options?: UpdateOptions,
-        ]
-      : [updater: PathOrUpdater, options?: UpdateOptions]
-  ): Promise<void>
+  update: {
+    // without path
+    (
+      updater: (data: Readonly<Data>) => SettablePossibleEmpty<Data>,
+      options?: UpdateOptions,
+    ): Promise<void>
+    // with path
+    <P extends string | string[]>(
+      path: P,
+      updater: (dataAtPath: Readonly<Get<Data, P>>) => Get<Data, P>,
+      options?: UpdateOptions,
+    ): Promise<void>
+  }
 }