astro-loader-pocketbase 3.1.1 → 3.1.2-next.2

package/src/schema/generate-schema.ts

@@ -1,200 +0,0 @@
-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";
-import { transformFiles } from "./transform-files";
-
-/**
- * Basic schema for every PocketBase collection.
- */
-const BASIC_SCHEMA = z.object({
-  id: z.string().meta({
-    title: "id",
-    description: "The unique identifier for the entry."
-  }),
-  collectionId: z.string().meta({
-    title: "collectionId",
-    description:
-      "The unique identifier for the collection the entity belongs to."
-  }),
-  collectionName: z.string().meta({
-    title: "collectionName",
-    description: "The name of the collection the entity belongs to."
-  })
-});
-
-/**
- * Types of fields that can be used as an ID.
- */
-const VALID_ID_TYPES = ["text", "number", "email", "url", "date"];
-
-/**
- * Generate a schema for the collection based on the collection's schema in PocketBase.
- * By default, a basic schema is returned if no other schema is available.
- * If superuser credentials are provided, the schema is fetched from the PocketBase API.
- * If a path to a local schema file is provided, the schema is read from the file.
- *
- * @param options Options for the loader. See {@link PocketBaseLoaderOptions} for more details.
- * @param token The superuser token to authenticate the request.
- */
-// oxlint-disable-next-line explicit-module-boundary-types
-export async function generateSchema(
-  options: PocketBaseLoaderOptions,
-  token: string | undefined
-) {
-  let collection: PocketBaseCollection | undefined;
-
-  if (token) {
-    // Try to get the schema directly from the PocketBase instance
-    collection = await getRemoteSchema(options, token);
-  }
-
-  const hasSuperuserRights = !!collection || !!options.superuserCredentials;
-
-  // If the schema is not available, try to read it from a local schema file
-  if (!collection && options.localSchema) {
-    collection = await readLocalSchema(
-      options.localSchema,
-      options.collectionName
-    );
-  }
-
-  // If the schema is still not available, return the basic schema
-  if (!collection) {
-    console.error(
-      `No schema available for "${options.collectionName}". Only basic types are available. Please check your configuration and provide a valid schema file or superuser credentials.`
-    );
-    // Return the basic schema since every collection has at least these fields
-    return BASIC_SCHEMA;
-  }
-
-  // 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,
-    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.shape,
-    ...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 the custom id field is present
- */
-function checkCustomIdField(
-  collection: PocketBaseCollection,
-  options: PocketBaseLoaderOptions
-): void {
-  if (!options.idField) {
-    return;
-  }
-
-  // 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(s) are present
- */
-function checkContentField(
-  fields: Record<string, z.ZodType>,
-  options: PocketBaseLoaderOptions
-): void {
-  if (
-    typeof options.contentFields === "string" &&
-    !fields[options.contentFields]
-  ) {
-    console.error(
-      `The content field "${options.contentFields}" is not present in the schema of the collection "${options.collectionName}".`
-    );
-  } else if (Array.isArray(options.contentFields)) {
-    for (const field of options.contentFields) {
-      if (!fields[field]) {
-        console.error(
-          `The content field "${field}" is not present in the schema of the collection "${options.collectionName}".`
-        );
-      }
-    }
-  }
-}
-
-/**
- * Check if the updated field is present
- */
-function checkUpdatedField(
-  fields: Record<string, z.ZodType>,
-  collection: PocketBaseCollection,
-  options: PocketBaseLoaderOptions
-): void {
-  if (!options.updatedField) {
-    return;
-  }
-
-  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?.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!`
-      );
-    }
-  }
-}

package/src/schema/generate-type.ts

@@ -1,23 +0,0 @@
-import type { ZodObject, ZodPipe } from "astro/zod";
-import {
-  createAuxiliaryTypeStore,
-  createTypeAlias,
-  printNode,
-  zodToTs
-} from "zod-to-ts";
-
-/**
- * Generate a TypeScript type from a Zod schema.
- */
-export function generateType(schema: ZodObject | ZodPipe): string {
-  // If the collection contains file fields, we transform the field values to file urls in a `transform` step.
-  // This means that the schema for the types is different from the schema for the data, so we need to extract the inner schema for the types.
-  const schemaForTypes = schema.type === "pipe" ? schema.in : schema;
-
-  const { node } = zodToTs(schemaForTypes, {
-    auxiliaryTypeStore: createAuxiliaryTypeStore()
-  });
-  const typeAlias = createTypeAlias(node, "Entry");
-
-  return `export ${printNode(typeAlias)}`;
-}

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

@@ -1,43 +0,0 @@
-import { pocketBaseErrorResponse } from "../types/pocketbase-api-response.type";
-import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
-import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
-import { pocketBaseCollection } from "../types/pocketbase-schema.type";
-
-/**
- * Fetches the schema for the specified collection from the PocketBase instance.
- *
- * @param options Options for the loader. See {@link PocketBaseLoaderOptions} for more details.
- * @param token The superuser token to authenticate the request.
- */
-export async function getRemoteSchema(
-  options: Pick<PocketBaseLoaderOptions, "collectionName" | "url">,
-  token: string
-): Promise<PocketBaseCollection | undefined> {
-  // Build URL and headers for the schema request
-  const schemaUrl = new URL(
-    `api/collections/${options.collectionName}`,
-    options.url
-  ).href;
-  const schemaHeaders = new Headers();
-  schemaHeaders.set("Authorization", token);
-
-  // Fetch the schema
-  const schemaRequest = await fetch(schemaUrl, {
-    headers: schemaHeaders
-  });
-
-  // If the request was not successful, try another method
-  if (!schemaRequest.ok) {
-    const errorResponse = pocketBaseErrorResponse.parse(
-      await schemaRequest.json()
-    );
-    const errorMessage = `Fetching schema from ${options.collectionName} failed with status code ${schemaRequest.status}.\nReason: ${errorResponse.message}`;
-    console.error(errorMessage);
-
-    return undefined;
-  }
-
-  // Get the schema from the response
-  const response = pocketBaseCollection.parse(await schemaRequest.json());
-  return response;
-}

package/src/schema/parse-schema.ts

@@ -1,170 +0,0 @@
-import { z } from "astro/zod";
-import type {
-  PocketBaseCollection,
-  PocketBaseSchemaEntry
-} from "../types/pocketbase-schema.type";
-
-export interface ParseSchemaOptions {
-  hasSuperuserRights: 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,
-  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 && !options.hasSuperuserRights) {
-      if (options.fieldsToInclude) {
-        console.warn(
-          `"${field.name}" is requested but hidden. Provide superuser credentials to include this field.`
-        );
-      }
-
-      continue;
-    }
-
-    let fieldType: z.ZodType;
-
-    // Determine the field type and create the corresponding Zod type
-    switch (field.type) {
-      case "number":
-        fieldType = z.number();
-        break;
-      case "bool":
-        fieldType = z.boolean();
-        break;
-      case "date":
-      case "autodate":
-        if (options.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;
-      case "geoPoint":
-        fieldType = z.object({
-          lon: z.number(),
-          lat: z.number()
-        });
-        break;
-      case "select": {
-        if (!field.values) {
-          throw new Error(
-            `Field ${field.name} is of type "select" but has no values defined.`
-          );
-        }
-
-        // Create an enum for the select values
-        // oxlint-disable-next-line no-unsafe-type-assertion
-        const values = z.enum(field.values as [string, ...Array<string>]);
-
-        // Parse the field type based on the number of values it can have
-        fieldType = parseSingleOrMultipleValues(field, values);
-        break;
-      }
-      case "relation":
-      case "file":
-        // NOTE: Relations are currently not supported and are treated as strings
-        // NOTE: Files are later transformed to URLs
-
-        // Parse the field type based on the number of values it can have
-        fieldType = parseSingleOrMultipleValues(field, z.string());
-        break;
-      case "json":
-        // Use the user defined custom schema for the field or fallback to unknown
-        fieldType = customSchemas?.[field.name] ?? z.unknown();
-        break;
-      default:
-        // Default to a string
-        fieldType = z.string();
-        break;
-    }
-
-    const isRequired =
-      // Check if the field is required
-      field.required ||
-      // `onCreate autodate` fields are always set
-      (field.type === "autodate" && field.onCreate) ||
-      // number and bool fields are always set
-      field.type === "number" ||
-      field.type === "bool";
-
-    // If the field is not required, mark it as optional
-    if (!isRequired) {
-      fieldType = z.preprocess(
-        (val) => val || undefined,
-        z.optional(fieldType)
-      );
-    }
-
-    // Add the field to the fields object
-    fields[field.name] = fieldType.meta({
-      id: field.id,
-      title: field.name,
-      description: getFieldDescription(field)
-    });
-  }
-
-  return fields;
-}
-
-/**
- * Parse the field type based on the number of values it can have
- *
- * @param field Field to parse
- * @param type Type of each value
- *
- * @returns The parsed field type
- */
-function parseSingleOrMultipleValues(
-  field: PocketBaseSchemaEntry,
-  type: z.ZodType
-): z.ZodType {
-  // If the select allows multiple values, create an array of the enum
-  if (field.maxSelect === undefined || field.maxSelect === 1) {
-    return type;
-  }
-
-  return z.array(type);
-}
-
-/**
- * Get the description for a field based on its help text and type.
- */
-function getFieldDescription(field: PocketBaseSchemaEntry): string | undefined {
-  switch (true) {
-    case !!field.help:
-      return field.help;
-    case field.type === "autodate" && field.onUpdate:
-      return "Date when the entry was last updated. This field is automatically updated by PocketBase whenever the entry is updated.";
-    case field.type === "autodate" && field.onCreate:
-      return "Date when the entry was created. This field is automatically set by PocketBase when the entry is created.";
-    case field.name === "id":
-      return "The unique identifier for the entry.";
-    case field.hidden:
-      return "This field is hidden and may require superuser credentials to access.";
-    default:
-      return undefined;
-  }
-}

package/src/schema/read-local-schema.ts

@@ -1,46 +0,0 @@
-import fs from "fs/promises";
-import path from "path";
-import type { PocketBaseCollection } from "../types/pocketbase-schema.type";
-import { pocketBaseDatabase } from "../types/pocketbase-schema.type";
-
-/**
- * Reads the local PocketBase schema file and returns the schema for the specified collection.
- *
- * @param localSchemaPath Path to the local schema file.
- * @param collectionName Name of the collection to get the schema for.
- */
-export async function readLocalSchema(
-  localSchemaPath: string,
-  collectionName: string
-): Promise<PocketBaseCollection | undefined> {
-  const realPath = path.join(process.cwd(), localSchemaPath);
-
-  try {
-    // Read the schema file
-    const schemaFile = await fs.readFile(realPath, "utf-8");
-    const fileContent = pocketBaseDatabase.safeParse(JSON.parse(schemaFile));
-
-    // Check if the database file is valid
-    if (!fileContent.success) {
-      throw new Error("Invalid schema file");
-    }
-
-    // Find and return the schema for the collection
-    const schema = fileContent.data.find(
-      (collection) => collection.name === collectionName
-    );
-
-    if (!schema) {
-      throw new Error(
-        `Collection "${collectionName}" not found in schema file`
-      );
-    }
-
-    return schema;
-  } catch (error) {
-    console.error(
-      `Failed to read local schema from ${localSchemaPath}. No types will be generated.\nReason: ${error}`
-    );
-    return undefined;
-  }
-}

package/src/schema/transform-files.ts

@@ -1,67 +0,0 @@
-import { z } from "astro/zod";
-import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
-import type { PocketBaseSchemaEntry } from "../types/pocketbase-schema.type";
-
-/**
- * Transforms file names in a PocketBase entry to file URLs.
- *
- * @param baseUrl URL of the PocketBase instance.
- * @param collection Collection of the entry.
- * @param entry Entry to transform.
- */
-export function transformFiles(
-  baseUrl: string,
-  fileFields: Array<PocketBaseSchemaEntry>,
-  entry: PocketBaseEntry
-): PocketBaseEntry {
-  // Transform all file names to file URLs
-  for (const field of fileFields) {
-    const fieldName = field.name;
-
-    if (field.maxSelect === 1) {
-      const fileName = z.optional(z.string()).parse(entry[fieldName]);
-      // Check if a file name is present
-      if (!fileName) {
-        continue;
-      }
-
-      // Transform the file name to a file URL
-      entry[fieldName] = transformFileUrl(
-        baseUrl,
-        entry.collectionName,
-        entry.id,
-        fileName
-      );
-    } else {
-      const fileNames = z.optional(z.array(z.string())).parse(entry[fieldName]);
-      // Check if file names are present
-      if (!fileNames) {
-        continue;
-      }
-
-      // Transform all file names to file URLs
-      entry[fieldName] = fileNames.map((file) =>
-        transformFileUrl(baseUrl, entry.collectionName, entry.id, file)
-      );
-    }
-  }
-
-  return entry;
-}
-
-/**
- * Transforms a file name to a PocketBase file URL.
- *
- * @param base Base URL of the PocketBase instance.
- * @param collectionName Name of the collection.
- * @param entryId ID of the entry.
- * @param file Name of the file.
- */
-export function transformFileUrl(
-  base: string,
-  collectionName: string,
-  entryId: string,
-  file: string
-): string {
-  return new URL(`api/files/${collectionName}/${entryId}/${file}`, base).href;
-}

package/src/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "extends": "../tsconfig.json",
-  "include": ["./**/*"],
-  "compilerOptions": {
-    "noUncheckedIndexedAccess": true
-  }
-}

package/src/types/errors.ts

@@ -1,19 +0,0 @@
-import { LiveCollectionError } from "astro/content/runtime";
-
-/**
- * Error thrown when there is an authentication issue with PocketBase.
- */
-export class PocketBaseAuthenticationError extends LiveCollectionError {
-  constructor(collection: string, message: string) {
-    super(collection, message);
-    this.name = "PocketBaseAuthenticationError";
-  }
-
-  static is(error: unknown): error is PocketBaseAuthenticationError {
-    // This is similar to the original implementation in Astro itself.
-    return (
-      // oxlint-disable-next-line no-unsafe-type-assertion
-      !!error && (error as Error).name === "PocketBaseAuthenticationError"
-    );
-  }
-}

package/src/types/pocketbase-api-response.type.ts

@@ -1,40 +0,0 @@
-import { z } from "astro/zod";
-import { pocketBaseEntry } from "./pocketbase-entry.type";
-
-/**
- * The schema for a PocketBase error response.
- */
-export const pocketBaseErrorResponse = z.object({
-  /**
-   * The error message returned by PocketBase.
-   */
-  message: z.string()
-});
-
-/**
- * The schema for a PocketBase list response.
- */
-export const pocketBaseListResponse = z.object({
-  /**
-   * Current page number.
-   */
-  page: z.number(),
-  /**
-   * Total number of pages available.
-   */
-  totalPages: z.number(),
-  /**
-   * Array of items in the current page.
-   */
-  items: z.array(pocketBaseEntry)
-});
-
-/**
- * The schema for a PocketBase login response.
- */
-export const pocketBaseLoginResponse = z.object({
-  /**
-   * The authentication token returned by PocketBase.
-   */
-  token: z.string()
-});

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

@@ -1,24 +0,0 @@
-import { z } from "astro/zod";
-
-/**
- * Schema for a PocketBase entry.
- */
-export const pocketBaseEntry = z.looseObject({
-  /**
-   * ID of the entry.
-   */
-  id: z.string(),
-  /**
-   * ID of the collection the entry belongs to.
-   */
-  collectionId: z.string(),
-  /**
-   * Name of the collection the entry belongs to.
-   */
-  collectionName: z.string()
-});
-
-/**
- * Type for a PocketBase entry.
- */
-export type PocketBaseEntry = z.infer<typeof pocketBaseEntry>;