feat: Add JS RPC Support for getYDoc and updateYDoc

[naporin0624]

closed: #49 closed: #46

This PR introduces several significant updates to the y-durableobjects library, with a major focus on adding new JS RPC support for getYDoc and updateYDoc APIs. These enhancements significantly improve the library's functionality and ease of integration with Hono. Key changes include:

1. Major Features:

   • JS RPC APIs getYDoc and updateYDoc:
     • Implemented new JS RPC APIs to fetch (getYDoc) and update (updateYDoc) YDocs within Durable Objects.
     • Allows manipulating YDocs from sources other than WebSocket, enhancing flexibility and control.

2. Hono Integration:

   • Added examples for integrating y-durableobjects with Hono, using both shorthand and detailed methods.
   • Demonstrated how to handle WebSocket connections via fetch due to the current limitations of JS RPC (see Cloudflare issue).

3. Extending with JS RPC:

   • Explained how to extend y-durableobjects for advanced operations, including accessing and manipulating protected fields:
     • app: The Hono app instance used to handle requests.
     • doc: An instance of WSSharedDoc managing the YDoc state.
     • storage: A YTransactionStorageImpl instance for storing and retrieving YDoc updates.
     • sessions: A map to manage active WebSocket sessions.
     • awarenessClients: A set to track client awareness states.
   • Provided a minimal example of creating a custom Durable Object by extending YDurableObjects.

4. Client-side Typed Fetch with Hono RPC:

   • Included a guide for creating a typed client using hc from hono/client to facilitate Hono RPC on the client side.

5. Documentation Updates:

   • Updated the README with detailed examples and explanations for the new features and integrations.
   • Ensured clarity and ease of understanding for developers looking to utilize the new functionalities.

These enhancements aim to provide developers with more robust tools and clearer guidance for integrating Yjs and Durable Objects within the Cloudflare Workers environment, leveraging the power of Hono for efficient and scalable real-time collaboration solutions.

[changeset-bot[bot]]

🦋 Changeset detected

Latest commit: 4b6afef618b719effd0655a16a4e45326e692ea5

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

| Name | Type | | ---------------- | ----- | | y-durableobjects | Major |

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cloudflare-workers-and-pages[bot]]

Deploying yjs-worker with    Cloudflare Pages

Latest commit:	4b6afef
Status:	✅  Deploy successful!
Preview URL:	https://f9f3aef5.yjs-worker.pages.dev
Branch Preview URL:	https://feat-add-y-doc-handle-method.yjs-worker.pages.dev

View logs

[pkg-pr-new[bot]]

commit: 4b6afef

pnpm add https://pkg.pr.new/napolab/y-durableobjects@50

Open in Stackblitz •

[github-actions[bot]]

📊 Package size report   21%↑

File	Before	After
dist/chunk-44JZXIF7.js	—	379 B
dist/chunk-44JZXIF7.js.map	—	784 B
dist/chunk-GLWCU3YD.cjs	—	473 B
dist/chunk-GLWCU3YD.cjs.map	—	783 B
dist/helpers/upgrade.cjs	—	216 B
dist/helpers/upgrade.cjs.map	—	51 B
dist/helpers/upgrade.d.cts	—	273 B
dist/helpers/upgrade.d.ts	—	273 B
dist/helpers/upgrade.js	—	107 B
dist/helpers/upgrade.js.map	—	71 B
dist/index.cjs	11.3 kB	6%↑12.0 kB
dist/index.cjs.map	20.9 kB	7%↑22.2 kB
dist/index.d.cts	2.2 kB	114%↑4.7 kB
dist/index.d.ts	2.2 kB	114%↑4.7 kB
dist/index.js	9.9 kB	6%↑10.5 kB
dist/index.js.map	21.0 kB	7%↑22.4 kB
package.json	2.0 kB	18%↑2.4 kB
README.md	5.0 kB	58%↑7.8 kB
Total (Includes all files)	75.6 kB	21%↑91.3 kB
Tarball size	15.3 kB	22%↑18.7 kB

Unchanged files

| File | Size | | -------------------------------------------------------------------------------------------------- | -------: | | [`LICENSE`](https://github.com/napolab/y-durableobjects/blob/feat/add-y-doc-handle-method/LICENSE) | `1.1 kB` |

_{🤖 This report was automatically generated by pkg-size-action}

[naporin0624]

Hi, @tobimori

I have pre-released an enhanced version of y-durableobjects with JSRPC added. It is available from https://pkg.pr.new/napolab/y-durableobjects@50 so please try it out and let me know what you think.

If it seems to be working well, I will release it.

Usage Examples

Usage including fetch (https://github.com/napolab/y-durableobjects/blob/6c2063d8b5745cab03c47d6f01fe6a70a7146868/src/e2e/e2e.test.ts)

getYDoc

API to get YDoc as Uint8Array

app.get("/rooms/:id/state", async (c) => {
  const roomId = c.req.param("id");
  const id = c.env.Y_DURABLE_OBJECTS.idFromName(roomId);
  const stub = c.env.Y_DURABLE_OBJECTS.get(id);

  const doc = await stub.getYDoc();
  const base64 = fromUint8Array(doc);

  return c.json({ doc: base64 }, 200);
});

updateYDoc

API for updating YDoc from Uint8Array

app.post("/rooms/:id/update", async (c) => {
  const roomId = c.req.param("id");
  const id = c.env.Y_DURABLE_OBJECTS.idFromName(roomId);
  const stub = c.env.Y_DURABLE_OBJECTS.get(id);

  const buffer = await c.req.arrayBuffer();
  const update = new Uint8Array(buffer);

  await stub.updateYDoc(update);

  return c.json(null, 200);
});

[naporin0624]

Partial support: https://github.com/napolab/y-durableobjects/pull/20