svelte-realtime 0.4.4 → 0.4.6

package/README.md

@@ -1,6 +1,20 @@
-# svelte-realtime
+<p align="center">
+  <a href="https://svelte-realtime.dev">
+    <img src="https://svelte-realtime.dev/svelte_orange.png" alt="svelte-realtime" width="240" />
+  </a>
+</p>
 
-Realtime RPC and reactive subscriptions for SvelteKit, built on [svelte-adapter-uws](https://github.com/lanteanio/svelte-adapter-uws).
+<h1 align="center">svelte-realtime</h1>
+
+<p align="center">
+  Realtime RPC and reactive subscriptions for SvelteKit, built on <a href="https://github.com/lanteanio/svelte-adapter-uws">svelte-adapter-uws</a>.
+</p>
+
+<p align="center">
+  <a href="https://svelte-realtime.dev">Documentation</a> · <a href="https://svelte-realtime.dev/tutorial">Tutorial</a> · <a href="https://svelte-realtime-demo.lantean.io">Live Demo</a>
+</p>
+
+---
 
 Write server functions. Import them in components. Call them over WebSocket. No boilerplate, no manual pub/sub wiring, no protocol design.
 

package/client.js

@@ -103,7 +103,7 @@ function ensureListener() {
 				pending.delete(result.id);
 				if (entry.timer) clearTimeout(entry.timer);
 				if (result.ok) {
-					entry.resolve(result.data);
+					entry.resolve(entry.stream ? result : result.data);
 				} else {
 					entry.reject(new RpcError(result.code || 'UNKNOWN', result.error || 'Unknown error'));
 				}
@@ -1503,7 +1503,7 @@ function _checkArgs(path, args) {
 		const t = typeof arg;
 		if (t === 'function' || t === 'symbol' || t === 'bigint' || t === 'undefined') {
 			console.warn(
-				`[svelte-realtime] RPC '${path}' called with non-JSON-serializable argument at index ${i} (${t}) -- this will be lost during transmission`
+				`[svelte-realtime] RPC '${path}' called with non-JSON-serializable argument at index ${i} (${t}) -- this will be lost during transmission\n  See: https://svti.me/rpc`
 			);
 		}
 	}
@@ -1644,10 +1644,10 @@ export function combine(...args) {
 	const sources = args;
 
 	if (typeof fn !== 'function') {
-		throw new Error('combine() requires a combining function as the last argument');
+		throw new Error('combine() requires a combining function as the last argument\n  See: https://svti.me/client');
 	}
 	if (sources.length < 2) {
-		throw new Error('combine() requires at least 2 source stores');
+		throw new Error('combine() requires at least 2 source stores\n  See: https://svti.me/client');
 	}
 
 	const values = new Array(sources.length);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-realtime",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Realtime RPC and reactive subscriptions for SvelteKit, built on svelte-adapter-uws",
   "author": "Kevin Radziszewski",
   "license": "MIT",

package/server.js

@@ -354,11 +354,11 @@ export function live(fn) {
  */
 live.stream = function stream(topic, initFn, options) {
 	if (typeof topic === 'string' && topic.startsWith('__')) {
-		throw new Error(`[svelte-realtime] live.stream topic '${topic}' uses reserved prefix '__'`);
+		throw new Error(`[svelte-realtime] live.stream topic '${topic}' uses reserved prefix '__'\n  See: https://svti.me/streams`);
 	}
 	if (typeof topic === 'function') {
 		if (topic.constructor?.name === 'AsyncFunction') {
-			throw new Error(`[svelte-realtime] live.stream topic function must not be async -- topic resolution is synchronous`);
+			throw new Error(`[svelte-realtime] live.stream topic function must not be async -- topic resolution is synchronous\n  See: https://svti.me/streams`);
 		}
 		_tagTopicFn(topic);
 	}
@@ -391,11 +391,11 @@ live.stream = function stream(topic, initFn, options) {
  */
 live.channel = function channel(topic, options) {
 	if (typeof topic === 'string' && topic.startsWith('__')) {
-		throw new Error(`[svelte-realtime] live.channel topic '${topic}' uses reserved prefix '__'`);
+		throw new Error(`[svelte-realtime] live.channel topic '${topic}' uses reserved prefix '__'\n  See: https://svti.me/streams`);
 	}
 	if (typeof topic === 'function') {
 		if (topic.constructor?.name === 'AsyncFunction') {
-			throw new Error(`[svelte-realtime] live.channel topic function must not be async -- topic resolution is synchronous`);
+			throw new Error(`[svelte-realtime] live.channel topic function must not be async -- topic resolution is synchronous\n  See: https://svti.me/streams`);
 		}
 		_tagTopicFn(topic);
 	}
@@ -1082,13 +1082,13 @@ live.room = function room(config) {
 	let _roomArgCount = Math.max(0, topicFn.length - 1);
 	if (config.topicArgs !== undefined) {
 		if (!Number.isInteger(config.topicArgs) || config.topicArgs < 0) {
-			throw new Error(`[svelte-realtime] live.room() topicArgs must be a non-negative integer, got ${config.topicArgs}`);
+			throw new Error(`[svelte-realtime] live.room() topicArgs must be a non-negative integer, got ${config.topicArgs}\n  See: https://svti.me/rooms`);
 		}
 		_roomArgCount = config.topicArgs;
 	} else if (actions) {
 		throw new Error(
 			`[svelte-realtime] live.room() with actions requires 'topicArgs'. ` +
-			`Set topicArgs to the number of room-identifying args (excluding ctx).`
+			`Set topicArgs to the number of room-identifying args (excluding ctx).\n  See: https://svti.me/rooms`
 		);
 	}
 
@@ -1216,7 +1216,7 @@ live.room = function room(config) {
 		for (const [name, fn] of Object.entries(actions)) {
 			if (!_validSegmentRe.test(name)) {
 				if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
-					console.warn(`[svelte-realtime] Room action '${name}' contains invalid characters (only a-z, A-Z, 0-9, _ allowed) -- skipped`);
+					console.warn(`[svelte-realtime] Room action '${name}' contains invalid characters (only a-z, A-Z, 0-9, _ allowed) -- skipped\n  See: https://svti.me/rooms`);
 				}
 				continue;
 			}
@@ -1713,7 +1713,7 @@ export async function _tickCron() {
 			try {
 				if (!_cronPlatform) {
 					if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
-						console.warn(`[svelte-realtime] Cron '${path}' fired but no platform captured. Call setCronPlatform(platform) in your open hook.`);
+						console.warn(`[svelte-realtime] Cron '${path}' fired but no platform captured. Call setCronPlatform(platform) in your open hook.\n  See: https://svti.me/cron`);
 					}
 					return;
 				}
@@ -1748,7 +1748,7 @@ export async function _tickCron() {
 function _parseCron(expr) {
 	const parts = expr.trim().split(/\s+/);
 	if (parts.length !== 5) {
-		throw new Error(`[svelte-realtime] Invalid cron expression '${expr}' -- expected 5 fields (minute hour day month weekday)`);
+		throw new Error(`[svelte-realtime] Invalid cron expression '${expr}' -- expected 5 fields (minute hour day month weekday)\n  See: https://svti.me/cron`);
 	}
 	return parts.map((field, idx) => _parseCronField(field, idx));
 }
@@ -1772,7 +1772,7 @@ function _parseCronField(field, idx) {
 	if (field.startsWith('*/')) {
 		const step = parseInt(field.slice(2), 10);
 		if (!Number.isFinite(step) || step < 1) {
-			throw new Error(`[svelte-realtime] Invalid cron step '${field}' -- step must be a positive integer`);
+			throw new Error(`[svelte-realtime] Invalid cron step '${field}' -- step must be a positive integer\n  See: https://svti.me/cron`);
 		}
 		return { step };
 	}
@@ -1782,7 +1782,7 @@ function _parseCronField(field, idx) {
 		const a = parseInt(parts[0], 10);
 		const b = parseInt(parts[1], 10);
 		if (!Number.isFinite(a) || !Number.isFinite(b) || a < min || b > max || a > b) {
-			throw new Error(`[svelte-realtime] Invalid cron range '${field}' -- values must be ${min}-${max}`);
+			throw new Error(`[svelte-realtime] Invalid cron range '${field}' -- values must be ${min}-${max}\n  See: https://svti.me/cron`);
 		}
 		const vals = new Set();
 		for (let i = a; i <= b; i++) vals.add(i);
@@ -1793,7 +1793,7 @@ function _parseCronField(field, idx) {
 		const nums = field.split(',').map(s => {
 			const n = parseInt(s, 10);
 			if (!Number.isFinite(n) || n < min || n > max) {
-				throw new Error(`[svelte-realtime] Invalid cron value '${s}' in '${field}' -- must be ${min}-${max}`);
+				throw new Error(`[svelte-realtime] Invalid cron value '${s}' in '${field}' -- must be ${min}-${max}\n  See: https://svti.me/cron`);
 			}
 			return n;
 		});
@@ -1802,7 +1802,7 @@ function _parseCronField(field, idx) {
 
 	const n = parseInt(field, 10);
 	if (!Number.isFinite(n) || n < min || n > max) {
-		throw new Error(`[svelte-realtime] Invalid cron value '${field}' -- must be ${min}-${max}`);
+		throw new Error(`[svelte-realtime] Invalid cron value '${field}' -- must be ${min}-${max}\n  See: https://svti.me/cron`);
 	}
 	return new Set([n]);
 }
@@ -1928,7 +1928,7 @@ export function handleRpc(ws, data, platform, options) {
 				}
 			} catch (err) {
 				if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
-					console.warn('[svelte-realtime] Failed to parse binary RPC header:', err);
+					console.warn('[svelte-realtime] Failed to parse binary RPC header:', err, '\n  See: https://svti.me/binary');
 				}
 			}
 		}
@@ -2050,7 +2050,7 @@ async function _executeSingleRpc(ws, msg, platform, options) {
 	const fn = await _resolveRegistryEntry(path);
 	if (!fn) {
 		if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
-			console.warn(`[svelte-realtime] RPC call to '${path}' -- no such live function registered`);
+			console.warn(`[svelte-realtime] RPC call to '${path}' -- no such live function registered\n  See: https://svti.me/rpc`);
 		}
 		_recordRpcMetrics(path, 'NOT_FOUND', _metricsStart);
 		return { id, ok: false, code: 'NOT_FOUND', error: 'Not found' };
@@ -2188,7 +2188,7 @@ async function _executeSingleRpc(ws, msg, platform, options) {
 			console.warn(
 				`[svelte-realtime] '${path}' threw a non-LiveError:`,
 				err,
-				'\nUse throw new LiveError(code, message) for client-visible errors. Raw errors are hidden from clients.'
+				'\nUse throw new LiveError(code, message) for client-visible errors. Raw errors are hidden from clients.\n  See: https://svti.me/errors'
 			);
 			console.error(`[svelte-realtime] Error in '${path}':`, err);
 		}
@@ -2415,7 +2415,7 @@ function _migrateItem(item, fromVersion, toVersion, migrateFns) {
 		if (fn) {
 			result = fn(result);
 		} else if (typeof process !== 'undefined' && process.env.NODE_ENV !== 'production') {
-			console.warn(`[svelte-realtime] Missing migration function for version ${v} -> ${v + 1}`);
+			console.warn(`[svelte-realtime] Missing migration function for version ${v} -> ${v + 1}\n  See: https://svti.me/schema`);
 		}
 	}
 	return result;
@@ -2428,7 +2428,7 @@ function _respond(ws, platform, correlationId, payload) {
 		if ((Array.isArray(data) && data.length > 100) || (typeof data === 'string' && data.length > 12000)) {
 			console.warn(
 				`[svelte-realtime] RPC response for '${correlationId}' contains ${data.length} items -- ` +
-				'large responses may exceed maxPayloadLength (16KB). Increase maxPayloadLength in adapter config if needed.'
+				'large responses may exceed maxPayloadLength (16KB). Increase maxPayloadLength in adapter config if needed.\n  See: https://svti.me/adapter-config'
 			);
 		}
 	}

package/vite.js

@@ -37,7 +37,7 @@ function _isValidExportName(name, filePath) {
 	if (!_warnedExports.has(warnKey)) {
 		_warnedExports.add(warnKey);
 		console.warn(
-			`[svelte-realtime] ${filePath}: export '${name}' contains characters not allowed in RPC paths (only a-z, A-Z, 0-9, _ are valid) -- skipped`
+			`[svelte-realtime] ${filePath}: export '${name}' contains characters not allowed in RPC paths (only a-z, A-Z, 0-9, _ are valid) -- skipped\n  See: https://svti.me/rpc`
 		);
 	}
 	return false;
@@ -131,7 +131,7 @@ function _readStringLiteral(s, start) {
 		if (q === '`' && ch === '$' && s[j + 1] === '{') {
 			const snippet = s.slice(start, Math.min(start + 40, s.length)).replace(/\n/g, '\\n');
 			throw new Error(
-				`[svelte-realtime] Template literal with interpolation cannot be statically analyzed: ${snippet}... -- use a plain string ('...' or "...") instead`
+				`[svelte-realtime] Template literal with interpolation cannot be statically analyzed: ${snippet}... -- use a plain string ('...' or "...") instead\n  See: https://svti.me/vite`
 			);
 		}
 		result += ch;
@@ -265,7 +265,7 @@ export default function svelteRealtime(options) {
 				_warnedExports.clear();
 			if (!existsSync(liveDir)) {
 				console.warn(
-					`[svelte-realtime] Plugin loaded but no live modules found in ${dir}/`
+					`[svelte-realtime] Plugin loaded but no live modules found in ${dir}/\n  See: https://svti.me/start`
 				);
 			} else {
 				if (typedImports) {
@@ -756,12 +756,12 @@ function _generateClientStubs(filePath, modulePath, dir) {
 		if (name.startsWith('_')) {
 			// Reserved names starting with _ (except _guard)
 			console.warn(
-				`[svelte-realtime] ${dir}/${modulePath} exports '${name}' starting with _ -- reserved for internal use`
+				`[svelte-realtime] ${dir}/${modulePath} exports '${name}' starting with _ -- reserved for internal use\n  See: https://svti.me/rpc`
 			);
 			continue;
 		}
 		console.warn(
-			`[svelte-realtime] ${dir}/${modulePath} exports '${name}' which is not wrapped in live() -- it won't be callable from the client. Did you forget live()?`
+			`[svelte-realtime] ${dir}/${modulePath} exports '${name}' which is not wrapped in live() -- it won't be callable from the client. Did you forget live()?\n  See: https://svti.me/rpc`
 		);
 	}
 
@@ -905,7 +905,7 @@ function _extractTopLevelKeys(body) {
 					if (/^[a-zA-Z0-9_]+$/.test(keyName)) {
 						keys.push(keyName);
 					} else if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
-						console.warn(`[svelte-realtime] Action name '${keyName}' contains characters not allowed in RPC paths -- skipped`);
+						console.warn(`[svelte-realtime] Action name '${keyName}' contains characters not allowed in RPC paths -- skipped\n  See: https://svti.me/rooms`);
 					}
 					i = closeIdx + 1 + afterClose[0].length;
 					// If the match ended with '(' (quoted method shorthand), track depth
@@ -929,7 +929,7 @@ function _extractTopLevelKeys(body) {
 				if (/^[a-zA-Z0-9_]+$/.test(m[1])) {
 					keys.push(m[1]);
 				} else if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
-					console.warn(`[svelte-realtime] Action name '${m[1]}' contains characters not allowed in RPC paths (only a-z, A-Z, 0-9, _ are valid) -- skipped`);
+					console.warn(`[svelte-realtime] Action name '${m[1]}' contains characters not allowed in RPC paths (only a-z, A-Z, 0-9, _ are valid) -- skipped\n  See: https://svti.me/rooms`);
 				}
 				i += m[0].length;
 				// If the match ended with '(' (method shorthand), account for the
@@ -1321,12 +1321,12 @@ function _generateRegistry(liveDir, dir) {
 				const topic = topicMatch[1];
 				if (topic.startsWith('__')) {
 					throw new Error(
-						`[svelte-realtime] ${dir}/${rel} uses reserved topic '${topic}' -- topics starting with __ are reserved for internal use`
+						`[svelte-realtime] ${dir}/${rel} uses reserved topic '${topic}' -- topics starting with __ are reserved for internal use\n  See: https://svti.me/streams`
 					);
 				}
 				if (seenTopics.has(topic)) {
 					throw new Error(
-						`[svelte-realtime] Duplicate stream topic '${topic}' in ${dir}/${rel} -- each topic must be unique across all modules`
+						`[svelte-realtime] Duplicate stream topic '${topic}' in ${dir}/${rel} -- each topic must be unique across all modules\n  See: https://svti.me/streams`
 					);
 				}
 				seenTopics.add(topic);
@@ -1482,7 +1482,8 @@ function _checkHooksFile(root, liveDir, dir) {
 			`WebSocket RPC will not work without it.\n` +
 			`  Create src/hooks.ws.js with at minimum:\n` +
 			`    export { message } from 'svelte-realtime/server';\n` +
-			`    export function upgrade() { return {}; }`
+			`    export function upgrade() { return {}; }\n` +
+			`  See: https://svti.me/hooks`
 		);
 		return;
 	}
@@ -1498,7 +1499,8 @@ function _checkHooksFile(root, liveDir, dir) {
 		console.warn(
 			`[svelte-realtime] ${name} exists but does not export a \`message\` handler -- ` +
 			`WebSocket RPC calls from ${dir}/ will go unhandled.\n` +
-			`  Add: export { message } from 'svelte-realtime/server';`
+			`  Add: export { message } from 'svelte-realtime/server';\n` +
+			`  See: https://svti.me/hooks`
 		);
 	}
 }
@@ -2267,7 +2269,7 @@ async function _hmrReloadRegistry(server, liveDir, dir, rel) {
 	try {
 		serverMod = await server.ssrLoadModule('svelte-realtime/server');
 	} catch {
-		console.error('[svelte-realtime] HMR failed: could not load svelte-realtime/server');
+		console.error('[svelte-realtime] HMR failed: could not load svelte-realtime/server\n  See: https://svti.me/vite');
 		return;
 	}