astro-loader-pocketbase 2.8.2-next.4 → 2.9.0-next.2

package/README.md

@@ -309,6 +309,17 @@ const blogLive = defineLiveCollection({
 });
 ```
 
+### Error handling
+
+The live content loader follows Astro's standard error handling conventions for live collections. For more information on how to handle errors in your components, see the [Astro documentation on error handling](https://docs.astro.build/en/reference/experimental-flags/live-content-collections/#error-handling).
+
+| Error                           | When it's returned                                                                                            |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `PocketBaseAuthenticationError` | Authentication or authorization fails (missing credentials or invalid token)                                  |
+| `LiveEntryNotFoundError`        | The requested entry doesn't exist or doesn't match the applied filters                                        |
+| `LiveCollectionValidationError` | The data returned by PocketBase doesn't match the Zod schema or the `updatedField` doesn't contain valid data |
+| `LiveCollectionError`           | Any other error occurs (network errors, invalid filter syntax, PocketBase server errors, etc.)                |
+
 ### Caveats
 
 Live content loaders do not (yet 🤞🏼) support zod schemas and thus schema generation and entry transformation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-loader-pocketbase",
-  "version": "2.8.2-next.4",
+  "version": "2.9.0-next.2",
   "description": "A content loader for Astro that uses the PocketBase API",
   "keywords": [
     "astro",
@@ -46,7 +46,7 @@
     "@commitlint/cli": "20.1.0",
     "@commitlint/config-conventional": "20.0.0",
     "@types/node": "24.9.1",
-    "@vitest/coverage-v8": "3.2.4",
+    "@vitest/coverage-v8": "4.0.3",
     "astro": "5.15.1",
     "globals": "16.4.0",
     "husky": "9.1.7",
@@ -57,7 +57,7 @@
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "2.5.19",
     "typescript": "5.9.3",
-    "vitest": "3.2.4"
+    "vitest": "4.0.3"
   },
   "peerDependencies": {
     "astro": "^5.10.0"

package/src/index.ts

@@ -2,6 +2,7 @@ import {
   experimentalPocketbaseLiveLoader,
   pocketbaseLoader
 } from "./pocketbase-loader";
+import { PocketBaseAuthenticationError } from "./types/errors";
 import type {
   ExperimentalPocketBaseLiveLoaderCollectionFilter,
   ExperimentalPocketBaseLiveLoaderEntryFilter
@@ -11,7 +12,11 @@ import type {
   PocketBaseLoaderOptions
 } from "./types/pocketbase-loader-options.type";
 
-export { experimentalPocketbaseLiveLoader, pocketbaseLoader };
+export {
+  experimentalPocketbaseLiveLoader,
+  PocketBaseAuthenticationError,
+  pocketbaseLoader
+};
 export type {
   ExperimentalPocketBaseLiveLoaderCollectionFilter,
   ExperimentalPocketBaseLiveLoaderEntryFilter,

package/src/loader/fetch-collection.ts

@@ -1,3 +1,8 @@
+import {
+  LiveCollectionError,
+  LiveEntryNotFoundError
+} from "astro/content/runtime";
+import { PocketBaseAuthenticationError } from "../types/errors";
 import {
   pocketBaseErrorResponse,
   pocketBaseListResponse
@@ -72,20 +77,32 @@ export async function fetchCollection<TEntry extends PocketBaseEntry>(
           options.superuserCredentials &&
           "impersonateToken" in options.superuserCredentials
         ) {
-          throw new Error("The given impersonate token is not valid.");
+          throw new PocketBaseAuthenticationError(
+            options.collectionName,
+            "The given impersonate token is not valid."
+          );
         } else {
-          throw new Error(
+          throw new PocketBaseAuthenticationError(
+            options.collectionName,
             "The collection is not accessible without superuser rights. Please provide superuser credentials in the config."
           );
         }
       }
 
+      if (collectionRequest.status === 404) {
+        throw new LiveEntryNotFoundError(options.collectionName, {
+          ...collectionFilter
+        });
+      }
+
       // Get the reason for the error
       const errorResponse = pocketBaseErrorResponse.parse(
         await collectionRequest.json()
       );
-      const errorMessage = `Fetching data failed with status code ${collectionRequest.status}.\nReason: ${errorResponse.message}`;
-      throw new Error(errorMessage);
+      throw new LiveCollectionError(
+        options.collectionName,
+        errorResponse.message
+      );
     }
 
     // Get the data from the response

package/src/loader/fetch-entry.ts

@@ -1,3 +1,8 @@
+import {
+  LiveCollectionError,
+  LiveEntryNotFoundError
+} from "astro/content/runtime";
+import { PocketBaseAuthenticationError } from "../types/errors";
 import { pocketBaseErrorResponse } from "../types/pocketbase-api-response.type";
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
 import { pocketBaseEntry } from "../types/pocketbase-entry.type";
@@ -45,20 +50,30 @@ export async function fetchEntry<TEntry extends PocketBaseEntry>(
         options.superuserCredentials &&
         "impersonateToken" in options.superuserCredentials
       ) {
-        throw new Error("The given impersonate token is not valid.");
+        throw new PocketBaseAuthenticationError(
+          options.collectionName,
+          "The given impersonate token is not valid."
+        );
       } else {
-        throw new Error(
+        throw new PocketBaseAuthenticationError(
+          options.collectionName,
           "The entry is not accessible without superuser rights. Please provide superuser credentials in the config."
         );
       }
     }
 
+    if (entryRequest.status === 404) {
+      throw new LiveEntryNotFoundError(options.collectionName, id);
+    }
+
     // Get the reason for the error
     const errorResponse = pocketBaseErrorResponse.parse(
       await entryRequest.json()
     );
-    const errorMessage = `Fetching entry "${id}" from collection "${options.collectionName}" failed.\nReason: ${errorResponse.message}`;
-    throw new Error(errorMessage);
+    throw new LiveCollectionError(
+      options.collectionName,
+      errorResponse.message
+    );
   }
 
   // Get the data from the response

package/src/loader/live-collection-loader.ts

@@ -1,4 +1,5 @@
 import type { LiveDataCollection, LiveDataEntry } from "astro";
+import { LiveCollectionError } from "astro/content/runtime";
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
 import type { ExperimentalPocketBaseLiveLoaderCollectionFilter } from "../types/pocketbase-live-loader-filter.type";
 import type { ExperimentalPocketBaseLiveLoaderOptions } from "../types/pocketbase-loader-options.type";
@@ -14,7 +15,7 @@ export async function liveCollectionLoader<TEntry extends PocketBaseEntry>(
     | undefined,
   options: ExperimentalPocketBaseLiveLoaderOptions,
   token: string | undefined
-): Promise<LiveDataCollection<TEntry> | { error: Error }> {
+): Promise<LiveDataCollection<TEntry> | { error: LiveCollectionError }> {
   const entries: Array<LiveDataEntry<TEntry>> = [];
 
   try {
@@ -27,7 +28,23 @@ export async function liveCollectionLoader<TEntry extends PocketBaseEntry>(
       collectionFilter
     );
   } catch (error) {
-    return { error: error instanceof Error ? error : new Error(String(error)) };
+    if (error instanceof LiveCollectionError) {
+      return { error };
+    }
+
+    if (error instanceof Error) {
+      return {
+        error: new LiveCollectionError(
+          options.collectionName,
+          error.message,
+          error
+        )
+      };
+    }
+
+    return {
+      error: new LiveCollectionError(options.collectionName, String(error))
+    };
   }
 
   return {

package/src/loader/live-entry-loader.ts

@@ -1,4 +1,5 @@
 import type { LiveDataEntry } from "astro";
+import { LiveCollectionError } from "astro/content/runtime";
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
 import type { ExperimentalPocketBaseLiveLoaderOptions } from "../types/pocketbase-loader-options.type";
 import { fetchEntry } from "./fetch-entry";
@@ -11,11 +12,27 @@ export async function liveEntryLoader<TEntry extends PocketBaseEntry>(
   id: string,
   options: ExperimentalPocketBaseLiveLoaderOptions,
   token: string | undefined
-): Promise<LiveDataEntry<TEntry> | { error: Error }> {
+): Promise<LiveDataEntry<TEntry> | { error: LiveCollectionError }> {
   try {
     const entry = await fetchEntry<TEntry>(id, options, token);
     return parseLiveEntry(entry, options);
   } catch (error) {
-    return { error: error instanceof Error ? error : new Error(String(error)) };
+    if (error instanceof LiveCollectionError) {
+      return { error };
+    }
+
+    if (error instanceof Error) {
+      return {
+        error: new LiveCollectionError(
+          options.collectionName,
+          error.message,
+          error
+        )
+      };
+    }
+
+    return {
+      error: new LiveCollectionError(options.collectionName, String(error))
+    };
   }
 }

package/src/loader/parse-live-entry.ts

@@ -1,4 +1,6 @@
 import type { LiveDataEntry } from "astro";
+import { LiveCollectionValidationError } from "astro/content/runtime";
+import { z } from "astro/zod";
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
 import type { ExperimentalPocketBaseLiveLoaderOptions } from "../types/pocketbase-loader-options.type";
 
@@ -17,18 +19,15 @@ export function parseLiveEntry<TEntry extends PocketBaseEntry>(
   // use it as the last modified date cache hint
   if (options.updatedField && entry[options.updatedField]) {
     const value = `${entry[options.updatedField]}`;
-    try {
-      const date = new Date(value);
-      if (isNaN(date.getTime())) {
-        throw new TypeError("Invalid date");
-      }
-
-      lastModified = date;
-    } catch {
-      console.warn(
-        `Entry ${entry.id} of collection ${options.collectionName} has an invalid date in ${options.updatedField}: ${value}`
+    const date = z.coerce.date().safeParse(value);
+    if (!date.success) {
+      throw new LiveCollectionValidationError(
+        options.collectionName,
+        entry.id,
+        date.error
       );
     }
+    lastModified = date.data;
   }
 
   if (!options.contentFields) {

package/src/pocketbase-loader.ts

@@ -1,4 +1,5 @@
 import type { LiveDataCollection, LiveDataEntry } from "astro";
+import type { LiveCollectionError } from "astro/content/runtime";
 import type { LiveLoader, Loader } from "astro/loaders";
 import type { ZodSchema } from "astro/zod";
 import { liveCollectionLoader } from "./loader/live-collection-loader";
@@ -65,7 +66,8 @@ export function experimentalPocketbaseLiveLoader<
 ): LiveLoader<
   TEntry,
   ExperimentalPocketBaseLiveLoaderEntryFilter,
-  ExperimentalPocketBaseLiveLoaderCollectionFilter
+  ExperimentalPocketBaseLiveLoaderCollectionFilter,
+  LiveCollectionError
 > {
   // Create shared promise for the superuser token, which can be reused
   const tokenPromise = createTokenPromise(options);
@@ -74,7 +76,9 @@ export function experimentalPocketbaseLiveLoader<
     name: "pocketbase-live-loader",
     loadCollection: async ({
       filter
-    }): Promise<LiveDataCollection<TEntry> | { error: Error }> => {
+    }): Promise<
+      LiveDataCollection<TEntry> | { error: LiveCollectionError }
+    > => {
       const token = await tokenPromise;
 
       // Load entries from the collection
@@ -82,7 +86,7 @@ export function experimentalPocketbaseLiveLoader<
     },
     loadEntry: async ({
       filter
-    }): Promise<LiveDataEntry<TEntry> | { error: Error }> => {
+    }): Promise<LiveDataEntry<TEntry> | { error: LiveCollectionError }> => {
       const token = await tokenPromise;
 
       // Load a single entry from the collection

package/src/types/errors.ts

@@ -0,0 +1,19 @@
+import { LiveCollectionError } from "astro/content/runtime";
+
+/**
+ * Error thrown when there is an authentication issue with PocketBase.
+ */
+export class PocketBaseAuthenticationError extends LiveCollectionError {
+  constructor(collection: string, message: string) {
+    super(collection, message);
+    this.name = "PocketBaseAuthenticationError";
+  }
+
+  static is(error: unknown): error is PocketBaseAuthenticationError {
+    // This is similar to the original implementation in Astro itself.
+    return (
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      !!error && (error as Error)?.name === "PocketBaseAuthenticationError"
+    );
+  }
+}