astro-loader-pocketbase 2.8.0-next.3 → 2.8.0-next.5

package/README.md

@@ -130,6 +130,24 @@ This filter will be added to the PocketBase API request and will only fetch entr
 This is in addition to the built-in filtering of the loader, which handles the incremental builds using the `updated` field.
 For more information on how to use filters, check out the [PocketBase documentation](https://pocketbase.io/docs/api-records/#listsearch-records).
 
+### Partial data loading
+
+By default, the loader fetches all fields for each entry in your PocketBase collection.
+If you want to optimize data loading or restrict the fields available in your content collection, you can use the `fields` option.
+
+```ts
+const blog = defineCollection({
+  loader: pocketbaseLoader({
+    ...options,
+    fields: ["title", "summary", "coverImage"]
+  })
+});
+```
+
+This parameter will be added to the PocketBase API request and will only return these fields for each entry.
+Additional system fields like `id`, `collectionName` and `collectionId`, as well as any fields specified for `idField`, `updatedField` or `contentFields` will be added automatically.
+For further details on field selection, see the [PocketBase API documentation](https://pocketbase.io/docs/api-records/#listsearch-records).
+
 ## Type generation
 
 The loader can automatically generate types for your collection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-loader-pocketbase",
-  "version": "2.8.0-next.3",
+  "version": "2.8.0-next.5",
   "description": "A content loader for Astro that uses the PocketBase API",
   "keywords": [
     "astro",

package/src/loader/cleanup-entries.ts

@@ -1,5 +1,5 @@
 import type { LoaderContext } from "astro/loaders";
-import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
+import type { PocketBaseLoaderBaseOptions } from "../types/pocketbase-loader-options.type";
 
 /**
  * Cleanup entries that are no longer in the collection.
@@ -9,7 +9,7 @@ import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options
  * @param superuserToken Superuser token to access all resources.
  */
 export async function cleanupEntries(
-  options: PocketBaseLoaderOptions,
+  options: PocketBaseLoaderBaseOptions,
   context: LoaderContext,
   superuserToken: string | undefined
 ): Promise<void> {

package/src/loader/fetch-collection.ts

@@ -1,6 +1,8 @@
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
 import type { ExperimentalPocketBaseLiveLoaderCollectionFilter } from "../types/pocketbase-live-loader-filter.type";
-import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
+import type { PocketBaseLoaderBaseOptions } from "../types/pocketbase-loader-options.type";
+import { combineFieldsForRequest } from "../utils/combine-fields-for-request";
+import { formatFields } from "../utils/format-fields";
 
 /**
  * Provides utilities to fetch entries from a PocketBase collection, supporting filtering and pagination.
@@ -17,14 +19,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: Pick<
-    PocketBaseLoaderOptions,
-    | "collectionName"
-    | "url"
-    | "updatedField"
-    | "filter"
-    | "superuserCredentials"
-  >,
+  options: PocketBaseLoaderBaseOptions,
   chunkLoaded: (entries: Array<TEntry>) => Promise<void>,
   token: string | undefined,
   collectionFilter: CollectionFilter | undefined
@@ -33,7 +28,7 @@ export async function fetchCollection<TEntry extends PocketBaseEntry>(
   const collectionUrl = new URL(
     `api/collections/${options.collectionName}/records`,
     options.url
-  ).href;
+  );
 
   // Create the headers for the request to append the token (if available)
   const collectionHeaders = new Headers();
@@ -41,25 +36,29 @@ export async function fetchCollection<TEntry extends PocketBaseEntry>(
     collectionHeaders.set("Authorization", token);
   }
 
+  // Cache fields computation outside the loop
+  const fieldsArray = formatFields(options.fields);
+  const combinedFields = combineFieldsForRequest(fieldsArray, options);
+
   // Prepare pagination variables
   let page = 0;
   let totalPages = 0;
 
   // Fetch all (modified) entries
   do {
-    const searchParams = buildSearchParams(options, {
+    const searchParams = buildSearchParams(options, combinedFields, {
       ...collectionFilter,
       page: collectionFilter?.page ?? ++page,
       perPage: collectionFilter?.perPage ?? 100
     });
 
+    // Apply search parameters to URL
+    collectionUrl.search = searchParams.toString();
+
     // Fetch entries from the collection
-    const collectionRequest = await fetch(
-      `${collectionUrl}?${searchParams.toString()}`,
-      {
-        headers: collectionHeaders
-      }
-    );
+    const collectionRequest = await fetch(collectionUrl.href, {
+      headers: collectionHeaders
+    });
 
     // If the request was not successful, print the error message and return
     if (!collectionRequest.ok) {
@@ -101,10 +100,10 @@ export async function fetchCollection<TEntry extends PocketBaseEntry>(
  * Build search parameters for the PocketBase collection request.
  */
 function buildSearchParams(
-  loaderOptions: Pick<PocketBaseLoaderOptions, "updatedField" | "filter">,
+  loaderOptions: PocketBaseLoaderBaseOptions,
+  combinedFields: Array<string> | undefined,
   collectionFilter: CollectionFilter
 ): URLSearchParams {
-  // Build search parameters
   const searchParams = new URLSearchParams();
 
   if (collectionFilter.page) {
@@ -145,5 +144,10 @@ function buildSearchParams(
     searchParams.set("sort", collectionFilter.sort);
   }
 
+  // Add fields parameter if specified
+  if (combinedFields) {
+    searchParams.set("fields", combinedFields.join(","));
+  }
+
   return searchParams;
 }

package/src/loader/fetch-entry.ts

@@ -1,5 +1,7 @@
 import type { 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";
 
 /**
  * Retrieves a specific entry from a PocketBase collection using its ID and loader options.
@@ -13,7 +15,14 @@ export async function fetchEntry<TEntry extends PocketBaseEntry>(
   const entryUrl = new URL(
     `api/collections/${options.collectionName}/records/${id}`,
     options.url
-  ).href;
+  );
+
+  // Add fields parameter if specified
+  const fieldsArray = formatFields(options.fields);
+  const combinedFields = combineFieldsForRequest(fieldsArray, options);
+  if (combinedFields) {
+    entryUrl.searchParams.set("fields", combinedFields.join(","));
+  }
 
   // Create the headers for the request to append the token (if available)
   const entryHeaders = new Headers();
@@ -22,7 +31,7 @@ export async function fetchEntry<TEntry extends PocketBaseEntry>(
   }
 
   // Fetch the entry from the collection
-  const entryRequest = await fetch(entryUrl, {
+  const entryRequest = await fetch(entryUrl.href, {
     headers: entryHeaders
   });
 

package/src/schema/generate-schema.ts

@@ -2,6 +2,9 @@ import type { ZodSchema } from "astro/zod";
 import { z } from "astro/zod";
 import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
 import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
+import { combineFieldsForRequest } from "../utils/combine-fields-for-request";
+import { extractFieldNames } from "../utils/extract-field-names";
+import { formatFields } from "../utils/format-fields";
 import { getRemoteSchema } from "./get-remote-schema";
 import { parseSchema } from "./parse-schema";
 import { readLocalSchema } from "./read-local-schema";
@@ -60,41 +63,87 @@ export async function generateSchema(
     return z.object(BASIC_SCHEMA);
   }
 
-  // Parse the schema
-  const fields = parseSchema(
-    collection,
-    options.jsonSchemas,
+  // Get fields to include from options
+  const formattedFields = formatFields(options.fields);
+  const fieldNames = extractFieldNames(formattedFields);
+  const fieldsToInclude = combineFieldsForRequest(fieldNames, options);
+
+  // Parse the schema with optional field filtering
+  const fields = parseSchema(collection, options.jsonSchemas, {
     hasSuperuserRights,
-    options.improveTypes ?? false,
-    options.experimental?.liveTypesOnly ?? false
+    improveTypes: options.improveTypes,
+    fieldsToInclude,
+    experimentalLiveTypesOnly: options.experimental?.liveTypesOnly
+  });
+
+  // Do some sanity checks on the provided options
+  checkCustomIdField(collection, options);
+  checkContentField(fields, options);
+  checkUpdatedField(fields, collection, options);
+
+  // Combine the basic schema with the parsed fields
+  const schema = z.object({
+    ...BASIC_SCHEMA,
+    ...fields
+  });
+
+  // Get all file fields
+  const fileFields = collection.fields
+    .filter((field) => field.type === "file")
+    // Only show hidden fields if the user has superuser rights
+    .filter((field) => !field.hidden || hasSuperuserRights);
+
+  if (fileFields.length === 0) {
+    return schema;
+  }
+
+  // Transform file names to file urls
+  return schema.transform((entry) =>
+    transformFiles(options.url, fileFields, entry)
   );
+}
 
-  // Check if custom id field is present
-  if (options.idField) {
-    // Find the id field in the schema
-    const idField = collection.fields.find(
-      (field) => field.name === options.idField
-    );
+/**
+ * Check if the custom id field is present
+ */
+function checkCustomIdField(
+  collection: PocketBaseCollection,
+  options: PocketBaseLoaderOptions
+): void {
+  if (!options.idField) {
+    return;
+  }
 
-    // Check if the id field is present and of a valid type
-    if (!idField) {
-      console.error(
-        `The id field "${options.idField}" is not present in the schema of the collection "${options.collectionName}".`
-      );
-    } else if (!VALID_ID_TYPES.includes(idField.type)) {
-      console.error(
-        `The id field "${options.idField}" for collection "${
-          options.collectionName
-        }" is of type "${
-          idField.type
-        }" which is not recommended. Please use one of the following types: ${VALID_ID_TYPES.join(
-          ", "
-        )}.`
-      );
-    }
+  // Find the id field in the schema
+  const idField = collection.fields.find(
+    (field) => field.name === options.idField
+  );
+
+  // Check if the id field is present and of a valid type
+  if (!idField) {
+    console.error(
+      `The id field "${options.idField}" is not present in the schema of the collection "${options.collectionName}".`
+    );
+  } else if (!VALID_ID_TYPES.includes(idField.type)) {
+    console.error(
+      `The id field "${options.idField}" for collection "${
+        options.collectionName
+      }" is of type "${
+        idField.type
+      }" which is not recommended. Please use one of the following types: ${VALID_ID_TYPES.join(
+        ", "
+      )}.`
+    );
   }
+}
 
-  // Check if the content field is present
+/**
+ * Check if the content field(s) are present
+ */
+function checkContentField(
+  fields: Record<string, z.ZodType>,
+  options: PocketBaseLoaderOptions
+): void {
   if (
     typeof options.contentFields === "string" &&
     !fields[options.contentFields]
@@ -111,47 +160,36 @@ export async function generateSchema(
       }
     }
   }
+}
 
-  // Check if the updated field is present
-  if (options.updatedField) {
-    if (!fields[options.updatedField]) {
-      console.error(
-        `The field "${options.updatedField}" is not present in the schema of the collection "${options.collectionName}".\nThis will lead to errors when trying to fetch only updated entries.`
-      );
-    } else {
-      const updatedField = collection.fields.find(
-        (field) => field.name === options.updatedField
-      );
-      if (
-        !updatedField ||
-        updatedField.type !== "autodate" ||
-        !updatedField.onUpdate
-      ) {
-        console.warn(
-          `The field "${options.updatedField}" is not of type "autodate" with the value "Update" or "Create/Update".\nMake sure that the field is automatically updated when the entry is updated!`
-        );
-      }
-    }
+/**
+ * Check if the updated field is present
+ */
+function checkUpdatedField(
+  fields: Record<string, z.ZodType>,
+  collection: PocketBaseCollection,
+  options: PocketBaseLoaderOptions
+): void {
+  if (!options.updatedField) {
+    return;
   }
 
-  // Combine the basic schema with the parsed fields
-  const schema = z.object({
-    ...BASIC_SCHEMA,
-    ...fields
-  });
-
-  // Get all file fields
-  const fileFields = collection.fields
-    .filter((field) => field.type === "file")
-    // Only show hidden fields if the user has superuser rights
-    .filter((field) => !field.hidden || hasSuperuserRights);
-
-  if (fileFields.length === 0) {
-    return schema;
+  if (!fields[options.updatedField]) {
+    console.error(
+      `The field "${options.updatedField}" is not present in the schema of the collection "${options.collectionName}".\nThis will lead to errors when trying to fetch only updated entries.`
+    );
+  } else {
+    const updatedField = collection.fields.find(
+      (field) => field.name === options.updatedField
+    );
+    if (
+      !updatedField ||
+      updatedField.type !== "autodate" ||
+      !updatedField.onUpdate
+    ) {
+      console.warn(
+        `The field "${options.updatedField}" is not of type "autodate" with the value "Update" or "Create/Update".\nMake sure that the field is automatically updated when the entry is updated!`
+      );
+    }
   }
-
-  // Transform file names to file urls
-  return schema.transform((entry) =>
-    transformFiles(options.url, fileFields, entry)
-  );
 }

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

@@ -8,7 +8,7 @@ import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
  * @param token The superuser token to authenticate the request.
  */
 export async function getRemoteSchema(
-  options: PocketBaseLoaderOptions,
+  options: Pick<PocketBaseLoaderOptions, "collectionName" | "url">,
   token: string
 ): Promise<PocketBaseCollection | undefined> {
   // Build URL and headers for the schema request

package/src/schema/parse-schema.ts

@@ -4,23 +4,42 @@ import type {
   PocketBaseSchemaEntry
 } from "../types/pocketbase-schema.type";
 
+export interface ParseSchemaOptions {
+  hasSuperuserRights: boolean;
+  improveTypes?: boolean;
+  fieldsToInclude?: Array<string>;
+  experimentalLiveTypesOnly?: boolean;
+}
+
 /**
  * Converts PocketBase collection fields into Zod types, handling field types, required status, and custom schemas.
  */
 export function parseSchema(
   collection: PocketBaseCollection,
   customSchemas: Record<string, z.ZodType> | undefined,
-  hasSuperuserRights: boolean,
-  improveTypes: boolean,
-  experimentalLiveTypesOnly?: boolean
+  options: ParseSchemaOptions
 ): Record<string, z.ZodType> {
   // Prepare the schemas fields
   const fields: Record<string, z.ZodType> = {};
 
   // Parse every field in the schema
   for (const field of collection.fields) {
+    // If fieldsToInclude is specified, only include fields that are in the list
+    if (
+      options.fieldsToInclude &&
+      !options.fieldsToInclude.includes(field.name)
+    ) {
+      continue;
+    }
+
     // Skip hidden fields if the user does not have superuser rights
-    if (field.hidden && !hasSuperuserRights) {
+    if (field.hidden && !options.hasSuperuserRights) {
+      if (options.fieldsToInclude) {
+        console.warn(
+          `"${field.name}" is requested but hidden. Provide superuser credentials to include this field.`
+        );
+      }
+
       continue;
     }
 
@@ -36,7 +55,7 @@ export function parseSchema(
         break;
       case "date":
       case "autodate":
-        if (experimentalLiveTypesOnly) {
+        if (options.experimentalLiveTypesOnly) {
           // If experimental live types only mode is enabled, treat dates as strings
           fieldType = z.string();
           break;
@@ -94,7 +113,8 @@ export function parseSchema(
       // `onCreate autodate` fields are always set
       (field.type === "autodate" && field.onCreate) ||
       // Improve number and boolean types by providing default values
-      (improveTypes && (field.type === "number" || field.type === "bool"));
+      (options.improveTypes &&
+        (field.type === "number" || field.type === "bool"));
 
     // If the field is not required, mark it as optional
     if (!isRequired) {

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

@@ -1,9 +1,9 @@
 import type { z } from "astro/zod";
 
 /**
- * Options for the PocketBase loader.
+ * Options for both build time and live collection loader
  */
-export interface PocketBaseLoaderOptions {
+export interface PocketBaseLoaderBaseOptions {
   /**
    * URL of the PocketBase instance.
    */
@@ -12,15 +12,6 @@ export interface PocketBaseLoaderOptions {
    * Name of the collection in PocketBase.
    */
   collectionName: string;
-  /**
-   * Field that should be used as the unique identifier for the collection.
-   * This must be the name of a field in the collection that contains unique values.
-   * If not provided, the `id` field will be used.
-   * The value of this field will be used in `getEntry` and `getEntries` to load the entry or entries.
-   *
-   * If the field is a string, it will be slugified to be used in the URL.
-   */
-  idField?: string;
   /**
    * Name of the field(s) containing the content of an entry.
    * This must be the name of a field in the PocketBase collection that contains the content.
@@ -34,12 +25,12 @@ export interface PocketBaseLoaderOptions {
   /**
    * Name of the field containing the last update date of an entry.
    * Ideally, this field should be of type `autodate` and have the value "Update" or "Create/Update".
-   * This field is used to only fetch entries that have been modified since the last build.
+   * For the build time loader, this field is used to only fetch entries that have been modified since the last build.
+   * For the live collection loader, this field is used to set the `lastModified` cache hint.
    */
   updatedField?: string;
   /**
    * Custom filter that is applied when loading data from PocketBase.
-   * Valid syntax can be found in the [PocketBase documentation](https://pocketbase.io/docs/api-records/#listsearch-records)
    *
    * The loader will also add it's own filters for incremental builds.
    * These will be added to your custom filter query.
@@ -52,8 +43,38 @@ export interface PocketBaseLoaderOptions {
    * // request
    * `?filter=(${loaderFilter})&&(release >= @now && deleted = false)`
    * ```
+   *
+   * @see {@link https://pocketbase.io/docs/api-records/#listsearch-records PocketBase documentation} for valid syntax
    */
   filter?: string;
+  /**
+   * Specify which fields to return for each record.
+   * This can be either a comma-separated string of field names or an array of field names.
+   * Only the specified fields will be included in the response and schema.
+   *
+   * Use "*" to include all fields (same as not specifying the fields option).
+   *
+   * Note: The basic fields (`id`, `collectionId`, `collectionName`) are automatically included
+   * in API requests when using field filtering. Additionally, any custom fields specified in the
+   * loader options (`idField`, `updatedField`, `contentFields`) are also automatically included.
+   *
+   * Warning: Expand fields are not currently supported by this loader.
+   *
+   * Example:
+   * ```ts
+   * // Using string format:
+   * fields: 'title,content,author'
+   *
+   * // Using array format:
+   * fields: ['title', 'content', 'author']
+   *
+   * // Include all fields:
+   * fields: '*'
+   * ```
+   *
+   * @see {@link https://pocketbase.io/docs/api-records/#listsearch-records PocketBase documentation} for valid syntax
+   */
+  fields?: string | 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.
@@ -76,6 +97,21 @@ export interface PocketBaseLoaderOptions {
          */
         impersonateToken: string;
       };
+}
+
+/**
+ * Options for the PocketBase loader.
+ */
+export type PocketBaseLoaderOptions = PocketBaseLoaderBaseOptions & {
+  /**
+   * Field that should be used as the unique identifier for the collection.
+   * This must be the name of a field in the collection that contains unique values.
+   * If not provided, the `id` field will be used.
+   * The value of this field will be used in `getEntry` and `getEntries` to load the entry or entries.
+   *
+   * If the field is a string, it will be slugified to be used in the URL.
+   */
+  idField?: string;
   /**
    * File path to the local schema file.
    * This file will be used to generate the schema for the collection.
@@ -112,19 +148,12 @@ export interface PocketBaseLoaderOptions {
      */
     liveTypesOnly?: boolean;
   };
-}
+};
 
 /**
  * Options for the PocketBase live loader.
  *
  * @experimental Live content collections are still experimental
  */
-export type ExperimentalPocketBaseLiveLoaderOptions = Pick<
-  PocketBaseLoaderOptions,
-  | "url"
-  | "collectionName"
-  | "contentFields"
-  | "updatedField"
-  | "filter"
-  | "superuserCredentials"
->;
+export type ExperimentalPocketBaseLiveLoaderOptions =
+  PocketBaseLoaderBaseOptions;

package/src/utils/combine-fields-for-request.ts

@@ -0,0 +1,55 @@
+import type {
+  PocketBaseLoaderBaseOptions,
+  PocketBaseLoaderOptions
+} from "../types/pocketbase-loader-options.type";
+
+/**
+ * Combine basic, special, and user-specified fields for PocketBase API requests.
+ * This utility ensures that required system fields are always included in API requests.
+ *
+ * @param userFields Array of fields specified by the user, or undefined for all fields
+ * @param options PocketBase loader options containing custom field configurations
+ * @returns Combined array of fields to include in the API request, or undefined for all fields
+ */
+export function combineFieldsForRequest(
+  userFields: Array<string> | undefined,
+  options: Pick<PocketBaseLoaderBaseOptions, "updatedField" | "contentFields"> &
+    Pick<PocketBaseLoaderOptions, "idField">
+): Array<string> | undefined {
+  // If no fields specified, return undefined to get all fields
+  if (!userFields) {
+    return undefined;
+  }
+
+  // Basic fields that are always required by the loader
+  const basicFields = ["id", "collectionId", "collectionName"];
+
+  // Special fields that are configured in options
+  const specialFields: Array<string> = [];
+
+  // Add custom id field if specified
+  if (options.idField && options.idField !== "id") {
+    specialFields.push(options.idField);
+  }
+
+  // Add updated field if specified
+  if (options.updatedField) {
+    specialFields.push(options.updatedField);
+  }
+
+  // Add content fields if specified
+  if (options.contentFields) {
+    if (Array.isArray(options.contentFields)) {
+      specialFields.push(...options.contentFields);
+    } else {
+      specialFields.push(options.contentFields);
+    }
+  }
+
+  // Combine all field sets, removing duplicates
+  const allFields = [
+    ...new Set([...basicFields, ...specialFields, ...userFields])
+  ];
+
+  return allFields;
+}

package/src/utils/create-token-promise.ts

@@ -1,11 +1,11 @@
-import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
+import type { PocketBaseLoaderBaseOptions } from "../types/pocketbase-loader-options.type";
 import { getSuperuserToken } from "./get-superuser-token";
 
 /**
  * Creates a promise that resolves to a superuser token or undefined.
  */
 export async function createTokenPromise(
-  options: Pick<PocketBaseLoaderOptions, "url" | "superuserCredentials">
+  options: Pick<PocketBaseLoaderBaseOptions, "superuserCredentials" | "url">
 ): Promise<string | undefined> {
   if (options.superuserCredentials) {
     if ("impersonateToken" in options.superuserCredentials) {

package/src/utils/extract-field-names.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract field names from fields that may contain modifiers like :excerpt().
+ *
+ * @param fields Array of field specifications that may contain modifiers
+ * @returns Array of clean field names suitable for schema parsing
+ */
+export function extractFieldNames(
+  fields: Array<string> | undefined
+): Array<string> | undefined {
+  if (!fields) {
+    return undefined;
+  }
+
+  return fields.map((field) => field.split(":")[0]);
+}

package/src/utils/format-fields.ts

@@ -0,0 +1,63 @@
+import type { PocketBaseLoaderBaseOptions } from "../types/pocketbase-loader-options.type";
+
+/**
+ * Format fields option into an array and validate for expand usage.
+ * Handles wildcard "*" and preserves excerpt field modifiers.
+ *
+ * @param fields The fields option (string or array)
+ * @returns Formatted fields array, or undefined if no fields specified or "*" wildcard is used
+ */
+export function formatFields(
+  fields: PocketBaseLoaderBaseOptions["fields"]
+): Array<string> | undefined {
+  if (!fields || fields.length === 0) {
+    return undefined;
+  }
+
+  let fieldList: Array<string>;
+  if (Array.isArray(fields)) {
+    fieldList = fields.map((f) => f.trim());
+  } else {
+    // Split carefully, respecting parentheses in excerpt syntax
+    fieldList = splitFieldsString(fields).map((f) => f.trim());
+  }
+
+  // Warn if expand is used since it's not currently supported
+  const hasExpand = fieldList.some((field) => field.includes("expand"));
+  if (hasExpand) {
+    console.warn(
+      'The "expand" parameter is not currently supported by astro-loader-pocketbase and will be filtered out.'
+    );
+    fieldList = fieldList.filter((field) => !field.includes("expand"));
+  }
+
+  // Check for "*" wildcard - if found anywhere, include all fields
+  const hasWildcard = fieldList.some((field) => field === "*");
+  if (hasWildcard) {
+    return undefined;
+  }
+
+  return fieldList;
+}
+
+/**
+ * Splits the fields string at `,` but respects the `:excerpt(number, boolean)` option
+ */
+function splitFieldsString(fieldsString: string): Array<string> {
+  // First, split by comma
+  const initialSplit = fieldsString.split(",");
+
+  const fields: Array<string> = [];
+  for (let i = 0; i < initialSplit.length; i++) {
+    const part = initialSplit[i];
+
+    if (part.includes("(") && !part.includes(")")) {
+      fields.push(`${part},${initialSplit[++i]}`);
+      continue;
+    }
+
+    fields.push(part);
+  }
+
+  return fields;
+}