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

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.4",
   "description": "A content loader for Astro that uses the PocketBase API",
   "keywords": [
     "astro",

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 { 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.
@@ -23,6 +25,7 @@ export async function fetchCollection<TEntry extends PocketBaseEntry>(
     | "url"
     | "updatedField"
     | "filter"
+    | "fields"
     | "superuserCredentials"
   >,
   chunkLoaded: (entries: Array<TEntry>) => Promise<void>,
@@ -33,7 +36,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 +44,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) {
@@ -102,9 +109,9 @@ export async function fetchCollection<TEntry extends PocketBaseEntry>(
  */
 function buildSearchParams(
   loaderOptions: Pick<PocketBaseLoaderOptions, "updatedField" | "filter">,
+  combinedFields: Array<string> | undefined,
   collectionFilter: CollectionFilter
 ): URLSearchParams {
-  // Build search parameters
   const searchParams = new URLSearchParams();
 
   if (collectionFilter.page) {
@@ -145,5 +152,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/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

@@ -39,7 +39,6 @@ export interface PocketBaseLoaderOptions {
   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 +51,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.
@@ -126,5 +155,6 @@ export type ExperimentalPocketBaseLiveLoaderOptions = Pick<
   | "contentFields"
   | "updatedField"
   | "filter"
+  | "fields"
   | "superuserCredentials"
 >;

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

@@ -0,0 +1,54 @@
+import type { 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<
+    PocketBaseLoaderOptions,
+    "idField" | "updatedField" | "contentFields"
+  >
+): 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/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 { PocketBaseLoaderOptions } 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: PocketBaseLoaderOptions["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;
+}