feat(expand): Enables the use of Pocketbases 'Expand' property

src/loader/load-entries.ts

@@ -66,6 +66,11 @@ export async function loadEntries(
       searchParams.set("filter", filters.join("&&"));
     }
 
+    // Add filters to search parameters
+    if (options.expand) {
+      searchParams.set("expand", options.expand.join(","));
+    }
+
     // Fetch entries from the collection
     const collectionRequest = await fetch(
       `${collectionUrl}?${searchParams.toString()}`,

src/schema/generate-schema.ts

@@ -1,7 +1,10 @@
-import type { ZodSchema } from "astro/zod";
+import type { ZodObject, ZodSchema } from "astro/zod";
 import { z } from "astro/zod";
+import type {
+  ExpandedFields,
+  PocketBaseCollection
+} from "../types/pocketbase-collection.type";
 import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
-import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
 import { getRemoteSchema } from "./get-remote-schema";
 import { parseSchema } from "./parse-schema";
 import { readLocalSchema } from "./read-local-schema";
@@ -33,6 +36,7 @@ export async function generateSchema(
   options: PocketBaseLoaderOptions
 ): Promise<ZodSchema> {
   let collection: PocketBaseCollection | undefined;
+  const expandedFields: ExpandedFields = {};
 
   // Try to get the schema directly from the PocketBase instance
   collection = await getRemoteSchema(options);
@@ -129,10 +133,52 @@ export async function generateSchema(
     }
   }
 
-  // Combine the basic schema with the parsed fields
+  if (options.expand && options.expand.length > 0) {
+    for (const expandedFieldName of options.expand) {
+      const [currentLevelFieldName, ...deeperExpandFields] =
+        getCurrentLevelExpandedFieldName(expandedFieldName);
+
+      const expandedFieldDefinition = collection.fields.find(
+        (field) => field.name === currentLevelFieldName
+      );
+
+      if (!expandedFieldDefinition) {
+        throw new Error(
+          `The provided field in the expand property "${expandedFieldName}" is not present in the schema of the collection "${options.collectionName}".\nThis will lead to use unable to provide a definition for this field.`
+        );
+      }
+
+      if (!expandedFieldDefinition.collectionId) {
+        throw new Error(
+          `The provided field in the expand property "${expandedFieldName}" does not have an associated collection linked to it, we need this in order to know the shape of the related schema.`
+        );
+      }
+
+      const expandedSchema = await generateSchema({
+        collectionName: expandedFieldDefinition.collectionId,
+        superuserCredentials: options.superuserCredentials,
+        expand: deeperExpandFields.length ? deeperExpandFields : undefined,
+        localSchema: options.localSchema,
+        jsonSchemas: options.jsonSchemas,
+        improveTypes: options.improveTypes,
+        url: options.url
+      });
+
+      expandedFields[expandedFieldName] = z.union([
+        expandedSchema,
+        z.array(expandedSchema)
+      ]);
+    }
+  }
+
+  const expandSchema = {
+    expand: buildExpandSchema(expandedFields).optional()
+  };
+
   const schema = z.object({
     ...BASIC_SCHEMA,
-    ...fields
+    ...fields,
+    ...expandSchema
   });
 
   // Get all file fields
@@ -146,7 +192,44 @@ export async function generateSchema(
   }
 
   // Transform file names to file urls
-  return schema.transform((entry) =>
-    transformFiles(options.url, fileFields, entry)
-  );
+  return schema.transform((entry) => {
+    if (Array.isArray(entry)) {
+      return entry.map((e) => transformFiles(options.url, fileFields, e));
+    }
+
+    return transformFiles(options.url, fileFields, entry);
+  });
+}
+
+/**
+ * Builds a Zod object schema from expandedFields, where each property is either a ZodSchema or an array of ZodSchema.
+ */
+export function buildExpandSchema(
+  expandedFields: ExpandedFields
+): ZodObject<Record<string, ZodSchema | z.ZodArray<ZodSchema>>> {
+  const shape: Record<string, ZodSchema | z.ZodArray<ZodSchema>> = {};
+
+  for (const key in expandedFields) {
+    const value = expandedFields[key];
+    if (Array.isArray(value)) {
+      // If it's an array, wrap the first element as a ZodArray (assuming all elements are the same schema)
+      shape[key] = z.array(value[0]);
+    } else {
+      shape[key] = value;
+    }
+  }
+
+  return z.object(shape);
+}
+
+function getCurrentLevelExpandedFieldName(s: string): Array<string> {
+  const fields = s.split(".");
+
+  if (fields.length >= 7) {
+    throw new Error(
+      `Expand value ${s} exceeds 6 levels of depth that Pocketbase allows`
+    );
+  }
+
+  return fields;
 }

src/schema/parse-schema.ts

@@ -1,8 +1,6 @@
 import { z } from "astro/zod";
-import type {
-  PocketBaseCollection,
-  PocketBaseSchemaEntry
-} from "../types/pocketbase-schema.type";
+import type { PocketBaseCollection } from "../types/pocketbase-collection.type";
+import type { PocketBaseSchemaEntry } from "../types/pocketbase-schema.type";
 
 export function parseSchema(
   collection: PocketBaseCollection,

src/schema/read-local-schema.ts

@@ -1,6 +1,6 @@
 import fs from "fs/promises";
 import path from "path";
-import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
+import type { PocketBaseCollection } from "../types/pocketbase-collection.type";
 
 /**
  * Reads the local PocketBase schema file and returns the schema for the specified collection.

src/types/pocketbase-collection.type.ts

@@ -0,0 +1,32 @@
+import type { ZodSchema } from "astro/zod";
+import type { PocketBaseSchemaEntry } from "./pocketbase-schema.type";
+
+/**
+ * Base interface for all PocketBase entries.
+ */
+interface PocketBaseBaseCollection {
+  /**
+   * ID of the collection.
+   */
+  id: string;
+  /**
+   * Name of the collection
+   */
+  name: string;
+  /**
+   * Type of the collection.
+   */
+  type: "base" | "view" | "auth";
+  /**
+   * Schema of the collection.
+   */
+  fields: Array<PocketBaseSchemaEntry>;
+}
+
+/**
+ * Type for a PocketBase entry.
+ */
+export type PocketBaseCollection = PocketBaseBaseCollection &
+  Record<string, unknown>;
+
+export type ExpandedFields = Record<string, ZodSchema | Array<ZodSchema>>;

src/types/pocketbase-entry.type.ts

@@ -14,6 +14,10 @@ interface PocketBaseBaseEntry {
    * Name of the collection the entry belongs to.
    */
   collectionName: string;
+  /**
+   * Optional property that contains all relational fields that have been expanded to contain their linked entry(s)
+   */
+  expand?: Record<string, PocketBaseEntry>;
 }
 
 /**

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

@@ -54,6 +54,19 @@ export interface PocketBaseLoaderOptions {
    * ```
    */
   filter?: string;
+  /**
+   * array of relational field names to auto expand when loading data from PocketBase.
+   * Valid syntax can be found in the [PocketBase documentation](https://pocketbase.io/docs/api-records/#listsearch-records)
+   * Example:
+   * ```ts
+   * // config:
+   * expand: ['relatedField1', 'relatedField2']
+   *
+   * // request
+   * `?expand=relatedField1,relatedField2`
+   * ```
+   */
+  expand?: Array<string>;
   /**
    * Credentials of a superuser to get full access to the PocketBase instance.
    * This is required to get automatic type generation without a local schema, to access all resources even if they are not public and to fetch content of hidden fields.

src/types/pocketbase-schema.type.ts

@@ -39,22 +39,10 @@ export interface PocketBaseSchemaEntry {
    * This is only present on "autodate" fields.
    */
   onUpdate?: boolean;
-}
 
-/**
- * Schema for a PocketBase collection.
- */
-export interface PocketBaseCollection {
-  /**
-   * Name of the collection.
-   */
-  name: string;
-  /**
-   * Type of the collection.
-   */
-  type: "base" | "view" | "auth";
   /**
-   * Schema of the collection.
+   * The associated collection id that the relation field is referencing
+   * This is only present on "relation" fields.
    */
-  fields: Array<PocketBaseSchemaEntry>;
+  collectionId?: string;
 }

test/_mocks/insert-collection.ts

@@ -1,11 +1,12 @@
 import { assert } from "console";
+import type { PocketBaseCollection } from "../../src/types/pocketbase-collection.type";
 import type { PocketBaseLoaderOptions } from "../../src/types/pocketbase-loader-options.type";
 
 export async function insertCollection(
   fields: Array<Record<string, unknown>>,
   options: PocketBaseLoaderOptions,
   superuserToken: string
-): Promise<void> {
+): Promise<PocketBaseCollection> {
   const insertRequest = await fetch(new URL(`api/collections`, options.url), {
     method: "POST",
     headers: {
@@ -19,4 +20,9 @@ export async function insertCollection(
   });
 
   assert(insertRequest.status === 200, "Collection is not available.");
+
+  const collection = await insertRequest.json();
+  assert(collection.id, "Collection ID is not available.");
+
+  return collection;
 }

test/loader/load-entries.e2e-spec.ts

@@ -8,17 +8,19 @@ import {
   describe,
   expect,
   test,
-  vi
+  vi,
+  type Mock
 } from "vitest";
 import { loadEntries } from "../../src/loader/load-entries";
 import { parseEntry } from "../../src/loader/parse-entry";
+import type { PocketBaseEntry } from "../../src/types/pocketbase-entry.type";
 import { getSuperuserToken } from "../../src/utils/get-superuser-token";
 import { checkE2eConnection } from "../_mocks/check-e2e-connection";
 import { createLoaderContext } from "../_mocks/create-loader-context";
 import { createLoaderOptions } from "../_mocks/create-loader-options";
 import { deleteCollection } from "../_mocks/delete-collection";
 import { insertCollection } from "../_mocks/insert-collection";
-import { insertEntries } from "../_mocks/insert-entry";
+import { insertEntries, insertEntry } from "../_mocks/insert-entry";
 
 vi.mock("../../src/loader/parse-entry");
 
@@ -119,6 +121,78 @@ describe("loadEntries", () => {
     await deleteCollection(testOptions, superuserToken);
   });
 
+  test("should expand related fields in pages", async () => {
+    const RELATION_FIELD_NAME = "related";
+    const BLUE_ENTRY_NAME_FIELD_VALUE = "blue entry";
+
+    const redCollectionOptions = {
+      ...options,
+      collectionName: `red_${randomUUID().replace(/-/g, "")}`
+    };
+
+    const blueCollectionOptions = {
+      ...options,
+      collectionName: `blue_${randomUUID().replace(/-/g, "")}`
+    };
+
+    const testOptions = {
+      ...options,
+      collectionName: redCollectionOptions.collectionName,
+      expand: [RELATION_FIELD_NAME]
+    };
+
+    const blueCollection = await insertCollection(
+      [
+        {
+          name: "name",
+          type: "text"
+        }
+      ],
+      blueCollectionOptions,
+      superuserToken
+    );
+
+    await insertCollection(
+      [
+        {
+          name: RELATION_FIELD_NAME,
+          type: "relation",
+          collectionId: blueCollection.id
+        }
+      ],
+      redCollectionOptions,
+      superuserToken
+    );
+
+    const parsedEntries: Array<PocketBaseEntry> = [];
+
+    const blueEntry = await insertEntry(
+      { name: BLUE_ENTRY_NAME_FIELD_VALUE },
+      blueCollectionOptions,
+      superuserToken
+    );
+
+    await insertEntry(
+      { [RELATION_FIELD_NAME]: blueEntry.id },
+      redCollectionOptions,
+      superuserToken
+    );
+
+    (parseEntry as Mock).mockImplementation((entry: PocketBaseEntry) => {
+      parsedEntries.push(entry);
+      return entry; // or whatever parseEntry should return
+    });
+
+    await loadEntries(testOptions, context, superuserToken, undefined);
+
+    expect(parsedEntries[0]?.expand?.related.name).toBe(
+      BLUE_ENTRY_NAME_FIELD_VALUE
+    );
+
+    await deleteCollection(redCollectionOptions, superuserToken);
+    await deleteCollection(blueCollectionOptions, superuserToken);
+  });
+
   describe("incremental updates", () => {
     test("should fetch all entries when updatedField is missing", async () => {
       const lastModified = new Date(Date.now() - DAY).toISOString();