@nxtedition/deepstream.io-client-js 30.0.1 → 31.0.0

package/src/record/record.d.ts

@@ -0,0 +1,110 @@
+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'
+
+// When getting, for convenience, we say the data might be partial under some
+// circumstances.
+//
+// When you e.g. do record.get or record.update, there is always a possibility
+// that the data object is empty. The naive correct type for that would be
+// `Data | EmptyObject`. However, that forces the user to always type guard
+// against the empty object case. This type tries to allow the user to skip
+// that check in some cases, where it should be safe to do so.
+export type GettablePossibleEmpty<Data> = keyof Data extends never
+  ? EmptyObject // If there are no keys at all
+  : Partial<Data> extends Data
+    ? // All properties in Data are already optional, so we can safely return it
+      // as is. The user just need to check the properties themselves instead.
+      Data
+    : SingleKeyObject<Data> extends never
+      ? // There are more than one property in Data, and some of them are
+        // required. That means that the user must always check for the empty
+        // object case.
+        Data | EmptyObject
+      : // There is exactly one property in Data, and it is required. In this
+        // particular case, we can safely use Data as the "empty" type, but
+        // with the single property turned optional.
+        {
+          [K in keyof Data]+?: Data[K]
+        }
+
+// When setting the data must fully adhere to the Data type, or exactly an
+// empty object.
+export type SettablePossibleEmpty<Data> = Data | EmptyObject
+
+export interface WhenOptions {
+  timeout?: number
+  signal?: AbortSignal
+}
+
+export interface UpdateOptions {
+  signal?: AbortSignal
+}
+
+export default class Record<Data> {
+  constructor(name: string, handler: RecordHandler)
+
+  readonly name: string
+  readonly version: string
+  readonly data: GettablePossibleEmpty<Data>
+  readonly state: number
+  readonly refs: number
+
+  ref(): Record<Data>
+  unref(): Record<Data>
+  subscribe(callback: (record: Record<Data>) => void, opaque?: unknown): Record<Data>
+  unsubscribe(callback: (record: Record<Data>) => void, opaque?: unknown): Record<Data>
+
+  get: {
+    // with path
+    <Path extends Paths<Data>, DataAtPath extends Get<Data, Path> = Get<Data, Path>>(
+      path: Path,
+    ): DataAtPath | undefined
+    // 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
+  }
+
+  set: {
+    // with path
+    <Path extends Paths<Data>, DataAtPath extends Get<Data, Path>>(
+      path: Path,
+      dataAtPath: DataAtPath,
+    ): 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: {
+    (): Promise<Record<Data>>
+    (state: number): Promise<Record<Data>>
+    (options: WhenOptions): Promise<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>
+}

package/src/record/record.js

@@ -15,7 +15,6 @@ class Record {
 
     this._handler = handler
     this._name = name
-    this._key = utils.h64ToString(name)
     this._version = ''
     this._data = jsonPath.EMPTY
     this._state = C.RECORD_STATE.VOID
@@ -25,15 +24,7 @@ class Record {
 
     /** @type Map? */ this._updating = null
     /** @type Array? */ this._patching = null
-    this._subscribed = connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SUBSCRIBE, [
-      this._key,
-      this._name,
-    ])
-  }
-
-  /** @type { string} */
-  get key() {
-    return this._key
+    this._subscribed = connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SUBSCRIBE, [this._name])
   }
 
   /** @type {string} */
@@ -71,8 +62,7 @@ class Record {
     if (this._refs === 1) {
       this._handler._onPruning(this, false)
       this._subscribed =
-        this._subscribed ||
-        connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SUBSCRIBE, [this._key, this._name])
+        this._subscribed || connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SUBSCRIBE, [this._name])
     }
     return this
   }
@@ -88,6 +78,10 @@ class Record {
     return this
   }
 
+  [Symbol.dispose]() {
+    this.unref()
+  }
+
   /**
    * @param {*} fn
    * @param {*} opaque
@@ -308,7 +302,7 @@ class Record {
       .then(() => {
         const prev = this.get(path)
         const next = updater(prev, this._version)
-        if (prev !== next) {
+        if (prev !== next && (path || next != null)) {
           this.set(path, next)
         }
       })
@@ -334,8 +328,7 @@ class Record {
 
     if (connected) {
       this._subscribed =
-        this._refs > 0 &&
-        connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SUBSCRIBE, [this._key, this._name])
+        this._refs > 0 && connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.SUBSCRIBE, [this._name])
 
       if (this._updating) {
         for (const update of this._updating.values()) {
@@ -360,7 +353,7 @@ class Record {
     invariant(!this._updating, 'must not have updates')
 
     if (this._subscribed) {
-      connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.UNSUBSCRIBE, [this._key])
+      connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.UNSUBSCRIBE, [this._name])
       this._subscribed = false
     }
 
@@ -382,7 +375,7 @@ class Record {
     const prevVersion = this._version
     const nextVersion = this._makeVersion(parseInt(prevVersion) + 1)
 
-    const update = [this._key, nextVersion, jsonPath.stringify(nextData), prevVersion]
+    const update = [this._name, nextVersion, jsonPath.stringify(nextData), prevVersion]
 
     if (!this._updating) {
       this._onUpdating(true)

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

@@ -0,0 +1,42 @@
+import RpcResponse from './rpc-response.js'
+
+export type RpcMethodDef = [arguments: unknown, response: unknown]
+
+export default class RpcHandler<Methods extends Record<string, RpcMethodDef>> {
+  connected: boolean
+  stats: RpcStats
+
+  provide: <Name extends keyof Methods>(
+    name: Name,
+    callback: (args: Methods[Name][0], response: RpcResponse<Methods[Name][1]>) => void,
+  ) => UnprovideFn
+
+  unprovide: <Name extends keyof Methods>(name: Name) => void
+
+  make: {
+    <
+      Name extends keyof Methods | string,
+      Args extends Name extends keyof Methods ? Methods[Name][0] : unknown,
+      ReturnValue extends Name extends keyof Methods ? Methods[Name][1] : unknown,
+    >(
+      name: Name,
+      args: Args,
+    ): Promise<ReturnValue>
+    <
+      Name extends keyof Methods | string,
+      Args extends Name extends keyof Methods ? Methods[Name][0] : unknown,
+      ReturnValue extends Name extends keyof Methods ? Methods[Name][1] : unknown,
+    >(
+      name: Name,
+      args: Args,
+      callback: (error: unknown, response: ReturnValue) => void,
+    ): void
+  }
+}
+
+type UnprovideFn = () => void
+
+export interface RpcStats {
+  listeners: number
+  rpcs: number
+}

package/src/rpc/rpc-response.d.ts

@@ -0,0 +1,5 @@
+export default class RpcResponse<Data> {
+  reject: () => void
+  error: (error: Error | string) => void
+  send: (data: Data) => void
+}

package/src/utils/multicast-listener.js

@@ -1,176 +1,6 @@
 import * as rxjs from 'rxjs'
 import * as C from '../constants/constants.js'
-import { h64ToString } from '../utils/utils.js'
-import * as timers from '../utils/timers.js'
-
-class Provider {
-  #sending = false
-  #accepted = false
-  #value$ = null
-  #name
-  #key
-  #version
-  #timeout
-  #valueSubscription
-  #patternSubscription
-  #observer
-  #listener
-
-  constructor(name, listener) {
-    this.#name = name
-    this.#key = h64ToString(name)
-    this.#listener = listener
-    this.#observer = {
-      next: (value) => {
-        if (value == null) {
-          this.next(null) // TODO (fix): This is weird...
-          return
-        }
-
-        if (this.#listener._topic === C.TOPIC.EVENT) {
-          this.#listener._handler.emit(this.#name, value)
-        } else if (this.#listener._topic === C.TOPIC.RECORD) {
-          if (typeof value !== 'object' && typeof value !== 'string') {
-            this.#listener._error(this.#name, 'invalid value')
-            return
-          }
-
-          const body = typeof value !== 'string' ? this.#listener._stringify(value) : value
-          const hash = h64ToString(body)
-          const version = `INF-${hash}`
-
-          if (this.#version !== version) {
-            this.#version = version
-            this.#listener._connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.UPDATE, [
-              this.#key,
-              version,
-              body,
-            ])
-          }
-        }
-      },
-      error: (err) => {
-        this.error(err)
-      },
-    }
-
-    this.#start()
-  }
-
-  dispose() {
-    this.#stop()
-  }
-
-  accept() {
-    if (!this.#value$) {
-      return
-    }
-
-    if (this.#valueSubscription) {
-      this.#listener._error(this.#name, 'invalid accept: listener started')
-    } else {
-      // TODO (fix): provider.version = message.data[2]
-      this.#valueSubscription = this.#value$.subscribe(this.#observer)
-    }
-  }
-
-  reject() {
-    this.#listener._error(this.#name, 'invalid reject: not implemented')
-  }
-
-  next(value$) {
-    if (!value$) {
-      value$ = null
-    } else if (typeof value$.subscribe !== 'function') {
-      value$ = rxjs.of(value$) // Compat for recursive with value
-    }
-
-    if (Boolean(this.#value$) !== Boolean(value$) && !this.#sending) {
-      this.#sending = true
-      // TODO (fix): Why async?
-      queueMicrotask(() => {
-        this.#sending = false
-
-        if (!this.#patternSubscription) {
-          return
-        }
-
-        const accepted = Boolean(this.#value$)
-        if (this.#accepted === accepted) {
-          return
-        }
-
-        this.#listener._connection.sendMsg(
-          this.#listener._topic,
-          accepted ? C.ACTIONS.LISTEN_ACCEPT : C.ACTIONS.LISTEN_REJECT,
-          [this.#listener._pattern, this.#key],
-        )
-
-        this.#version = null
-        this.#accepted = accepted
-      })
-    }
-
-    this.#value$ = value$
-
-    if (this.#valueSubscription) {
-      this.#valueSubscription.unsubscribe()
-      this.#valueSubscription = this.#value$?.subscribe(this.#observer)
-    }
-  }
-
-  error(err) {
-    this.#stop()
-    // TODO (feat): backoff retryCount * delay?
-    // TODO (feat): backoff option?
-    this.#timeout = timers.setTimeout(
-      (provider) => {
-        provider.start()
-      },
-      10e3,
-      this,
-    )
-    this.#listener._error(this.#name, err)
-  }
-
-  #start() {
-    try {
-      const ret$ = this.#listener._callback(this.#name)
-      if (this.#listener._recursive && typeof ret$?.subscribe === 'function') {
-        this.patternSubscription = ret$.subscribe(this)
-      } else {
-        this.patternSubscription = rxjs.of(ret$).subscribe(this)
-      }
-    } catch (err) {
-      this.#listener._error(this.#name, err)
-    }
-  }
-
-  #stop() {
-    if (this.#listener.connected && this.#accepted) {
-      this.#listener._connection.sendMsg(this.#listener._topic, C.ACTIONS.LISTEN_REJECT, [
-        this.#listener._pattern,
-        this.#key,
-      ])
-    }
-
-    this.#value$ = null
-    this.#version = null
-    this.#accepted = false
-    this.#sending = false
-
-    if (this.#timeout) {
-      timers.clearTimeout(this.#timeout)
-      this.#timeout = null
-    }
-
-    this.#patternSubscription?.unsubscribe()
-    this.#patternSubscription = null
-
-    this.#valueSubscription?.unsubscribe()
-    this.#valueSubscription = null
-  }
-}
+import { h64ToString, findBigIntPaths } from '../utils/utils.js'
 
 export default class Listener {
   constructor(topic, pattern, callback, handler, { recursive = false, stringify = null } = {}) {
@@ -221,20 +51,173 @@ export default class Listener {
     if (message.action === C.ACTIONS.SUBSCRIPTION_FOR_PATTERN_FOUND) {
       if (this._subscriptions.has(name)) {
         this._error(name, 'invalid add: listener exists')
-      } else {
-        this._subscriptions.set(name, new Provider(name, this))
+        return
+      }
+
+      // TODO (refactor): Move to class
+      const provider = {
+        name,
+        value$: null,
+        sending: false,
+        accepted: false,
+        version: null,
+        timeout: null,
+        patternSubscription: null,
+        valueSubscription: null,
+      }
+      provider.stop = () => {
+        if (this.connected && provider.accepted) {
+          this._connection.sendMsg(this._topic, C.ACTIONS.LISTEN_REJECT, [
+            this._pattern,
+            provider.name,
+          ])
+        }
+
+        provider.value$ = null
+        provider.version = null
+        provider.accepted = false
+        provider.sending = false
+
+        clearTimeout(provider.timeout)
+        provider.timeout = null
+
+        provider.patternSubscription?.unsubscribe()
+        provider.patternSubscription = null
+
+        provider.valueSubscription?.unsubscribe()
+        provider.valueSubscription = null
       }
+      provider.send = () => {
+        provider.sending = false
+
+        if (!provider.patternSubscription) {
+          return
+        }
+
+        const accepted = Boolean(provider.value$)
+        if (provider.accepted === accepted) {
+          return
+        }
+
+        this._connection.sendMsg(
+          this._topic,
+          accepted ? C.ACTIONS.LISTEN_ACCEPT : C.ACTIONS.LISTEN_REJECT,
+          [this._pattern, provider.name],
+        )
+
+        provider.version = null
+        provider.accepted = accepted
+      }
+      provider.next = (value$) => {
+        if (!value$) {
+          value$ = null
+        } else if (typeof value$.subscribe !== 'function') {
+          value$ = rxjs.of(value$) // Compat for recursive with value
+        }
+
+        if (Boolean(provider.value$) !== Boolean(value$) && !provider.sending) {
+          provider.sending = true
+          queueMicrotask(provider.send)
+        }
+
+        provider.value$ = value$
+
+        if (provider.valueSubscription) {
+          provider.valueSubscription.unsubscribe()
+          provider.valueSubscription = provider.value$?.subscribe(provider.observer)
+        }
+      }
+      provider.error = (err) => {
+        provider.stop()
+        // TODO (feat): backoff retryCount * delay?
+        // TODO (feat): backoff option?
+        provider.timeout = setTimeout(() => {
+          provider.start()
+        }, 10e3)
+        this._error(provider.name, err)
+      }
+      provider.observer = {
+        next: (value) => {
+          if (value == null) {
+            provider.next(null) // TODO (fix): This is weird...
+            return
+          }
+
+          if (this._topic === C.TOPIC.EVENT) {
+            this._handler.emit(provider.name, value)
+          } else if (this._topic === C.TOPIC.RECORD) {
+            if (typeof value !== 'object' && typeof value !== 'string') {
+              this._error(provider.name, 'invalid value')
+              return
+            }
+
+            if (typeof value !== 'string') {
+              try {
+                value = this._stringify(value)
+              } catch (err) {
+                const bigIntPaths = /BigInt/.test(err.message) ? findBigIntPaths(value) : undefined
+                this._error(
+                  Object.assign(new Error(`invalid value: ${value}`), {
+                    cause: err,
+                    data: { name: provider.name, bigIntPaths },
+                  }),
+                )
+                return
+              }
+            }
+
+            const body = value
+            const hash = h64ToString(body)
+            const version = `INF-${hash}`
+
+            if (provider.version !== version) {
+              provider.version = version
+              this._connection.sendMsg(C.TOPIC.RECORD, C.ACTIONS.UPDATE, [
+                provider.name,
+                version,
+                body,
+              ])
+            }
+          }
+        },
+        error: provider.error,
+      }
+      provider.start = () => {
+        try {
+          const ret$ = this._callback(name)
+          if (this._recursive && typeof ret$?.subscribe === 'function') {
+            provider.patternSubscription = ret$.subscribe(provider)
+          } else {
+            provider.patternSubscription = rxjs.of(ret$).subscribe(provider)
+          }
+        } catch (err) {
+          this._error(provider.name, err)
+        }
+      }
+
+      provider.start()
+
+      this._subscriptions.set(provider.name, provider)
     } else if (message.action === C.ACTIONS.LISTEN_ACCEPT) {
-      this._subscriptions.get(name)?.accept()
-    } else if (message.action === C.ACTIONS.LISTEN_REJECT) {
-      this._subscriptions.get(name)?.reject()
-    } else if (message.action === C.ACTIONS.SUBSCRIPTION_FOR_PATTERN_REMOVED) {
       const provider = this._subscriptions.get(name)
-      if (provider) {
-        provider.dispose()
-        this._subscriptions.delete(name)
+      if (!provider?.value$) {
+        return
+      }
+
+      if (provider.valueSubscription) {
+        this._error(name, 'invalid accept: listener started')
       } else {
+        // TODO (fix): provider.version = message.data[2]
+        provider.valueSubscription = provider.value$.subscribe(provider.observer)
+      }
+    } else if (message.action === C.ACTIONS.SUBSCRIPTION_FOR_PATTERN_REMOVED) {
+      const provider = this._subscriptions.get(name)
+
+      if (!provider) {
         this._error(name, 'invalid remove: listener missing')
+      } else {
+        provider.stop()
+        this._subscriptions.delete(provider.name)
       }
     } else {
       return false
@@ -256,7 +239,7 @@ export default class Listener {
 
   _reset() {
     for (const provider of this._subscriptions.values()) {
-      provider.dispose()
+      provider.stop()
     }
     this._subscriptions.clear()
   }

package/src/utils/timers.js

@@ -78,6 +78,10 @@ class Timeout {
   clear() {
     this.state = -1
   }
+
+  [Symbol.dispose]() {
+    this.state = -1
+  }
 }
 
 export function setTimeout(callback, delay, opaque) {