feat(entry): add option for custom id field (#14)

* chore(loader): add support for custom unique identifier

* fix(parse-entry): use custom entry ID if available

* refactor(*): update custom id field logic and documentation

* build(deps): update dependencies

* fix(cleanup): use PocketBase id in cleanup function

* fix(schema): check for presence of custom id field

* chore(release): 0.5.0-custom-id-rc.1

* fix(schema): check for valid type of custom id field

* fix(parse-entry): print warning for different entries with identical id

* chore(release): 0.5.0-custom-id-rc.2

* Fix typo

---------

Co-authored-by: Kibet Ishmael <kmishmael@gmail.com>
Co-authored-by: lujoho <104842986+lujoho@users.noreply.github.com>

Author: 3 people

README.md

@@ -62,6 +62,25 @@ While the API only returns the filenames of these images and files, the loader w
 This doesn't mean that the files are downloaded during the build process.
 But you can directly use these URLs in your Astro components to display images or link to the files.
 
+### Custom ids
+
+By default, the loader will use the `id` field of the collection as the unique identifier.
+If you want to use another field as the id, e.g. a slug of the title, you can specify this field via the `id` option.
+
+```ts
+const blog = defineCollection({
+  loader: pocketbaseLoader({
+    ...options,
+    id: "<field-in-collection>"
+  })
+});
+```
+
+Please note that the id should be unique for every entry in the collection.
+The loader will also automatically convert the value into a slug to be easily used in URLs.
+It's recommended to use e.g. the title of the entry to be easily searchable and readable.
+**Do not use e.g. rich text fields as ids.**
+
 ## Type generation
 
 The loader can automatically generate types for your collection.
@@ -116,6 +135,7 @@ This manual schema will **always override the automatic type generation**.
 | `content`        | `string \| Array<string>`     |          | 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. |
+| `id`             | `string`                      |          | The field in the collection to use as unique id. Defaults to `id`.                                              |
 | `localSchema`    | `string`                      |          | The path to a local schema file. This is used for automatic type generation.                                                        |
 | `jsonSchemas`    | `Record<string, z.ZodSchema>` |          | A record of Zod schemas to use for type generation of `json` fields.                                                                |
 | `forceUpdate`    | `boolean`                     |          | If set to `true`, the loader will fetch every entry instead of only the ones modified since the last build.                         |

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-loader-pocketbase",
-  "version": "0.4.0",
+  "version": "0.5.0-custom-id-rc.2",
   "description": "A content loader for Astro that uses the PocketBase API",
   "license": "MIT",
   "author": "Luis Wolf <development@pawcode.de> (https://pawcode.de)",
@@ -24,7 +24,7 @@
     "@eslint/js": "^9.11.1",
     "@stylistic/eslint-plugin": "^2.8.0",
     "@types/node": "^22.7.4",
-    "astro": "^5.0.0-beta.2",
+    "astro": "^5.0.0-beta.6",
     "eslint": "^9.11.1",
     "globals": "^15.9.0",
     "husky": "^9.1.6",

package.json

@@ -74,7 +74,7 @@ export async function cleanupEntries(
   let cleanedUp = 0;
 
   // Get all ids of the entries in the store
-  const storedIds = context.store.keys();
+  const storedIds = context.store.values().map((entry) => entry.data.id) as Array<string>;
   for (const id of storedIds) {
     // If the id is not in the entries set, remove the entry from the store
     if (!entries.has(id)) {

src/cleanup-entries.ts

@@ -11,7 +11,7 @@ import { transformFiles } from "./utils/transform-files";
  * Basic schema for every PocketBase collection.
  */
 const BASIC_SCHEMA = {
-  id: z.string().length(15),
+  id: z.string(),
   collectionId: z.string().length(15),
   collectionName: z.string(),
   created: z.coerce.date(),
@@ -29,6 +29,11 @@ const VIEW_SCHEMA = {
   updated: z.preprocess((val) => val || undefined, z.optional(z.coerce.date()))
 };
 
+/**
+ * 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.
@@ -65,6 +70,31 @@ export async function generateSchema(
   // Parse the schema
   const fields = parseSchema(collection, options.jsonSchemas);
 
+  // Check if custom id field is present
+  if (options.id) {
+    // Find the id field in the schema
+    const idField = collection.schema.find(
+      (field) => field.name === options.id
+    );
+
+    // Check if the id field is present and of a valid type
+    if (!idField) {
+      console.error(
+        `The id field "${options.id}" 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.id}" 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 is present
   if (typeof options.content === "string" && !fields[options.content]) {
     console.error(

src/generate-schema.ts

@@ -82,7 +82,7 @@ export async function loadEntries(
 
     // Parse and store the entries
     for (const entry of response.items) {
-      await parseEntry(entry, context, options.content);
+      await parseEntry(entry, context, options.id, options.content);
 
       // Check if the entry has an `updated` column
       // This is used to enable the incremental fetching of entries

src/load-entries.ts

@@ -12,6 +12,15 @@ export interface PocketBaseLoaderOptions {
    * Name of the collection in PocketBase.
    */
   collectionName: string;
+  /**
+   * 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.
+   */
+  id?: string;
   /**
    * Content of the collection in PocketBase.
    * This must be the name of a field in the collection that contains the content.

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

@@ -1,23 +1,48 @@
 import type { LoaderContext } from "astro/loaders";
 import type { PocketBaseEntry } from "../types/pocketbase-entry.type";
+import { slugify } from "./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 }: LoaderContext,
+  { generateDigest, parseData, store, logger }: LoaderContext,
+  idField?: string,
   contentFields?: string | Array<string>
 ): 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: entry.id,
+    id,
     data: entry
   });
 
@@ -30,7 +55,7 @@ export async function parseEntry(
   if (!contentFields) {
     // Store the entry
     store.set({
-      id: entry.id,
+      id,
       data,
       digest
     });
@@ -52,7 +77,7 @@ export async function parseEntry(
 
   // Store the entry
   store.set({
-    id: entry.id,
+    id,
     data,
     digest,
     rendered: {

src/utils/parse-entry.ts

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