svelte-adapter-uws-extensions 0.1.2

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "svelte-adapter-uws-extensions",
+  "version": "0.1.2",
+  "description": "Redis and Postgres extensions for svelte-adapter-uws - distributed pub/sub, replay buffers, presence tracking, rate limiting, groups, and DB change notifications",
+  "author": "Kevin Radziszewski",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lanteanio/svelte-adapter-uws-extensions.git"
+  },
+  "homepage": "https://github.com/lanteanio/svelte-adapter-uws-extensions#readme",
+  "bugs": {
+    "url": "https://github.com/lanteanio/svelte-adapter-uws-extensions/issues"
+  },
+  "type": "module",
+  "exports": {
+    "./redis": {
+      "types": "./redis/index.d.ts",
+      "default": "./redis/index.js"
+    },
+    "./redis/pubsub": {
+      "types": "./redis/pubsub.d.ts",
+      "default": "./redis/pubsub.js"
+    },
+    "./redis/replay": {
+      "types": "./redis/replay.d.ts",
+      "default": "./redis/replay.js"
+    },
+    "./redis/presence": {
+      "types": "./redis/presence.d.ts",
+      "default": "./redis/presence.js"
+    },
+    "./postgres": {
+      "types": "./postgres/index.d.ts",
+      "default": "./postgres/index.js"
+    },
+    "./postgres/replay": {
+      "types": "./postgres/replay.d.ts",
+      "default": "./postgres/replay.js"
+    },
+    "./postgres/notify": {
+      "types": "./postgres/notify.d.ts",
+      "default": "./postgres/notify.js"
+    },
+    "./redis/ratelimit": {
+      "types": "./redis/ratelimit.d.ts",
+      "default": "./redis/ratelimit.js"
+    },
+    "./redis/groups": {
+      "types": "./redis/groups.d.ts",
+      "default": "./redis/groups.js"
+    },
+    "./redis/cursor": {
+      "types": "./redis/cursor.d.ts",
+      "default": "./redis/cursor.js"
+    }
+  },
+  "files": [
+    "redis",
+    "postgres",
+    "shared",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "svelte-adapter-uws": ">=0.2.0"
+  },
+  "dependencies": {
+    "ioredis": "^5.0.0"
+  },
+  "optionalDependencies": {
+    "pg": "^8.0.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "svelte",
+    "sveltekit",
+    "uwebsockets",
+    "redis",
+    "postgres",
+    "pubsub",
+    "websocket",
+    "presence",
+    "replay",
+    "ratelimit",
+    "groups",
+    "cursor",
+    "notify"
+  ]
+}

package/postgres/index.d.ts

@@ -0,0 +1,26 @@
+import type { Pool, PoolConfig, QueryResult, Client } from 'pg';
+
+export interface PgClientOptions {
+	/** Postgres connection string. Required. */
+	connectionString: string;
+	/** Listen for `sveltekit:shutdown` and disconnect. @default true */
+	autoShutdown?: boolean;
+	/** Extra pg Pool options. */
+	options?: PoolConfig;
+}
+
+export interface PgClient {
+	/** The underlying pg Pool. */
+	readonly pool: Pool;
+	/** Run a query. */
+	query(text: string, values?: any[]): Promise<QueryResult>;
+	/** Create a standalone pg.Client with the same connection config (not from the pool). */
+	createClient(): Client;
+	/** Gracefully close the pool. */
+	end(): Promise<void>;
+}
+
+/**
+ * Create a Postgres client with lifecycle management.
+ */
+export function createPgClient(options: PgClientOptions): PgClient;

package/postgres/index.js

@@ -0,0 +1,88 @@
+/**
+ * Postgres client factory for svelte-adapter-uws-extensions.
+ *
+ * Wraps pg Pool with lifecycle management and graceful shutdown
+ * via the SvelteKit `sveltekit:shutdown` event.
+ *
+ * @module svelte-adapter-uws-extensions/postgres
+ */
+
+import pg from 'pg';
+import { ConnectionError } from '../shared/errors.js';
+
+const { Pool, Client } = pg;
+
+/**
+ * @typedef {Object} PgClientOptions
+ * @property {string} connectionString - Postgres connection string
+ * @property {boolean} [autoShutdown=true] - Listen for `sveltekit:shutdown` and disconnect
+ * @property {import('pg').PoolConfig} [options] - Extra pg Pool options
+ */
+
+/**
+ * @typedef {Object} PgClient
+ * @property {import('pg').Pool} pool - The underlying pg Pool
+ * @property {(text: string, values?: any[]) => Promise<import('pg').QueryResult>} query - Run a query
+ * @property {() => Promise<void>} end - Gracefully close the pool
+ */
+
+/**
+ * Create a Postgres client.
+ *
+ * @param {PgClientOptions} opts
+ * @returns {PgClient}
+ */
+export function createPgClient(opts) {
+	if (!opts || !opts.connectionString) {
+		throw new ConnectionError('postgres', 'connectionString is required');
+	}
+
+	const autoShutdown = opts.autoShutdown !== false;
+
+	let pool;
+	try {
+		pool = new Pool({
+			connectionString: opts.connectionString,
+			...(opts.options || {})
+		});
+	} catch (err) {
+		throw new ConnectionError('postgres', 'failed to create pool', err);
+	}
+
+	pool.on('error', (err) => {
+		// Idle client errors should not crash the process.
+		// pg Pool handles reconnection automatically.
+		console.error('postgres: idle client error', err.message);
+	});
+
+	let ended = false;
+
+	async function end() {
+		if (ended) return;
+		ended = true;
+		await pool.end();
+	}
+
+	if (autoShutdown && typeof process !== 'undefined') {
+		process.once('sveltekit:shutdown', end);
+	}
+
+	const connectionConfig = {
+		connectionString: opts.connectionString,
+		...(opts.options || {})
+	};
+
+	return {
+		pool,
+
+		query(text, values) {
+			return pool.query(text, values);
+		},
+
+		createClient() {
+			return new Client(connectionConfig);
+		},
+
+		end
+	};
+}

package/postgres/notify.d.ts

@@ -0,0 +1,33 @@
+import type { Platform } from 'svelte-adapter-uws';
+import type { PgClient } from './index.js';
+
+export interface NotifyBridgeOptions {
+	/** Postgres LISTEN channel name. Required. */
+	channel: string;
+
+	/**
+	 * Parse the notification payload into a publish call.
+	 * Return null to skip the notification.
+	 * Defaults to JSON.parse expecting `{ topic, event, data }`.
+	 */
+	parse?: (payload: string, channel: string) => { topic: string; event: string; data?: unknown } | null;
+
+	/** Reconnect on connection loss. @default true */
+	autoReconnect?: boolean;
+
+	/** ms between reconnect attempts. @default 3000 */
+	reconnectInterval?: number;
+}
+
+export interface NotifyBridge {
+	/** Start listening. Forwards notifications to platform.publish(). Idempotent. */
+	activate(platform: Platform): Promise<void>;
+
+	/** Stop listening and release the connection. */
+	deactivate(): Promise<void>;
+}
+
+/**
+ * Create a Postgres LISTEN/NOTIFY bridge.
+ */
+export function createNotifyBridge(client: PgClient, options: NotifyBridgeOptions): NotifyBridge;

package/postgres/notify.js

@@ -0,0 +1,214 @@
+/**
+ * Postgres LISTEN/NOTIFY bridge for svelte-adapter-uws.
+ *
+ * Listens on a Postgres channel for notifications and forwards them to
+ * platform.publish(). The user is responsible for setting up the trigger
+ * that calls pg_notify() -- this module only handles the listening side.
+ *
+ * Uses a dedicated connection (not from the pool) since LISTEN requires
+ * a persistent connection that cannot be shared.
+ *
+ * @module svelte-adapter-uws-extensions/postgres/notify
+ */
+
+/**
+ * @typedef {Object} NotifyBridgeOptions
+ * @property {string} channel - Postgres LISTEN channel name (required)
+ * @property {(payload: string, channel: string) => { topic: string, event: string, data?: unknown } | null} [parse] -
+ *   Parse the notification payload into a publish call. Return null to skip.
+ *   Defaults to JSON.parse expecting { topic, event, data }.
+ * @property {boolean} [autoReconnect=true] - Reconnect on connection loss
+ * @property {number} [reconnectInterval=3000] - ms between reconnect attempts
+ */
+
+/**
+ * @typedef {Object} NotifyBridge
+ * @property {(platform: import('svelte-adapter-uws').Platform) => Promise<void>} activate -
+ *   Start listening. Forwards notifications to platform.publish().
+ * @property {() => Promise<void>} deactivate -
+ *   Stop listening and release the connection.
+ */
+
+/**
+ * Create a Postgres LISTEN/NOTIFY bridge.
+ *
+ * @param {import('./index.js').PgClient} client
+ * @param {NotifyBridgeOptions} options
+ * @returns {NotifyBridge}
+ *
+ * @example
+ * ```js
+ * import { pg } from './pg.js';
+ * import { createNotifyBridge } from 'svelte-adapter-uws-extensions/postgres/notify';
+ *
+ * const bridge = createNotifyBridge(pg, {
+ *   channel: 'table_changes',
+ *   parse: (payload) => {
+ *     const row = JSON.parse(payload);
+ *     return { topic: row.table, event: row.op, data: row.data };
+ *   }
+ * });
+ *
+ * // In your open hook (once):
+ * bridge.activate(platform);
+ * ```
+ *
+ * Then create a trigger on your table:
+ * ```sql
+ * CREATE OR REPLACE FUNCTION notify_table_change() RETURNS trigger AS $$
+ * BEGIN
+ *   PERFORM pg_notify('table_changes', json_build_object(
+ *     'table', TG_TABLE_NAME,
+ *     'op', lower(TG_OP),
+ *     'data', CASE TG_OP
+ *       WHEN 'DELETE' THEN row_to_json(OLD)
+ *       ELSE row_to_json(NEW)
+ *     END
+ *   )::text);
+ *   RETURN COALESCE(NEW, OLD);
+ * END;
+ * $$ LANGUAGE plpgsql;
+ *
+ * CREATE TRIGGER messages_notify
+ *   AFTER INSERT OR UPDATE OR DELETE ON messages
+ *   FOR EACH ROW EXECUTE FUNCTION notify_table_change();
+ * ```
+ */
+export function createNotifyBridge(client, options) {
+	if (!options || typeof options.channel !== 'string' || options.channel.length === 0) {
+		throw new Error('notify bridge: channel must be a non-empty string');
+	}
+
+	const channel = options.channel;
+	const autoReconnect = options.autoReconnect !== false;
+	const reconnectInterval = options.reconnectInterval || 3000;
+	const parse = options.parse || defaultParse;
+
+	/** @type {import('pg').Client | null} */
+	let conn = null;
+	/** @type {import('svelte-adapter-uws').Platform | null} */
+	let activePlatform = null;
+	let active = false;
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let reconnectTimer = null;
+
+	function defaultParse(payload) {
+		try {
+			const obj = JSON.parse(payload);
+			if (!obj.topic || !obj.event) return null;
+			return { topic: obj.topic, event: obj.event, data: obj.data };
+		} catch {
+			return null;
+		}
+	}
+
+	function onNotification(msg) {
+		if (msg.channel !== channel) return;
+		try {
+			const result = parse(msg.payload, msg.channel);
+			if (result && activePlatform) {
+				// relay: false -- in clustered mode each worker has its own
+				// LISTEN connection, so relaying would duplicate delivery.
+				activePlatform.publish(result.topic, result.event, result.data, { relay: false });
+			}
+		} catch {
+			// Parse errors are non-fatal -- skip the notification
+		}
+	}
+
+	async function connect() {
+		try {
+			// Use a standalone Client instead of pool.connect() to avoid
+			// permanently holding a pool connection. LISTEN needs a persistent
+			// connection that stays open for the lifetime of the bridge --
+			// borrowing from the pool would reduce available connections for queries.
+			conn = client.createClient();
+			conn.on('notification', onNotification);
+			conn.on('error', handleError);
+			await conn.connect();
+
+			// pg requires channel name to be a valid identifier or quoted
+			// Use double-quoting to handle any channel name safely
+			await conn.query(`LISTEN "${channel.replace(/"/g, '""')}"`);
+		} catch (err) {
+			if (conn) {
+				try { await conn.end(); } catch { /* ignore */ }
+			}
+			conn = null;
+			if (active && autoReconnect) {
+				scheduleReconnect();
+			}
+			throw err;
+		}
+	}
+
+	function handleError() {
+		cleanup();
+		if (active && autoReconnect) {
+			scheduleReconnect();
+		}
+	}
+
+	function scheduleReconnect() {
+		if (reconnectTimer) return;
+		reconnectTimer = setTimeout(async () => {
+			reconnectTimer = null;
+			if (!active) return;
+			try {
+				await connect();
+			} catch {
+				// connect() already schedules another retry on failure
+			}
+		}, reconnectInterval);
+		if (reconnectTimer.unref) reconnectTimer.unref();
+	}
+
+	function cleanup() {
+		if (conn) {
+			conn.removeListener('notification', onNotification);
+			conn.removeListener('error', handleError);
+			conn.end().catch(() => { /* already closed */ });
+			conn = null;
+		}
+	}
+
+	return {
+		async activate(platform) {
+			// Always update the platform reference so notifications
+			// are forwarded through the latest platform, even if a
+			// previous activate() already started the listener.
+			activePlatform = platform;
+			if (active) return;
+			active = true;
+			try {
+				await connect();
+			} catch (err) {
+				if (!autoReconnect) {
+					// Without autoReconnect, reset so activate() can be retried
+					active = false;
+					activePlatform = null;
+				}
+				// With autoReconnect, connect() already scheduled a retry
+				throw err;
+			}
+		},
+
+		async deactivate() {
+			if (!active) return;
+			active = false;
+			activePlatform = null;
+			if (reconnectTimer) {
+				clearTimeout(reconnectTimer);
+				reconnectTimer = null;
+			}
+			if (conn) {
+				try {
+					await conn.query(`UNLISTEN "${channel.replace(/"/g, '""')}"`);
+				} catch {
+					// Connection may already be dead
+				}
+				cleanup();
+			}
+		}
+	};
+}

package/postgres/replay.d.ts

@@ -0,0 +1,56 @@
+import type { Platform } from 'svelte-adapter-uws';
+import type { PgClient } from './index.js';
+
+export interface PgReplayOptions {
+	/** Table name. @default 'ws_replay' */
+	table?: string;
+	/** Max messages per topic. @default 1000 */
+	size?: number;
+	/** TTL in seconds (0 = no expiry). @default 0 */
+	ttl?: number;
+	/** Auto-create table on first use. @default true */
+	autoMigrate?: boolean;
+	/** Cleanup interval in ms (0 to disable). @default 60000 */
+	cleanupInterval?: number;
+}
+
+export interface BufferedMessage {
+	seq: number;
+	topic: string;
+	event: string;
+	data: unknown;
+}
+
+export interface PgReplayBuffer {
+	/**
+	 * Publish a message through the buffer. Stores it in Postgres with a
+	 * sequence number, then calls platform.publish() as normal.
+	 */
+	publish(platform: Platform, topic: string, event: string, data?: unknown): Promise<boolean>;
+
+	/** Get the current sequence number for a topic. Returns 0 if unknown. */
+	seq(topic: string): Promise<number>;
+
+	/** Get all buffered messages after a given sequence number. */
+	since(topic: string, since: number): Promise<BufferedMessage[]>;
+
+	/**
+	 * Send buffered messages to a single connection. Sends each missed
+	 * message on `__replay:{topic}`, then an end marker.
+	 */
+	replay(ws: any, topic: string, sinceSeq: number, platform: Platform): Promise<void>;
+
+	/** Clear all replay data. */
+	clear(): Promise<void>;
+
+	/** Clear replay data for a single topic. */
+	clearTopic(topic: string): Promise<void>;
+
+	/** Stop the cleanup timer. */
+	destroy(): void;
+}
+
+/**
+ * Create a Postgres-backed replay buffer.
+ */
+export function createReplay(client: PgClient, options?: PgReplayOptions): PgReplayBuffer;