added experimental expand, filter, fields, custom query and headers p…

…arameters support for the realtime subscriptions

CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.20.0-rc
+
+- Added experimental `expand`, `filter`, `fields`, custom query and headers parameters support for the realtime subscriptions.
+    ```js
+    pb.collection("example").subscribe("*", (e) => {
+      ...
+    }, { filter: "someField > 10" });
+    ```
+    _This works only with PocketBase v0.20.0-rc._
+
+
 ## 0.19.0
 
 - Added `pb.filter(rawExpr, params?)` helper to construct a filter string with placeholder parameters populated from an object.

README.md

@@ -833,7 +833,7 @@ const pb = new PocketBase(baseUrl = '/', authStore = LocalAuthStore);
 //
 // You can use the returned UnsubscribeFunc to remove a single registered subscription.
 // If you want to remove all subscriptions related to the topic use unsubscribe(topic).
-🔓 pb.collection(collectionIdOrName).subscribe(topic, callback);
+🔓 pb.collection(collectionIdOrName).subscribe(topic, callback, options = {});
 
 // Unsubscribe from all registered subscriptions to the specified topic ("*" or recordId).
 // If topic is not set, then it will remove all registered collection subscriptions.
@@ -1011,7 +1011,7 @@ const pb = new PocketBase(baseUrl = '/', authStore = LocalAuthStore);
 
 ```js
 // Initialize the realtime connection (if not already) and register the subscription listener.
-🔓 pb.realtime.subscribe(topic, callback);
+🔓 pb.realtime.subscribe(topic, callback, options = {});
 
 // Unsubscribe from all subscription listeners with the specified topic.
 🔓 pb.realtime.unsubscribe(topic?);

dist/pocketbase.cjs.d.ts

@@ -458,7 +458,7 @@ declare class RealtimeService extends BaseService {
     clientId: string;
     private eventSource;
     private subscriptions;
-    private lastSentTopics;
+    private lastSentSubscriptions;
     private connectTimeoutId;
     private maxConnectTimeout;
     private reconnectTimeoutId;
@@ -478,7 +478,7 @@ declare class RealtimeService extends BaseService {
      * If the SSE connection is not started yet,
      * this method will also initialize it.
      */
-    subscribe(topic: string, callback: (data: any) => void): Promise<UnsubscribeFunc>;
+    subscribe(topic: string, callback: (data: any) => void, options?: SendOptions): Promise<UnsubscribeFunc>;
     /**
      * Unsubscribe from all subscription listeners with the specified topic.
      *
@@ -499,7 +499,7 @@ declare class RealtimeService extends BaseService {
      * The related sse connection will be autoclosed if after the
      * unsubscribe operation there are no active subscriptions left.
      */
-    unsubscribeByPrefix(topicPrefix: string): Promise<void>;
+    unsubscribeByPrefix(keyPrefix: string): Promise<void>;
     /**
      * Unsubscribe from all subscriptions matching the specified topic and listener function.
      *
@@ -513,7 +513,8 @@ declare class RealtimeService extends BaseService {
     private hasSubscriptionListeners;
     private submitSubscriptions;
     private getSubscriptionsCancelKey;
-    private getNonEmptySubscriptionTopics;
+    private getSubscriptionsByTopic;
+    private getNonEmptySubscriptionKeys;
     private addAllSubscriptionListeners;
     private removeAllSubscriptionListeners;
     private connect;
@@ -587,16 +588,6 @@ declare class RecordService<M = RecordModel> extends CrudService<M> {
     // ---------------------------------------------------------------
     // Realtime handlers
     // ---------------------------------------------------------------
-    /**
-     * @deprecated Use subscribe(recordId, callback) instead.
-     *
-     * Subscribe to the realtime changes of a single record in the collection.
-     */
-    subscribeOne<T = M>(recordId: string, callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
-    /**
-     * @deprecated This form of subscribe is deprecated. Please use `subscribe("*", callback)`.
-     */
-    subscribe<T = M>(callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
     /**
      * Subscribe to realtime changes to the specified topic ("*" or record id).
      *
@@ -610,7 +601,7 @@ declare class RecordService<M = RecordModel> extends CrudService<M> {
      * You can use the returned `UnsubscribeFunc` to remove only a single subscription.
      * Or use `unsubscribe(topic)` if you want to remove all subscriptions attached to the topic.
      */
-    subscribe<T = M>(topic: string, callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
+    subscribe<T = M>(topic: string, callback: (data: RecordSubscription<T>) => void, options?: SendOptions): Promise<UnsubscribeFunc>;
     /**
      * Unsubscribe from all subscriptions of the specified topic
      * ("*" or record id).

dist/pocketbase.es.d.mts

@@ -218,6 +218,8 @@ interface AuthOptions extends CommonOptions {
      */
     autoRefreshThreshold?: number;
 }
+// modifies in place the provided options by moving unknown send options as query parameters.
+declare function normalizeUnknownQueryParams(options?: SendOptions): void;
 interface appleClientSecret {
     secret: string;
 }
@@ -479,7 +481,7 @@ declare class RealtimeService extends BaseService {
     clientId: string;
     private eventSource;
     private subscriptions;
-    private lastSentTopics;
+    private lastSentSubscriptions;
     private connectTimeoutId;
     private maxConnectTimeout;
     private reconnectTimeoutId;
@@ -499,7 +501,7 @@ declare class RealtimeService extends BaseService {
      * If the SSE connection is not started yet,
      * this method will also initialize it.
      */
-    subscribe(topic: string, callback: (data: any) => void): Promise<UnsubscribeFunc>;
+    subscribe(topic: string, callback: (data: any) => void, options?: SendOptions): Promise<UnsubscribeFunc>;
     /**
      * Unsubscribe from all subscription listeners with the specified topic.
      *
@@ -520,7 +522,7 @@ declare class RealtimeService extends BaseService {
      * The related sse connection will be autoclosed if after the
      * unsubscribe operation there are no active subscriptions left.
      */
-    unsubscribeByPrefix(topicPrefix: string): Promise<void>;
+    unsubscribeByPrefix(keyPrefix: string): Promise<void>;
     /**
      * Unsubscribe from all subscriptions matching the specified topic and listener function.
      *
@@ -534,7 +536,8 @@ declare class RealtimeService extends BaseService {
     private hasSubscriptionListeners;
     private submitSubscriptions;
     private getSubscriptionsCancelKey;
-    private getNonEmptySubscriptionTopics;
+    private getSubscriptionsByTopic;
+    private getNonEmptySubscriptionKeys;
     private addAllSubscriptionListeners;
     private removeAllSubscriptionListeners;
     private connect;
@@ -608,16 +611,6 @@ declare class RecordService<M = RecordModel> extends CrudService<M> {
     // ---------------------------------------------------------------
     // Realtime handlers
     // ---------------------------------------------------------------
-    /**
-     * @deprecated Use subscribe(recordId, callback) instead.
-     *
-     * Subscribe to the realtime changes of a single record in the collection.
-     */
-    subscribeOne<T = M>(recordId: string, callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
-    /**
-     * @deprecated This form of subscribe is deprecated. Please use `subscribe("*", callback)`.
-     */
-    subscribe<T = M>(callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
     /**
      * Subscribe to realtime changes to the specified topic ("*" or record id).
      *
@@ -631,7 +624,7 @@ declare class RecordService<M = RecordModel> extends CrudService<M> {
      * You can use the returned `UnsubscribeFunc` to remove only a single subscription.
      * Or use `unsubscribe(topic)` if you want to remove all subscriptions attached to the topic.
      */
-    subscribe<T = M>(topic: string, callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
+    subscribe<T = M>(topic: string, callback: (data: RecordSubscription<T>) => void, options?: SendOptions): Promise<UnsubscribeFunc>;
     /**
      * Unsubscribe from all subscriptions of the specified topic
      * ("*" or record id).
@@ -1292,4 +1285,4 @@ declare function getTokenPayload(token: string): {
  * @param [expirationThreshold] Time in seconds that will be subtracted from the token `exp` property.
  */
 declare function isTokenExpired(token: string, expirationThreshold?: number): boolean;
-export { Client as default, BeforeSendResult, ClientResponseError, ListResult, BaseModel, AdminModel, SchemaField, CollectionModel, ExternalAuthModel, LogRequestModel, RecordModel, SendOptions, CommonOptions, ListOptions, FullListOptions, RecordOptions, RecordListOptions, RecordFullListOptions, LogStatsOptions, FileOptions, AuthOptions, CrudService, AdminAuthResponse, AdminService, CollectionService, HourlyStats, LogService, UnsubscribeFunc, RealtimeService, RecordAuthResponse, AuthProviderInfo, AuthMethodsList, RecordSubscription, OAuth2UrlCallback, OAuth2AuthConfig, RecordService, AuthModel, OnStoreChangeFunc, BaseAuthStore, LocalAuthStore, AsyncSaveFunc, AsyncClearFunc, AsyncAuthStore, getTokenPayload, isTokenExpired, ParseOptions, cookieParse, SerializeOptions, cookieSerialize };
+export { Client as default, BeforeSendResult, ClientResponseError, ListResult, BaseModel, AdminModel, SchemaField, CollectionModel, ExternalAuthModel, LogRequestModel, RecordModel, SendOptions, CommonOptions, ListOptions, FullListOptions, RecordOptions, RecordListOptions, RecordFullListOptions, LogStatsOptions, FileOptions, AuthOptions, normalizeUnknownQueryParams, CrudService, AdminAuthResponse, AdminService, CollectionService, HourlyStats, LogService, UnsubscribeFunc, RealtimeService, RecordAuthResponse, AuthProviderInfo, AuthMethodsList, RecordSubscription, OAuth2UrlCallback, OAuth2AuthConfig, RecordService, AuthModel, OnStoreChangeFunc, BaseAuthStore, LocalAuthStore, AsyncSaveFunc, AsyncClearFunc, AsyncAuthStore, getTokenPayload, isTokenExpired, ParseOptions, cookieParse, SerializeOptions, cookieSerialize };

dist/pocketbase.es.d.ts

@@ -218,6 +218,8 @@ interface AuthOptions extends CommonOptions {
      */
     autoRefreshThreshold?: number;
 }
+// modifies in place the provided options by moving unknown send options as query parameters.
+declare function normalizeUnknownQueryParams(options?: SendOptions): void;
 interface appleClientSecret {
     secret: string;
 }
@@ -479,7 +481,7 @@ declare class RealtimeService extends BaseService {
     clientId: string;
     private eventSource;
     private subscriptions;
-    private lastSentTopics;
+    private lastSentSubscriptions;
     private connectTimeoutId;
     private maxConnectTimeout;
     private reconnectTimeoutId;
@@ -499,7 +501,7 @@ declare class RealtimeService extends BaseService {
      * If the SSE connection is not started yet,
      * this method will also initialize it.
      */
-    subscribe(topic: string, callback: (data: any) => void): Promise<UnsubscribeFunc>;
+    subscribe(topic: string, callback: (data: any) => void, options?: SendOptions): Promise<UnsubscribeFunc>;
     /**
      * Unsubscribe from all subscription listeners with the specified topic.
      *
@@ -520,7 +522,7 @@ declare class RealtimeService extends BaseService {
      * The related sse connection will be autoclosed if after the
      * unsubscribe operation there are no active subscriptions left.
      */
-    unsubscribeByPrefix(topicPrefix: string): Promise<void>;
+    unsubscribeByPrefix(keyPrefix: string): Promise<void>;
     /**
      * Unsubscribe from all subscriptions matching the specified topic and listener function.
      *
@@ -534,7 +536,8 @@ declare class RealtimeService extends BaseService {
     private hasSubscriptionListeners;
     private submitSubscriptions;
     private getSubscriptionsCancelKey;
-    private getNonEmptySubscriptionTopics;
+    private getSubscriptionsByTopic;
+    private getNonEmptySubscriptionKeys;
     private addAllSubscriptionListeners;
     private removeAllSubscriptionListeners;
     private connect;
@@ -608,16 +611,6 @@ declare class RecordService<M = RecordModel> extends CrudService<M> {
     // ---------------------------------------------------------------
     // Realtime handlers
     // ---------------------------------------------------------------
-    /**
-     * @deprecated Use subscribe(recordId, callback) instead.
-     *
-     * Subscribe to the realtime changes of a single record in the collection.
-     */
-    subscribeOne<T = M>(recordId: string, callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
-    /**
-     * @deprecated This form of subscribe is deprecated. Please use `subscribe("*", callback)`.
-     */
-    subscribe<T = M>(callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
     /**
      * Subscribe to realtime changes to the specified topic ("*" or record id).
      *
@@ -631,7 +624,7 @@ declare class RecordService<M = RecordModel> extends CrudService<M> {
      * You can use the returned `UnsubscribeFunc` to remove only a single subscription.
      * Or use `unsubscribe(topic)` if you want to remove all subscriptions attached to the topic.
      */
-    subscribe<T = M>(topic: string, callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
+    subscribe<T = M>(topic: string, callback: (data: RecordSubscription<T>) => void, options?: SendOptions): Promise<UnsubscribeFunc>;
     /**
      * Unsubscribe from all subscriptions of the specified topic
      * ("*" or record id).
@@ -1292,4 +1285,4 @@ declare function getTokenPayload(token: string): {
  * @param [expirationThreshold] Time in seconds that will be subtracted from the token `exp` property.
  */
 declare function isTokenExpired(token: string, expirationThreshold?: number): boolean;
-export { Client as default, BeforeSendResult, ClientResponseError, ListResult, BaseModel, AdminModel, SchemaField, CollectionModel, ExternalAuthModel, LogRequestModel, RecordModel, SendOptions, CommonOptions, ListOptions, FullListOptions, RecordOptions, RecordListOptions, RecordFullListOptions, LogStatsOptions, FileOptions, AuthOptions, CrudService, AdminAuthResponse, AdminService, CollectionService, HourlyStats, LogService, UnsubscribeFunc, RealtimeService, RecordAuthResponse, AuthProviderInfo, AuthMethodsList, RecordSubscription, OAuth2UrlCallback, OAuth2AuthConfig, RecordService, AuthModel, OnStoreChangeFunc, BaseAuthStore, LocalAuthStore, AsyncSaveFunc, AsyncClearFunc, AsyncAuthStore, getTokenPayload, isTokenExpired, ParseOptions, cookieParse, SerializeOptions, cookieSerialize };
+export { Client as default, BeforeSendResult, ClientResponseError, ListResult, BaseModel, AdminModel, SchemaField, CollectionModel, ExternalAuthModel, LogRequestModel, RecordModel, SendOptions, CommonOptions, ListOptions, FullListOptions, RecordOptions, RecordListOptions, RecordFullListOptions, LogStatsOptions, FileOptions, AuthOptions, normalizeUnknownQueryParams, CrudService, AdminAuthResponse, AdminService, CollectionService, HourlyStats, LogService, UnsubscribeFunc, RealtimeService, RecordAuthResponse, AuthProviderInfo, AuthMethodsList, RecordSubscription, OAuth2UrlCallback, OAuth2AuthConfig, RecordService, AuthModel, OnStoreChangeFunc, BaseAuthStore, LocalAuthStore, AsyncSaveFunc, AsyncClearFunc, AsyncAuthStore, getTokenPayload, isTokenExpired, ParseOptions, cookieParse, SerializeOptions, cookieSerialize };

dist/pocketbase.iife.d.ts

@@ -458,7 +458,7 @@ declare class RealtimeService extends BaseService {
     clientId: string;
     private eventSource;
     private subscriptions;
-    private lastSentTopics;
+    private lastSentSubscriptions;
     private connectTimeoutId;
     private maxConnectTimeout;
     private reconnectTimeoutId;
@@ -478,7 +478,7 @@ declare class RealtimeService extends BaseService {
      * If the SSE connection is not started yet,
      * this method will also initialize it.
      */
-    subscribe(topic: string, callback: (data: any) => void): Promise<UnsubscribeFunc>;
+    subscribe(topic: string, callback: (data: any) => void, options?: SendOptions): Promise<UnsubscribeFunc>;
     /**
      * Unsubscribe from all subscription listeners with the specified topic.
      *
@@ -499,7 +499,7 @@ declare class RealtimeService extends BaseService {
      * The related sse connection will be autoclosed if after the
      * unsubscribe operation there are no active subscriptions left.
      */
-    unsubscribeByPrefix(topicPrefix: string): Promise<void>;
+    unsubscribeByPrefix(keyPrefix: string): Promise<void>;
     /**
      * Unsubscribe from all subscriptions matching the specified topic and listener function.
      *
@@ -513,7 +513,8 @@ declare class RealtimeService extends BaseService {
     private hasSubscriptionListeners;
     private submitSubscriptions;
     private getSubscriptionsCancelKey;
-    private getNonEmptySubscriptionTopics;
+    private getSubscriptionsByTopic;
+    private getNonEmptySubscriptionKeys;
     private addAllSubscriptionListeners;
     private removeAllSubscriptionListeners;
     private connect;
@@ -587,16 +588,6 @@ declare class RecordService<M = RecordModel> extends CrudService<M> {
     // ---------------------------------------------------------------
     // Realtime handlers
     // ---------------------------------------------------------------
-    /**
-     * @deprecated Use subscribe(recordId, callback) instead.
-     *
-     * Subscribe to the realtime changes of a single record in the collection.
-     */
-    subscribeOne<T = M>(recordId: string, callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
-    /**
-     * @deprecated This form of subscribe is deprecated. Please use `subscribe("*", callback)`.
-     */
-    subscribe<T = M>(callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
     /**
      * Subscribe to realtime changes to the specified topic ("*" or record id).
      *
@@ -610,7 +601,7 @@ declare class RecordService<M = RecordModel> extends CrudService<M> {
      * You can use the returned `UnsubscribeFunc` to remove only a single subscription.
      * Or use `unsubscribe(topic)` if you want to remove all subscriptions attached to the topic.
      */
-    subscribe<T = M>(topic: string, callback: (data: RecordSubscription<T>) => void): Promise<UnsubscribeFunc>;
+    subscribe<T = M>(topic: string, callback: (data: RecordSubscription<T>) => void, options?: SendOptions): Promise<UnsubscribeFunc>;
     /**
      * Unsubscribe from all subscriptions of the specified topic
      * ("*" or record id).