@absolutejs/sync-yjs 0.0.1

package/README.md

@@ -0,0 +1,57 @@
+# @absolutejs/sync-yjs
+
+A [Yjs](https://github.com/yjs/yjs)-backed collaborative-text CRDT for
+[`@absolutejs/sync`](https://github.com/absolutejs/sync), behind the same
+`CrdtText` / `TextCrdtAdapter` contract as the core's zero-dependency `rgaText`.
+
+`@absolutejs/sync/crdt` ships a first-party RGA text CRDT that's great for
+offline-merge and moderate collaboration. When you need production-scale
+collaborative text — efficient deltas, no unbounded tombstone growth, the
+interleaving guarantees the community relies on — Yjs is the staple. This adapter
+lets you swap it in without touching your call sites.
+
+## Install
+
+```bash
+bun add @absolutejs/sync-yjs yjs
+```
+
+`@absolutejs/sync` is a peer dependency (you already have it). `yjs` is a runtime
+dependency you install alongside.
+
+## Use
+
+```ts
+import { yjsText } from '@absolutejs/sync-yjs';
+// ...instead of: import { rgaText } from '@absolutejs/sync/crdt';
+
+// Client — a live doc per replica (e.g. per tab/device)
+const doc = yjsText.create('tab-a', initialStateFromServer);
+doc.setText(textarea.value); // reconciles via a minimal diff
+socket.send(doc.state()); // broadcast the serialized (base64) state
+doc.merge(incomingState); // fold a peer's state into local edits
+doc.text(); // the merged visible text
+
+// Server — merge-on-write so concurrent writes combine instead of clobbering
+const next = yjsText.merge(storedState, incomingState);
+// store `next`; yjsText.textOf(next) is the plain text
+```
+
+The serialized state is a base64 string of a Yjs update — JSON-safe for the sync
+engine's change feed and for storing as a row field. `merge` is
+commutative/associative/idempotent, so the order writes arrive in doesn't matter.
+
+## The contract
+
+This package implements `TextCrdtAdapter<string>` from `@absolutejs/sync/crdt`:
+
+| Member                      | What it does                                                  |
+| --------------------------- | ------------------------------------------------------------- |
+| `create(replica, initial?)` | A live `CrdtText` doc: `text/setText/merge/state`.            |
+| `merge(a, b)`               | Combine two persisted states (server-side, no live instance). |
+| `empty()`                   | The serialized state of an empty document.                    |
+| `textOf(state)`             | The plain text of a persisted state.                          |
+
+## License
+
+CC BY-NC 4.0

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A Yjs-backed collaborative-text CRDT for `@absolutejs/sync`.
+ *
+ * `@absolutejs/sync` ships a zero-dependency RGA text CRDT (`rgaText`) that is
+ * fine for offline-merge and moderate collaboration. Yjs is the community staple
+ * for production-scale collaborative text — it solves the real footguns (tombstone
+ * growth, efficient deltas, interleaving). This adapter wraps Yjs behind the exact
+ * same `CrdtText` / `TextCrdtAdapter` contract, so swapping `rgaText` for `yjsText`
+ * needs no other change at the call site.
+ *
+ * The serialized state is a **base64 string** of a Yjs update, so it stays
+ * JSON-safe for transport over the sync engine's change feed and storage as a row
+ * field. Merges are commutative/associative/idempotent (Yjs guarantees it), so a
+ * merge-on-write mutation combines concurrent edits without clobbering.
+ */
+import type { CrdtText, TextCrdtAdapter } from '@absolutejs/sync/crdt';
+/** Create a live Yjs-backed collaborative-text doc for `replica`. */
+export declare const createYjsText: (replica: string, initial?: string) => CrdtText<string>;
+/**
+ * The Yjs collaborative-text backend as a {@link TextCrdtAdapter}. Drop-in for
+ * the first-party `rgaText`: `create` mints a live doc, `merge` combines two
+ * persisted states server-side, `empty`/`textOf` are conveniences.
+ */
+export declare const yjsText: TextCrdtAdapter<string>;

package/dist/index.js

@@ -0,0 +1,95 @@
+// @bun
+// src/index.ts
+import * as Y from "yjs";
+var TEXT_KEY = "text";
+var toBase64 = (bytes) => {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+};
+var fromBase64 = (base64) => {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0;index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+};
+var encode = (doc) => toBase64(Y.encodeStateAsUpdate(doc));
+var apply = (doc, state) => {
+  if (state.length > 0) {
+    Y.applyUpdate(doc, fromBase64(state));
+  }
+};
+var clientIdFor = (replica) => {
+  let hash = 0;
+  for (let index = 0;index < replica.length; index += 1) {
+    hash = Math.imul(hash, 31) + replica.charCodeAt(index) | 0;
+  }
+  return hash >>> 0;
+};
+var docFrom = (replica, initial) => {
+  const doc = new Y.Doc;
+  doc.clientID = clientIdFor(replica);
+  if (initial !== undefined) {
+    apply(doc, initial);
+  }
+  return doc;
+};
+var reconcile = (text, next) => {
+  const current = text.toString();
+  if (current === next) {
+    return;
+  }
+  let prefix = 0;
+  const maxPrefix = Math.min(current.length, next.length);
+  while (prefix < maxPrefix && current[prefix] === next[prefix]) {
+    prefix += 1;
+  }
+  let suffix = 0;
+  while (suffix < maxPrefix - prefix && current[current.length - 1 - suffix] === next[next.length - 1 - suffix]) {
+    suffix += 1;
+  }
+  const removed = current.length - prefix - suffix;
+  const inserted = next.slice(prefix, next.length - suffix);
+  if (removed > 0) {
+    text.delete(prefix, removed);
+  }
+  if (inserted.length > 0) {
+    text.insert(prefix, inserted);
+  }
+};
+var createYjsText = (replica, initial) => {
+  const doc = docFrom(replica, initial);
+  const text = doc.getText(TEXT_KEY);
+  return {
+    merge: (state) => apply(doc, state),
+    setText: (next) => doc.transact(() => reconcile(text, next)),
+    state: () => encode(doc),
+    text: () => text.toString()
+  };
+};
+var yjsText = {
+  create: createYjsText,
+  empty: () => encode(new Y.Doc),
+  merge: (a, b) => {
+    const doc = new Y.Doc;
+    apply(doc, a);
+    apply(doc, b);
+    return encode(doc);
+  },
+  textOf: (state) => {
+    const doc = new Y.Doc;
+    apply(doc, state);
+    return doc.getText(TEXT_KEY).toString();
+  }
+};
+export {
+  yjsText,
+  createYjsText
+};
+
+//# debugId=B68ED6342B46BD1064756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * A Yjs-backed collaborative-text CRDT for `@absolutejs/sync`.\n *\n * `@absolutejs/sync` ships a zero-dependency RGA text CRDT (`rgaText`) that is\n * fine for offline-merge and moderate collaboration. Yjs is the community staple\n * for production-scale collaborative text — it solves the real footguns (tombstone\n * growth, efficient deltas, interleaving). This adapter wraps Yjs behind the exact\n * same `CrdtText` / `TextCrdtAdapter` contract, so swapping `rgaText` for `yjsText`\n * needs no other change at the call site.\n *\n * The serialized state is a **base64 string** of a Yjs update, so it stays\n * JSON-safe for transport over the sync engine's change feed and storage as a row\n * field. Merges are commutative/associative/idempotent (Yjs guarantees it), so a\n * merge-on-write mutation combines concurrent edits without clobbering.\n */\nimport type { CrdtText, TextCrdtAdapter } from '@absolutejs/sync/crdt';\nimport * as Y from 'yjs';\n\nconst TEXT_KEY = 'text';\n\n// Isomorphic base64 (browser + Bun both expose btoa/atob), so the adapter runs\n// unchanged on the client (live editing) and the server (merge-on-write).\nconst toBase64 = (bytes: Uint8Array): string => {\n\tlet binary = '';\n\tfor (const byte of bytes) {\n\t\tbinary += String.fromCharCode(byte);\n\t}\n\n\treturn btoa(binary);\n};\n\nconst fromBase64 = (base64: string): Uint8Array => {\n\tconst binary = atob(base64);\n\tconst bytes = new Uint8Array(binary.length);\n\tfor (let index = 0; index < binary.length; index += 1) {\n\t\tbytes[index] = binary.charCodeAt(index);\n\t}\n\n\treturn bytes;\n};\n\nconst encode = (doc: Y.Doc): string => toBase64(Y.encodeStateAsUpdate(doc));\n\nconst apply = (doc: Y.Doc, state: string) => {\n\tif (state.length > 0) {\n\t\tY.applyUpdate(doc, fromBase64(state));\n\t}\n};\n\n// A stable, deterministic Yjs clientID per replica id (Yjs needs distinct\n// clients to keep distinct identities; deriving it from `replica` also makes\n// merges reproducible instead of depending on a random per-instance id).\nconst clientIdFor = (replica: string): number => {\n\tlet hash = 0;\n\tfor (let index = 0; index < replica.length; index += 1) {\n\t\thash = (Math.imul(hash, 31) + replica.charCodeAt(index)) | 0;\n\t}\n\n\treturn hash >>> 0;\n};\n\nconst docFrom = (replica: string, initial?: string): Y.Doc => {\n\tconst doc = new Y.Doc();\n\tdoc.clientID = clientIdFor(replica);\n\tif (initial !== undefined) {\n\t\tapply(doc, initial);\n\t}\n\n\treturn doc;\n};\n\n/** Reconcile `text` to `next` by editing only the changed middle (keep the\n * common prefix/suffix), so two replicas editing different spots merge. */\nconst reconcile = (text: Y.Text, next: string) => {\n\tconst current = text.toString();\n\tif (current === next) {\n\t\treturn;\n\t}\n\tlet prefix = 0;\n\tconst maxPrefix = Math.min(current.length, next.length);\n\twhile (prefix < maxPrefix && current[prefix] === next[prefix]) {\n\t\tprefix += 1;\n\t}\n\tlet suffix = 0;\n\twhile (\n\t\tsuffix < maxPrefix - prefix &&\n\t\tcurrent[current.length - 1 - suffix] === next[next.length - 1 - suffix]\n\t) {\n\t\tsuffix += 1;\n\t}\n\tconst removed = current.length - prefix - suffix;\n\tconst inserted = next.slice(prefix, next.length - suffix);\n\tif (removed > 0) {\n\t\ttext.delete(prefix, removed);\n\t}\n\tif (inserted.length > 0) {\n\t\ttext.insert(prefix, inserted);\n\t}\n};\n\n/** Create a live Yjs-backed collaborative-text doc for `replica`. */\nexport const createYjsText = (\n\treplica: string,\n\tinitial?: string\n): CrdtText<string> => {\n\tconst doc = docFrom(replica, initial);\n\tconst text = doc.getText(TEXT_KEY);\n\n\treturn {\n\t\tmerge: (state) => apply(doc, state),\n\t\tsetText: (next) => doc.transact(() => reconcile(text, next)),\n\t\tstate: () => encode(doc),\n\t\ttext: () => text.toString()\n\t};\n};\n\n/**\n * The Yjs collaborative-text backend as a {@link TextCrdtAdapter}. Drop-in for\n * the first-party `rgaText`: `create` mints a live doc, `merge` combines two\n * persisted states server-side, `empty`/`textOf` are conveniences.\n */\nexport const yjsText: TextCrdtAdapter<string> = {\n\tcreate: createYjsText,\n\tempty: () => encode(new Y.Doc()),\n\tmerge: (a, b) => {\n\t\tconst doc = new Y.Doc();\n\t\tapply(doc, a);\n\t\tapply(doc, b);\n\n\t\treturn encode(doc);\n\t},\n\ttextOf: (state) => {\n\t\tconst doc = new Y.Doc();\n\t\tapply(doc, state);\n\n\t\treturn doc.getText(TEXT_KEY).toString();\n\t}\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "B68ED6342B46BD1064756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@absolutejs/sync-yjs",
+	"version": "0.0.1",
+	"description": "Yjs-backed collaborative-text CRDT adapter for @absolutejs/sync",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/absolutejs/sync-adapters.git",
+		"directory": "yjs"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"license": "CC BY-NC 4.0",
+	"author": "Alex Kahn",
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"absolutejs",
+		"sync",
+		"crdt",
+		"yjs",
+		"collaborative",
+		"multiplayer"
+	],
+	"scripts": {
+		"build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=bun --external @absolutejs/sync --external yjs && tsc --project tsconfig.build.json",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"format": "prettier --write \"./**/*.{ts,json,md}\"",
+		"release": "bun run format && bun run build && bun publish"
+	},
+	"dependencies": {
+		"yjs": "^13.6.30"
+	},
+	"peerDependencies": {
+		"@absolutejs/sync": ">= 0.10.0"
+	},
+	"devDependencies": {
+		"@absolutejs/sync": "^0.10.0",
+		"@types/bun": "1.3.14",
+		"prettier": "3.5.3",
+		"typescript": "5.8.3"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	]
+}