astro-loader-pocketbase 2.7.1-next.3 → 2.8.0-next.1

package/README.md

@@ -41,6 +41,9 @@ If you want to update your deployed site with new entries, you need to rebuild i
 
 <sub>When running the dev server, you can trigger a reload by using `s + enter`.</sub>
 
+> [!TIP]
+> If you need live data on your production site, you can use the experimental live content loader described below.
+
 ## Incremental builds
 
 Since PocketBase 0.23.0, the `updated` field is not mandatory anymore.
@@ -210,6 +213,109 @@ This will remove `undefined` from the type of these fields and mark them as requ
 | `jsonSchemas`          | `Record<string, z.ZodSchema>`                                         |          | A record of Zod schemas to use for type generation of `json` fields.                                                               |
 | `improveTypes`         | `boolean`                                                             |          | Whether to improve the types of `number` and `boolean` fields, removing `undefined` from them.                                     |
 
+## Experimental live content loader
+
+> [!WARNING]
+> Live content collections are still experimental and may change in the future.
+> This means that this packages live content loader is also experimental and may include breaking changes with every release.
+
+For more information on how to enable and use live content collections, please refer to the [Astro documentation](https://docs.astro.build/en/reference/experimental-flags/live-content-collections/).
+
+### General usage
+
+#### Setup
+
+The options for this packages loader are similar to the regular PocketBase loader:
+
+```ts
+const blogLive = defineLiveCollection({
+  loader: experimentalPocketbaseLiveLoader({
+    url: "https://<your-pocketbase-url>",
+    collectionName: "<collection-in-pocketbase>"
+  })
+});
+
+export const collections = { blogLive };
+```
+
+You can also specify additional options for the live content loader, such as filters and content fields.
+For access to private collections and hidden fields, you need to provide superuser credentials, also similar to the regular PocketBase loader.
+
+#### Accessing a single entry
+
+To access a single entry you can use the default `getLiveEntry` function:
+
+```ts
+// Get a single entry by its id
+const entry = await getLiveEntry("blogLive", { id: "<entry-id>" });
+```
+
+In here you need to specify the id of the entry you want to access.
+In contrast to the regular content loader, the live content loader can not use a custom id field, so this needs to be the primary id used by PocketBase.
+
+#### Accessing a collection of entries
+
+To access a collection of entries, you can use the default `getLiveCollection` function:
+
+```ts
+// Get a whole collection of entries
+const entries = await getLiveCollection("blogLive");
+
+// Get a filtered and paginated collection of entries
+const entries2 = await getLiveCollection("blogLive", {
+  filters: "release >= @now && deleted = false",
+  sort: "-created,id",
+  page: 1,
+  perPage: 10
+});
+```
+
+By default, the loader will fetch all entries in the collection.
+But you can also specify additional options, such as filters (will be added to the global filters), sorting, and pagination.
+
+### Using cache hints
+
+The loader automatically adds cache hints for each entry / collection.
+By default only the `tags` hint is used, which includes the collection name and the id of the entry.
+
+If you also want to use the `lastModified` hint, just tell the loader which field to use for this date:
+
+```ts
+const blogLive = defineLiveCollection({
+  loader: experimentalPocketbaseLiveLoader({
+    ...options,
+    updatedField: "<field-in-collection>"
+  })
+});
+```
+
+### Caveats
+
+Live content loaders do not (yet 🤞🏼) support zod schemas and thus schema generation and entry transformation.
+This means that options like custom ids or image and file transformations are not available.
+Dates will also be treated as plain ISO strings instead of date objects.
+
+If you want an accompanying type for your live content, you can use the `experimental.liveTypesOnly` option on the regular loader.
+This will cause it to skip the data fetching and only generate types, fitting the live content structure.
+
+```ts
+const blogTypes = defineCollection({
+  loader: pocketbaseLoader({
+    ...options,
+    experimental: {
+      liveTypesOnly: true
+    }
+  })
+});
+
+const blogLive = defineLiveCollection({
+  loader:
+    experimentalPocketbaseLiveLoader<CollectionEntry<"blogTypes">["data"]>(
+      options
+    )
+});
+```
+
 ## Special cases
 
 ### Private collections and hidden fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-loader-pocketbase",
-  "version": "2.7.1-next.3",
+  "version": "2.8.0-next.1",
   "description": "A content loader for Astro that uses the PocketBase API",
   "keywords": [
     "astro",
@@ -47,11 +47,11 @@
     "@commitlint/config-conventional": "^19.8.1",
     "@types/node": "^22.14.1",
     "@vitest/coverage-v8": "^3.2.4",
-    "astro": "^5.12.9",
+    "astro": "^5.13.2",
     "globals": "^16.3.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.1.5",
-    "oxlint": "^1.11.1",
+    "oxlint": "^1.11.2",
     "prettier": "^3.6.2",
     "prettier-plugin-organize-imports": "^4.2.0",
     "prettier-plugin-packagejson": "^2.5.19",
@@ -59,7 +59,7 @@
     "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "astro": "^5.0.0"
+    "astro": "^5.10.0"
   },
   "packageManager": "npm@11.5.2",
   "publishConfig": {

package/src/index.ts

@@ -1,5 +1,20 @@
-import { pocketbaseLoader } from "./pocketbase-loader";
-import type { PocketBaseLoaderOptions } from "./types/pocketbase-loader-options.type";
+import {
+  experimentalPocketbaseLiveLoader,
+  pocketbaseLoader
+} from "./pocketbase-loader";
+import type {
+  ExperimentalPocketBaseLiveLoaderCollectionFilter,
+  ExperimentalPocketBaseLiveLoaderEntryFilter
+} from "./types/pocketbase-live-loader-filter.type";
+import type {
+  ExperimentalPocketBaseLiveLoaderOptions,
+  PocketBaseLoaderOptions
+} from "./types/pocketbase-loader-options.type";
 
-export { pocketbaseLoader };
-export type { PocketBaseLoaderOptions };
+export { experimentalPocketbaseLiveLoader, pocketbaseLoader };
+export type {
+  ExperimentalPocketBaseLiveLoaderCollectionFilter,
+  ExperimentalPocketBaseLiveLoaderEntryFilter,
+  ExperimentalPocketBaseLiveLoaderOptions,
+  PocketBaseLoaderOptions
+};

package/src/loader/fetch-collection.ts

@@ -0,0 +1,149 @@
+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";
+
+/**
+ * Provides utilities to fetch entries from a PocketBase collection, supporting filtering and pagination.
+ */
+export type CollectionFilter = {
+  /**
+   * Date string to only fetch entries that have been modified since this date.
+   * If not provided, all entries will be fetched.
+   */
+  lastModified?: string;
+} & ExperimentalPocketBaseLiveLoaderCollectionFilter;
+
+/**
+ * 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"
+  >,
+  chunkLoaded: (entries: Array<TEntry>) => Promise<void>,
+  token: string | undefined,
+  collectionFilter: CollectionFilter | undefined
+): Promise<void> {
+  // Build the URL for the collections endpoint
+  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();
+  if (token) {
+    collectionHeaders.set("Authorization", token);
+  }
+
+  // Prepare pagination variables
+  let page = 0;
+  let totalPages = 0;
+
+  // Fetch all (modified) entries
+  do {
+    const searchParams = buildSearchParams(options, {
+      ...collectionFilter,
+      page: collectionFilter?.page ?? ++page,
+      perPage: collectionFilter?.perPage ?? 100
+    });
+
+    // Fetch entries from the collection
+    const collectionRequest = await fetch(
+      `${collectionUrl}?${searchParams.toString()}`,
+      {
+        headers: collectionHeaders
+      }
+    );
+
+    // If the request was not successful, print the error message and return
+    if (!collectionRequest.ok) {
+      // If the collection is locked, an superuser token is required
+      if (collectionRequest.status === 403) {
+        if (
+          options.superuserCredentials &&
+          "impersonateToken" in options.superuserCredentials
+        ) {
+          throw new Error("The given impersonate token is not valid.");
+        } else {
+          throw new Error(
+            "The collection is not accessible without superuser rights. Please provide superuser credentials in the config."
+          );
+        }
+      }
+
+      // Get the reason for the error
+      const reason = await collectionRequest
+        .json()
+        .then((data) => data.message);
+      const errorMessage = `Fetching data failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
+      throw new Error(errorMessage);
+    }
+
+    // Get the data from the response
+    const response = await collectionRequest.json();
+
+    // Return current chunk
+    await chunkLoaded(response.items);
+
+    // Update the page and total pages
+    page = response.page;
+    totalPages = response.totalPages;
+  } while (!collectionFilter?.perPage && page < totalPages);
+}
+
+/**
+ * Build search parameters for the PocketBase collection request.
+ */
+function buildSearchParams(
+  loaderOptions: Pick<PocketBaseLoaderOptions, "updatedField" | "filter">,
+  collectionFilter: CollectionFilter
+): URLSearchParams {
+  // Build search parameters
+  const searchParams = new URLSearchParams();
+
+  if (collectionFilter.page) {
+    searchParams.set("page", `${collectionFilter.page}`);
+  }
+
+  if (collectionFilter.perPage) {
+    searchParams.set("perPage", `${collectionFilter.perPage}`);
+  }
+
+  const filters = [];
+
+  // If `lastModified` is set, only fetch entries that have been modified since the last fetch
+  // Sort by the updated field and id
+  if (collectionFilter.lastModified && loaderOptions.updatedField) {
+    filters.push(
+      `(${loaderOptions.updatedField}>"${collectionFilter.lastModified}")`
+    );
+    searchParams.set("sort", `-${loaderOptions.updatedField},id`);
+  }
+
+  // Add filter from the loader options
+  if (loaderOptions.filter) {
+    filters.push(`(${loaderOptions.filter})`);
+  }
+
+  // Add additional filter from the collection filter
+  if (collectionFilter.filter) {
+    filters.push(`(${collectionFilter.filter})`);
+  }
+
+  // Add filters to search parameters
+  if (filters.length > 0) {
+    searchParams.set("filter", filters.join("&&"));
+  }
+
+  if (collectionFilter.sort) {
+    searchParams.set("sort", collectionFilter.sort);
+  }
+
+  return searchParams;
+}

package/src/loader/fetch-entry.ts

@@ -0,0 +1,55 @@
+import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
+import type { ExperimentalPocketBaseLiveLoaderOptions } from "../types/pocketbase-loader-options.type";
+
+/**
+ * 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,
+  token: string | undefined
+): Promise<TEntry> {
+  // Build the URL for the entry endpoint
+  const entryUrl = new URL(
+    `api/collections/${options.collectionName}/records/${id}`,
+    options.url
+  ).href;
+
+  // Create the headers for the request to append the token (if available)
+  const entryHeaders = new Headers();
+  if (token) {
+    entryHeaders.set("Authorization", token);
+  }
+
+  // Fetch the entry from the collection
+  const entryRequest = await fetch(entryUrl, {
+    headers: entryHeaders
+  });
+
+  // If the request was not successful, return an error
+  if (!entryRequest.ok) {
+    // If the entry is locked, a superuser token is required
+    if (entryRequest.status === 403) {
+      if (
+        options.superuserCredentials &&
+        "impersonateToken" in options.superuserCredentials
+      ) {
+        throw new Error("The given impersonate token is not valid.");
+      } else {
+        throw new Error(
+          "The entry is not accessible without superuser rights. Please provide superuser credentials in the config."
+        );
+      }
+    }
+
+    // Get the reason for the error
+    const reason = await entryRequest.json().then((data) => data.message);
+    const errorMessage = `Fetching entry "${id}" from collection "${options.collectionName}" failed.\nReason: ${reason}`;
+    throw new Error(errorMessage);
+  }
+
+  // Get the data from the response
+  const response = await entryRequest.json();
+
+  return response;
+}

package/src/loader/live-collection-loader.ts

@@ -0,0 +1,37 @@
+import type { LiveDataCollection, LiveDataEntry } from "astro";
+import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
+import type { ExperimentalPocketBaseLiveLoaderCollectionFilter } from "../types/pocketbase-live-loader-filter.type";
+import type { ExperimentalPocketBaseLiveLoaderOptions } from "../types/pocketbase-loader-options.type";
+import { fetchCollection } from "./fetch-collection";
+import { parseLiveEntry } from "./parse-live-entry";
+
+/**
+ * Loads and parses a PocketBase collection for live data, returning entries or an error.
+ */
+export async function liveCollectionLoader<TEntry extends PocketBaseEntry>(
+  collectionFilter:
+    | ExperimentalPocketBaseLiveLoaderCollectionFilter
+    | undefined,
+  options: ExperimentalPocketBaseLiveLoaderOptions,
+  token: string | undefined
+): Promise<LiveDataCollection<TEntry> | { error: Error }> {
+  const entries: Array<LiveDataEntry<TEntry>> = [];
+
+  try {
+    await fetchCollection<TEntry>(
+      options,
+      // oxlint-disable-next-line require-await
+      async (chunk) => {
+        entries.push(...chunk.map((entry) => parseLiveEntry(entry, options)));
+      },
+      token,
+      collectionFilter
+    );
+  } catch (error) {
+    return { error: error as Error };
+  }
+
+  return {
+    entries
+  };
+}

package/src/loader/live-entry-loader.ts

@@ -0,0 +1,21 @@
+import type { LiveDataEntry } from "astro";
+import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
+import type { ExperimentalPocketBaseLiveLoaderOptions } from "../types/pocketbase-loader-options.type";
+import { fetchEntry } from "./fetch-entry";
+import { parseLiveEntry } from "./parse-live-entry";
+
+/**
+ * Loads and parses a single PocketBase entry for live data, returning the entry or an error.
+ */
+export async function liveEntryLoader<TEntry extends PocketBaseEntry>(
+  id: string,
+  options: ExperimentalPocketBaseLiveLoaderOptions,
+  token: string | undefined
+): Promise<LiveDataEntry<TEntry> | { error: Error }> {
+  try {
+    const entry = await fetchEntry<TEntry>(id, options, token);
+    return parseLiveEntry(entry, options);
+  } catch (error) {
+    return { error: error as Error };
+  }
+}

package/src/loader/load-entries.ts

@@ -1,5 +1,6 @@
 import type { LoaderContext } from "astro/loaders";
 import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
+import { fetchCollection } from "./fetch-collection";
 import { parseEntry } from "./parse-entry";
 
 /**
@@ -16,18 +17,6 @@ export async function loadEntries(
   superuserToken: string | undefined,
   lastModified: string | undefined
 ): Promise<void> {
-  // Build the URL for the collections endpoint
-  const collectionUrl = new URL(
-    `api/collections/${options.collectionName}/records`,
-    options.url
-  ).href;
-
-  // Create the headers for the request to append the superuser token (if available)
-  const collectionHeaders = new Headers();
-  if (superuserToken) {
-    collectionHeaders.set("Authorization", superuserToken);
-  }
-
   // Log the fetching of the entries
   context.logger.info(
     `Fetching${lastModified ? " modified" : ""} data${
@@ -35,87 +24,29 @@ export async function loadEntries(
     }${superuserToken ? " as superuser" : ""}`
   );
 
-  // Prepare pagination variables
-  let page = 0;
-  let totalPages = 0;
-  let entries = 0;
-
-  // Fetch all (modified) entries
-  do {
-    // Build search parameters
-    const searchParams = new URLSearchParams({
-      page: `${++page}`,
-      perPage: "100"
-    });
-
-    const filters = [];
-    if (lastModified && options.updatedField) {
-      // If `lastModified` is set, only fetch entries that have been modified since the last fetch
-      filters.push(`(${options.updatedField}>"${lastModified}")`);
-      // Sort by the updated field and id
-      searchParams.set("sort", `-${options.updatedField},id`);
-    }
-    if (options.filter) {
-      filters.push(`(${options.filter})`);
-    }
-
-    // Add filters to search parameters
-    if (filters.length > 0) {
-      searchParams.set("filter", filters.join("&&"));
-    }
-
-    // Fetch entries from the collection
-    const collectionRequest = await fetch(
-      `${collectionUrl}?${searchParams.toString()}`,
-      {
-        headers: collectionHeaders
+  let numEntries = 0;
+  await fetchCollection(
+    options,
+    async (entries) => {
+      // Parse and store the entries
+      for (const entry of entries) {
+        await parseEntry(entry, context, options);
       }
-    );
 
-    // If the request was not successful, print the error message and return
-    if (!collectionRequest.ok) {
-      // If the collection is locked, an superuser token is required
-      if (collectionRequest.status === 403) {
-        if (
-          options.superuserCredentials &&
-          "impersonateToken" in options.superuserCredentials
-        ) {
-          throw new Error("The given impersonate token is not valid.");
-        } else {
-          throw new Error(
-            "The collection is not accessible without superuser rights. Please provide superuser credentials in the config."
-          );
-        }
-      }
-
-      // Get the reason for the error
-      const reason = await collectionRequest
-        .json()
-        .then((data) => data.message);
-      const errorMessage = `Fetching data failed with status code ${collectionRequest.status}.\nReason: ${reason}`;
-      throw new Error(errorMessage);
+      numEntries += entries.length;
+    },
+    superuserToken,
+    {
+      lastModified
     }
-
-    // Get the data from the response
-    const response = await collectionRequest.json();
-
-    // Parse and store the entries
-    for (const entry of response.items) {
-      await parseEntry(entry, context, options);
-    }
-
-    // Update the page and total pages
-    page = response.page;
-    totalPages = response.totalPages;
-    entries += response.items.length;
-  } while (page < totalPages);
+  );
 
   // Log the number of fetched entries
   if (lastModified) {
     context.logger.info(
-      `Updated ${entries}/${context.store.keys().length} entries.`
+      `Updated ${numEntries}/${context.store.keys().length} entries.`
     );
   } else {
-    context.logger.info(`Fetched ${entries} entries.`);
+    context.logger.info(`Fetched ${numEntries} entries.`);
   }
 }

package/src/loader/parse-live-entry.ts

@@ -0,0 +1,68 @@
+import type { LiveDataEntry } from "astro";
+import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
+import type { ExperimentalPocketBaseLiveLoaderOptions } from "../types/pocketbase-loader-options.type";
+
+/**
+ * Converts a PocketBase entry into a LiveDataEntry for Astro, extracting content and cache metadata.
+ */
+export function parseLiveEntry<TEntry extends PocketBaseEntry>(
+  entry: TEntry,
+  options: ExperimentalPocketBaseLiveLoaderOptions
+): LiveDataEntry<TEntry> {
+  // Build a cache tag
+  const tag = `${options.collectionName}-${entry.id}`;
+
+  let lastModified: Date | undefined = undefined;
+  // If an updated field is provided and the entry has a valid date value,
+  // use it as the last modified date cache hint
+  if (options.updatedField && entry[options.updatedField]) {
+    const value = `${entry[options.updatedField]}`;
+    try {
+      const date = new Date(value);
+      if (isNaN(date.getTime())) {
+        throw new TypeError("Invalid date");
+      }
+
+      lastModified = date;
+    } catch {
+      console.warn(
+        `Entry ${entry.id} of collection ${options.collectionName} has an invalid date in ${options.updatedField}: ${value}`
+      );
+    }
+  }
+
+  if (!options.contentFields) {
+    return {
+      id: entry.id,
+      data: entry,
+      cacheHint: {
+        tags: [tag],
+        lastModified
+      }
+    };
+  }
+
+  let content: string;
+  if (typeof options.contentFields === "string") {
+    // If a single content field is provided, use it directly
+    content = `${entry[options.contentFields]}`;
+  } else {
+    // If multiple content fields are provided, concatenate them with `<section>` tags
+    content = options.contentFields
+      .map((field) => `<section>${entry[field]}</section>`)
+      .join("");
+  }
+
+  return {
+    id: entry.id,
+    data: entry,
+    // @ts-expect-error - Docs say this is possible
+    rendered: {
+      html: content
+    },
+    cacheHint: {
+      tags: [tag],
+      lastModified
+    }
+  };
+}

package/src/pocketbase-loader.ts

@@ -1,8 +1,19 @@
-import type { Loader } from "astro/loaders";
+import type { LiveDataCollection, LiveDataEntry } from "astro";
+import type { LiveLoader, Loader } from "astro/loaders";
 import type { ZodSchema } from "astro/zod";
+import { liveCollectionLoader } from "./loader/live-collection-loader";
+import { liveEntryLoader } from "./loader/live-entry-loader";
 import { loader } from "./loader/loader";
 import { generateSchema } from "./schema/generate-schema";
-import type { PocketBaseLoaderOptions } from "./types/pocketbase-loader-options.type";
+import type { PocketBaseEntry } from "./types/pocketbase-entry.type";
+import type {
+  ExperimentalPocketBaseLiveLoaderCollectionFilter,
+  ExperimentalPocketBaseLiveLoaderEntryFilter
+} from "./types/pocketbase-live-loader-filter.type";
+import type {
+  ExperimentalPocketBaseLiveLoaderOptions,
+  PocketBaseLoaderOptions
+} from "./types/pocketbase-loader-options.type";
 import { createTokenPromise } from "./utils/create-token-promise";
 
 /**
@@ -17,6 +28,14 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
   return {
     name: "pocketbase-loader",
     load: async (context): Promise<void> => {
+      if (options.experimental?.liveTypesOnly) {
+        context.logger.label = `pocketbase-loader:${options.collectionName}`;
+        context.logger.info(
+          "Experimental live types only mode enabled. No data will be loaded, only types will be generated."
+        );
+        return;
+      }
+
       const token = await tokenPromise;
 
       // Load the entries from the collection
@@ -30,3 +49,44 @@ export function pocketbaseLoader(options: PocketBaseLoaderOptions): Loader {
     }
   };
 }
+
+/**
+ * Live loader for collections stored in PocketBase.
+ * This loader is currently experimental and may change in any future release.
+ *
+ * @param options Options for the live loader. See {@link ExperimentalPocketBaseLiveLoaderOptions} for more details.
+ *
+ * @experimental Live content collections are still experimental
+ */
+export function experimentalPocketbaseLiveLoader<
+  TEntry extends PocketBaseEntry
+>(
+  options: ExperimentalPocketBaseLiveLoaderOptions
+): LiveLoader<
+  TEntry,
+  ExperimentalPocketBaseLiveLoaderEntryFilter,
+  ExperimentalPocketBaseLiveLoaderCollectionFilter
+> {
+  // Create shared promise for the superuser token, which can be reused
+  const tokenPromise = createTokenPromise(options);
+
+  return {
+    name: "pocketbase-live-loader",
+    loadCollection: async ({
+      filter
+    }): Promise<LiveDataCollection<TEntry> | { error: Error }> => {
+      const token = await tokenPromise;
+
+      // Load entries from the collection
+      return await liveCollectionLoader(filter, options, token);
+    },
+    loadEntry: async ({
+      filter
+    }): Promise<LiveDataEntry<TEntry> | { error: Error }> => {
+      const token = await tokenPromise;
+
+      // Load a single entry from the collection
+      return await liveEntryLoader(filter.id, options, token);
+    }
+  };
+}

package/src/schema/generate-schema.ts

@@ -65,7 +65,8 @@ export async function generateSchema(
     collection,
     options.jsonSchemas,
     hasSuperuserRights,
-    options.improveTypes ?? false
+    options.improveTypes ?? false,
+    options.experimental?.liveTypesOnly ?? false
   );
 
   // Check if custom id field is present

package/src/schema/parse-schema.ts

@@ -4,11 +4,15 @@ import type {
   PocketBaseSchemaEntry
 } from "../types/pocketbase-schema.type";
 
+/**
+ * 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
+  improveTypes: boolean,
+  experimentalLiveTypesOnly?: boolean
 ): Record<string, z.ZodType> {
   // Prepare the schemas fields
   const fields: Record<string, z.ZodType> = {};
@@ -32,6 +36,11 @@ export function parseSchema(
         break;
       case "date":
       case "autodate":
+        if (experimentalLiveTypesOnly) {
+          // If experimental live types only mode is enabled, treat dates as strings
+          fieldType = z.string();
+          break;
+        }
         // Coerce and parse the value as a date
         fieldType = z.coerce.date();
         break;

package/src/types/pocketbase-live-loader-filter.type.ts

@@ -0,0 +1,59 @@
+/**
+ * Filter for a single entry
+ *
+ * @experimental Live content collections are still experimental
+ */
+export interface ExperimentalPocketBaseLiveLoaderEntryFilter {
+  /**
+   * Id of the entry.
+   */
+  id: string;
+}
+
+/**
+ * Filter for a collection of entries.
+ *
+ * @experimental Live content collections are still experimental
+ */
+export interface ExperimentalPocketBaseLiveLoaderCollectionFilter {
+  /**
+   * Additional filter to apply to the collection.
+   * This will be added to the filter supplied in the {@link ExperimentalPocketBaseLiveLoaderOptions}.
+   *
+   * Valid syntax can be found in the [PocketBase documentation](https://pocketbase.io/docs/api-records/#listsearch-records)
+   *
+   * Example:
+   * ```ts
+   * // config:
+   * filter: 'release >= @now && deleted = false'
+   *
+   * // request
+   * `?filter=(${loaderFilter})&&(release >= @now && deleted = false)`
+   * ```
+   */
+  filter?: string;
+  /**
+   * Page number to load (1-indexed).
+   */
+  page?: number;
+  /**
+   * Number of entries to load per page.
+   * If not provided all entries will be loaded in chunks of 100.
+   */
+  perPage?: number;
+  /**
+   * Sort order in which the entries should be returned.
+   *
+   * Valid syntax can be found in the [PocketBase documentation](https://pocketbase.io/docs/api-records/#listsearch-records)
+   *
+   * Example:
+   * ```ts
+   * // config:
+   * sort: '-created,id'
+   *
+   * // request
+   * `?sort=-created,id`
+   * ```
+   */
+  sort?: string;
+}

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

@@ -98,4 +98,33 @@ export interface PocketBaseLoaderOptions {
    * The PocketBase API does always return at least `0` or `false` as the default values, even though the fields are not marked as required in the schema.
    */
   improveTypes?: boolean;
+  /**
+   * Experimental options for the loader.
+   *
+   * @experimental All of these options are experimental and may change in the future.
+   */
+  experimental?: {
+    /**
+     * Whether to only create types for the live loader.
+     * This will not load any data, but only generate types that can be used with the live loader.
+     *
+     * @experimental Live content collections are still experimental
+     */
+    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"
+>;