feat(files): transform file names to file urls

This commit adds built in support for files in PocketBase collections.
The loader now automatically transforms file names retured by the
PocketBase API to URLs where these files can be accessed.

While testing this change, I found another bug in the incremental
updates, where unchanged entries would not update the file URL with the
new values, due to the same digest value. This is why the loader now
forces a complete refresh when the version of this package is updated.

Author: pawcoding

src/generate-schema.ts

@@ -5,6 +5,7 @@ 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.
@@ -84,8 +85,21 @@ export async function generateSchema(
   const base = collection.type === "view" ? VIEW_SCHEMA : BASIC_SCHEMA;
 
   // Combine the basic schema with the parsed fields
-  return z.object({
+  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)
+  );
 }

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,6 +15,16 @@ 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
@@ -67,6 +78,8 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
 
       // 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

src/utils/parse-schema.ts

@@ -44,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());

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}`;
+}