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

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

@@ -1,55 +0,0 @@
-/**
- * Filter for a single entry
- */
-export interface PocketBaseLiveLoaderEntryFilter {
-  /**
-   * Id of the entry.
-   */
-  id: string;
-}
-
-/**
- * Filter for a collection of entries.
- */
-export interface PocketBaseLiveLoaderCollectionFilter {
-  /**
-   * Additional filter to apply to the collection.
-   * This will be added to the filter supplied in the {@link PocketBaseLiveLoaderOptions}.
-   *
-   * Example:
-   * ```ts
-   * // config:
-   * filter: 'release >= @now && deleted = false'
-   *
-   * // request
-   * `?filter=(${loaderFilter})&&(release >= @now && deleted = false)`
-   * ```
-   *
-   * @see {@link https://pocketbase.io/docs/api-records/#listsearch-records PocketBase documentation} for valid syntax
-   */
-  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.
-   *
-   * Example:
-   * ```ts
-   * // config:
-   * sort: '-created,id'
-   *
-   * // request
-   * `?sort=-created,id`
-   * ```
-   *
-   * @see {@link https://pocketbase.io/docs/api-records/#listsearch-records PocketBase documentation} for valid syntax
-   */
-  sort?: string;
-}

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

@@ -1,146 +0,0 @@
-import type { ZodType } from "astro/zod";
-
-/**
- * Options for both build time and live collection loader
- */
-export interface PocketBaseLoaderBaseOptions {
-  /**
-   * URL of the PocketBase instance.
-   */
-  url: string;
-  /**
-   * Name of the collection in PocketBase.
-   */
-  collectionName: 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.
-   * The content will be parsed as HTML and rendered to the page.
-   *
-   * If you want to render multiple fields as main content, you can pass an array of field names.
-   * The loader will concatenate the content of all fields in the order they are defined in the array.
-   * Each block will be contained in a `<section>` element.
-   */
-  contentFields?: string | Array<string>;
-  /**
-   * 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".
-   * 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.
-   *
-   * The loader will also add it's own filters for incremental builds.
-   * These will be added to your custom filter query.
-   *
-   * Example:
-   * ```ts
-   * // config:
-   * filter: 'release >= @now && deleted = false'
-   *
-   * // 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.
-   */
-  superuserCredentials?:
-    | {
-        /**
-         * Email of the superuser.
-         */
-        email: string;
-        /**
-         * Password of the superuser.
-         */
-        password: string;
-      }
-    | {
-        /**
-         * Impersonate auth token of the superuser.
-         * This token will take precedence over the email and password.
-         */
-        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.
-   * If `superuserCredentials` are provided, this option will be ignored.
-   */
-  localSchema?: string;
-  /**
-   * Record of zod schemas for all JSON fields in the collection.
-   * The key must be the name of a field in the collection.
-   * If no schema is provided for a field, the value will be treated as `unknown`.
-   *
-   * Note that this will only be used for fields of type `json`.
-   */
-  jsonSchemas?: Record<string, ZodType>;
-  /**
-   * 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.
-     */
-    liveTypesOnly?: boolean;
-  };
-};
-
-/**
- * Options for the PocketBase live loader.
- */
-export type PocketBaseLiveLoaderOptions = PocketBaseLoaderBaseOptions;

package/src/types/pocketbase-schema.type.ts

@@ -1,101 +0,0 @@
-import { z } from "astro/zod";
-
-/**
- * Entry for a collections schema in PocketBase.
- */
-export const pocketBaseSchemaEntry = z.object({
-  /**
-   * Flag to indicate if the field is hidden.
-   * Hidden fields are not returned in the API response.
-   */
-  hidden: z.optional(z.boolean()),
-  /**
-   * Unique identifier for the field.
-   */
-  id: z.string(),
-  /**
-   * Name of the field.
-   */
-  name: z.string(),
-  /**
-   * Help text for the field.
-   * This is only present if the field has help text defined.
-   */
-  help: z.optional(z.string()),
-  /**
-   * Type of the field.
-   */
-  type: z.enum([
-    "text",
-    "editor",
-    "number",
-    "bool",
-    "email",
-    "url",
-    "date",
-    "autodate",
-    "select",
-    "file",
-    "relation",
-    "json",
-    "geoPoint",
-    "password"
-  ]),
-  /**
-   * Whether the field is required.
-   */
-  required: z.optional(z.boolean()),
-  /**
-   * Values for a select field.
-   * This is only present if the field type is "select".
-   */
-  values: z.optional(z.array(z.string())),
-  /**
-   * Maximum number of values for a select field.
-   * This is only present on "select", "relation", and "file" fields.
-   */
-  maxSelect: z.optional(z.number()),
-  /**
-   * Whether the field is filled when the entry is created.
-   * This is only present on "autodate" fields.
-   */
-  onCreate: z.optional(z.boolean()),
-  /**
-   * Whether the field is updated when the entry is updated.
-   * This is only present on "autodate" fields.
-   */
-  onUpdate: z.optional(z.boolean())
-});
-
-/**
- * Entry for a collections schema in PocketBase.
- */
-export type PocketBaseSchemaEntry = z.infer<typeof pocketBaseSchemaEntry>;
-
-/**
- * Schema for a PocketBase collection.
- */
-export const pocketBaseCollection = z.object({
-  /**
-   * Name of the collection.
-   */
-  name: z.string(),
-  /**
-   * Type of the collection.
-   */
-  type: z.enum(["base", "view", "auth"]),
-  /**
-   * Schema of the collection.
-   */
-  fields: z.array(pocketBaseSchemaEntry)
-});
-
-/**
- * Type for a PocketBase collection.
- */
-export type PocketBaseCollection = z.infer<typeof pocketBaseCollection>;
-
-/**
- * Schema for an entire PocketBase database.
- */
-export const pocketBaseDatabase = z.array(pocketBaseCollection);

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

@@ -1,55 +0,0 @@
-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,25 +0,0 @@
-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<PocketBaseLoaderBaseOptions, "superuserCredentials" | "url">
-): Promise<string | undefined> {
-  if (options.superuserCredentials) {
-    if ("impersonateToken" in options.superuserCredentials) {
-      // Impersonate token provided, so use it directly.
-      return options.superuserCredentials.impersonateToken;
-    }
-    // Email and password provided, so get a temporary superuser token.
-    const token = await getSuperuserToken(
-      options.url,
-      options.superuserCredentials
-    );
-    return token;
-  }
-
-  // No credentials provided, so no token can be used.
-  return undefined;
-}

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

@@ -1,15 +0,0 @@
-/**
- * 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(":").at(0) ?? field);
-}

package/src/utils/format-fields.ts

@@ -1,66 +0,0 @@
-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.at(i);
-    if (!part) {
-      continue;
-    }
-
-    if (part.includes("(") && !part.includes(")")) {
-      fields.push(`${part},${initialSplit[++i]}`);
-      continue;
-    }
-
-    fields.push(part);
-  }
-
-  return fields;
-}

package/src/utils/get-superuser-token.ts

@@ -1,76 +0,0 @@
-import type { AstroIntegrationLogger } from "astro";
-import {
-  pocketBaseErrorResponse,
-  pocketBaseLoginResponse
-} from "../types/pocketbase-api-response.type";
-
-/**
- * This function will get a superuser token from the given PocketBase instance.
- *
- * @param url URL of the PocketBase instance
- * @param superuserCredentials Credentials of the superuser
- *
- * @returns A superuser token to access all resources of the PocketBase instance.
- */
-export async function getSuperuserToken(
-  url: string,
-  superuserCredentials: {
-    email: string;
-    password: string;
-  },
-  logger?: AstroIntegrationLogger
-): Promise<string | undefined> {
-  // Build the URL for the login endpoint
-  const loginUrl = new URL(
-    `api/collections/_superusers/auth-with-password`,
-    url
-  ).href;
-
-  // Create a new FormData object to send the login data
-  const loginData = new FormData();
-  loginData.set("identity", superuserCredentials.email);
-  loginData.set("password", superuserCredentials.password);
-
-  // Send the login request to get a token
-  const loginRequest = await fetch(loginUrl, {
-    method: "POST",
-    body: loginData
-  });
-
-  // If the login request was not successful, print the error message and return undefined
-  if (!loginRequest.ok) {
-    if (loginRequest.status === 429) {
-      const info =
-        "A rate limit was hit while trying to authenticate with PocketBase. Consider using an `impersonateToken` as credentials to avoid this issue.";
-      if (logger) {
-        logger.info(info);
-      } else {
-        console.info(info);
-      }
-
-      // Random wait between 3 (default rate limit interval) and 8 seconds
-      const retryAfter = Math.random() * 5 + 3;
-      // oxlint-disable-next-line promise/avoid-new
-      await new Promise((resolve) => {
-        setTimeout(resolve, retryAfter * 1000);
-      });
-
-      return getSuperuserToken(url, superuserCredentials, logger);
-    }
-
-    const errorResponse = pocketBaseErrorResponse.parse(
-      await loginRequest.json()
-    );
-    const errorMessage = `The given email / password for ${url} was not correct. Astro can't generate type definitions automatically and may not have access to all resources.\nReason: ${errorResponse.message}`;
-    if (logger) {
-      logger.error(errorMessage);
-    } else {
-      console.error(errorMessage);
-    }
-    return undefined;
-  }
-
-  // Return the token
-  const response = pocketBaseLoginResponse.parse(await loginRequest.json());
-  return response.token;
-}

package/src/utils/is-realtime-data.ts

@@ -1,34 +0,0 @@
-import { z } from "astro/zod";
-
-/**
- * Schema for realtime data received from PocketBase.
- */
-const realtimeDataSchema = z.object({
-  action: z.union([
-    z.literal("create"),
-    z.literal("update"),
-    z.literal("delete")
-  ]),
-  record: z.object({
-    id: z.string(),
-    collectionName: z.string(),
-    collectionId: z.string()
-  })
-});
-
-/**
- * Type for realtime data received from PocketBase.
- */
-export type RealtimeData = z.infer<typeof realtimeDataSchema>;
-
-/**
- * Checks if the given data is realtime data received from PocketBase.
- */
-export function isRealtimeData(data: unknown): data is RealtimeData {
-  try {
-    realtimeDataSchema.parse(data);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/utils/should-refresh.ts

@@ -1,37 +0,0 @@
-import type { LoaderContext } from "astro/loaders";
-
-/**
- * Checks if the collection should be refreshed.
- */
-export function shouldRefresh(
-  context: LoaderContext["refreshContextData"],
-  collectionName: string
-): "refresh" | "skip" | "force" {
-  // Check if the refresh was triggered by the `astro-integration-pocketbase`
-  // and the correct metadata is provided.
-  if (context?.source !== "astro-integration-pocketbase") {
-    return "refresh";
-  }
-
-  // Check if all collections should be refreshed.
-  if (context.force) {
-    return "force";
-  }
-
-  if (!context.collection) {
-    return "refresh";
-  }
-
-  // Check if the collection name matches the current collection.
-  if (typeof context.collection === "string") {
-    return context.collection === collectionName ? "refresh" : "skip";
-  }
-
-  // Check if the collection is included in the list of collections.
-  if (Array.isArray(context.collection)) {
-    return context.collection.includes(collectionName) ? "refresh" : "skip";
-  }
-
-  // Should not happen but return true to be safe.
-  return "refresh";
-}

package/src/utils/slugify.ts

@@ -1,21 +0,0 @@
-/**
- * Convert a string to a slug.
- *
- * Example:
- * ```ts
- * slugify("Hello World!"); // hello-world
- * ```
- */
-export function slugify(input: string): string {
-  return input
-    .toLowerCase()
-    .replaceAll(/\s+/g, "-") // Replace spaces with -
-    .replaceAll("ä", "ae") // Replace umlauts
-    .replaceAll("ö", "oe")
-    .replaceAll("ü", "ue")
-    .replaceAll("ß", "ss")
-    .replaceAll(/[^\w-]+/g, "") // Remove all non-word chars
-    .replaceAll(/--+/g, "-") // Replace multiple - with single -
-    .replace(/^-+/, "") // Trim - from start of text
-    .replace(/-+$/, ""); // Trim - from end of text
-}