@dittolive/ditto 4.5.1-experimental.aarch64-linux.1.aarch64 → 4.5.2-rc.2

package/react-native/src/sources/pending-cursor-operation.ts

@@ -0,0 +1,218 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+
+import { Bridge } from './bridge'
+import { Subscription } from './subscription'
+import { DocumentID } from './document-id'
+import { LiveQuery } from './live-query'
+import { performAsyncToWorkaroundNonAsyncFFIAPI } from './internal'
+import { BasePendingCursorOperation } from './base-pending-cursor-operation'
+
+import type { QueryArguments, SortDirection } from './essentials'
+import type { Document, MutableDocument } from './document'
+import type { UpdateResultsMap } from './update-results-map'
+import type { LiveQueryEvent } from './live-query-event'
+import type { Collection } from './collection'
+
+// -----------------------------------------------------------------------------
+
+/**
+ * The closure that is called whenever the documents covered by a live query
+ * change.
+ */
+export type QueryObservationHandler = (documents: Document[], event: LiveQueryEvent, signalNext?: () => void) => void | Promise<void>
+
+// -----------------------------------------------------------------------------
+
+/**
+ * These objects are returned when using `find`-like functionality on
+ * {@link Collection}.
+ *
+ * They allow chaining of further query-related functions to do things like add
+ * a limit to the number of documents you want returned or specify how you want
+ * the documents to be sorted and ordered.
+ *
+ * You can either call {@link exec | exec()} on the object to get an array of
+ * {@link Document | documents} as an immediate return value, or you can
+ * establish either a live query or a subscription, which both work over time.
+ *
+ * A live query, established by calling
+ * {@link PendingCursorOperation.observeLocal | observeLocal()}, will notify you
+ * every time there's an update to a document that matches the query you
+ * provided in the preceding `find`-like call.
+ *
+ * A subscription, established by calling
+ * {@link PendingCursorOperation.subscribe | subscribe()}, will act as a signal
+ * to other peers that the device connects to that you would like to receive
+ * updates from them about documents that match the query you provided in the
+ * preceding `find`-like call.
+ *
+ * Update and remove functionality is also exposed through this object.
+ */
+export class PendingCursorOperation extends BasePendingCursorOperation {
+  sort(propertyPath: string, direction: SortDirection = 'ascending'): PendingCursorOperation {
+    return super.sort(propertyPath, direction) as PendingCursorOperation
+  }
+
+  offset(offset: number): PendingCursorOperation {
+    return super.offset(offset) as PendingCursorOperation
+  }
+
+  limit(limit: number): PendingCursorOperation {
+    return super.limit(limit) as PendingCursorOperation
+  }
+
+  async remove(): Promise<DocumentID[]> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferCloseAsync(async () => {
+      const query = this.query
+      const documentsX = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const results = await FFI.collectionRemoveQueryStr(dittoHandle.deref(), this.collection.name, writeTransactionX, query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return results
+      })
+
+      return documentsX.map((idCBOR: Uint8Array) => {
+        return new DocumentID(idCBOR, true)
+      })
+    })
+  }
+
+  async evict(): Promise<DocumentID[]> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferCloseAsync(async () => {
+      const query = this.query
+      const documentsX = await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const results = await FFI.collectionEvictQueryStr(dittoHandle.deref(), this.collection.name, writeTransactionX, query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return results
+      })
+
+      return documentsX.map((idCBOR: Uint8Array) => {
+        return new DocumentID(idCBOR, true)
+      })
+    })
+  }
+
+  async update(closure: (documents: MutableDocument[]) => void): Promise<UpdateResultsMap> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    return ditto.deferCloseAsync(async () => {
+      return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const results = await super.updateWithTransaction(closure, writeTransactionX)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return results
+      })
+    })
+  }
+
+  /**
+   * Enables you to subscribe to changes that occur in a collection remotely.
+   *
+   * Having a subscription acts as a signal to other peers that you are
+   * interested in receiving updates when local or remote changes are made to
+   * documents that match the query generated by the chain of operations that
+   * precedes the call to {@link subscribe | subscribe()}.
+   *
+   * The returned {@link Subscription} object must be kept in scope for as long
+   * as you want to keep receiving updates.
+   *
+   * @returns A {@link Subscription} object that must be kept in scope for as
+   * long as you want to keep receiving updates for documents that match the
+   * query specified in the preceding chain.
+   */
+  subscribe(): Subscription {
+    const subscription = new Subscription(this.collection as Collection, this.query, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset)
+    this.collection.store.ditto.subscriptionManager.add(subscription)
+    return subscription
+  }
+
+  /**
+   * Enables you to listen for changes that occur in a collection locally.
+   *
+   * The `handler` block will be called when local changes are
+   * made to documents that match the query generated by the chain of operations
+   * that precedes the call to {@link PendingCursorOperation.observeLocal | observeLocal()}.
+   * The returned {@link LiveQuery} object must be kept in scope for as long as
+   * you want the provided `handler` to be called when an update occurs.
+   *
+   * This won't subscribe to receive changes made remotely by others and so it
+   * will only fire updates when a local change is made. If you want to receive
+   * remotely performed updates as well, you'll have to create a subscription
+   * via {@link PendingCursorOperation.subscribe | subscribe()} with the
+   * relevant query. The returned {@link LiveQuery} object must be kept in scope
+   * for as long as you want the provided `eventHandler` to be called when an
+   * update occurs.
+   *
+   * @param handler A closure that will be called every time there is a
+   * transaction committed to the store that involves modifications to documents
+   * matching the query in the collection this method was called on.
+   *
+   * @return A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocal(handler: QueryObservationHandler): LiveQuery {
+    return this._observe(handler, false)
+  }
+
+  /**
+   * Enables you to listen for changes that occur in a collection locally and
+   * to signal when you are ready for the live query to deliver the next event.
+   *
+   * The `handler` block will be called when local changes are
+   * made to documents that match the query generated by the chain of operations
+   * that precedes the call to {@link PendingCursorOperation.observeLocalWithNextSignal | observeLocalWithNextSignal()}.
+   * The returned {@link LiveQuery} object must be kept in scope for as long as
+   * you want the provided `handler` to be called when an update occurs.
+   *
+   * This won't subscribe to receive changes made remotely by others and so it
+   * will only fire updates when a local change is made. If you want to receive
+   * remotely performed updates as well, you'll have to create a subscription
+   * via {@link PendingCursorOperation.subscribe | subscribe()} with the
+   * relevant query. The returned {@link LiveQuery} object must be kept in scope
+   * for as long as you want the provided `eventHandler` to be called when an
+   * update occurs.
+   *
+   * @param handler A closure that will be called every time there is a
+   * transaction committed to the store that involves modifications to
+   * documents matching the query in the collection that this method was called
+   * on.
+   *
+   * @return A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocalWithNextSignal(handler: QueryObservationHandler): LiveQuery {
+    return this._observe(handler, true)
+  }
+
+  // ----------------------------------------------------------- Internal ------
+
+  /** @internal */
+  constructor(query: string, queryArgs: QueryArguments | null, collection: Collection) {
+    super(query, queryArgs, collection)
+  }
+
+  /** @internal */
+  _observe(handler: QueryObservationHandler, waitForNextSignal: boolean): LiveQuery {
+    function wrappedHandler(documents, event, nextSignal) {
+      try {
+        return handler.call(this, documents, event)
+      } finally {
+        nextSignal()
+      }
+    }
+
+    const handlerOrWrapped: QueryObservationHandler = waitForNextSignal ? handler : wrappedHandler
+    const liveQuery = new LiveQuery(this.query, this.queryArgs, this.queryArgsCBOR, this.orderBys, this.currentLimit, this.currentOffset, this.collection as Collection, handlerOrWrapped)
+    this.collection.store.ditto.liveQueryManager.startLiveQuery(liveQuery)
+    return liveQuery
+  }
+}

package/react-native/src/sources/pending-id-specific-operation.ts

@@ -0,0 +1,218 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+
+import { Bridge } from './bridge'
+import { Subscription } from './subscription'
+import { LiveQuery } from './live-query'
+import { Document, MutableDocument } from './document'
+import { performAsyncToWorkaroundNonAsyncFFIAPI } from './internal'
+import { BasePendingIDSpecificOperation } from './base-pending-id-specific-operation'
+import { SingleDocumentLiveQueryEvent } from './live-query-event'
+
+import type { DocumentID } from './document-id'
+import type { UpdateResult } from './update-result'
+import type { Collection } from './collection'
+
+
+/**
+ * The closure that is called whenever a single documunent covered by a
+ * live query changes.
+ */
+export type SingleObservationHandler = (document: Document | null, event: SingleDocumentLiveQueryEvent, signalNext?: () => void) => void | Promise<void>
+
+// -----------------------------------------------------------------------------
+
+/**
+ * These objects are returned when using {@link Collection.findByID | findByID()}
+ * functionality on {@link Collection | collections}.
+ *
+ * You can either call {@link exec | exec()} on the  object to get an immediate
+ * return value, or you can establish either a live query or a subscription,
+ * which both work over time.
+ *
+ * A live query, established by calling
+ * {@link PendingIDSpecificOperation.observeLocal | observeLocal()}, will notify
+ * you every time there's an update to the document with the ID you provided in
+ * the preceding {@link Collection.findByID | findByID()} call.
+ *
+ * A subscription, established by calling {@link PendingIDSpecificOperation.subscribe | subscribe()}, will
+ * act as a signal to other peers that you would like to receive updates from
+ * them about the document with the ID you provided in the preceding
+ * {@link Collection.findByID | findByID()} call.
+ *
+ * Update and remove functionality is also exposed through this object.
+ */
+export class PendingIDSpecificOperation extends BasePendingIDSpecificOperation {
+  async remove(): Promise<boolean> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+
+    return ditto.deferCloseAsync(async () => {
+      return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const didRemove = await FFI.collectionRemove(dittoHandle.deref(), this.collection.name, writeTransactionX, this.documentIDCBOR)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return didRemove
+      })
+    })
+  }
+
+  async evict(): Promise<boolean> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+
+    return ditto.deferCloseAsync(async () => {
+      return await performAsyncToWorkaroundNonAsyncFFIAPI(async () => {
+        const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+        const didEvict = await FFI.collectionEvict(dittoHandle.deref(), this.collection.name, writeTransactionX, this.documentIDCBOR)
+        await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+        return didEvict
+      })
+    })
+  }
+
+  async update(closure: (document: MutableDocument) => void): Promise<UpdateResult[]> {
+    const ditto = this.collection.store.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+
+    return ditto.deferCloseAsync(async () => {
+      const readTransactionX = await FFI.readTransaction(dittoHandle.deref())
+      const documentX = await FFI.collectionGet(dittoHandle.deref(), this.collection.name, this.documentIDCBOR, readTransactionX)
+      FFI.readTransactionFree(readTransactionX)
+
+      if (!documentX) throw new Error(`Can't update, document with ID '${this.documentID.toString()}' not found in collection named '${this.collection.name}'`)
+
+      const mutableDocument = Bridge.mutableDocument.bridge(documentX, () => new MutableDocument())
+      closure(mutableDocument)
+
+      // Ownership is transferred back to the FFI layer via collectionUpdate(),
+      // we therefore need to explicitly unregister the instance.
+      Bridge.mutableDocument.unregister(mutableDocument)
+
+      const writeTransactionX = await FFI.writeTransaction(dittoHandle.deref())
+      await FFI.collectionUpdate(dittoHandle.deref(), this.collection.name, writeTransactionX, documentX)
+      await FFI.writeTransactionCommit(dittoHandle.deref(), writeTransactionX)
+
+      return mutableDocument['@ditto.updateResults'].slice()
+    })
+  }
+
+  /**
+   * Enables you to subscribe to changes that occur in relation to a document
+   * remotely.
+   *
+   * Having a subscription acts as a signal to other peers that you are
+   * interested in receiving updates when local or remote changes are made to
+   * the relevant document.
+   *
+   * The returned {@link Subscription} object must be kept in scope for as long
+   * as you want to keep receiving updates.
+   *
+   * @returns A {@link Subscription} object that must be kept in scope for as
+   * long as you want to keep receiving updates for the document.
+   */
+  subscribe(): Subscription {
+    const subscription = new Subscription(this.collection as Collection, this.query, null, [], -1, 0)
+    this.collection.store.ditto.subscriptionManager.add(subscription)
+    return subscription
+  }
+
+  /**
+   * Enables you to listen for changes that occur in relation to a document
+   * locally.
+   *
+   * This won't subscribe to receive changes made remotely by others and so it
+   * will only fire updates when a local change is made. If you want to receive
+   * remotely performed updates as well, you'll have to create a subscription
+   * via {@link PendingIDSpecificOperation.subscribe | subscribe()} for the same
+   * document ID.
+   *
+   * The returned {@link LiveQuery} object must be kept in scope for as long
+   * as you want the provided `handler` to be called when an update
+   * occurs.
+   *
+   * @param handler A block that will be called every time there is a
+   * transaction committed to the store that involves a modification to the
+   * document with the relevant ID in the collection that
+   * {@link PendingIDSpecificOperation.observeLocal | observeLocal()} was called on.
+   *
+   * @returns A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocal(handler: SingleObservationHandler): LiveQuery {
+    return this._observe(handler, false)
+  }
+
+  /**
+   * Enables you to listen for changes that occur in relation to a document
+   * locally and to signal when you are ready for the live query to deliver
+   * the next event.
+   *
+   * This won't subscribe to receive changes made remotely by others and so it
+   * will only fire updates when a local change is made. If you want to receive
+   * remotely performed updates as well, you'll have to create a subscription
+   * via {@link PendingIDSpecificOperation.subscribe | subscribe()} for the same
+   * document ID.
+   *
+   * The returned {@link LiveQuery} object must be kept in scope for as long
+   * as you want the provided `handler` to be called when an update
+   * occurs.
+   *
+   * @param handler A block that will be called every time there is a
+   * transaction committed to the store that involves a modification to the
+   * document with the relevant ID in the collection that
+   * {@link PendingIDSpecificOperation.observeLocal | observeLocal()} was called on.
+   *
+   * @returns A {@link LiveQuery} object that must be kept in scope for as long
+   * as you want to keep receiving updates.
+   */
+  observeLocalWithNextSignal(handler: SingleObservationHandler): LiveQuery {
+    return this._observe(handler, true)
+  }
+
+  /** @internal */
+  constructor(documentID: DocumentID, collection: Collection) {
+    super(documentID, collection)
+  }
+
+  /** @internal */
+  _observe(handler: SingleObservationHandler, waitForNextSignal: boolean): LiveQuery {
+    const liveQuery = new LiveQuery(this.query, null, null, [], -1, 0, this.collection as Collection, (documents, event, signalNext) => {
+      if (documents.length > 1) {
+        const documentIDsAsBase64Strings = documents.map((document) => document.id.toBase64String())
+        throw new Error(`Internal inconsistency, single document live query returned more than one document. Query: ${this.query}, documentIDs: ${documentIDsAsBase64Strings.join(', ')}.`)
+      }
+
+      if (event.isInitial === false && event.oldDocuments.length > 1) throw new Error(`Internal inconsistency, single document live query returned an update event with more than one old documents. Query ${this.query}.`)
+      if (event.isInitial === false && event.insertions.length > 1) throw new Error(`Internal inconsistency, single document live query returned an update event with more than one insertion, which doesn't make sense for single document observations. Query ${this.query}.`)
+      if (event.isInitial === false && event.deletions.length > 1) throw new Error(`Internal inconsistency, single document live query returned an update event with more than one deletion, which doesn't make sense for single document observations. Query ${this.query}.`)
+      if (event.isInitial === false && event.updates.length > 1) throw new Error(`Internal inconsistency, single document live query returned an update event with more than one update, which doesn't make sense for single document observations. Query ${this.query}.`)
+      if (event.isInitial === false && event.moves.length > 0) throw new Error(`Internal inconsistency, single document live query returned an update event with moves, which doesn't make sense for single document observations. Query ${this.query}.`)
+
+      const totalNumberOfManipulations = event.isInitial === true ? 0 : event.insertions.length + event.deletions.length + event.updates.length
+      if (totalNumberOfManipulations > 1) throw new Error(`Internal inconsistency, single document live query returned a combination of inserts, updates, and/or deletes, which doesn't make sense for single document observation. Query ${this.query}.`)
+
+      // IDEA: use `undefined` instead of `null` and
+      // adapt Wasm variant plus API definition.
+      const document = documents[0] || null
+      const oldDocument = event.isInitial === true ? undefined : event.oldDocuments[0]
+
+      const singleDocumentEvent = new SingleDocumentLiveQueryEvent(event.isInitial, oldDocument)
+      if (waitForNextSignal) {
+        handler(document, singleDocumentEvent, signalNext)
+      } else {
+        try {
+          handler(document, singleDocumentEvent)
+        } finally {
+          signalNext()
+        }
+      }
+    })
+
+    this.collection.store.ditto.liveQueryManager.startLiveQuery(liveQuery)
+    return liveQuery
+  }
+}

package/react-native/src/sources/presence-manager.ts

@@ -0,0 +1,161 @@
+//
+// Copyright © 2021 DittoLive Incorporated. All rights reserved.
+//
+
+import * as FFI from './ffi'
+import { Bridge } from './bridge'
+import { generateEphemeralToken } from './internal'
+
+import type { Ditto, RemotePeer } from './ditto'
+
+/** @internal */
+export type PresenceToken = string
+
+/**
+ * @internal
+ * @deprecated Replaced by `Presence`.
+ */
+export class PresenceManager {
+  readonly ditto: Ditto
+
+  constructor(ditto: Ditto) {
+    this.ditto = ditto
+    this.isClosed = false
+    this.isRegistered = false
+    this.currentRemotePeers = []
+    this.callbacksByPresenceToken = {}
+  }
+
+  /** @internal */
+  addObserver(callback: (remotePeers: RemotePeer[]) => void): PresenceToken {
+    if (this.isClosed) {
+
+      throw new Error(`Internal inconsistency, can't add presence observer, observer mananger close()-ed.`)
+    }
+
+    this.registerIfNeeded()
+
+    const token = generateEphemeralToken()
+    this.callbacksByPresenceToken[token] = callback
+    this.ditto.keepAlive.retain(`PresenceObservation.${token}`)
+
+    callback(this.currentRemotePeers)
+
+    return token
+  }
+
+  /** @internal */
+  removeObserver(token: PresenceToken) {
+    const callback = this.callbacksByPresenceToken[token]
+
+    if (typeof callback === 'undefined') {
+      throw new Error(`Can't remove presence observer, token '${token}' has never been registered before.`)
+    }
+
+    if (callback === null) {
+      // Observer has already been removed, no-op.
+      return
+    }
+
+    if (typeof this.callbacksByPresenceToken[token] != 'undefined') {
+      this.ditto.keepAlive.release(`PresenceObservation.${token}`)
+
+      this.callbacksByPresenceToken[token] = null
+      this.unregisterIfNeeded()
+    }
+  }
+
+  /** @internal */
+  hasObserver(token: PresenceToken): boolean {
+    return typeof this.callbacksByPresenceToken[token] != 'undefined'
+  }
+
+  /** @internal */
+  close() {
+    this.isClosed = true
+    for (const token in this.callbacksByPresenceToken) {
+      this.removeObserver(token)
+    }
+  }
+
+  // ------------------------------------------------------------ Private ------
+
+  private isClosed: boolean
+  private isRegistered: boolean
+  private currentRemotePeers: RemotePeer[]
+  private callbacksByPresenceToken: { [key: string]: ((remotePeers: RemotePeer[]) => void) | null }
+
+  private hasObservers(): boolean {
+    return Object.keys(this.callbacksByPresenceToken).length > 0
+  }
+
+  private registerIfNeeded() {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(this.ditto)
+    ditto.deferClose(() => {
+      const needsToRegister = !this.isRegistered
+      if (needsToRegister) {
+        this.isRegistered = true
+        const remotePeersJSONString = FFI.dittoPresenceV1(dittoHandle.deref())
+        this.currentRemotePeers = this.decode(remotePeersJSONString).sort(this.compareRemotePeers)
+        FFI.dittoRegisterPresenceV1Callback(dittoHandle.deref(), this.handlePresenceV1Callback.bind(this))
+      }
+    })
+  }
+
+  private unregisterIfNeeded() {
+    const ditto = this.ditto
+    const dittoHandle = Bridge.ditto.handleFor(ditto)
+    ditto.deferClose(() => {
+      const needsToUnregister = !this.hasObservers() && this.isRegistered
+      if (needsToUnregister) {
+        this.isRegistered = false
+        FFI.dittoClearPresenceCallback(dittoHandle.deref())
+        this.currentRemotePeers = []
+      }
+    })
+  }
+
+  private handlePresenceV1Callback(remotePeersJSONString: string) {
+    const remotePeers = this.decode(remotePeersJSONString).sort(this.compareRemotePeers)
+    this.currentRemotePeers = remotePeers
+    this.notify()
+  }
+
+  private notify() {
+    if (this.isClosed) {
+      // NOTE: we don't notify observers after closing.
+      return
+    }
+
+    for (const token in this.callbacksByPresenceToken) {
+      const callback = this.callbacksByPresenceToken[token]
+      if (callback) callback(this.currentRemotePeers)
+    }
+  }
+
+  private decode(remotePeersJSONString: string): RemotePeer[] {
+    const remotePeersJSON: any[] = JSON.parse(remotePeersJSONString)
+    return remotePeersJSON.map((remotePeerJSON) => {
+      return {
+        networkID: remotePeerJSON['network_id'],
+        deviceName: remotePeerJSON['device_name'],
+        rssi: remotePeerJSON['rssi'] ?? undefined,
+        approximateDistanceInMeters: remotePeerJSON['approximate_distance_in_meters'] ?? undefined,
+        connections: remotePeerJSON['connections'],
+      }
+    })
+  }
+
+  private compareRemotePeers(left: RemotePeer, right: RemotePeer) {
+    // NOTE: we use the exact same sort order here as in the ObjC version.
+
+    if (left.connections.length === 0 && right.connections.length > 0) return +1
+    if (left.connections.length > 0 && right.connections.length === 0) return -1
+
+    if (left.deviceName < right.deviceName) return -1
+    if (left.deviceName > right.deviceName) return +1
+
+    return 0
+  }
+}