feat(live-loader): add experimental expand parameter support

Co-authored-by: pawcoding <78467484+pawcoding@users.noreply.github.com>

Author: Copilot

src/loader/fetch-collection.ts

@@ -9,8 +9,12 @@ import {
 } 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";
+import type {
+  ExperimentalPocketBaseLiveLoaderOptions,
+  PocketBaseLoaderOptions
+} from "../types/pocketbase-loader-options.type";
 import { combineFieldsForRequest } from "../utils/combine-fields-for-request";
+import { formatExpand } from "../utils/format-expand";
 import { formatFields } from "../utils/format-fields";
 
 /**
@@ -28,7 +32,7 @@ export type CollectionFilter = {
  * Fetches entries from a PocketBase collection, optionally filtering by modification date and supporting pagination.
  */
 export async function fetchCollection<TEntry extends PocketBaseEntry>(
-  options: PocketBaseLoaderBaseOptions,
+  options: PocketBaseLoaderOptions | ExperimentalPocketBaseLiveLoaderOptions,
   chunkLoaded: (entries: Array<TEntry>) => Promise<void>,
   token: string | undefined,
   collectionFilter: CollectionFilter | undefined
@@ -124,7 +128,9 @@ export async function fetchCollection<TEntry extends PocketBaseEntry>(
  * Build search parameters for the PocketBase collection request.
  */
 function buildSearchParams(
-  loaderOptions: PocketBaseLoaderBaseOptions,
+  loaderOptions:
+    | PocketBaseLoaderOptions
+    | ExperimentalPocketBaseLiveLoaderOptions,
   combinedFields: Array<string> | undefined,
   collectionFilter: CollectionFilter
 ): URLSearchParams {
@@ -173,5 +179,15 @@ function buildSearchParams(
     searchParams.set("fields", combinedFields.join(","));
   }
 
+  if (loaderOptions.experimental && "expand" in loaderOptions.experimental) {
+    const expandString = formatExpand(
+      loaderOptions.experimental.expand,
+      loaderOptions.collectionName
+    );
+    if (expandString) {
+      searchParams.set("expand", expandString);
+    }
+  }
+
   return searchParams;
 }

src/loader/fetch-entry.ts

@@ -6,16 +6,20 @@ 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";
-import type { ExperimentalPocketBaseLiveLoaderOptions } from "../types/pocketbase-loader-options.type";
+import type {
+  ExperimentalPocketBaseLiveLoaderOptions,
+  PocketBaseLoaderOptions
+} from "../types/pocketbase-loader-options.type";
 import { combineFieldsForRequest } from "../utils/combine-fields-for-request";
+import { formatExpand } from "../utils/format-expand";
 import { formatFields } from "../utils/format-fields";
 
 /**
  * Retrieves a specific entry from a PocketBase collection using its ID and loader options.
  */
 export async function fetchEntry<TEntry extends PocketBaseEntry>(
   id: string,
-  options: ExperimentalPocketBaseLiveLoaderOptions,
+  options: PocketBaseLoaderOptions | ExperimentalPocketBaseLiveLoaderOptions,
   token: string | undefined
 ): Promise<TEntry> {
   // Build the URL for the entry endpoint
@@ -31,6 +35,17 @@ export async function fetchEntry<TEntry extends PocketBaseEntry>(
     entryUrl.searchParams.set("fields", combinedFields.join(","));
   }
 
+  // Add expand parameter if specified in experimental options
+  if (options.experimental && "expand" in options.experimental) {
+    const expandString = formatExpand(
+      options.experimental.expand,
+      options.collectionName
+    );
+    if (expandString) {
+      entryUrl.searchParams.set("expand", expandString);
+    }
+  }
+
   // Create the headers for the request to append the token (if available)
   const entryHeaders = new Headers();
   if (token) {

src/types/errors.ts

@@ -17,3 +17,21 @@ export class PocketBaseAuthenticationError extends LiveCollectionError {
     );
   }
 }
+
+/**
+ * Error thrown when there is a configuration issue with the loader.
+ */
+export class PocketBaseConfigurationError extends LiveCollectionError {
+  constructor(collection: string, message: string) {
+    super(collection, message);
+    this.name = "PocketBaseConfigurationError";
+  }
+
+  static is(error: unknown): error is PocketBaseConfigurationError {
+    // This is similar to the original implementation in Astro itself.
+    return (
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      !!error && (error as Error)?.name === "PocketBaseConfigurationError"
+    );
+  }
+}

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

@@ -156,4 +156,33 @@ export type PocketBaseLoaderOptions = PocketBaseLoaderBaseOptions & {
  * @experimental Live content collections are still experimental
  */
 export type ExperimentalPocketBaseLiveLoaderOptions =
-  PocketBaseLoaderBaseOptions;
+  PocketBaseLoaderBaseOptions & {
+    /**
+     * Experimental options for the live loader.
+     *
+     * @experimental All of these options are experimental and may change in the future.
+     */
+    experimental?: {
+      /**
+       * Specify relations to auto expand in the API response.
+       * This can be an array of relation field names to expand.
+       * Supports dot notation for nested relations up to 6 levels deep.
+       *
+       * Note: This option is not compatible with the `fields` option.
+       *
+       * Example:
+       * ```ts
+       * // Using array format:
+       * expand: ['author', 'category']
+       *
+       * // Nested relations:
+       * expand: ['author.profile', 'category.parent']
+       * ```
+       *
+       * @see {@link https://pocketbase.io/docs/collections/#expand-relation-fields PocketBase documentation} for valid syntax
+       *
+       * @experimental This feature is experimental and may change in the future
+       */
+      expand?: Array<string>;
+    };
+  };

src/utils/format-expand.ts

@@ -0,0 +1,41 @@
+import { PocketBaseConfigurationError } from "../types/errors";
+
+/**
+ * Maximum nesting depth for expand relations as enforced by PocketBase
+ */
+const MAX_EXPAND_DEPTH = 6;
+
+/**
+ * Format and validate expand option for PocketBase API requests.
+ * Validates nesting depth and returns formatted expand string.
+ */
+export function formatExpand(
+  expand: Array<string> | undefined,
+  collectionName: string
+): string | undefined {
+  if (!expand || expand.length === 0) {
+    return undefined;
+  }
+
+  // Validate each expand field for maximum nesting depth and invalid characters
+  for (const field of expand) {
+    // Check for comma in field name
+    if (field.includes(",")) {
+      throw new PocketBaseConfigurationError(
+        collectionName,
+        `Expand field "${field}" contains a comma. Use separate array entries instead of comma-separated values.`
+      );
+    }
+
+    const depth = (field.match(/\./g) || []).length + 1;
+    if (depth > MAX_EXPAND_DEPTH) {
+      throw new PocketBaseConfigurationError(
+        collectionName,
+        `Expand field "${field}" exceeds maximum nesting depth of ${MAX_EXPAND_DEPTH} levels.`
+      );
+    }
+  }
+
+  // Join all expand fields with comma as required by PocketBase
+  return expand.join(",");
+}

test/utils/format-expand.spec.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "vitest";
+import { PocketBaseConfigurationError } from "../../src/types/errors";
+import { formatExpand } from "../../src/utils/format-expand";
+
+describe("formatExpand", () => {
+  test("should return undefined when expand is undefined", () => {
+    const result = formatExpand(undefined, "");
+    expect(result).toBeUndefined();
+  });
+
+  test("should return undefined when expand is empty array", () => {
+    const result = formatExpand([], "");
+    expect(result).toBeUndefined();
+  });
+
+  test("should format single expand field", () => {
+    const result = formatExpand(["author"], "");
+    expect(result).toBe("author");
+  });
+
+  test("should format multiple expand fields with comma", () => {
+    const result = formatExpand(["author", "category"], "");
+    expect(result).toBe("author,category");
+  });
+
+  test("should handle nested expand fields", () => {
+    const result = formatExpand(["author.profile", "category.parent"], "");
+    expect(result).toBe("author.profile,category.parent");
+  });
+
+  test("should handle deeply nested expand fields up to 6 levels", () => {
+    const result = formatExpand(
+      ["level1.level2.level3.level4.level5.level6"],
+      ""
+    );
+    expect(result).toBe("level1.level2.level3.level4.level5.level6");
+  });
+
+  test("should throw error when expand exceeds 6 levels", () => {
+    expect(() =>
+      formatExpand(["level1.level2.level3.level4.level5.level6.level7"], "")
+    ).toThrow(PocketBaseConfigurationError);
+  });
+
+  test("should throw error when field contains comma", () => {
+    expect(() => formatExpand(["author,category"], "")).toThrow(
+      PocketBaseConfigurationError
+    );
+  });
+});