astro-loader-pocketbase 0.2.2 → 0.3.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-loader-pocketbase",
-  "version": "0.2.2",
+  "version": "0.3.0-rc.2",
   "description": "A content loader for Astro that uses the PocketBase API",
   "license": "MIT",
   "author": "Luis Wolf <development@pawcode.de> (https://pawcode.de)",

package/src/generate-schema.ts

@@ -1,10 +1,11 @@
 import type { ZodSchema } from "astro/zod";
 import { z } from "astro/zod";
 import type { PocketBaseLoaderOptions } from "./types/pocketbase-loader-options.type";
-import type { PocketBaseSchemaEntry } from "./types/pocketbase-schema.type";
+import type { PocketBaseCollection } from "./types/pocketbase-schema.type";
 import { getRemoteSchema } from "./utils/get-remote-schema";
 import { parseSchema } from "./utils/parse-schema";
 import { readLocalSchema } from "./utils/read-local-schema";
+import { transformFiles } from "./utils/transform-files";
 
 /**
  * Basic schema for every PocketBase collection.
@@ -13,39 +14,56 @@ const BASIC_SCHEMA = {
   id: z.string().length(15),
   collectionId: z.string().length(15),
   collectionName: z.string(),
-  created: z.date({ coerce: true }),
-  updated: z.date({ coerce: true })
+  created: z.coerce.date(),
+  updated: z.coerce.date()
+};
+
+/**
+ * Basic schema for a view in PocketBase.
+ */
+const VIEW_SCHEMA = {
+  id: z.string(),
+  collectionId: z.string().length(15),
+  collectionName: z.string(),
+  created: z.preprocess((val) => val || undefined, z.optional(z.coerce.date())),
+  updated: z.preprocess((val) => val || undefined, z.optional(z.coerce.date()))
 };
 
 /**
  * Generate a schema for the collection based on the collection's schema in PocketBase.
- * If no login credentials are provided, a {@link BASIC_SCHEMA} for every PocketBase collection is returned.
+ * By default, a basic schema is returned if no other schema is available.
+ * If admin credentials are provided, the schema is fetched from the PocketBase API.
+ * If a path to a local schema file is provided, the schema is read from the file.
  *
  * @param options Options for the loader. See {@link PocketBaseLoaderOptions} for more details.
  */
 export async function generateSchema(
   options: PocketBaseLoaderOptions
 ): Promise<ZodSchema> {
-  let schema: Array<PocketBaseSchemaEntry> | undefined;
+  let collection: PocketBaseCollection | undefined;
 
   // Try to get the schema directly from the PocketBase instance
-  schema = await getRemoteSchema(options);
+  collection = await getRemoteSchema(options);
 
   // If the schema is not available, try to read it from a local schema file
-  if (!schema && options.localSchema) {
-    schema = await readLocalSchema(options.localSchema, options.collectionName);
+  if (!collection && options.localSchema) {
+    collection = await readLocalSchema(
+      options.localSchema,
+      options.collectionName
+    );
   }
 
   // If the schema is still not available, return the basic schema
-  if (!schema) {
+  if (!collection) {
     console.error(
       `No schema available for ${options.collectionName}. Only basic types are available. Please check your configuration and provide a valid schema file or admin credentials.`
     );
-    return z.object(BASIC_SCHEMA);
+    // Return the view schema since every collection has at least the view schema
+    return z.object(VIEW_SCHEMA);
   }
 
   // Parse the schema
-  const fields = parseSchema(schema);
+  const fields = parseSchema(collection);
 
   // Check if the content field is present
   if (typeof options.content === "string" && !fields[options.content]) {
@@ -62,9 +80,26 @@ export async function generateSchema(
     }
   }
 
+  // Use the corresponding base schema for the type of collection
+  // Auth collections are basically a superset of the basic schema.
+  const base = collection.type === "view" ? VIEW_SCHEMA : BASIC_SCHEMA;
+
   // Combine the basic schema with the parsed fields
-  return z.object({
-    ...BASIC_SCHEMA,
+  const schema = z.object({
+    ...base,
     ...fields
   });
+
+  // Get all file fields
+  const fileFields = collection.schema.filter((field) => field.type === "file");
+
+  if (fileFields.length === 0) {
+    return schema;
+  }
+
+  // Transform file names to file urls
+  return schema.transform((entry) =>
+    // @ts-expect-error - `updated` and `created` are already transformed to dates
+    transformFiles(options.url, fileFields, entry)
+  );
 }

package/src/load-entries.ts

@@ -9,13 +9,15 @@ import { parseEntry } from "./utils/parse-entry";
  * @param context Context of the loader.
  * @param adminToken Admin token to access all resources.
  * @param lastModified Date of the last fetch to only update changed entries.
+ *
+ * @returns `true` if the collection has an updated column, `false` otherwise.
  */
 export async function loadEntries(
   options: PocketBaseLoaderOptions,
   context: LoaderContext,
   adminToken: string | undefined,
   lastModified: string | undefined
-): Promise<void> {
+): Promise<boolean> {
   // Build the URL for the collections endpoint
   const collectionUrl = new URL(
     `api/collections/${options.collectionName}/records`,
@@ -41,14 +43,17 @@ export async function loadEntries(
   let page = 1;
   let totalPages = 0;
   let entries = 0;
+  let hasUpdatedColumn = !!lastModified;
 
   // Fetch all (modified) entries
   do {
     // Fetch entries from the collection
     // If `lastModified` is set, only fetch entries that have been modified since the last fetch
     const collectionRequest = await fetch(
-      `${collectionUrl}?page=${page}&perPage=100&sort=-updated,id${
-        lastModified ? `&filter=(updated>"${lastModified}")` : ""
+      `${collectionUrl}?page=${page}&perPage=100${
+        lastModified
+          ? `&sort=-updated,id&filter=(updated>"${lastModified}")`
+          : ""
       }`,
       {
         headers: collectionHeaders
@@ -59,10 +64,9 @@ export async function loadEntries(
     if (!collectionRequest.ok) {
       // If the collection is locked, an admin token is required
       if (collectionRequest.status === 403) {
-        context.logger.error(
+        throw new Error(
           `The collection ${options.collectionName} is not accessible without an admin rights. Please provide an admin email and password in the config.`
         );
-        return;
       }
 
       // Get the reason for the error
@@ -70,8 +74,7 @@ export async function loadEntries(
         .json()
         .then((data) => data.message);
       const errorMessage = `Fetching data from ${options.collectionName} failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
-      context.logger.error(errorMessage);
-      return;
+      throw new Error(errorMessage);
     }
 
     // Get the data from the response
@@ -80,6 +83,12 @@ export async function loadEntries(
     // Parse and store the entries
     for (const entry of response.items) {
       await parseEntry(entry, context, options.content);
+
+      // Check if the entry has an `updated` column
+      // This is used to enable the incremental fetching of entries
+      if (!hasUpdatedColumn && "updated" in entry) {
+        hasUpdatedColumn = true;
+      }
     }
 
     // Update the page and total pages
@@ -94,4 +103,7 @@ export async function loadEntries(
       context.collection
     }`
   );
+
+  // Return if the collection has an updated column
+  return hasUpdatedColumn;
 }

package/src/pocketbase-loader.ts

@@ -1,4 +1,5 @@
 import type { Loader, LoaderContext } from "astro/loaders";
+import packageJson from "./../package.json";
 import { cleanupEntries } from "./cleanup-entries";
 import { generateSchema } from "./generate-schema";
 import { loadEntries } from "./load-entries";
@@ -14,12 +15,25 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
   return {
     name: "pocketbase-loader",
     load: async (context: LoaderContext): Promise<void> => {
+      // Check if the version has changed to force an update
+      const lastVersion = context.meta.get("version");
+      if (lastVersion !== packageJson.version) {
+        context.logger.info(
+          `PocketBase loader was updated from ${lastVersion} to ${packageJson.version}. All entries will be loaded again.`
+        );
+
+        options.forceUpdate = true;
+      }
+
       // Get the date of the last fetch to only update changed entries.
       // If `forceUpdate` is set to `true`, this will be `undefined` to fetch all entries again.
       const lastModified = options.forceUpdate
         ? undefined
         : context.meta.get("last-modified");
 
+      // Get the `has-updated-column` meta to check if the collection has an updated column
+      let hasUpdatedColumn = context.meta.get("has-updated-column") === "true";
+
       // Clear the store if we want to fetch all entries again
       if (options.forceUpdate) {
         context.store.clear();
@@ -42,10 +56,30 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
       }
 
       // Load the (modified) entries
-      await loadEntries(options, context, token, lastModified);
+      try {
+        hasUpdatedColumn = await loadEntries(
+          options,
+          context,
+          token,
+          // Only fetch entries that have been modified since the last fetch
+          // If the collection does not have an updated column, all entries will be fetched
+          hasUpdatedColumn ? lastModified : undefined
+        );
+      } catch (error) {
+        // Set the `has-updated-column` meta to `false` if an error occurred
+        // This will force the loader to fetch all entries again in the next run
+        context.meta.set("has-updated-column", `${false}`);
+
+        throw error;
+      }
+
+      // Set the `has-updated-column` meta to `true` if the collection has an updated column
+      context.meta.set("has-updated-column", `${hasUpdatedColumn}`);
 
       // Set the last modified date to the current date
       context.meta.set("last-modified", new Date().toISOString());
+
+      context.meta.set("version", packageJson.version);
     },
     schema: async () => {
       // Generate the schema for the collection according to the API

package/src/types/{pocketbase-base.type.ts → pocketbase-entry.type.ts}

@@ -17,11 +17,11 @@ interface PocketBaseBaseEntry {
   /**
    * Date the entry was created.
    */
-  created: string;
+  created?: string | undefined;
   /**
    * Date the entry was last updated.
    */
-  updated: string;
+  updated?: string | undefined;
 }
 
 /**

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

@@ -19,7 +19,7 @@ export interface PocketBaseLoaderOptions {
    * The loader will concatenate the content of all fields in the order they are defined in the array.
    * Each block will be contained in a `<section>` element.
    */
-  content: string | Array<string>;
+  content?: string | Array<string>;
   /**
    * Email of an admin to get full access to the PocketBase instance.
    * Together with `adminPassword` this is required to get automatic type generation and to access all resources even if they are not public.

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

@@ -39,6 +39,10 @@ export interface PocketBaseCollection {
    * Name of the collection.
    */
   name: string;
+  /**
+   * Type of the collection.
+   */
+  type: 'base' | 'view' | 'auth';
   /**
    * Schema of the collection.
    */

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

@@ -1,8 +1,5 @@
 import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
-import type {
-  PocketBaseCollection,
-  PocketBaseSchemaEntry
-} from "../types/pocketbase-schema.type";
+import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
 import { getAdminToken } from "./get-admin-token";
 
 /**
@@ -12,7 +9,7 @@ import { getAdminToken } from "./get-admin-token";
  */
 export async function getRemoteSchema(
   options: PocketBaseLoaderOptions
-): Promise<Array<PocketBaseSchemaEntry> | undefined> {
+): Promise<PocketBaseCollection | undefined> {
   if (!options.adminEmail || !options.adminPassword) {
     return undefined;
   }
@@ -52,6 +49,5 @@ export async function getRemoteSchema(
   }
 
   // Get the schema from the response
-  const schema: PocketBaseCollection = await schemaRequest.json();
-  return schema.schema;
+  return await schemaRequest.json();
 }

package/src/utils/parse-entry.ts

@@ -1,5 +1,5 @@
 import type { LoaderContext } from "astro/loaders";
-import type { PocketBaseEntry } from "../types/pocketbase-base.type";
+import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
 
 /**
  * Parse an entry from PocketBase to match the schema and store it in the store.
@@ -12,7 +12,7 @@ import type { PocketBaseEntry } from "../types/pocketbase-base.type";
 export async function parseEntry(
   entry: PocketBaseEntry,
   { generateDigest, parseData, store }: LoaderContext,
-  contentFields: string | Array<string>
+  contentFields?: string | Array<string>
 ): Promise<void> {
   // Parse the data to match the schema
   // This will throw an error if the data does not match the schema
@@ -22,8 +22,20 @@ export async function parseEntry(
   });
 
   // Generate a digest for the entry
-  // We can use the updated data as an identifier if the entry has changed since PocketBase automatically updates this value on every change
-  const digest = generateDigest(entry.updated);
+  // Normal collections use the updated date that is always updated when the entry is updated.
+  // If the entry was never updated, the created date can be used as a fallback.
+  // View collections don't necessarily publish the updated date, so the whole entry is used for the digest.
+  const digest = generateDigest(entry.updated ?? entry.created ?? entry);
+
+  if (!contentFields) {
+    // Store the entry
+    store.set({
+      id: entry.id,
+      data,
+      digest
+    });
+    return;
+  }
 
   // Generate the content for the entry
   let content: string;

package/src/utils/parse-schema.ts

@@ -1,14 +1,17 @@
 import { z } from "astro/zod";
-import type { PocketBaseSchemaEntry } from "../types/pocketbase-schema.type";
+import type {
+  PocketBaseCollection,
+  PocketBaseSchemaEntry
+} from "../types/pocketbase-schema.type";
 
 export function parseSchema(
-  schema: Array<PocketBaseSchemaEntry>
+  collection: PocketBaseCollection
 ): Record<string, z.ZodType> {
   // Prepare the schemas fields
   const fields: Record<string, z.ZodType> = {};
 
   // Parse every field in the schema
-  for (const field of schema) {
+  for (const field of collection.schema) {
     let fieldType;
 
     // Determine the field type and create the corresponding Zod type
@@ -41,7 +44,8 @@ export function parseSchema(
         break;
       case "relation":
       case "file":
-        // NOTE: Relations and files are currently not supported and are treated as strings
+        // NOTE: Relations are currently not supported and are treated as strings
+        // NOTE: Files are later transformed to URLs
 
         // Parse the field type based on the number of values it can have
         fieldType = parseSingleOrMultipleValues(field, z.string());

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

@@ -1,9 +1,6 @@
 import fs from "fs/promises";
 import path from "path";
-import type {
-  PocketBaseCollection,
-  PocketBaseSchemaEntry
-} from "../types/pocketbase-schema.type";
+import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
 
 /**
  * Reads the local PocketBase schema file and returns the schema for the specified collection.
@@ -14,7 +11,7 @@ import type {
 export async function readLocalSchema(
   localSchemaPath: string,
   collectionName: string
-): Promise<Array<PocketBaseSchemaEntry> | undefined> {
+): Promise<PocketBaseCollection | undefined> {
   const realPath = path.join(process.cwd(), localSchemaPath);
 
   try {
@@ -38,7 +35,7 @@ export async function readLocalSchema(
       );
     }
 
-    return schema.schema;
+    return schema;
   } catch (error) {
     console.error(
       `Failed to read local schema from ${localSchemaPath}. No types will be generated.\nReason: ${error}`

package/src/utils/transform-files.ts

@@ -0,0 +1,66 @@
+import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
+import type { PocketBaseSchemaEntry } from "../types/pocketbase-schema.type";
+
+/**
+ * Transforms file names in a PocketBase entry to file URLs.
+ *
+ * @param baseUrl URL of the PocketBase instance.
+ * @param collection Collection of the entry.
+ * @param entry Entry to transform.
+ */
+export function transformFiles(
+  baseUrl: string,
+  fileFields: Array<PocketBaseSchemaEntry>,
+  entry: PocketBaseEntry
+): PocketBaseEntry {
+  // Transform all file names to file URLs
+  for (const field of fileFields) {
+    const fieldName = field.name;
+
+    if (field.options.maxSelect === 1) {
+      const fileName = entry[fieldName] as string | undefined;
+      // Check if a file name is present
+      if (!fileName) {
+        continue;
+      }
+
+      // Transform the file name to a file URL
+      entry[fieldName] = transformFileUrl(
+        baseUrl,
+        entry.collectionName,
+        entry.id,
+        fileName
+      );
+    } else {
+      const fileNames = entry[fieldName] as Array<string> | undefined;
+      // Check if file names are present
+      if (!fileNames) {
+        continue;
+      }
+
+      // Transform all file names to file URLs
+      entry[fieldName] = fileNames.map((file) =>
+        transformFileUrl(baseUrl, entry.collectionName, entry.id, file)
+      );
+    }
+  }
+
+  return entry;
+}
+
+/**
+ * Transforms a file name to a PocketBase file URL.
+ *
+ * @param base Base URL of the PocketBase instance.
+ * @param collectionName Name of the collection.
+ * @param entryId ID of the entry.
+ * @param file Name of the file.
+ */
+function transformFileUrl(
+  base: string,
+  collectionName: string,
+  entryId: string,
+  file: string
+): string {
+  return `${base}/api/files/${collectionName}/${entryId}/${file}`;
+}