astro-integration-pocketbase 1.1.0 → 1.2.0-next.2

package/README.md

@@ -8,7 +8,7 @@
 
 This package provides an Astro toolbar for users of [astro-loader-pocketbase](https://github.com/pawcoding/astro-loader-pocketbase) to view PocketBase data directly in the Astro dev server.
 
-![PocketBase Toolbar](/assets/toolbar.png)
+![PocketBase Toolbar](https://github.com/pawcoding/astro-integration-pocketbase/blob/master/assets/toolbar.png?raw=true)
 
 ## Compatibility
 
@@ -43,6 +43,8 @@ If a loader is found, the viewer will show a refresh button to reload all entrie
 
 ## Realtime updates
 
+### Basic setup
+
 PocketBase allows you to subscribe to collection changes via its [Realtime API](https://pocketbase.io/docs/api-realtime/).
 This integration allows you to subscribe to these changes and reload the entries / collections.
 Note that Node.js currently does not support the [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) API, so the integration uses the [eventsource](https://www.npmjs.com/package/eventsource) package to provide the same functionality.
@@ -64,6 +66,28 @@ pocketbaseIntegration({
 
 **Tip:** You can disable the realtime updates temporarily via the toolbar.
 
+### Advanced setup
+
+If you work with view collections, you need some more advanced options to get the realtime updates working as expected.
+Since [view collections don't receive realtime events](https://pocketbase.io/docs/collections/#view-collection), you need to watch the source base collection instead, by providing one or more collections to watch.
+
+```ts
+pocketbaseIntegration({
+  ...options,
+  collectionsToWatch: {
+    // Same effect as basic setup watching the same collection
+    // Recommended for basic / auth collections
+    users: true,
+    // Watch the source collection(s) of a view collection
+    // Recommended for view collections
+    postings: ["posts", "comments"]
+  }
+});
+```
+
+When using `true`, the integration will subscribe and reload the entries of the same collection mentioned in the key.
+When using an array of other collections, the integration will subscribe to changes of collections given in the array and reload the entries of the collection mentioned in the key.
+
 ## Entity viewer
 
 To view the PocketBase entries inside the entity viewer, you need to use `Astro.props` to pass the entries to your page (and thus to the toolbar).
@@ -106,8 +130,8 @@ The integration will automatically detect PocketBase entries in the props and di
 
 ## All options
 
-| Option                 | Type                                  | Required | Description                                                                                                                   |
-| ---------------------- | ------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `url`                  | `string`                              | x        | The URL of your PocketBase instance.                                                                                          |
-| `collectionsToWatch`   | `Array<string>`                       |          | Collections to watch for changes.                                                                                             |
-| `superuserCredentials` | `{ email: string, password: string }` |          | The email and password of a superuser of the PocketBase instance. This is used for realtime updates of restricted collection. |
+| Option                 | Type                                                     | Required | Description                                                                                                                   |
+| ---------------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `url`                  | `string`                                                 | x        | The URL of your PocketBase instance.                                                                                          |
+| `collectionsToWatch`   | `Array<string> \| Record<string, true \| Array<string>>` |          | Collections to watch for changes.                                                                                             |
+| `superuserCredentials` | `{ email: string, password: string }`                    |          | The email and password of a superuser of the PocketBase instance. This is used for realtime updates of restricted collection. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-integration-pocketbase",
-  "version": "1.1.0",
+  "version": "1.2.0-next.2",
   "license": "MIT",
   "author": "Luis Wolf <development@pawcode.de> (https://pawcode.de)",
   "homepage": "https://github.com/pawcoding/astro-integration-pocketbase",

package/src/core/refresh-collections-realtime.ts

@@ -2,6 +2,7 @@ import type { BaseIntegrationHooks } from "astro";
 import { EventSource } from "eventsource";
 import type { PocketBaseIntegrationOptions } from "../types/pocketbase-integration-options.type";
 import { getSuperuserToken } from "../utils/get-superuser-token";
+import { mapCollectionsToWatch } from "../utils/map-collections-to-watch";
 
 export function refreshCollectionsRealtime(
   {
@@ -16,9 +17,11 @@ export function refreshCollectionsRealtime(
   }: Parameters<BaseIntegrationHooks["astro:server:setup"]>[0]
 ): EventSource | undefined {
   // Check if collections should be watched
-  if (!collectionsToWatch || collectionsToWatch.length === 0) {
+  const collectionsMap = mapCollectionsToWatch(collectionsToWatch);
+  if (!collectionsMap) {
     return undefined;
   }
+  const remoteCollections = [...collectionsMap.keys()];
 
   // Check if content loader is used
   if (!refreshContent) {
@@ -65,7 +68,7 @@ export function refreshCollectionsRealtime(
   };
 
   // Add event listeners for all collections
-  for (const collection of collectionsToWatch) {
+  for (const collection of remoteCollections) {
     eventSource.addEventListener(`${collection}/*`, async () => {
       // Do not refresh if the refresh is disabled
       if (!refreshEnabled) {
@@ -78,7 +81,7 @@ export function refreshCollectionsRealtime(
         loaders: ["pocketbase-loader"],
         context: {
           source: "astro-integration-pocketbase",
-          collection
+          collection: collectionsMap.get(collection)
         }
       });
     });
@@ -108,7 +111,7 @@ export function refreshCollectionsRealtime(
       },
       body: JSON.stringify({
         clientId: clientId,
-        subscriptions: collectionsToWatch.map((collection) => `${collection}/*`)
+        subscriptions: remoteCollections.map((collection) => `${collection}/*`)
       })
     });
 
@@ -123,7 +126,7 @@ export function refreshCollectionsRealtime(
     if (!wasConnectedOnce) {
       wasConnectedOnce = true;
       logger.info(
-        `Subscribed to PocketBase realtime API. Waiting for updates on ${collectionsToWatch.join(
+        `Subscribed to PocketBase realtime API. Waiting for updates on ${remoteCollections.join(
           ", "
         )}.`
       );

package/src/types/pocketbase-integration-options.type.ts

@@ -23,6 +23,28 @@ export interface PocketBaseIntegrationOptions {
   /**
    * List of PocketBase collections to watch for changes.
    * When an entry in one of these collections changes, the content will be reloaded.
+   *
+   * Example:
+   * ```ts
+   * collectionsToWatch: ["users", "posts"]
+   * ```
+   *
+   * For advanced usage, you can specify a map where the key is the collection that is used to load the content.
+   * The value can be:
+   * - `true` to watch the collection itself for changes (base collection)
+   * - an array of strings to watch multiple collections for changes (view collection)
+   *
+   * These advanced options are especially useful when you're working with view collections.
+   * [View collections](https://pocketbase.io/docs/collections/#view-collection) don't emit events when their
+   * entries change, since they are based on other collections.
+   *
+   * Example:
+   * ```ts
+   * collectionsToWatch: {
+   *  "users": true,
+   *  "postings": ["posts", "comments"]
+   * }
+   * ```
    */
-  collectionsToWatch?: Array<string>;
+  collectionsToWatch?: Array<string> | Record<string, true | Array<string>>;
 }

package/src/utils/map-collections-to-watch.ts

@@ -0,0 +1,53 @@
+import type { PocketBaseIntegrationOptions } from "../types/pocketbase-integration-options.type";
+import { pushToMapArray } from "./push-to-map-array";
+
+/**
+ * Create a map of remote collections to watch.
+ * Each key in the map represents a remote collection to subscribe to.
+ * The value is an array of local collections that should be refreshed when an entry in the remote collection changes.
+ */
+export function mapCollectionsToWatch(
+  collectionsToWatch: PocketBaseIntegrationOptions["collectionsToWatch"]
+): Map<string, Array<string>> | undefined {
+  // Check if collections should be watched
+  if (!collectionsToWatch) {
+    return;
+  }
+
+  // Check if collectionsToWatch is an array
+  if (Array.isArray(collectionsToWatch)) {
+    // Check if the array is empty
+    if (collectionsToWatch.length === 0) {
+      return;
+    }
+
+    // Create a map where each collection is watched by itself
+    return new Map(
+      collectionsToWatch.map((collection) => [collection, [collection]])
+    );
+  }
+
+  // Check if collectionsToWatch is an empty object
+  if (Object.keys(collectionsToWatch).length === 0) {
+    return;
+  }
+
+  // Map collections to watch
+  const collectionsMap = new Map<string, Array<string>>();
+  for (const localCollection in collectionsToWatch) {
+    const watch = collectionsToWatch[localCollection];
+
+    // Check if collection should be watched by itself
+    if (watch === true) {
+      pushToMapArray(collectionsMap, localCollection, localCollection);
+      continue;
+    }
+
+    // Collection should be watched by multiple collections
+    for (const remoteCollection of watch) {
+      pushToMapArray(collectionsMap, remoteCollection, localCollection);
+    }
+  }
+
+  return collectionsMap;
+}

package/src/utils/push-to-map-array.ts

@@ -0,0 +1,14 @@
+/**
+ * Adds a value to an array in a map. If the key does not exist, it will be created.
+ */
+export function pushToMapArray<TKey, TArray>(
+  map: Map<TKey, Array<TArray>>,
+  key: TKey,
+  value: TArray
+): void {
+  if (map.has(key)) {
+    map.get(key)!.push(value);
+  } else {
+    map.set(key, [value]);
+  }
+}