snapshot of https://github.com/ueberdosis/hocuspocus.git @ cf3cfa355b4d3bb61c6b6c80071f71783e32470e (2026-09-15)

packages/extension-database/README.md

@@ -0,0 +1,51 @@
+# @hocuspocus/extension-database
+[![Version](https://img.shields.io/npm/v/@hocuspocus/extension-database.svg?label=version)](https://www.npmjs.com/package/@hocuspocus/extension-database)
+[![Downloads](https://img.shields.io/npm/dm/@hocuspocus/extension-database.svg)](https://npmcharts.com/compare/tiptap?minimal=true)
+[![License](https://img.shields.io/npm/l/@hocuspocus/extension-database.svg)](https://www.npmjs.com/package/@hocuspocus/extension-database)
+[![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ueberdosis)
+
+A generic persistence base class for [Hocuspocus](https://github.com/ueberdosis/hocuspocus). Provide your own `fetch` and `store` functions to plug any database into the collaboration backend — Postgres, MySQL, MongoDB, a REST API, etc.
+
+## Installation
+
+```bash
+npm install @hocuspocus/extension-database
+```
+
+## Usage
+
+Plug in any storage backend by implementing two async functions:
+
+```js
+import { Server } from "@hocuspocus/server"
+import { Database } from "@hocuspocus/extension-database"
+
+const server = new Server({
+  extensions: [
+    new Database({
+      fetch: async ({ documentName }) => {
+        // return a Uint8Array of the stored Y.js update, or null for new documents
+        return await yourDb.findDocument(documentName)
+      },
+      store: async ({ documentName, state }) => {
+        // persist the binary Y.js state wherever you like
+        await yourDb.upsertDocument(documentName, state)
+      },
+    }),
+  ],
+})
+
+server.listen()
+```
+
+`state` is a `Buffer` containing the encoded Y.js update. Store it as-is and return it unchanged from `fetch`.
+
+For dedicated storage drivers, see [`@hocuspocus/extension-sqlite`](../extension-sqlite) or [`@hocuspocus/extension-s3`](../extension-s3), both of which extend this base class.
+
+## Documentation
+
+Persistence patterns and performance tips: [tiptap.dev/docs/hocuspocus/guides/persistence](https://tiptap.dev/docs/hocuspocus/guides/persistence).
+
+## License
+
+MIT — see [LICENSE.md](https://github.com/ueberdosis/hocuspocus/blob/main/LICENSE.md).

packages/extension-database/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@hocuspocus/extension-database",
+	"description": "a generic Hocuspocus persistence driver for the database",
+	"version": "4.7.0",
+	"homepage": "https://hocuspocus.dev",
+	"keywords": [
+		"hocuspocus",
+		"yjs"
+	],
+	"license": "MIT",
+	"type": "module",
+	"main": "dist/hocuspocus-database.cjs",
+	"module": "dist/hocuspocus-database.esm.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		"source": {
+			"import": "./src/index.ts"
+		},
+		"default": {
+			"import": "./dist/hocuspocus-database.esm.js",
+			"require": "./dist/hocuspocus-database.cjs",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"src",
+		"dist"
+	],
+	"dependencies": {
+		"@hocuspocus/server": "workspace:^"
+	},
+	"peerDependencies": {
+		"yjs": "^13.6.8"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"gitHead": "b3454a4ca289a84ddfb7fa5607a2d4b8d5c37e9d",
+	"repository": {
+		"url": "https://github.com/ueberdosis/hocuspocus"
+	}
+}

packages/extension-database/src/Database.ts

@@ -0,0 +1,62 @@
+import type {
+	Extension,
+	fetchPayload,
+	onChangePayload,
+	onLoadDocumentPayload,
+	onStoreDocumentPayload,
+	storePayload,
+} from "@hocuspocus/server";
+import * as Y from "yjs";
+
+export interface DatabaseConfiguration {
+	/**
+	 * Pass a Promise to retrieve updates from your database. The Promise should resolve to
+	 * an array of items with Y.js-compatible binary data.
+	 */
+	fetch: (data: fetchPayload) => Promise<Uint8Array | null>;
+	/**
+	 * Pass a function to store updates in your database.
+	 */
+	store: (data: storePayload) => Promise<void>;
+}
+
+export class Database implements Extension {
+	/**
+	 * Default configuration
+	 */
+	configuration: DatabaseConfiguration = {
+		fetch: async () => null,
+		store: async () => {},
+	};
+
+	/**
+	 * Constructor
+	 */
+	constructor(configuration: Partial<DatabaseConfiguration>) {
+		this.configuration = {
+			...this.configuration,
+			...configuration,
+		};
+	}
+
+	/**
+	 * Get stored data from the database.
+	 */
+	async onLoadDocument(data: onLoadDocumentPayload): Promise<any> {
+		const update = await this.configuration.fetch(data);
+
+		if (update) {
+			Y.applyUpdate(data.document, update);
+		}
+	}
+
+	/**
+	 * Store new updates in the database.
+	 */
+	async onStoreDocument(data: onStoreDocumentPayload) {
+		await this.configuration.store({
+			...data,
+			state: Buffer.from(Y.encodeStateAsUpdate(data.document)),
+		});
+	}
+}

packages/extension-database/src/index.ts

@@ -0,0 +1 @@
+export * from "./Database.ts";