lazypock 0.8.4 → 0.9.0

package/src/collection.ts

@@ -60,6 +60,23 @@ export interface RealtimeMessage {
 /** Subscription callback for a collection's realtime events. */
 export type RealtimeCallback = (e: RealtimeMessage) => void;
 
+/**
+ * Options for {@link CollectionService.subscribe} (PocketBase-compatible).
+ *
+ * `expand` and any extra keys are forwarded to the server channel join
+ * payload (available to `onRealtimeSubscribeRequest` hooks). `headers` is
+ * accepted for PocketBase signature compatibility but has no effect over
+ * WebSocket — it is not forwarded.
+ */
+export interface RealtimeSubscribeOptions {
+	/** Fields to expand on the subscribed records (server join payload). */
+	expand?: string;
+	/** Accepted for PocketBase parity; not sent over the WebSocket. */
+	headers?: Record<string, string>;
+	/** Any extra keys are forwarded verbatim to the server join payload. */
+	[key: string]: unknown;
+}
+
 /** Raw event passed by the low-level realtime service. */
 interface RealtimeEventLike {
 	event: string;
@@ -505,23 +522,64 @@ export class CollectionService<T = ApiRecord, TData = never> {
 
 	/**
 	 * Subscribe to realtime changes for this collection.
-	 * The event's `action` is one of `"create" | "update" | "delete"`.
+	 * The event's `action` is one of `"create" | "update" | "delete"` and the
+	 * callback always receives the **full record** (all fields, regardless of
+	 * any `select()` projection on the service).
 	 *
 	 * Access is governed by the collection's `listRule` (PocketBase semantics):
 	 * public collections allow anonymous subscriptions; other collections
 	 * require a matching logged-in user or superuser.
 	 *
-	 * @param callback Received on every record change.
-	 * @param recordId Optional — subscribe to a single record instead of `*`.
+	 * PocketBase-compatible argument forms:
+	 *   - `subscribe(cb)` — all records of the collection
+	 *   - `subscribe('*', cb)` — all records (explicit wildcard)
+	 *   - `subscribe('RECORD_ID', cb)` — a single record
+	 *   - `subscribe('*' | 'RECORD_ID', cb, options)` — with join options
+	 *
+	 * Legacy form (callback first) is still accepted: `subscribe(cb, recordId)`.
+	 *
 	 * @returns A function that unsubscribes this callback.
 	 */
-	subscribe(callback: RealtimeCallback, recordId?: string): () => void {
+	subscribe(callback: RealtimeCallback): () => void;
+	subscribe(
+		recordId: string,
+		callback: RealtimeCallback,
+		options?: RealtimeSubscribeOptions,
+	): () => void;
+	/** @deprecated Use `subscribe(recordId, callback)` — PocketBase order. */
+	subscribe(callback: RealtimeCallback, recordId?: string): () => void;
+	subscribe(
+		topicOrCallback: string | RealtimeCallback,
+		maybeCallback?: RealtimeCallback | string,
+		options?: RealtimeSubscribeOptions,
+	): () => void {
 		if (!this.realtime) {
 			console.warn("[lazypock] No realtime service configured.");
 			return () => {};
 		}
+
+		// Normalise PocketBase-style args; also accept the legacy callback-first
+		// form (subscribe(cb, recordId)) for backward compatibility.
+		let recordId: string | undefined;
+		let callback: RealtimeCallback;
+		let joinPayload: Record<string, unknown> | undefined;
+
+		if (typeof topicOrCallback === "function") {
+			callback = topicOrCallback;
+			if (typeof maybeCallback === "string") recordId = maybeCallback;
+		} else {
+			callback = maybeCallback as RealtimeCallback;
+			recordId = topicOrCallback === "*" ? undefined : topicOrCallback;
+			// Forward subscribe options (minus HTTP-only headers) to the server
+			// channel join payload.
+			const { headers: _ignored, ...rest } = options ?? {};
+			if (Object.keys(rest).length > 0) joinPayload = rest;
+		}
+
 		const topic =
-			"collection:" + this.collectionName + (recordId ? ":" + recordId : "");
+			"collection:" +
+			this.collectionName +
+			(recordId ? ":" + recordId : "");
 		const handler = (raw: RealtimeEventLike) => {
 			const record = (raw.payload?.["record"] ?? {}) as Record<string, unknown>;
 			callback({
@@ -531,17 +589,27 @@ export class CollectionService<T = ApiRecord, TData = never> {
 			});
 		};
 		this.realtime.ensureConnected();
-		this.realtime.subscribe(topic, handler as never);
+		this.realtime.subscribe(topic, handler as never, joinPayload);
 		return () => this.realtime?.unsubscribe(topic, handler as never);
 	}
 
 	/**
-	 * Unsubscribe all callbacks from this collection (or a specific record).
-	 * @param recordId Optional record id; omitting it unsubs everything.
+	 * Unsubscribe from realtime changes (PocketBase-compatible):
+	 *   - `unsubscribe()` — remove **all** subscriptions of this collection
+	 *   - `unsubscribe('*')` — remove wildcard subscriptions
+	 *   - `unsubscribe('RECORD_ID')` — remove that record's subscriptions
 	 */
 	unsubscribe(recordId?: string): void {
+		if (recordId === undefined) {
+			this.realtime?.unsubscribeByPrefix(
+				"collection:" + this.collectionName,
+			);
+			return;
+		}
 		const topic =
-			"collection:" + this.collectionName + (recordId ? ":" + recordId : "");
+			"collection:" +
+			this.collectionName +
+			(recordId === "*" ? "" : ":" + recordId);
 		this.realtime?.unsubscribe(topic);
 	}
 

package/src/index.ts

@@ -56,5 +56,5 @@ export type {
 	LazypockClientOptions,
 } from "./lazypock";
 export type { LazypockCollections } from "./client";
-export type { RealtimeMessage, RealtimeCallback } from "./collection";
+export type { RealtimeMessage, RealtimeCallback, RealtimeSubscribeOptions } from "./collection";
 export type { CollectionsMessage } from "./collections";

package/src/lazypock.ts

@@ -28,6 +28,7 @@ import {
 	type FieldKey,
 } from "./types";
 import { RealtimeService, wsUrlFromBaseUrl } from "./realtime";
+import type { RealtimeConnectOpts, RealtimeTokenProvider } from "./realtime";
 import {
 	FilesService,
 	getFileUrl,
@@ -69,6 +70,9 @@ export type {
 	SystemFields,
 	RequestOptions,
 	FileRecord,
+	// realtime
+	RealtimeConnectOpts,
+	RealtimeTokenProvider,
 	CollectionSchema,
 	SchemaField,
 	// schema-driven query typing
@@ -154,6 +158,12 @@ export class LazypockClient {
 		if (!options.realtime) {
 			this.realtime.setUrl(wsUrlFromBaseUrl(baseUrl));
 		}
+		// Keep the realtime socket authenticated with the current auth token
+		// and reconnect whenever auth changes (login/logout/token refresh) —
+		// PocketBase parity. Reconnect is a no-op until something subscribes.
+		this.realtime.setTokenProvider(() => this.authStore.token);
+		this.authStore.onChange(() => this.realtime.refresh());
+		this.authReady.then(() => this.realtime.refresh());
 		this.files = new FilesService(this.http);
 		this.collections = new CollectionsService(this.http, this.realtime);
 		if (options.types?.schemas) {

package/src/realtime.ts

@@ -16,6 +16,8 @@ interface RealtimeEvent {
 interface SubEntry {
 	topic: string;
 	callback: (e: RealtimeEvent) => void;
+	/** Optional payload forwarded with the channel join (e.g. expand). */
+	joinPayload?: Record<string, unknown>;
 }
 
 export type RealtimeConnectOpts = {
@@ -25,6 +27,13 @@ export type RealtimeConnectOpts = {
 	token?: string;
 };
 
+/**
+ * Provides the current auth token at connect/reconnect time.
+ * Wired by {@link LazypockClient} from its `authStore` so the socket is
+ * always authenticated with the latest token (PocketBase parity).
+ */
+export type RealtimeTokenProvider = () => string | undefined;
+
 /**
  * Derive a WebSocket URL from an HTTP base URL.
  * http://localhost:4000/api → ws://localhost:4000/socket/websocket
@@ -67,6 +76,7 @@ export class RealtimeService {
 
 	private url: string = "";
 	private token: string | undefined;
+	private tokenProvider: RealtimeTokenProvider | null = null;
 
 	/** Whether the WebSocket is currently open. */
 	get isOpen(): boolean {
@@ -94,6 +104,35 @@ export class RealtimeService {
 		this.url = url;
 	}
 
+	/**
+	 * Register a token provider consulted at every (re)connect.
+	 * When set, it takes precedence over the token passed to {@link connect}.
+	 */
+	setTokenProvider(provider: RealtimeTokenProvider): void {
+		this.tokenProvider = provider;
+	}
+
+	/**
+	 * Reconnect the socket immediately with the current token.
+	 * Called by the SDK when auth changes (login/logout/token refresh) so
+	 * private-channel joins are authorized with the new credentials. No-op
+	 * when the socket has never been opened and nothing is subscribed.
+	 */
+	refresh(): void {
+		if (typeof WebSocket === "undefined") return;
+		if (!this.ws && this.subscriptions.size === 0) return;
+		this.clearReconnectTimer();
+		const ws = this.ws;
+		this.ws = null;
+		if (ws) {
+			// Suppress the auto-reconnect path for this intentional close.
+			ws.onclose = null;
+			ws.close();
+		}
+		this.reconnectAttempt = 0;
+		this.doConnect();
+	}
+
 	/*
 	 * Ensure the socket is connected, then subscribe.
 	 * Used by collection-level convenience wrappers so a connection is opened
@@ -120,16 +159,36 @@ export class RealtimeService {
 	}
 
 	/**
-	 * Subscribe to a topic (e.g. "collection:posts" or "collection:posts:*").
+	 * Subscribe to a topic (e.g. "collection:posts" or "custom:chat-room").
 	 * The backend Channel authorizes via listRule on join.
+	 *
+	 * @param joinPayload Optional payload forwarded with the channel join
+	 * (available to the server's join callback / hooks, e.g. `expand`).
 	 */
-	subscribe(topic: string, callback: (e: RealtimeEvent) => void): void {
+	subscribe(
+		topic: string,
+		callback: (e: RealtimeEvent) => void,
+		joinPayload?: Record<string, unknown>,
+	): void {
 		const subs = this.subscriptions.get(topic) || [];
-		subs.push({ topic, callback });
+		subs.push({ topic, callback, joinPayload });
 		this.subscriptions.set(topic, subs);
 
 		if (this.ws?.readyState === WebSocket.OPEN) {
-			this.joinTopic(topic);
+			this.joinTopic(topic, joinPayload);
+		}
+	}
+
+	/**
+	 * Remove all subscriptions for topics under `prefix` (the topic itself or
+	 * any topic starting with `prefix + ":"`). Used by collection-level
+	 * `unsubscribe()` to drop every subscription of a collection.
+	 */
+	unsubscribeByPrefix(prefix: string): void {
+		for (const topic of [...this.subscriptions.keys()]) {
+			if (topic === prefix || topic.startsWith(prefix + ":")) {
+				this.subscriptions.delete(topic);
+			}
 		}
 	}
 
@@ -152,9 +211,14 @@ export class RealtimeService {
 	}
 
 	private resubscribeAll(): void {
-		for (const topic of this.subscriptions.keys()) {
-			if (this.ws?.readyState === WebSocket.OPEN) {
-				this.joinTopic(topic);
+		const seen = new Set<string>();
+		for (const entries of this.subscriptions.values()) {
+			for (const entry of entries) {
+				if (seen.has(entry.topic)) continue;
+				seen.add(entry.topic);
+				if (this.ws?.readyState === WebSocket.OPEN) {
+					this.joinTopic(entry.topic, entry.joinPayload);
+				}
 			}
 		}
 	}
@@ -168,11 +232,12 @@ export class RealtimeService {
 		}
 
 		let url = this.url;
-		if (this.token) {
+		const token = this.tokenProvider ? this.tokenProvider() : this.token;
+		if (token) {
 			url +=
 				(url.includes("?") ? "&" : "?") +
 				"token=" +
-				encodeURIComponent(this.token);
+				encodeURIComponent(token);
 		}
 
 		this.ws = new WebSocket(url);
@@ -232,13 +297,16 @@ export class RealtimeService {
 		}
 	}
 
-	private joinTopic(topic: string): void {
+	private joinTopic(
+		topic: string,
+		joinPayload?: Record<string, unknown>,
+	): void {
 		const ref = this.nextRef();
 		// Phoenix V1 JSON Serializer expects a JSON object, not an array
 		const msg = JSON.stringify({
 			topic: topic,
 			event: "phx_join",
-			payload: {},
+			payload: joinPayload ?? {},
 			ref: ref,
 		});
 		this.ws?.send(msg);