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

package/README.md

@@ -172,7 +172,9 @@ const blog = defineCollection({
 });
 ```
 
-_It's recommended to use an [impersonate token (API token)](https://pocketbase.io/docs/authentication/#api-keys) instead of the email and password, as this is more secure and can be easily revoked._
+> [!TIP]
+> It's recommended to use an [impersonate token (API token)](https://pocketbase.io/docs/authentication/#api-keys) instead of the email and password, as this is more secure and can be easily revoked.
+> This also prevents the loader from hitting some rate limits with PocketBase, since the default is 2 authentication requests per 3 second interval.
 
 Under the hood, the loader will use the [PocketBase API](https://pocketbase.io/docs/api-collections/#view-collection) to fetch the schema of your collection and generate types with Zod based on that schema.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-loader-pocketbase",
-  "version": "2.8.2-next.2",
+  "version": "2.8.2-next.4",
   "description": "A content loader for Astro that uses the PocketBase API",
   "keywords": [
     "astro",
@@ -29,8 +29,8 @@
   "scripts": {
     "format": "npx prettier . --write --cache",
     "format:check": "npx prettier . --check --cache",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
+    "lint": "oxlint --type-aware",
+    "lint:fix": "oxlint --type-aware --fix",
     "prepare": "husky",
     "test": "vitest run",
     "test:e2e": "vitest run $(find test -name '*.e2e-spec.ts')",
@@ -45,13 +45,14 @@
   "devDependencies": {
     "@commitlint/cli": "20.1.0",
     "@commitlint/config-conventional": "20.0.0",
-    "@types/node": "24.8.1",
+    "@types/node": "24.9.1",
     "@vitest/coverage-v8": "3.2.4",
-    "astro": "5.14.6",
+    "astro": "5.15.1",
     "globals": "16.4.0",
     "husky": "9.1.7",
-    "lint-staged": "16.2.4",
-    "oxlint": "1.23.0",
+    "lint-staged": "16.2.6",
+    "oxlint": "1.24.0",
+    "oxlint-tsgolint": "^0.3.0",
     "prettier": "3.6.2",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-packagejson": "2.5.19",

package/src/loader/cleanup-entries.ts

@@ -1,4 +1,11 @@
 import type { LoaderContext } from "astro/loaders";
+import { z } from "astro/zod";
+import {
+  pocketBaseErrorResponse,
+  pocketBaseListResponse
+} from "../types/pocketbase-api-response.type";
+import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
+import { pocketBaseBaseEntry } from "../types/pocketbase-entry.type";
 import type { PocketBaseLoaderBaseOptions } from "../types/pocketbase-loader-options.type";
 
 /**
@@ -67,10 +74,10 @@ export async function cleanupEntries(
           );
         }
       } else {
-        const reason = await collectionRequest
-          .json()
-          .then((data) => data.message);
-        const errorMessage = `Fetching ids failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
+        const errorResponse = pocketBaseErrorResponse.parse(
+          await collectionRequest.json()
+        );
+        const errorMessage = `Fetching ids failed with status code ${collectionRequest.status}.\nReason: ${errorResponse.message}`;
         context.logger.error(errorMessage);
       }
 
@@ -81,7 +88,9 @@ export async function cleanupEntries(
     }
 
     // Get the data from the response
-    const response = await collectionRequest.json();
+    const response = cleanUpEntriesResponse.parse(
+      await collectionRequest.json()
+    );
 
     // Add the ids to the set
     for (const item of response.items) {
@@ -97,7 +106,10 @@ export async function cleanupEntries(
 
   // Create a mapping from PocketBase IDs to store keys for proper cleanup
   const storedIds = new Map<string, string>(
-    context.store.values().map((entry) => [entry.data.id as string, entry.id])
+    context.store
+      .values()
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      .map((entry) => [(entry.data as PocketBaseEntry).id, entry.id])
   );
 
   // Check which PocketBase IDs are missing from the server response
@@ -114,3 +126,12 @@ export async function cleanupEntries(
     context.logger.info(`Cleaned up ${cleanedUp} old entries.`);
   }
 }
+
+/**
+ * The response schema for cleaning up entries.
+ */
+const cleanUpEntriesResponse = pocketBaseListResponse
+  .omit({ items: true })
+  .extend({
+    items: z.array(pocketBaseBaseEntry.pick({ id: true }))
+  });

package/src/loader/fetch-collection.ts

@@ -1,3 +1,7 @@
+import {
+  pocketBaseErrorResponse,
+  pocketBaseListResponse
+} from "../types/pocketbase-api-response.type";
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
 import type { ExperimentalPocketBaseLiveLoaderCollectionFilter } from "../types/pocketbase-live-loader-filter.type";
 import type { PocketBaseLoaderBaseOptions } from "../types/pocketbase-loader-options.type";
@@ -77,18 +81,21 @@ export async function fetchCollection<TEntry extends PocketBaseEntry>(
       }
 
       // Get the reason for the error
-      const reason = await collectionRequest
-        .json()
-        .then((data) => data.message);
-      const errorMessage = `Fetching data failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
+      const errorResponse = pocketBaseErrorResponse.parse(
+        await collectionRequest.json()
+      );
+      const errorMessage = `Fetching data failed with status code ${collectionRequest.status}.\nReason: ${errorResponse.message}`;
       throw new Error(errorMessage);
     }
 
     // Get the data from the response
-    const response = await collectionRequest.json();
+    const response = pocketBaseListResponse.parse(
+      await collectionRequest.json()
+    );
 
     // Return current chunk
-    await chunkLoaded(response.items);
+    // oxlint-disable-next-line no-unsafe-type-assertion
+    await chunkLoaded(response.items as Array<TEntry>);
 
     // Update the page and total pages
     page = response.page;

package/src/loader/fetch-entry.ts

@@ -1,4 +1,6 @@
+import { pocketBaseErrorResponse } from "../types/pocketbase-api-response.type";
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
+import { pocketBaseEntry } from "../types/pocketbase-entry.type";
 import type { ExperimentalPocketBaseLiveLoaderOptions } from "../types/pocketbase-loader-options.type";
 import { combineFieldsForRequest } from "../utils/combine-fields-for-request";
 import { formatFields } from "../utils/format-fields";
@@ -52,13 +54,15 @@ export async function fetchEntry<TEntry extends PocketBaseEntry>(
     }
 
     // Get the reason for the error
-    const reason = await entryRequest.json().then((data) => data.message);
-    const errorMessage = `Fetching entry "${id}" from collection "${options.collectionName}" failed.\nReason: ${reason}`;
+    const errorResponse = pocketBaseErrorResponse.parse(
+      await entryRequest.json()
+    );
+    const errorMessage = `Fetching entry "${id}" from collection "${options.collectionName}" failed.\nReason: ${errorResponse.message}`;
     throw new Error(errorMessage);
   }
 
   // Get the data from the response
-  const response = await entryRequest.json();
-
-  return response;
+  const response = pocketBaseEntry.parse(await entryRequest.json());
+  // oxlint-disable-next-line no-unsafe-type-assertion
+  return response as TEntry;
 }

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

@@ -20,7 +20,6 @@ export async function liveCollectionLoader<TEntry extends PocketBaseEntry>(
   try {
     await fetchCollection<TEntry>(
       options,
-      // oxlint-disable-next-line require-await
       async (chunk) => {
         entries.push(...chunk.map((entry) => parseLiveEntry(entry, options)));
       },
@@ -28,7 +27,7 @@ export async function liveCollectionLoader<TEntry extends PocketBaseEntry>(
       collectionFilter
     );
   } catch (error) {
-    return { error: error as Error };
+    return { error: error instanceof Error ? error : new Error(String(error)) };
   }
 
   return {

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

@@ -16,6 +16,6 @@ export async function liveEntryLoader<TEntry extends PocketBaseEntry>(
     const entry = await fetchEntry<TEntry>(id, options, token);
     return parseLiveEntry(entry, options);
   } catch (error) {
-    return { error: error as Error };
+    return { error: error instanceof Error ? error : new Error(String(error)) };
   }
 }

package/src/pocketbase-loader.ts

@@ -45,7 +45,7 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
       const token = await tokenPromise;
 
       // Generate the schema for the collection according to the API
-      return await generateSchema(options, token);
+      return generateSchema(options, token);
     }
   };
 }
@@ -78,7 +78,7 @@ export function experimentalPocketbaseLiveLoader<
       const token = await tokenPromise;
 
       // Load entries from the collection
-      return await liveCollectionLoader(filter, options, token);
+      return liveCollectionLoader<TEntry>(filter, options, token);
     },
     loadEntry: async ({
       filter
@@ -86,7 +86,7 @@ export function experimentalPocketbaseLiveLoader<
       const token = await tokenPromise;
 
       // Load a single entry from the collection
-      return await liveEntryLoader(filter.id, options, token);
+      return liveEntryLoader<TEntry>(filter.id, options, token);
     }
   };
 }

package/src/schema/get-remote-schema.ts

@@ -1,5 +1,7 @@
+import { pocketBaseErrorResponse } from "../types/pocketbase-api-response.type";
 import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
 import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
+import { pocketBaseCollection } from "../types/pocketbase-schema.type";
 
 /**
  * Fetches the schema for the specified collection from the PocketBase instance.
@@ -26,13 +28,16 @@ export async function getRemoteSchema(
 
   // If the request was not successful, try another method
   if (!schemaRequest.ok) {
-    const reason = await schemaRequest.json().then((data) => data.message);
-    const errorMessage = `Fetching schema from ${options.collectionName} failed with status code ${schemaRequest.status}.\nReason: ${reason}`;
+    const errorResponse = pocketBaseErrorResponse.parse(
+      await schemaRequest.json()
+    );
+    const errorMessage = `Fetching schema from ${options.collectionName} failed with status code ${schemaRequest.status}.\nReason: ${errorResponse.message}`;
     console.error(errorMessage);
 
     return undefined;
   }
 
   // Get the schema from the response
-  return await schemaRequest.json();
+  const response = pocketBaseCollection.parse(await schemaRequest.json());
+  return response;
 }

package/src/schema/parse-schema.ts

@@ -46,6 +46,7 @@ export function parseSchema(
     let fieldType;
 
     // Determine the field type and create the corresponding Zod type
+    // oxlint-disable-next-line switch-exhaustiveness-check
     switch (field.type) {
       case "number":
         fieldType = z.number();
@@ -77,6 +78,7 @@ export function parseSchema(
         }
 
         // Create an enum for the select values
+        // oxlint-disable-next-line no-unsafe-type-assertion
         const values = z.enum(field.values as [string, ...Array<string>]);
 
         // Parse the field type based on the number of values it can have

package/src/schema/read-local-schema.ts

@@ -1,6 +1,7 @@
 import fs from "fs/promises";
 import path from "path";
 import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
+import { pocketBaseDatabase } from "../types/pocketbase-schema.type";
 
 /**
  * Reads the local PocketBase schema file and returns the schema for the specified collection.
@@ -17,15 +18,15 @@ export async function readLocalSchema(
   try {
     // Read the schema file
     const schemaFile = await fs.readFile(realPath, "utf-8");
-    const database: Array<PocketBaseCollection> = JSON.parse(schemaFile);
+    const fileContent = pocketBaseDatabase.safeParse(JSON.parse(schemaFile));
 
     // Check if the database file is valid
-    if (!database || !Array.isArray(database)) {
+    if (!fileContent.success) {
       throw new Error("Invalid schema file");
     }
 
     // Find and return the schema for the collection
-    const schema = database.find(
+    const schema = fileContent.data.find(
       (collection) => collection.name === collectionName
     );
 

package/src/schema/transform-files.ts

@@ -1,3 +1,4 @@
+import { z } from "astro/zod";
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
 import type { PocketBaseSchemaEntry } from "../types/pocketbase-schema.type";
 
@@ -18,7 +19,7 @@ export function transformFiles(
     const fieldName = field.name;
 
     if (field.maxSelect === 1) {
-      const fileName = entry[fieldName] as string | undefined;
+      const fileName = z.optional(z.string()).parse(entry[fieldName]);
       // Check if a file name is present
       if (!fileName) {
         continue;
@@ -32,7 +33,7 @@ export function transformFiles(
         fileName
       );
     } else {
-      const fileNames = entry[fieldName] as Array<string> | undefined;
+      const fileNames = z.optional(z.array(z.string())).parse(entry[fieldName]);
       // Check if file names are present
       if (!fileNames) {
         continue;

package/src/types/pocketbase-api-response.type.ts

@@ -0,0 +1,40 @@
+import { z } from "astro/zod";
+import { pocketBaseEntry } from "./pocketbase-entry.type";
+
+/**
+ * The schema for a PocketBase error response.
+ */
+export const pocketBaseErrorResponse = z.object({
+  /**
+   * The error message returned by PocketBase.
+   */
+  message: z.string()
+});
+
+/**
+ * The schema for a PocketBase list response.
+ */
+export const pocketBaseListResponse = z.object({
+  /**
+   * Current page number.
+   */
+  page: z.number(),
+  /**
+   * Total number of pages available.
+   */
+  totalPages: z.number(),
+  /**
+   * Array of items in the current page.
+   */
+  items: z.array(pocketBaseEntry)
+});
+
+/**
+ * The schema for a PocketBase login response.
+ */
+export const pocketBaseLoginResponse = z.object({
+  /**
+   * The authentication token returned by PocketBase.
+   */
+  token: z.string()
+});

package/src/types/pocketbase-entry.type.ts

@@ -1,22 +1,34 @@
+import { z } from "astro/zod";
+
 /**
- * Base interface for all PocketBase entries.
+ * Base schema for all PocketBase entries.
  */
-interface PocketBaseBaseEntry {
+export const pocketBaseBaseEntry = z.object({
   /**
    * ID of the entry.
    */
-  id: string;
+  id: z.string(),
   /**
    * ID of the collection the entry belongs to.
    */
-  collectionId: string;
+  collectionId: z.string(),
   /**
    * Name of the collection the entry belongs to.
    */
-  collectionName: string;
-}
+  collectionName: z.string()
+});
+
+/**
+ * Base interface for all PocketBase entries.
+ */
+export type PocketBaseBaseEntry = z.infer<typeof pocketBaseBaseEntry>;
+
+/**
+ * Schema for a PocketBase entry.
+ */
+export const pocketBaseEntry = pocketBaseBaseEntry.passthrough();
 
 /**
  * Type for a PocketBase entry.
  */
-export type PocketBaseEntry = PocketBaseBaseEntry & Record<string, unknown>;
+export type PocketBaseEntry = z.infer<typeof pocketBaseEntry>;

package/src/types/pocketbase-schema.type.ts

@@ -1,60 +1,92 @@
+import { z } from "astro/zod";
+
 /**
  * Entry for a collections schema in PocketBase.
  */
-export interface PocketBaseSchemaEntry {
+export const pocketBaseSchemaEntry = z.object({
   /**
    * Flag to indicate if the field is hidden.
    * Hidden fields are not returned in the API response.
    */
-  hidden: boolean;
+  hidden: z.optional(z.boolean()),
   /**
    * Name of the field.
    */
-  name: string;
+  name: z.string(),
   /**
    * Type of the field.
    */
-  type: string;
+  type: z.enum([
+    "text",
+    "editor",
+    "number",
+    "bool",
+    "email",
+    "url",
+    "date",
+    "autodate",
+    "select",
+    "file",
+    "relation",
+    "json",
+    "geoPoint",
+    "password"
+  ]),
   /**
    * Whether the field is required.
    */
-  required: boolean;
+  required: z.optional(z.boolean()),
   /**
    * Values for a select field.
    * This is only present if the field type is "select".
    */
-  values?: Array<string>;
+  values: z.optional(z.array(z.string())),
   /**
    * Maximum number of values for a select field.
    * This is only present on "select", "relation", and "file" fields.
    */
-  maxSelect?: number;
+  maxSelect: z.optional(z.number()),
   /**
    * Whether the field is filled when the entry is created.
    * This is only present on "autodate" fields.
    */
-  onCreate?: boolean;
+  onCreate: z.optional(z.boolean()),
   /**
    * Whether the field is updated when the entry is updated.
    * This is only present on "autodate" fields.
    */
-  onUpdate?: boolean;
-}
+  onUpdate: z.optional(z.boolean())
+});
+
+/**
+ * Entry for a collections schema in PocketBase.
+ */
+export type PocketBaseSchemaEntry = z.infer<typeof pocketBaseSchemaEntry>;
 
 /**
  * Schema for a PocketBase collection.
  */
-export interface PocketBaseCollection {
+export const pocketBaseCollection = z.object({
   /**
    * Name of the collection.
    */
-  name: string;
+  name: z.string(),
   /**
    * Type of the collection.
    */
-  type: "base" | "view" | "auth";
+  type: z.enum(["base", "view", "auth"]),
   /**
    * Schema of the collection.
    */
-  fields: Array<PocketBaseSchemaEntry>;
-}
+  fields: z.array(pocketBaseSchemaEntry)
+});
+
+/**
+ * Type for a PocketBase collection.
+ */
+export type PocketBaseCollection = z.infer<typeof pocketBaseCollection>;
+
+/**
+ * Schema for an entire PocketBase database.
+ */
+export const pocketBaseDatabase = z.array(pocketBaseCollection);

package/src/utils/get-superuser-token.ts

@@ -1,4 +1,8 @@
 import type { AstroIntegrationLogger } from "astro";
+import {
+  pocketBaseErrorResponse,
+  pocketBaseLoginResponse
+} from "../types/pocketbase-api-response.type";
 
 /**
  * This function will get a superuser token from the given PocketBase instance.
@@ -35,8 +39,27 @@ export async function getSuperuserToken(
 
   // If the login request was not successful, print the error message and return undefined
   if (!loginRequest.ok) {
-    const reason = await loginRequest.json().then((data) => data.message);
-    const errorMessage = `The given email / password for ${url} was not correct. Astro can't generate type definitions automatically and may not have access to all resources.\nReason: ${reason}`;
+    if (loginRequest.status === 429) {
+      const info =
+        "A rate limit was hit while trying to authenticate with PocketBase. Consider using an `impersonateToken` as credentials to avoid this issue.";
+      if (logger) {
+        logger.info(info);
+      } else {
+        console.info(info);
+      }
+
+      // Random wait between 3 (default rate limit interval) and 8 seconds
+      const retryAfter = Math.random() * 5 + 3;
+      // oxlint-disable-next-line promise/avoid-new
+      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
+
+      return getSuperuserToken(url, superuserCredentials, logger);
+    }
+
+    const errorResponse = pocketBaseErrorResponse.parse(
+      await loginRequest.json()
+    );
+    const errorMessage = `The given email / password for ${url} was not correct. Astro can't generate type definitions automatically and may not have access to all resources.\nReason: ${errorResponse.message}`;
     if (logger) {
       logger.error(errorMessage);
     } else {
@@ -46,5 +69,6 @@ export async function getSuperuserToken(
   }
 
   // Return the token
-  return await loginRequest.json().then((data) => data.token);
+  const response = pocketBaseLoginResponse.parse(await loginRequest.json());
+  return response.token;
 }