chore: improve types for Hypercore peers (#735)

*This is a types-only change.*

Before this change, we used `any` for a Hypercore peer's type.

After this change, we use a new type, `HypercorePeer`, designed to match
[Hypercore's `Peer` class][0].

Ideally, we would put this in `@digidem/types` or DefinitelyTyped. For
now, I think this is an improvement over the `any`s we currently use.

I did this because I'm working with peer-related code and found the
`any`s difficult to work with.

[0]: https://github.com/holepunchto/hypercore/blob/de993dc051301f03570df0eb7929c06286745563/lib/replicator.js#L331

Author: EvanHahn

src/core-manager/index.js

@@ -14,6 +14,8 @@ import { coresTable } from '../schema/project.js'
 import * as rle from './bitfield-rle.js'
 import { CoreIndex } from './core-index.js'
 
+/** @typedef {import('../types.js').HypercorePeer} HypercorePeer */
+
 const WRITER_CORE_PREHAVES_DEBOUNCE_DELAY = 1000
 
 export const kCoreManagerReplicate = Symbol('replicate core manager')
@@ -401,7 +403,7 @@ export class CoreManager extends TypedEmitter {
 
   /**
    * @param {ProjectExtension} msg
-   * @param {any} peer
+   * @param {HypercorePeer} peer
    */
   #handleProjectMessage({ wantCoreKeys, ...coreKeys }, peer) {
     const message = ProjectExtension.create()
@@ -426,7 +428,7 @@ export class CoreManager extends TypedEmitter {
 
   /**
    * @param {Omit<HaveMsg, 'namespace'> & { namespace: Namespace | 'UNRECOGNIZED' }} msg
-   * @param {any} peer
+   * @param {HypercorePeer} peer
    */
   #handleHaveMessage(msg, peer) {
     const { start, discoveryKey, bitfield, namespace } = msg
@@ -444,7 +446,7 @@ export class CoreManager extends TypedEmitter {
 
   /**
    *
-   * @param {any} peer
+   * @param {HypercorePeer} peer
    * @param {Iterable<{ core: Hypercore<Hypercore.ValueEncoding, Buffer>, namespace: Namespace }>} cores
    */
   async #sendHaves(peer, cores) {
@@ -639,7 +641,7 @@ function findPeer(core, publicKey, { timeout = 200 } = {}) {
 
     core.on('peer-add', onPeer)
 
-    /** @param {any} peer */
+    /** @param {HypercorePeer} peer */
     function onPeer(peer) {
       if (peer.remotePublicKey.equals(publicKey)) {
         clearTimeout(timeoutId)

src/sync/core-sync-state.js

@@ -2,6 +2,8 @@ import { keyToId } from '../utils.js'
 import RemoteBitfield, {
   BITS_PER_PAGE,
 } from '../core-manager/remote-bitfield.js'
+/** @typedef {import('../types.js').HypercoreRemoteBitfield} HypercoreRemoteBitfield */
+/** @typedef {import('../types.js').HypercorePeer} HypercorePeer */
 
 /**
  * @typedef {RemoteBitfield} Bitfield
@@ -192,7 +194,7 @@ export class CoreSyncState {
    * emit state updates whenever the peer remote bitfield changes
    *
    * (defined as class field to bind to `this`)
-   * @param {any} peer
+   * @param {HypercorePeer} peer
    */
   #onPeerAdd = (peer) => {
     const peerId = keyToId(peer.remotePublicKey)
@@ -217,11 +219,11 @@ export class CoreSyncState {
     // a result of these two internal calls.
     const originalOnBitfield = peer.onbitfield
     const originalOnRange = peer.onrange
-    peer.onbitfield = (/** @type {any[]} */ ...args) => {
+    peer.onbitfield = (...args) => {
       originalOnBitfield.apply(peer, args)
       this.#update()
     }
-    peer.onrange = (/** @type {any[]} */ ...args) => {
+    peer.onrange = (...args) => {
       originalOnRange.apply(peer, args)
       this.#update()
     }
@@ -231,7 +233,7 @@ export class CoreSyncState {
    * Handle a peer being removed - keeps it in state, but sets state.connected = false
    *
    * (defined as class field to bind to `this`)
-   * @param {any} peer
+   * @param {HypercorePeer} peer
    */
   #onPeerRemove = (peer) => {
     const peerId = keyToId(peer.remotePublicKey)
@@ -253,7 +255,7 @@ export class CoreSyncState {
 export class PeerState {
   /** @type {Bitfield} */
   #preHaves = new RemoteBitfield()
-  /** @type {Bitfield | undefined} */
+  /** @type {HypercoreRemoteBitfield | undefined} */
   #haves
   /** @type {Bitfield} */
   #wants = new RemoteBitfield()
@@ -274,7 +276,7 @@ export class PeerState {
     return this.#preHaves.insert(start, bitfield)
   }
   /**
-   * @param {Bitfield} bitfield
+   * @param {HypercoreRemoteBitfield} bitfield
    */
   setHavesBitfield(bitfield) {
     this.#haves = bitfield
@@ -434,7 +436,7 @@ export function bitCount32(n) {
 /**
  * Get a 32-bit "chunk" (word) of the bitfield.
  *
- * @param {RemoteBitfield} bitfield
+ * @param {Bitfield | HypercoreRemoteBitfield} bitfield
  * @param {number} index
  */
 function getBitfieldWord(bitfield, index) {

src/types.ts

@@ -7,6 +7,7 @@ import type {
 } from 'type-fest'
 import { SUPPORTED_BLOB_VARIANTS } from './blob-store/index.js'
 import { MapeoCommon, MapeoDoc, MapeoValue, decode } from '@mapeo/schema'
+import type BigSparseArray from 'big-sparse-array'
 import type Protomux from 'protomux'
 import type NoiseStream from '@hyperswarm/secret-stream'
 import { Duplex } from 'streamx'
@@ -105,6 +106,30 @@ export type PublicKey = Buffer
 export type SecretKey = Buffer
 export type IdentityKeyPair = KeyPair
 
+type HypercoreRemoteBitfieldPage = {
+  bitfield: Uint32Array
+}
+
+/**
+ * A subset of Hypercore's `RemoteBitfield` class that we use.
+ */
+export type HypercoreRemoteBitfield = {
+  _pages: BigSparseArray<HypercoreRemoteBitfieldPage>
+  get(index: number): boolean
+}
+
+/**
+ * A subset of Hypercore's `Peer` class that we use.
+ * TODO: Contribute these types upstream.
+ */
+export type HypercorePeer = {
+  protomux: Protomux
+  remotePublicKey: Buffer
+  remoteBitfield: HypercoreRemoteBitfield
+  onbitfield: (options: { start: number; bitfield: Buffer }) => void
+  onrange: (options: { drop: boolean; start: number; length: number }) => void
+}
+
 export { NoiseStream }
 type ProtocolStream = Omit<NoiseStream, 'userData'> & {
   userData: Protomux