Re-use realtime event data to refresh collections

eslint.config.js

@@ -27,7 +27,7 @@ const config = tseslint.config({
     ],
     "@typescript-eslint/no-inferrable-types": "off",
     "@typescript-eslint/no-non-null-assertion": "off",
-    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/explicit-function-return-type": "warn",
     "@typescript-eslint/array-type": [
       "error",
       {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-loader-pocketbase",
-  "version": "2.2.1",
+  "version": "2.3.0-next.1",
   "description": "A content loader for Astro that uses the PocketBase API",
   "license": "MIT",
   "author": "Luis Wolf <[email protected]> (https://pawcode.de)",

src/cleanup-entries.ts

@@ -45,15 +45,15 @@ export async function cleanupEntries(
       // If the collection is locked, an superuser token is required
       if (collectionRequest.status === 403) {
         context.logger.error(
-          `(${options.collectionName}) The collection is not accessible without superuser rights. Please provide superuser credentials in the config.`
+          `The collection is not accessible without superuser rights. Please provide superuser credentials in the config.`
         );
         return;
       }
 
       const reason = await collectionRequest
         .json()
         .then((data) => data.message);
-      const errorMessage = `(${options.collectionName}) Fetching ids failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
+      const errorMessage = `Fetching ids failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
       context.logger.error(errorMessage);
       return;
     }
@@ -74,7 +74,9 @@ export async function cleanupEntries(
   let cleanedUp = 0;
 
   // Get all ids of the entries in the store
-  const storedIds = context.store.values().map((entry) => entry.data.id) as Array<string>;
+  const storedIds = context.store
+    .values()
+    .map((entry) => entry.data.id) as Array<string>;
   for (const id of storedIds) {
     // If the id is not in the entries set, remove the entry from the store
     if (!entries.has(id)) {
@@ -85,8 +87,6 @@ export async function cleanupEntries(
 
   if (cleanedUp > 0) {
     // Log the number of cleaned up entries
-    context.logger.info(
-      `(${options.collectionName}) Cleaned up ${cleanedUp} old entries.`
-    );
+    context.logger.info(`Cleaned up ${cleanedUp} old entries.`);
   }
 }

src/handle-realtime-updates.ts

@@ -0,0 +1,48 @@
+import type { LoaderContext } from "astro/loaders";
+import type { PocketBaseLoaderOptions } from "./types/pocketbase-loader-options.type";
+import { isRealtimeData } from "./utils/is-realtime-data";
+import { parseEntry } from "./utils/parse-entry";
+
+/**
+ * Handles realtime updates for the loader without making any new network requests.
+ *
+ * Returns `true` if the data was handled and no further action is needed.
+ */
+export async function handleRealtimeUpdates(
+  context: LoaderContext,
+  options: PocketBaseLoaderOptions
+): Promise<boolean> {
+  // Check if data was provided via the refresh context
+  if (!context.refreshContextData?.data) {
+    return false;
+  }
+
+  // Check if the data is PocketBase realtime data
+  const data = context.refreshContextData.data;
+  if (!isRealtimeData(data)) {
+    return false;
+  }
+
+  // Check if the collection name matches the current collection
+  if (data.record.collectionName !== options.collectionName) {
+    return false;
+  }
+
+  // Handle deleted entry
+  if (data.action === "delete") {
+    context.logger.info("Removing deleted entry");
+    context.store.delete(data.record.id);
+    return true;
+  }
+
+  // Handle updated or new entry
+  if (data.action === "update") {
+    context.logger.info("Updating outdated entry");
+  } else {
+    context.logger.info("Creating new entry");
+  }
+
+  // Parse the entry and store
+  await parseEntry(data.record, context, options);
+  return true;
+}

src/load-entries.ts

@@ -32,11 +32,9 @@ export async function loadEntries(
 
   // Log the fetching of the entries
   context.logger.info(
-    `(${options.collectionName}) Fetching${
-      lastModified ? " modified" : ""
-    } data${lastModified ? ` starting at ${lastModified}` : ""}${
-      superuserToken ? " as superuser" : ""
-    }`
+    `Fetching${lastModified ? " modified" : ""} data${
+      lastModified ? ` starting at ${lastModified}` : ""
+    }${superuserToken ? " as superuser" : ""}`
   );
 
   // Prepare pagination variables
@@ -64,15 +62,15 @@ export async function loadEntries(
       // If the collection is locked, an superuser token is required
       if (collectionRequest.status === 403) {
         throw new Error(
-          `(${options.collectionName}) The collection is not accessible without superuser rights. Please provide superuser credentials in the config.`
+          `The collection is not accessible without superuser rights. Please provide superuser credentials in the config.`
         );
       }
 
       // Get the reason for the error
       const reason = await collectionRequest
         .json()
         .then((data) => data.message);
-      const errorMessage = `(${options.collectionName}) Fetching data failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
+      const errorMessage = `Fetching data failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
       throw new Error(errorMessage);
     }
 
@@ -92,8 +90,6 @@ export async function loadEntries(
 
   // Log the number of fetched entries
   context.logger.info(
-    `(${options.collectionName}) Fetched ${entries}${
-      lastModified ? " changed" : ""
-    } entries.`
+    `Fetched ${entries}${lastModified ? " changed" : ""} entries.`
   );
 }

src/pocketbase-loader.ts

@@ -1,7 +1,9 @@
 import type { Loader, LoaderContext } from "astro/loaders";
+import type { ZodSchema } from "astro/zod";
 import packageJson from "./../package.json";
 import { cleanupEntries } from "./cleanup-entries";
 import { generateSchema } from "./generate-schema";
+import { handleRealtimeUpdates } from "./handle-realtime-updates";
 import { loadEntries } from "./load-entries";
 import type { PocketBaseLoaderOptions } from "./types/pocketbase-loader-options.type";
 import { getSuperuserToken } from "./utils/get-superuser-token";
@@ -16,6 +18,8 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
   return {
     name: "pocketbase-loader",
     load: async (context: LoaderContext): Promise<void> => {
+      context.logger.label = `pocketbase-loader:${options.collectionName}`;
+
       // Check if the collection should be refreshed.
       const refresh = shouldRefresh(
         context.refreshContextData,
@@ -25,6 +29,12 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
         return;
       }
 
+      // Handle realtime updates
+      const handled = await handleRealtimeUpdates(context, options);
+      if (handled) {
+        return;
+      }
+
       // Get the date of the last fetch to only update changed entries.
       let lastModified = context.meta.get("last-modified");
 
@@ -45,7 +55,7 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
       // Disable incremental builds if no updated field is provided
       if (!options.updatedField) {
         context.logger.info(
-          `(${options.collectionName}) No "updatedField" was provided. Incremental builds are disabled.`
+          `No "updatedField" was provided. Incremental builds are disabled.`
         );
         lastModified = undefined;
       }
@@ -76,7 +86,7 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
 
       context.meta.set("version", packageJson.version);
     },
-    schema: async () => {
+    schema: async (): Promise<ZodSchema> => {
       // Generate the schema for the collection according to the API
       return await generateSchema(options);
     }

src/utils/is-realtime-data.ts

@@ -0,0 +1,34 @@
+import { z } from "astro/zod";
+
+/**
+ * Schema for realtime data received from PocketBase.
+ */
+const realtimeDataSchema = z.object({
+  action: z.union([
+    z.literal("create"),
+    z.literal("update"),
+    z.literal("delete")
+  ]),
+  record: z.object({
+    id: z.string(),
+    collectionName: z.string(),
+    collectionId: z.string()
+  })
+});
+
+/**
+ * Type for realtime data received from PocketBase.
+ */
+export type RealtimeData = z.infer<typeof realtimeDataSchema>;
+
+/**
+ * Checks if the given data is realtime data received from PocketBase.
+ */
+export function isRealtimeData(data: unknown): data is RealtimeData {
+  try {
+    realtimeDataSchema.parse(data);
+    return true;
+  } catch {
+    return false;
+  }
+}

src/utils/parse-schema.ts

@@ -106,7 +106,7 @@ export function parseSchema(
 function parseSingleOrMultipleValues(
   field: PocketBaseSchemaEntry,
   type: z.ZodType
-) {
+): z.ZodType {
   // If the select allows multiple values, create an array of the enum
   if (field.maxSelect === undefined || field.maxSelect === 1) {
     return type;