@edryslabs/genericprovider 1.0.4 → 1.5.2

package/dist/transport.d.ts

@@ -24,23 +24,29 @@ export interface Transport {
      * @param data - Binary data to send (Yjs updates or awareness)
      */
     send(data: Uint8Array): void | Promise<void>;
-    /**
-     * Optional: send binary data to a single peer instead of broadcasting.
-     * Only transports with a peer concept (e.g. WebRTC) can implement this.
-     * When absent, the provider falls back to broadcast-and-filter.
-     *
-     * @param peerId - Target peer's ID
-     * @param data - Binary data to send
-     */
-    sendTo?(peerId: string, data: Uint8Array): void | Promise<void>;
     /**
      * Register a callback for incoming binary data.
      * The transport calls this callback whenever data is received.
      *
-     * @param callback - Function to call with received data
+     * @param callback - Function to call with received data. Transports that
+     * know which peer a message came from pass that peer's address as the
+     * second argument (the same id `sendTo` accepts); relays that only see a
+     * room call it with the data alone. GenericProvider remembers the address
+     * per remote clientID and, when `sendTo` exists, answers that peer's
+     * requests directly instead of broadcasting the reply to the room.
      * @returns Cleanup function to unregister the callback
      */
-    onMessage(callback: (data: Uint8Array) => void): () => void;
+    onMessage(callback: (data: Uint8Array, from?: string) => void): () => void;
+    /**
+     * Optional: send binary data to ONE peer, identified by the address the
+     * transport passed as `from` to the onMessage callback. Mesh transports
+     * (peerjs, simple-peer, trystero) implement this with the peer's data
+     * channel; relays leave it undefined and every reply stays a broadcast,
+     * exactly as before this method existed. When present, SyncStep2 replies,
+     * acks and presence responses to a join go to the requester only: N-1
+     * deliveries per request become 1.
+     */
+    sendTo?(peerId: string, data: Uint8Array): void | Promise<void>;
     /**
      * Optional: register a callback that fires whenever a new peer data channel
      * opens. The provider uses this to push its local state to the new peer
@@ -51,11 +57,14 @@ export interface Transport {
      */
     onPeerConnect?(callback: (peerId: string) => void): () => void;
     /**
-     * Optional: register a callback that fires when a connected peer disconnects
-     * (channel close or error). Consumers use this for presence/leave tracking.
-     *
-     * @param callback - Function to call with the departed peer's ID
-     * @returns Cleanup function to unregister the callback
+     * Optional: the counterpart of onPeerConnect - fires when a peer's data
+     * channel closes (mesh transports) or the backend's presence service
+     * reports it gone (PubNub leave/timeout). The id is the one `onMessage`
+     * passed as `from` for that peer. GenericProvider then drops that peer's
+     * awareness state at once instead of after the awareness lease, forgets
+     * its address, and - since departures are reported by the transport -
+     * lets `awarenessTimeoutMs` default to a long safety net, which removes
+     * the 15 s awareness renewal broadcasts (round 5, item 2).
      */
     onPeerDisconnect?(callback: (peerId: string) => void): () => void;
     /**
@@ -98,6 +107,37 @@ export interface Transport {
      * without reducing round trips that were already cheap.
      */
     readonly preferredBatchMs?: number;
+    /**
+     * Optional hint: the round-trip time class (ms) this transport expects -
+     * e.g. ~700 for a Matrix homeserver long-poll, ~500 for a Gun relay
+     * mesh, undefined for low-latency push transports. GenericProvider uses
+     * it to seed its round-trip estimate before the first measured sample
+     * arrives, so the first response wait after a join and the first reply
+     * suppression window already fit the transport instead of the
+     * low-latency defaults (measured before this hint: on a 350 ms profile a
+     * 100-peer join burst spent most of its traffic on retries fired before
+     * the first replies could have arrived). Replaced by measured samples as
+     * soon as they exist.
+     */
+    readonly expectedRttMs?: number;
+    /**
+     * Optional hint: default for `compressionThresholdBytes` when the caller
+     * passes nothing. Transports that cap a single message (PubNub 32 KiB,
+     * Ably 64 KiB, Matrix 64 KiB, Nostr 64 KiB) or bill per delivered size
+     * (Ably, 5 KiB units) set this so a full-document push is compressed
+     * before it is chunked. Changes the transport's default wire format (a
+     * 1-byte flag on every message) - all peers of a room must run the same
+     * library version, as the README already requires. An explicit
+     * `compressionThresholdBytes: 0` still disables compression.
+     */
+    readonly preferredCompressMinBytes?: number;
+    /**
+     * Optional hint: default for `awarenessInterval` (ms). A transport whose
+     * backend rate-limits sends per user (Synapse: 0.2 messages/s, burst 10
+     * by default) sets this well above the 100 ms default, so cursor traffic
+     * does not spend the burst within seconds.
+     */
+    readonly preferredAwarenessMs?: number;
 }
 /**
  * Connection configuration passed to transport.connect()
@@ -108,6 +148,19 @@ export interface ConnectionConfig {
     room: string;
     /** Optional password for encrypted communication */
     password?: string;
+    /**
+     * Optional: a promise GenericProvider.connect() awaits after the
+     * transport is connected and before it sends its first sync - typically
+     * the connect() promise of a persistence provider (IndexedDB) on the same
+     * document. Sent before the local copy is loaded, the first beacon
+     * carries an empty state vector and the room answers with the whole
+     * document although it is already on disk (round 5, item 7). While
+     * waiting, doc updates are treated as the load and not broadcast, and
+     * the loaded state then counts as confirmed by the room (no full-state
+     * push): the beacon reconciles both directions. Incoming messages are
+     * processed while waiting; a rejected promise is ignored.
+     */
+    waitFor?: Promise<unknown>;
     /** Any other backend-specific configuration */
     [key: string]: any;
 }

package/dist/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhD;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAA;IAElB;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5C;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/D;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAE3D;;;;;;;OAOG;IACH,aAAa,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAE9D;;;;;;OAMG;IACH,gBAAgB,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAEjE;;;;;;;;OAQG;IACH,WAAW,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAAA;IAEvD;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAErC;;;;;OAKG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAEpF;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAE7B;;;;;;;;;OASG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IAEZ,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB,+CAA+C;IAC/C,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,cAAc,CAAA;CAAE,GACzB;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,GACvB;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAA"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhD;;;OAGG;IACH,UAAU,IAAI,IAAI,CAAA;IAElB;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5C;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAE1E;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/D;;;;;;;OAOG;IACH,aAAa,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAE9D;;;;;;;;;OASG;IACH,gBAAgB,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAEjE;;;;;;;;OAQG;IACH,WAAW,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAAA;IAEvD;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAErC;;;;;OAKG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAEpF;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAE7B;;;;;;;;;OASG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAElC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAE/B;;;;;;;;;OASG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAE3C;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IAEZ,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;IAE1B,+CAA+C;IAC/C,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,cAAc,CAAA;CAAE,GACzB;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,GACvB;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edryslabs/genericprovider",
-  "version": "1.0.4",
+  "version": "1.5.2",
   "description": "A clean, minimal, backend-agnostic provider for Yjs that lets you implement any transport mechanism.",
   "license": "ISC",
   "author": "André Dietrich",
@@ -8,6 +8,10 @@
     "type": "git",
     "url": "git+https://github.com/andre-dietrich/y-generic.git"
   },
+  "bugs": {
+    "url": "https://github.com/andre-dietrich/y-generic/issues"
+  },
+  "homepage": "https://github.com/andre-dietrich/y-generic#readme",
   "main": "./dist/lib.js",
   "types": "./dist/lib.d.ts",
   "targets": {
@@ -62,24 +66,29 @@
     "./providers/nostr": {
       "types": "./dist/providers/nostr/index.d.ts",
       "default": "./dist/providers/nostr/index.js"
+    },
+    "./providers/ably": {
+      "types": "./dist/providers/ably/index.d.ts",
+      "default": "./dist/providers/ably/index.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "dev:dummy": "npx parcel serve test/dummy/index.html --open --port 3011",
-    "dev:edge-cases": "npx parcel serve test/dummy/edge-cases.html --open --port 3012",
-    "dev:simple-peer": "npx parcel serve test/simple-peer/index.html --open --port 3002",
-    "dev:peerjs": "npx parcel serve test/peerjs/index.html --open --port 3003",
-    "dev:indexeddb": "npx parcel serve test/indexeddb/index.html --open --port 3004",
-    "dev:gun": "npx parcel serve test/gun/index.html --open --port 3005",
-    "dev:trystero": "npx parcel serve test/trystero/index.html --open --port 3006",
-    "dev:pubnub": "npx parcel serve test/pubnub/index.html --open --port 3007",
-    "dev:websocket": "npx parcel serve test/websocket/index.html --open --port 3008",
-    "dev:matrix": "npx parcel serve test/matrix/index.html --open --port 3009",
-    "dev:supabase": "npx parcel serve test/supabase/index.html --open --port 3010",
-    "dev:nostr": "npx parcel serve test/nostr/index.html --open --port 3013",
+    "dev:dummy": "npx parcel serve --dist-dir .parcel-dev test/dummy/index.html --open --port 3011",
+    "dev:edge-cases": "npx parcel serve --dist-dir .parcel-dev test/dummy/edge-cases.html --open --port 3012",
+    "dev:simple-peer": "npx parcel serve --dist-dir .parcel-dev test/simple-peer/index.html --open --port 3002",
+    "dev:peerjs": "npx parcel serve --dist-dir .parcel-dev test/peerjs/index.html --open --port 3003",
+    "dev:indexeddb": "npx parcel serve --dist-dir .parcel-dev test/indexeddb/index.html --open --port 3004",
+    "dev:gun": "npx parcel serve --dist-dir .parcel-dev test/gun/index.html --open --port 3005",
+    "dev:trystero": "npx parcel serve --dist-dir .parcel-dev test/trystero/index.html --open --port 3006",
+    "dev:pubnub": "npx parcel serve --dist-dir .parcel-dev test/pubnub/index.html --open --port 3007",
+    "dev:websocket": "npx parcel serve --dist-dir .parcel-dev test/websocket/index.html --open --port 3008",
+    "dev:matrix": "npx parcel serve --dist-dir .parcel-dev test/matrix/index.html --open --port 3009",
+    "dev:supabase": "npx parcel serve --dist-dir .parcel-dev test/supabase/index.html --open --port 3010",
+    "dev:nostr": "npx parcel serve --dist-dir .parcel-dev test/nostr/index.html --open --port 3013",
+    "dev:ably": "npx parcel serve --dist-dir .parcel-dev test/ably/index.html --open --port 3014",
     "test": "parcel test.html --open",
     "build": "rm -rf dist && tsc",
     "build:demo:index": "npx parcel build test/index.html --dist-dir demos --public-url ./ --no-source-maps",
@@ -91,22 +100,27 @@
     "build:demo:trystero": "npx parcel build test/trystero/index.html --dist-dir demos/trystero --public-url ./ --no-source-maps",
     "build:demo:pubnub": "npx parcel build test/pubnub/index.html --dist-dir demos/pubnub --public-url ./ --no-source-maps",
     "build:demo:websocket": "npx parcel build test/websocket/index.html --dist-dir demos/websocket --public-url ./ --no-source-maps",
+    "build:demo:matrix": "npx parcel build test/matrix/index.html --dist-dir demos/matrix --public-url ./ --no-source-maps",
     "build:demo:supabase": "npx parcel build test/supabase/index.html --dist-dir demos/supabase --public-url ./ --no-source-maps",
     "build:demo:nostr": "npx parcel build test/nostr/index.html --dist-dir demos/nostr --public-url ./ --no-source-maps",
-    "build:demos": "rm -rf demos && npm run build:demo:index && npm run build:demo:dummy && npm run build:demo:simple-peer && npm run build:demo:peerjs && npm run build:demo:indexeddb && npm run build:demo:gun && npm run build:demo:trystero && npm run build:demo:pubnub && npm run build:demo:websocket && npm run build:demo:matrix && npm run build:demo:supabase && npm run build:demo:nostr"
+    "build:demo:ably": "npx parcel build test/ably/index.html --dist-dir demos/ably --public-url ./ --no-source-maps",
+    "build:demos": "rm -rf demos && npm run build:demo:index && npm run build:demo:dummy && npm run build:demo:simple-peer && npm run build:demo:peerjs && npm run build:demo:indexeddb && npm run build:demo:gun && npm run build:demo:trystero && npm run build:demo:pubnub && npm run build:demo:websocket && npm run build:demo:matrix && npm run build:demo:supabase && npm run build:demo:nostr && npm run build:demo:ably"
   },
   "dependencies": {
-    "y-provider": "^0.10.3-canary.2"
+    "lib0": "^0.2.98",
+    "y-protocols": "^1.0.6",
+    "yjs": "^13.6.29"
   },
   "peerDependencies": {
+    "ably": "^2.0.0",
     "gun": "^0.2020.1240",
-    "lib0": "^0.2.98",
     "peerjs": "^1.5.0",
-    "simple-peer": "^9.11.0",
-    "y-protocols": "^1.0.6",
-    "yjs": "^13.6.29"
+    "simple-peer": "^9.11.0"
   },
   "peerDependenciesMeta": {
+    "ably": {
+      "optional": true
+    },
     "gun": {
       "optional": true
     },
@@ -122,16 +136,13 @@
     "@types/node": "^20.0.0",
     "buffer": "^6.0.3",
     "events": "^3.3.0",
-    "lib0": "^0.2.98",
     "parcel": "^2.16.4",
     "process": "^0.11.10",
-    "quill-cursors": "^4.0.4",
     "quill": "^2.0.3",
+    "quill-cursors": "^4.0.4",
     "typescript": "^5.0.0",
-    "y-protocols": "^1.0.6",
     "y-quill": "^1.0.0",
     "y-webrtc": "^10.3.0",
-    "y-websocket": "^3.0.0",
-    "yjs": "^13.6.29"
+    "y-websocket": "^3.0.0"
   }
 }