astro-loader-pocketbase 3.1.0 → 3.1.2-next.1

package/src/loader/fetch-entry.ts

@@ -1,83 +0,0 @@
-import {
-  LiveCollectionError,
-  LiveEntryNotFoundError
-} from "astro/content/runtime";
-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 { PocketBaseLiveLoaderOptions } 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.
- */
-export async function fetchEntry<TEntry extends PocketBaseEntry>(
-  id: string,
-  options: PocketBaseLiveLoaderOptions,
-  token: string | undefined
-): Promise<TEntry> {
-  // Build the URL for the entry endpoint
-  const entryUrl = new URL(
-    `api/collections/${options.collectionName}/records/${id}`,
-    options.url
-  );
-
-  // 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();
-  if (token) {
-    entryHeaders.set("Authorization", token);
-  }
-
-  // Fetch the entry from the collection
-  const entryRequest = await fetch(entryUrl.href, {
-    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 PocketBaseAuthenticationError(
-          options.collectionName,
-          "The given impersonate token is not valid."
-        );
-      } else {
-        throw new PocketBaseAuthenticationError(
-          options.collectionName,
-          "The entry is not accessible without superuser rights. Please provide superuser credentials in the config."
-        );
-      }
-    }
-
-    if (entryRequest.status === 404) {
-      throw new LiveEntryNotFoundError(options.collectionName, id);
-    }
-
-    // Get the reason for the error
-    const errorResponse = pocketBaseErrorResponse.parse(
-      await entryRequest.json()
-    );
-    throw new LiveCollectionError(
-      options.collectionName,
-      errorResponse.message
-    );
-  }
-
-  // Get the data from the response
-  const response = pocketBaseEntry.parse(await entryRequest.json());
-  // oxlint-disable-next-line no-unsafe-type-assertion
-  return response as TEntry;
-}

package/src/loader/handle-realtime-updates.ts

@@ -1,56 +0,0 @@
-import type { LoaderContext } from "astro/loaders";
-import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
-import { isRealtimeData } from "../utils/is-realtime-data";
-import { parseEntry } from "./parse-entry";
-
-/**
- * Handles realtime updates for the loader without making any new network requests.
- *
- * Returns `true` if the data was handled and no further action is needed.
- */
-export async function handleRealtimeUpdates(
-  context: LoaderContext,
-  options: PocketBaseLoaderOptions
-): Promise<boolean> {
-  // Check if a custom filter is set
-  if (options.filter) {
-    // Updating an entry directly via realtime updates is not supported when using a custom filter.
-    // This is because the filter can only be applied via the get request and is not considered in the realtime updates.
-    // Updating the entry directly would bypass the filter and could lead to inconsistent data.
-    return false;
-  }
-
-  // Check if data was provided via the refresh context
-  if (!context.refreshContextData?.data) {
-    return false;
-  }
-
-  // Check if the data is PocketBase realtime data
-  const data = context.refreshContextData.data;
-  if (!isRealtimeData(data)) {
-    return false;
-  }
-
-  // Check if the collection name matches the current collection
-  if (data.record.collectionName !== options.collectionName) {
-    return false;
-  }
-
-  // Handle deleted entry
-  if (data.action === "delete") {
-    context.logger.info("Removing deleted entry");
-    context.store.delete(data.record.id);
-    return true;
-  }
-
-  // Handle updated or new entry
-  if (data.action === "update") {
-    context.logger.info("Updating outdated entry");
-  } else {
-    context.logger.info("Creating new entry");
-  }
-
-  // Parse the entry and store
-  await parseEntry(data.record, context, options);
-  return true;
-}

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

@@ -1,51 +0,0 @@
-import type { LiveDataCollection, LiveDataEntry } from "astro";
-import { LiveCollectionError } from "astro/content/runtime";
-import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
-import type { PocketBaseLiveLoaderCollectionFilter } from "../types/pocketbase-live-loader-filter.type";
-import type { PocketBaseLiveLoaderOptions } 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: PocketBaseLiveLoaderCollectionFilter | undefined,
-  options: PocketBaseLiveLoaderOptions,
-  token: string | undefined
-): Promise<LiveDataCollection<TEntry> | { error: LiveCollectionError }> {
-  const entries: Array<LiveDataEntry<TEntry>> = [];
-
-  try {
-    await fetchCollection<TEntry>(
-      options,
-      async (chunk) => {
-        entries.push(...chunk.map((entry) => parseLiveEntry(entry, options)));
-      },
-      token,
-      collectionFilter
-    );
-  } catch (error) {
-    if (error instanceof LiveCollectionError) {
-      return { error };
-    }
-
-    if (error instanceof Error) {
-      return {
-        error: new LiveCollectionError(
-          options.collectionName,
-          error.message,
-          error
-        )
-      };
-    }
-
-    return {
-      error: new LiveCollectionError(options.collectionName, String(error))
-    };
-  }
-
-  return {
-    entries
-  };
-}

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

@@ -1,38 +0,0 @@
-import type { LiveDataEntry } from "astro";
-import { LiveCollectionError } from "astro/content/runtime";
-import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
-import type { PocketBaseLiveLoaderOptions } 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: PocketBaseLiveLoaderOptions,
-  token: string | undefined
-): Promise<LiveDataEntry<TEntry> | { error: LiveCollectionError }> {
-  try {
-    const entry = await fetchEntry<TEntry>(id, options, token);
-    return parseLiveEntry(entry, options);
-  } catch (error) {
-    if (error instanceof LiveCollectionError) {
-      return { error };
-    }
-
-    if (error instanceof Error) {
-      return {
-        error: new LiveCollectionError(
-          options.collectionName,
-          error.message,
-          error
-        )
-      };
-    }
-
-    return {
-      error: new LiveCollectionError(options.collectionName, String(error))
-    };
-  }
-}

package/src/loader/load-entries.ts

@@ -1,52 +0,0 @@
-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";
-
-/**
- * Load (modified) entries from a PocketBase collection.
- *
- * @param options Options for the loader.
- * @param context Context of the loader.
- * @param superuserToken Superuser token to access all resources.
- * @param lastModified Date of the last fetch to only update changed entries.
- */
-export async function loadEntries(
-  options: PocketBaseLoaderOptions,
-  context: LoaderContext,
-  superuserToken: string | undefined,
-  lastModified: string | undefined
-): Promise<void> {
-  // Log the fetching of the entries
-  context.logger.info(
-    `Fetching${lastModified ? " modified" : ""} data${
-      lastModified ? ` starting at ${lastModified}` : ""
-    }${superuserToken ? " as superuser" : ""}`
-  );
-
-  let numEntries = 0;
-  await fetchCollection(
-    options,
-    async (entries) => {
-      // Parse and store the entries
-      for (const entry of entries) {
-        await parseEntry(entry, context, options);
-      }
-
-      numEntries += entries.length;
-    },
-    superuserToken,
-    {
-      lastModified
-    }
-  );
-
-  // Log the number of fetched entries
-  if (lastModified) {
-    context.logger.info(
-      `Updated ${numEntries}/${context.store.keys().length} entries.`
-    );
-  } else {
-    context.logger.info(`Fetched ${numEntries} entries.`);
-  }
-}

package/src/loader/loader.ts

@@ -1,77 +0,0 @@
-import type { LoaderContext } from "astro/loaders";
-import packageJson from "../../package.json";
-import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
-import { shouldRefresh } from "../utils/should-refresh";
-import { cleanupEntries } from "./cleanup-entries";
-import { handleRealtimeUpdates } from "./handle-realtime-updates";
-import { loadEntries } from "./load-entries";
-
-/**
- * Load entries from a PocketBase collection.
- */
-export async function loader(
-  context: LoaderContext,
-  options: PocketBaseLoaderOptions,
-  token: string | undefined
-): Promise<void> {
-  context.logger.label = `pocketbase-loader:${options.collectionName}`;
-
-  // Check if the collection should be refreshed.
-  const refresh = shouldRefresh(
-    context.refreshContextData,
-    options.collectionName
-  );
-  if (refresh === "skip") {
-    return;
-  }
-
-  // Handle realtime updates
-  const handled = await handleRealtimeUpdates(context, options);
-  if (handled) {
-    return;
-  }
-
-  // Get the date of the last fetch to only update changed entries.
-  let lastModified = context.meta.get("last-modified");
-
-  // Force a full update if the refresh is forced
-  if (refresh === "force") {
-    lastModified = undefined;
-    context.store.clear();
-  }
-
-  // Check if the version has changed to force an update
-  const lastVersion = context.meta.get("version");
-  if (lastVersion !== packageJson.version) {
-    if (lastVersion) {
-      context.logger.info(
-        `PocketBase loader was updated from ${lastVersion} to ${packageJson.version}. All entries will be loaded again.`
-      );
-    }
-
-    // Disable incremental builds and clear the store
-    lastModified = undefined;
-    context.store.clear();
-  }
-
-  // Disable incremental builds if no updated field is provided
-  if (!options.updatedField) {
-    context.logger.info(
-      `No "updatedField" was provided. Incremental builds are disabled.`
-    );
-    lastModified = undefined;
-  }
-
-  if (context.store.keys().length > 0) {
-    // Cleanup entries that are no longer in the collection
-    await cleanupEntries(options, context, token);
-  }
-
-  // Load the (modified) entries
-  await loadEntries(options, context, token, lastModified);
-
-  // Set the last modified date to the current date
-  context.meta.set("last-modified", new Date().toISOString().replace("T", " "));
-
-  context.meta.set("version", packageJson.version);
-}

package/src/loader/parse-entry.ts

@@ -1,90 +0,0 @@
-import type { LoaderContext } from "astro/loaders";
-import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
-import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
-import { slugify } from "../utils/slugify";
-
-/**
- * Parse an entry from PocketBase to match the schema and store it in the store.
- *
- * @param entry Entry to parse.
- * @param context Context of the loader.
- * @param idField Field to use as id for the entry.
- *                If not provided, the id of the entry will be used.
- * @param contentFields Field(s) to use as content for the entry.
- *                      If multiple fields are used, they will be concatenated and wrapped in `<section>` elements.
- */
-export async function parseEntry(
-  entry: PocketBaseEntry,
-  { generateDigest, parseData, store, logger }: LoaderContext,
-  { idField, contentFields, updatedField }: PocketBaseLoaderOptions
-): Promise<void> {
-  let id = entry.id;
-  if (idField) {
-    // Get the custom ID of the entry if it exists
-    const customEntryId = entry[idField];
-
-    if (!customEntryId) {
-      logger.warn(
-        `The entry "${id}" does not have a value for field ${idField}. Using the default ID instead.`
-      );
-    } else {
-      id = slugify(`${customEntryId}`);
-    }
-  }
-
-  const oldEntry = store.get(id);
-  if (oldEntry && oldEntry.data.id !== entry.id) {
-    logger.warn(
-      `The entry "${entry.id}" seems to be a duplicate of "${oldEntry.data.id}". Please make sure to use unique IDs in the column "${idField}".`
-    );
-  }
-
-  // Parse the data to match the schema
-  // This will throw an error if the data does not match the schema
-  const data = await parseData({
-    id,
-    data: entry
-  });
-
-  // Get the updated date of the entry
-  let updated: string | undefined;
-  if (updatedField) {
-    updated = `${entry[updatedField]}`;
-  }
-
-  // Generate a digest for the entry
-  // If no updated date is available, the digest will be generated from the whole entry
-  const digest = generateDigest(updated ?? entry);
-
-  if (!contentFields) {
-    // Store the entry
-    store.set({
-      id,
-      data,
-      digest
-    });
-    return;
-  }
-
-  // Generate the content for the entry
-  let content: string;
-  if (typeof contentFields === "string") {
-    // Only one field is used as content
-    content = `${entry[contentFields]}`;
-  } else {
-    // Multiple fields are used as content, wrap each block in a section and concatenate them
-    content = contentFields
-      .map((field) => `<section id="${field}">${entry[field]}</section>`)
-      .join("");
-  }
-
-  // Store the entry
-  store.set({
-    id,
-    data,
-    digest,
-    rendered: {
-      html: content
-    }
-  });
-}

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

@@ -1,66 +0,0 @@
-import type { LiveDataEntry } from "astro";
-import { LiveCollectionValidationError } from "astro/content/runtime";
-import { z } from "astro/zod";
-import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
-import type { PocketBaseLiveLoaderOptions } 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: PocketBaseLiveLoaderOptions
-): 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]}`;
-    const date = z.coerce.date().safeParse(value);
-    if (!date.success) {
-      throw new LiveCollectionValidationError(
-        options.collectionName,
-        entry.id,
-        date.error
-      );
-    }
-    lastModified = date.data;
-  }
-
-  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 id="${field}">${entry[field]}</section>`)
-      .join("");
-  }
-
-  return {
-    id: entry.id,
-    data: entry,
-    rendered: {
-      html: content
-    },
-    cacheHint: {
-      tags: [tag],
-      lastModified
-    }
-  };
-}

package/src/pocketbase-loader.ts

@@ -1,98 +0,0 @@
-import type { LiveDataCollection, LiveDataEntry } from "astro";
-import type { LiveCollectionError } from "astro/content/runtime";
-import type { LiveLoader, Loader, LoaderContext } from "astro/loaders";
-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 { generateType } from "./schema/generate-type";
-import type { PocketBaseEntry } from "./types/pocketbase-entry.type";
-import type {
-  PocketBaseLiveLoaderCollectionFilter,
-  PocketBaseLiveLoaderEntryFilter
-} from "./types/pocketbase-live-loader-filter.type";
-import type {
-  PocketBaseLiveLoaderOptions,
-  PocketBaseLoaderOptions
-} from "./types/pocketbase-loader-options.type";
-import { createTokenPromise } from "./utils/create-token-promise";
-
-/**
- * Loader for collections stored in PocketBase.
- *
- * @param options Options for the loader. See {@link PocketBaseLoaderOptions} for more details.
- */
-// oxlint-disable-next-line explicit-module-boundary-types
-export function pocketbaseLoader(options: PocketBaseLoaderOptions) {
-  // Create shared promise for the superuser token, which can be reused
-  const tokenPromise = createTokenPromise(options);
-
-  return {
-    name: "pocketbase-loader",
-    load: async (context: LoaderContext): 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
-      await loader(context, options, token);
-    },
-    createSchema: async () => {
-      const token = await tokenPromise;
-
-      // Generate the schema for the collection according to the API
-      const schema = await generateSchema(options, token);
-      const types = generateType(schema);
-
-      return {
-        schema,
-        types
-      };
-    }
-  } satisfies Loader;
-}
-
-/**
- * Live loader for collections stored in PocketBase.
- *
- * @param options Options for the live loader. See {@link PocketBaseLiveLoaderOptions} for more details.
- */
-export function pocketbaseLiveLoader<TEntry extends PocketBaseEntry>(
-  options: PocketBaseLiveLoaderOptions
-): LiveLoader<
-  TEntry,
-  PocketBaseLiveLoaderEntryFilter,
-  PocketBaseLiveLoaderCollectionFilter,
-  LiveCollectionError
-> {
-  // 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: LiveCollectionError }
-    > => {
-      const token = await tokenPromise;
-
-      // Load entries from the collection
-      return liveCollectionLoader<TEntry>(filter, options, token);
-    },
-    loadEntry: async ({
-      filter
-    }): Promise<LiveDataEntry<TEntry> | { error: LiveCollectionError }> => {
-      const token = await tokenPromise;
-
-      // Load a single entry from the collection
-      return liveEntryLoader<TEntry>(filter.id, options, token);
-    }
-  };
-}