feat(experimental): MultiShapeStream and TransactionalMultiShapeStream APIs (#2356)

This adds two new APIs to the @electric-sql/experimental package:

## `MultiShapeStream`

A multi-shape stream is a stream that can subscribe to multiple shapes.
It ensures that all shapes will receive at least an `up-to-date` message
from Electric within the `checkForUpdatesAfter` interval.

The emitted messages have an additional `shape` prop that is the name of
the shape provided in the shapes object when constructing the
`MultiShapeStream`.

```ts
const multiShapeStream = new MultiShapeStream({
  shapes: {
    shape1: {
      url: 'http://localhost:3000/v1/shape1',
    },
    shape2: {
      url: 'http://localhost:3000/v1/shape2',
    },
  },
})

multiShapeStream.subscribe((msgs) => {
  console.log(msgs)
})

// or with ShapeStream instances
const multiShapeStream = new MultiShapeStream({
  shapes: {
    shape1: new ShapeStream({ url: 'http://localhost:3000/v1/shape1' }),
    shape2: new ShapeStream({ url: 'http://localhost:3000/v1/shape2' }),
  },
})
```

## `TransactionalMultiShapeStream`

A transactional multi-shape stream is a multi-shape stream that emits
the messages in transactional batches.
It uses the `lsn` metadata to infer transaction boundaries, and the
`op_position` metadata to sort the messages within a transaction.

Note that you will only receive change massages on the main subscription
(in transactional batches), and not any control massages.

```ts
const transactionalMultiShapeStream = new TransactionalMultiShapeStream({
  shapes: {
    shape1: {
      url: 'http://localhost:3000/v1/shape1',
    },
    shape2: {
      url: 'http://localhost:3000/v1/shape2',
    },
  },
})

transactionalMultiShapeStream.subscribe((msgs) => {
  console.log(msgs)
})

// or with ShapeStream instances
const transactionalMultiShapeStream = new TransactionalMultiShapeStream({
  shapes: {
    shape1: new ShapeStream({ url: 'http://localhost:3000/v1/shape1' }),
    shape2: new ShapeStream({ url: 'http://localhost:3000/v1/shape2' }),
  },
})
```

Author: samwillis

.changeset/old-tigers-collect.md

@@ -0,0 +1,5 @@
+---
+"@electric-sql/client": patch
+---
+
+Correctly set the cache busting url param when using `forceDisconnectAndRefresh`

.changeset/serious-clouds-thank.md

@@ -0,0 +1,5 @@
+---
+"@electric-sql/experimental": patch
+---
+
+New experimental MultiShapeStream and TransactionalMultiShapeStream APIs that combine multiple shapes streams into a single stream. Note: these two APIs are experimental and are likely to change in a future version of the package.

packages/experimental/package.json

@@ -6,10 +6,8 @@
   "bugs": {
     "url": "https://github.com/electric-sql/electric/issues"
   },
-  "dependencies": {
-    "@electric-sql/client": "workspace:*"
-  },
   "devDependencies": {
+    "@electric-sql/client": "workspace:*",
     "@types/pg": "^8.11.6",
     "@types/uuid": "^10.0.0",
     "@typescript-eslint/eslint-plugin": "^7.14.1",
@@ -27,6 +25,14 @@
     "uuid": "^10.0.0",
     "vitest": "^2.0.2"
   },
+  "peerDependencies": {
+    "@electric-sql/client": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@electric-sql/client": {
+      "optional": false
+    }
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {

packages/experimental/src/index.ts

@@ -1 +1,2 @@
 export * from './match'
+export * from './multi-shape-stream'