astro-loader-pocketbase 0.1.0 → 0.2.0

package/README.md

@@ -19,12 +19,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 +63,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

@@ -2,7 +2,7 @@
   "name": "astro-loader-pocketbase",
   "description": "A content loader for Astro that uses the PocketBase API",
   "homepage": "https://github.com/pawcoding/astro-loader-pocketbase",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": "./index.ts"
@@ -25,14 +25,12 @@
   ],
   "scripts": {},
   "devDependencies": {
-    "astro": "^5.0.0-beta.1"
+    "@types/node": "^22.5.5",
+    "astro": "^5.0.0-beta.1",
+    "typescript": "^5.6.2"
   },
   "peerDependencies": {
     "astro": "^5.0.0"
   },
-  "dependencies": {
-    "@astrojs/check": "^0.9.3",
-    "typescript": "^5.6.2"
-  },
   "license": "MIT"
 }

package/src/generate-schema.ts

@@ -1,8 +1,9 @@
 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 { 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 +25,26 @@ const BASIC_SCHEMA = {
 export async function generateSchema(
   options: PocketBaseLoaderOptions
 ): Promise<ZodSchema> {
-  // TODO: Add support for local schema files
+  let schema: Array<Record<string, any>> | 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-loader-options.type.ts

@@ -30,6 +30,12 @@ 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`.

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

@@ -0,0 +1,53 @@
+import type { PocketBaseLoaderOptions } from "../types/pocketbase-loader-options.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<Record<string, any>> | 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 = await schemaRequest.json();
+  return schema.schema;
+}

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

@@ -0,0 +1,37 @@
+import fs from "fs/promises";
+import path from "path";
+
+/**
+ * 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<Record<string, any>> | undefined> {
+  const realPath = path.join(process.cwd(), localSchemaPath);
+
+  try {
+    // Read the schema file
+    const schemaFile = await fs.readFile(realPath, "utf-8");
+    const database = 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
+    );
+    return schema.schema;
+  } catch (error) {
+    console.error(
+      `Failed to read local schema from ${localSchemaPath}. No types will be generated.\nReason: ${error}`
+    );
+    return undefined;
+  }
+}