astro-loader-pocketbase 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 pawcode Development
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,10 @@
-# astro-pocketbase-loader
+# astro-loader-pocketbase
+
+<!-- ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/pawcoding/astro-loader-pocketbase/release.yaml?style=flat-square) -->
+[![NPM Version](https://img.shields.io/npm/v/astro-loader-pocketbase?style=flat-square)](https://www.npmjs.com/package/astro-loader-pocketbase)
+[![NPM Downloads](https://img.shields.io/npm/dw/astro-loader-pocketbase?style=flat-square)](https://www.npmjs.com/package/astro-loader-pocketbase)
+[![GitHub License](https://img.shields.io/github/license/pawcoding/astro-loader-pocketbase?style=flat-square)](https://github.com/pawcoding/astro-loader-pocketbase/blob/master/LICENSE)
+[![Discord](https://img.shields.io/discord/484669557747875862?style=flat-square&label=Discord)](https://discord.gg/GzgTh4hxrx)
 
 This package is a simple loader to load data from a PocketBase database into Astro using the [Astro Loader API](https://5-0-0-beta.docs.astro.build/en/reference/loader-reference/) introduced in Astro 5.
 
@@ -19,12 +25,36 @@ const blog = defineCollection({
 });
 ```
 
+By default, the loader will only fetch entries that have been modified since the last build.
+Remember that due to the nature [Astros Content Layer lifecycle](https://astro.build/blog/content-layer-deep-dive#content-layer-lifecycle), the loader will **only fetch entries at build time**, even when using on-demand rendering.
+If you want to update your deployed site with new entries, you need to rebuild it.
+
+<sub>When running the dev server, you can trigger a reload by using `s + enter`.</sub>
+
 ### Type Generation
 
 The loader can automatically generate types for your collection.
-To do this, you need to provide the email and password of an admin of the PocketBase instance.
+This is useful for type checking and autocompletion in your editor.
+These types can be generated in two ways:
+
+#### Remote Schema
+
+To use the lice remote schema, you need to provide the email and password of an admin of the PocketBase instance.
 Under the hood, the loader will use the [PocketBase API](https://pocketbase.io/docs/api-collections/#view-collection) to fetch the schema of your collection and generate types with Zod based on that schema.
 
+#### Local Schema
+
+If you don't want to provide the admin credentials (e.g. in a public repository), you can also provide the schema manually via a JSON file.
+In PocketBase you can export the schema of the whole database to a `pb_schema.json` file.
+If you provide the path to this file, the loader will use this schema to generate the types locally.
+
+When admin credentials are provided, the loader will **always use the remote schema** since it's more up-to-date.
+
+#### Manual Schema
+
+If you don't want to use the automatic type generation, you can also [provide your own schema manually](https://5-0-0-beta.docs.astro.build/en/guides/content-collections/#defining-the-collection-schema).
+This manual schema will **always override the automatic type generation**.
+
 ### Private Collections
 
 If you want to access a private collection, you also need to provide the admin credentials.
@@ -39,4 +69,5 @@ Otherwise, you need to make the collection public in the PocketBase dashboard.
 | `content`        | `string \| Array<string>` | x        | The field in the collection to use as content. This can also be an array of fields.                                                 |
 | `adminEmail`     | `string`                  |          | The email of the admin of the PocketBase instance. This is used for automatic type generation and access to private collections.    |
 | `adminPassword`  | `string`                  |          | The password of the admin of the PocketBase instance. This is used for automatic type generation and access to private collections. |
+| `localSchema`    | `string`                  |          | The path to a local schema file. This is used for automatic type generation.                                                        |
 | `forceUpdate`    | `boolean`                 |          | If set to `true`, the loader will fetch every entry instead of only the ones modified since the last build.                         |

package/package.json

@@ -1,38 +1,41 @@
 {
   "name": "astro-loader-pocketbase",
+  "version": "0.2.1",
   "description": "A content loader for Astro that uses the PocketBase API",
+  "license": "MIT",
+  "author": "Luis Wolf <development@pawcode.de> (https://pawcode.de)",
   "homepage": "https://github.com/pawcoding/astro-loader-pocketbase",
-  "version": "0.1.0",
   "type": "module",
   "exports": {
     ".": "./index.ts"
   },
   "files": [
-    "src",
-    "index.ts"
+    "index.ts",
+    "src"
   ],
-  "author": {
-    "name": "Luis Wolf",
-    "email": "development@pawcode.de",
-    "url": "https://pawcode.de"
-  },
-  "keywords": [
-    "withastro",
-    "astro",
-    "astro-loader",
-    "astro-content-loader",
-    "pocketbase"
-  ],
-  "scripts": {},
-  "devDependencies": {
-    "astro": "^5.0.0-beta.1"
+  "scripts": {
+    "lint": "npx eslint",
+    "prepare": "husky"
   },
   "peerDependencies": {
     "astro": "^5.0.0"
   },
-  "dependencies": {
-    "@astrojs/check": "^0.9.3",
-    "typescript": "^5.6.2"
+  "devDependencies": {
+    "@eslint/js": "^9.11.1",
+    "@stylistic/eslint-plugin": "^2.8.0",
+    "@types/node": "^22.5.5",
+    "astro": "^5.0.0-beta.1",
+    "eslint": "^9.11.1",
+    "globals": "^15.9.0",
+    "husky": "^9.1.6",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.7.0"
   },
-  "license": "MIT"
+  "keywords": [
+    "astro",
+    "astro-content-loader",
+    "astro-loader",
+    "pocketbase",
+    "withastro"
+  ]
 }

package/src/generate-schema.ts

@@ -1,8 +1,10 @@
 import type { ZodSchema } from "astro/zod";
 import { z } from "astro/zod";
 import type { PocketBaseLoaderOptions } from "./types/pocketbase-loader-options.type";
-import { getAdminToken } from "./utils/get-admin-token";
+import type { PocketBaseSchemaEntry } from "./types/pocketbase-schema.type";
+import { getRemoteSchema } from "./utils/get-remote-schema";
 import { parseSchema } from "./utils/parse-schema";
+import { readLocalSchema } from "./utils/read-local-schema";
 
 /**
  * Basic schema for every PocketBase collection.
@@ -24,57 +26,26 @@ const BASIC_SCHEMA = {
 export async function generateSchema(
   options: PocketBaseLoaderOptions
 ): Promise<ZodSchema> {
-  // TODO: Add support for local schema files
+  let schema: Array<PocketBaseSchemaEntry> | undefined;
 
-  // If no admin email and password are provided, we can't get the schema from the API
-  if (!options.adminEmail || !options.adminPassword) {
-    console.warn(
-      "Make sure to add an admin email and password to the config to get automatic type generation."
-    );
+  // Try to get the schema directly from the PocketBase instance
+  schema = await getRemoteSchema(options);
 
-    // Return the basic schema
-    return z.object(BASIC_SCHEMA);
+  // If the schema is not available, try to read it from a local schema file
+  if (!schema && options.localSchema) {
+    schema = await readLocalSchema(options.localSchema, options.collectionName);
   }
 
-  // Get the admin token
-  const token = await getAdminToken(
-    options.url,
-    options.adminEmail,
-    options.adminPassword
-  );
-
-  // If the token is invalid, return the basic schema
-  if (!token) {
-    return z.object(BASIC_SCHEMA);
-  }
-
-  // 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, return the basic schema
-  if (!schemaRequest.ok) {
-    const reason = await schemaRequest.json().then((data) => data.message);
-    const errorMessage = `Fetching schema from ${options.collectionName} failed with status code ${schemaRequest.status}.\nReason: ${reason}`;
-    console.error(errorMessage);
-
+  // If the schema is still not available, return the basic schema
+  if (!schema) {
+    console.error(
+      `No schema available for ${options.collectionName}. Only basic types are available. Please check your configuration and provide a valid schema file or admin credentials.`
+    );
     return z.object(BASIC_SCHEMA);
   }
 
-  // Get the schema from the response
-  const schema = await schemaRequest.json();
-
   // Parse the schema
-  const fields = parseSchema(schema.schema);
+  const fields = parseSchema(schema);
 
   // Check if the content field is present
   if (typeof options.content === "string" && !fields[options.content]) {

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

@@ -0,0 +1,30 @@
+/**
+ * Base interface for all PocketBase entries.
+ */
+interface PocketBaseBaseEntry {
+  /**
+   * ID of the entry.
+   */
+  id: string;
+  /**
+   * ID of the collection the entry belongs to.
+   */
+  collectionId: string;
+  /**
+   * Name of the collection the entry belongs to.
+   */
+  collectionName: string;
+  /**
+   * Date the entry was created.
+   */
+  created: string;
+  /**
+   * Date the entry was last updated.
+   */
+  updated: string;
+}
+
+/**
+ * Type for a PocketBase entry.
+ */
+export type PocketBaseEntry = PocketBaseBaseEntry & Record<string, unknown>;

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

@@ -1,7 +1,7 @@
 /**
  * Options for the PocketBase loader.
  */
-export type PocketBaseLoaderOptions = {
+export interface PocketBaseLoaderOptions {
   /**
    * URL of the PocketBase instance.
    */
@@ -30,9 +30,15 @@ export type PocketBaseLoaderOptions = {
    * Together with `adminEmail` this is required to get automatic type generation and to access all resources even if they are not public.
    */
   adminPassword?: string;
+  /**
+   * File path to the local schema file.
+   * This file will be used to generate the schema for the collection.
+   * If admin credentials are provided (see `adminEmail` and `adminPassword`), this option will be ignored.
+   */
+  localSchema?: string;
   /**
    * By default, the loader will only fetch entries that have been modified since the last fetch.
    * If you want to fetch all entries, set this to `true`.
    */
   forceUpdate?: boolean;
-};
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Entry for a collections schema in PocketBase.
+ */
+export interface PocketBaseSchemaEntry {
+  /**
+   * Name of the field.
+   */
+  name: string;
+  /**
+   * Type of the field.
+   */
+  type: string;
+  /**
+   * Whether the field is required.
+   */
+  required: boolean;
+  /**
+   * Options for the field.
+   */
+  options: {
+    /**
+     * Values for a select field.
+     * This is only present if the field type is "select".
+     */
+    values?: Array<string>;
+    /**
+     * Maximum number of values for a select field.
+     * This is only present on "select", "relation", and "file" fields.
+     */
+    maxSelect?: number;
+  };
+}
+
+/**
+ * Schema for a PocketBase collection.
+ */
+export interface PocketBaseCollection {
+  /**
+   * Name of the collection.
+   */
+  name: string;
+  /**
+   * Schema of the collection.
+   */
+  schema: Array<PocketBaseSchemaEntry>;
+}

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

@@ -0,0 +1,57 @@
+import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.type";
+import type {
+  PocketBaseCollection,
+  PocketBaseSchemaEntry
+} from "../types/pocketbase-schema.type";
+import { getAdminToken } from "./get-admin-token";
+
+/**
+ * Fetches the schema for the specified collection from the PocketBase instance.
+ *
+ * @param options Options for the loader. See {@link PocketBaseLoaderOptions} for more details.
+ */
+export async function getRemoteSchema(
+  options: PocketBaseLoaderOptions
+): Promise<Array<PocketBaseSchemaEntry> | undefined> {
+  if (!options.adminEmail || !options.adminPassword) {
+    return undefined;
+  }
+
+  // Get the admin token
+  const token = await getAdminToken(
+    options.url,
+    options.adminEmail,
+    options.adminPassword
+  );
+
+  // If the token is invalid, return the basic schema
+  if (!token) {
+    return 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, return the basic schema
+  if (!schemaRequest.ok) {
+    const reason = await schemaRequest.json().then((data) => data.message);
+    const errorMessage = `Fetching schema from ${options.collectionName} failed with status code ${schemaRequest.status}.\nReason: ${reason}`;
+    console.error(errorMessage);
+
+    return undefined;
+  }
+
+  // Get the schema from the response
+  const schema: PocketBaseCollection = await schemaRequest.json();
+  return schema.schema;
+}

package/src/utils/parse-entry.ts

@@ -1,4 +1,5 @@
 import type { LoaderContext } from "astro/loaders";
+import type { PocketBaseEntry } from "../types/pocketbase-base.type";
 
 /**
  * Parse an entry from PocketBase to match the schema and store it in the store.
@@ -9,7 +10,7 @@ import type { LoaderContext } from "astro/loaders";
  *                      If multiple fields are used, they will be concatenated and wrapped in `<section>` elements.
  */
 export async function parseEntry(
-  entry: Record<string, any>,
+  entry: PocketBaseEntry,
   { generateDigest, parseData, store }: LoaderContext,
   contentFields: string | Array<string>
 ): Promise<void> {
@@ -28,7 +29,7 @@ export async function parseEntry(
   let content: string;
   if (typeof contentFields === "string") {
     // Only one field is used as content
-    content = entry[contentFields];
+    content = `${entry[contentFields]}`;
   } else {
     // Multiple fields are used as content, wrap each block in a section and concatenate them
     content = contentFields

package/src/utils/parse-schema.ts

@@ -1,7 +1,8 @@
 import { z } from "astro/zod";
+import type { PocketBaseSchemaEntry } from "../types/pocketbase-schema.type";
 
 export function parseSchema(
-  schema: Array<Record<string, any>>
+  schema: Array<PocketBaseSchemaEntry>
 ): Record<string, z.ZodType> {
   // Prepare the schemas fields
   const fields: Record<string, z.ZodType> = {};
@@ -25,18 +26,25 @@ export function parseSchema(
         fieldType = z.date({ coerce: true });
         break;
       case "select":
+        if (!field.options.values) {
+          throw new Error(
+            `Field ${field.name} is of type "select" but has no values defined.`
+          );
+        }
+
         // Create an enum for the select values
+        // @ts-expect-error - Zod complains because the values are not known at compile time and thus the array is not static.
         const values = z.enum(field.options.values);
 
         // Parse the field type based on the number of values it can have
-        fieldType = parseSingleOrMultipleValues(field as any, values);
+        fieldType = parseSingleOrMultipleValues(field, values);
         break;
       case "relation":
       case "file":
         // NOTE: Relations and files are currently not supported and are treated as strings
 
         // Parse the field type based on the number of values it can have
-        fieldType = parseSingleOrMultipleValues(field as any, z.string());
+        fieldType = parseSingleOrMultipleValues(field, z.string());
         break;
       case "json":
         // Parse the field as an object
@@ -69,11 +77,11 @@ export function parseSchema(
  * @returns The parsed field type
  */
 function parseSingleOrMultipleValues(
-  field: { options: { maxSelect: number } },
+  field: PocketBaseSchemaEntry,
   type: z.ZodType
 ) {
   // If the select allows multiple values, create an array of the enum
-  if (field.options.maxSelect === 1) {
+  if (field.options.maxSelect === undefined || field.options.maxSelect === 1) {
     return type;
   } else {
     return z.array(type);

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

@@ -0,0 +1,48 @@
+import fs from "fs/promises";
+import path from "path";
+import type {
+  PocketBaseCollection,
+  PocketBaseSchemaEntry
+} 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<Array<PocketBaseSchemaEntry> | undefined> {
+  const realPath = path.join(process.cwd(), localSchemaPath);
+
+  try {
+    // Read the schema file
+    const schemaFile = await fs.readFile(realPath, "utf-8");
+    const database: Array<PocketBaseCollection> = JSON.parse(schemaFile);
+
+    // Check if the database file is valid
+    if (!database || !Array.isArray(database)) {
+      throw new Error("Invalid schema file");
+    }
+
+    // Find and return the schema for the collection
+    const schema = database.find(
+      (collection) => collection.name === collectionName
+    );
+
+    if (!schema) {
+      throw new Error(
+        `Collection "${collectionName}" not found in schema file`
+      );
+    }
+
+    return schema.schema;
+  } catch (error) {
+    console.error(
+      `Failed to read local schema from ${localSchemaPath}. No types will be generated.\nReason: ${error}`
+    );
+    return undefined;
+  }
+}