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

packages/extension-logger/README.md

@@ -0,0 +1,56 @@
+# @hocuspocus/extension-logger
+[![Version](https://img.shields.io/npm/v/@hocuspocus/extension-logger.svg?label=version)](https://www.npmjs.com/package/@hocuspocus/extension-logger)
+[![Downloads](https://img.shields.io/npm/dm/@hocuspocus/extension-logger.svg)](https://npmcharts.com/compare/tiptap?minimal=true)
+[![License](https://img.shields.io/npm/l/@hocuspocus/extension-logger.svg)](https://www.npmjs.com/package/@hocuspocus/extension-logger)
+[![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ueberdosis)
+
+Logs connection, document, and lifecycle events for a [Hocuspocus](https://github.com/ueberdosis/hocuspocus) server to the console. Useful during development and debugging to see when clients connect, documents load and store, and changes come in.
+
+## Installation
+
+```bash
+npm install @hocuspocus/extension-logger
+```
+
+## Usage
+
+```js
+import { Server } from "@hocuspocus/server"
+import { Logger } from "@hocuspocus/extension-logger"
+
+const server = new Server({
+  extensions: [new Logger()],
+})
+
+server.listen()
+```
+
+### Silence specific hooks
+
+Pass booleans per hook to quiet down the ones you don't care about:
+
+```js
+new Logger({
+  onConnect: false,
+  onDisconnect: false,
+  onChange: false,
+})
+```
+
+### Use a custom log function
+
+Route output to your own logger (pino, winston, structured JSON, etc.):
+
+```js
+new Logger({
+  log: (...args) => myLogger.info({ msg: args.join(" ") }),
+})
+```
+
+## Documentation
+
+Full options reference: [tiptap.dev/docs/hocuspocus/server/extensions/logger](https://tiptap.dev/docs/hocuspocus/server/extensions/logger).
+
+## License
+
+MIT — see [LICENSE.md](https://github.com/ueberdosis/hocuspocus/blob/main/LICENSE.md).

packages/extension-logger/package.json

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

packages/extension-logger/src/Logger.ts

@@ -0,0 +1,164 @@
+import type {
+	Extension,
+	onChangePayload,
+	onConfigurePayload,
+	onConnectPayload,
+	onDestroyPayload,
+	onDisconnectPayload,
+	onLoadDocumentPayload,
+	onRequestPayload,
+	onStoreDocumentPayload,
+	onUpgradePayload,
+} from "@hocuspocus/server";
+
+export interface LoggerConfiguration {
+	/**
+	 * Prepend all logging message with a string.
+	 *
+	 * @deprecated
+	 */
+	prefix: null | string;
+	/**
+	 * Whether to log something for the `onLoadDocument` hook.
+	 */
+	onLoadDocument: boolean;
+	/**
+	 * Whether to log something for the `onChange` hook.
+	 */
+	onChange: boolean;
+	/**
+	 * Whether to log something for the `onStoreDocument` hook.
+	 */
+	onStoreDocument: boolean;
+	/**
+	 * Whether to log something for the `onConnect` hook.
+	 */
+	onConnect: boolean;
+	/**
+	 * Whether to log something for the `onDisconnect` hook.
+	 */
+	onDisconnect: boolean;
+	/**
+	 * Whether to log something for the `onUpgrade` hook.
+	 */
+	onUpgrade: boolean;
+	/**
+	 * Whether to log something for the `onRequest` hook.
+	 */
+	onRequest: boolean;
+	/**
+	 * Whether to log something for the `onDestroy` hook.
+	 */
+	onDestroy: boolean;
+	/**
+	 * Whether to log something for the `onConfigure` hook.
+	 */
+	onConfigure: boolean;
+	/**
+	 * A log function, if none is provided output will go to console
+	 */
+	log: (...args: any[]) => void;
+}
+
+export class Logger implements Extension {
+	name: string | null = null;
+
+	configuration: LoggerConfiguration = {
+		prefix: null,
+		onLoadDocument: true,
+		onChange: true,
+		onStoreDocument: true,
+		onConnect: true,
+		onDisconnect: true,
+		onUpgrade: true,
+		onRequest: true,
+		onDestroy: true,
+		onConfigure: true,
+		log: console.log, // eslint-disable-line
+	};
+
+	/**
+	 * Constructor
+	 */
+	constructor(configuration?: Partial<LoggerConfiguration>) {
+		this.configuration = {
+			...this.configuration,
+			...configuration,
+		};
+	}
+
+	async onConfigure(data: onConfigurePayload) {
+		this.name = data.instance.configuration.name;
+
+		if (!this.configuration.onConfigure) {
+			return;
+		}
+
+		if (this.configuration.prefix) {
+			console.warn(
+				"[hocuspocus warn] The Logger 'prefix' is deprecated. Pass a 'name' to the Hocuspocus configuration instead.",
+			);
+		}
+	}
+
+	async onLoadDocument(data: onLoadDocumentPayload) {
+		if (this.configuration.onLoadDocument) {
+			this.log(`Loaded document "${data.documentName}".`);
+		}
+	}
+
+	async onChange(data: onChangePayload) {
+		if (this.configuration.onChange) {
+			this.log(`Document "${data.documentName}" changed.`);
+		}
+	}
+
+	async onStoreDocument(data: onStoreDocumentPayload) {
+		if (this.configuration.onStoreDocument) {
+			this.log(`Store "${data.documentName}".`);
+		}
+	}
+
+	async onConnect(data: onConnectPayload) {
+		if (this.configuration.onConnect) {
+			this.log(`New connection to "${data.documentName}".`);
+		}
+	}
+
+	async onDisconnect(data: onDisconnectPayload) {
+		if (this.configuration.onDisconnect) {
+			this.log(`Connection to "${data.documentName}" closed.`);
+		}
+	}
+
+	async onUpgrade(data: onUpgradePayload) {
+		if (this.configuration.onUpgrade) {
+			this.log("Upgrading connection …");
+		}
+	}
+
+	async onRequest(data: onRequestPayload) {
+		if (this.configuration.onRequest) {
+			this.log(`Incoming HTTP Request to ${data.request.url}`);
+		}
+	}
+
+	async onDestroy(data: onDestroyPayload) {
+		if (this.configuration.onDestroy) {
+			this.log("Shut down.");
+		}
+	}
+
+	private log(message: string) {
+		const date = new Date().toISOString();
+		let meta = `${date}`;
+
+		if (this.name) {
+			meta = `${this.name} ${meta}`;
+		}
+
+		message = `[${meta}] ${message}`;
+
+		this.configuration.log(message);
+	}
+}

packages/extension-logger/src/index.ts

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