astro-relatinator 2.0.0 → 2.1.0

package/README.md

@@ -47,35 +47,42 @@ export default defineConfig({
 
 ## Usage
 
-The integration hooks into the Astro build (or dev) process, and will train the model based on the files you've provided. You can then use the `findRelated` function from the package to find related content.
+The integration hooks into the Astro build (or dev) process, and will train the model based on the files you've provided. You can then use the utility functions exported by the package (`BM25Utils` or `TfIdfUtils`, depending on your chosen `similarityMethod`) to find related content and terms.
 
 ### Example:
 
 ```astro
 ---
 import { getCollection } from "astro:content";
-import { findRelated } from "astro-relatinator";
+// Import the utils corresponding to your configured similarityMethod
+// (BM25Utils in this example, matching the config example above)
+import { BM25Utils } from "astro-relatinator";
 
 const blogEntries = await getCollection("posts"); // assuming your collection is called posts
 // let's say we want to compare against the first blog entry
 const first = blogEntries[0];
 
 // Concatenate the same fields we used for training and declare how many related posts we want to find
-const related = findRelated(`${first.frontmatter.title} ${first.frontmatter.description} ${first.frontmatter.tags.join(' ')} ${first.body}`, first.id, 3)
+const related = await BM25Utils.findRelated(`${first.data.title} ${first.data.description} ${first.data.tags.join(' ')} ${first.body}`, first.id, 3)
 
 ---
 
 <div>
 <!-- render your related posts here -->
 { related.map((id) => {
-  const post = posts.find((post) => post.id === id);
+  const post = blogEntries.find((post) => post.id === id);
+  if (!post) return null; // Handle case where post might not be found
   return (
-    <a href={post.slug}>
-      <h2>{post.frontmatter.title}</h2>
-      <p>{post.frontmatter.description}</p>
+    <a href={`/posts/${post.slug}/`}> {/* Adjust href based on your routing */}
+      <h2>{post.data.title}</h2>
+      <p>{post.data.description}</p>
     </a>
   );
 }) }
 </div>
 
 ```
+
+**Note:** The `BM25Utils` and `TfIdfUtils` objects also provide `getTopTermsForId` and `getTopRelatedDocumentsForTerm` functions, similar to the core `relatinator` library.
+
+**Development Server:** When running `astro dev`, the integration uses debouncing (a small delay) before re-training the model after a markdown file change. This improves performance for larger sites by preventing rapid, successive re-trains during saves.

package/integration.ts

@@ -1,6 +1,6 @@
 import type { AstroIntegration } from "astro";
 import path from "node:path";
-import { train, getInstance } from "relatinator";
+import { TfIdfUtils, BM25Utils } from "relatinator";
 import { glob } from "glob";
 import matter from "gray-matter";
 import fs from "node:fs/promises";
@@ -11,7 +11,12 @@ async function writeDebug(message: string) {
   console.log("[astro-relatinator]", message);
 }
 
-async function trainModel(paths: string[], schema: string[], debug = false) {
+async function trainModel(
+  similarityMethod: "tfidf" | "bm25",
+  paths: string[],
+  schema: string[],
+  debug = false
+) {
   const documents: RelatinatorDocument[] = [];
 
   if (debug) {
@@ -62,7 +67,11 @@ async function trainModel(paths: string[], schema: string[], debug = false) {
   }
 
   // Train the existing instance
-  train(documents, debug);
+  if (similarityMethod === "tfidf") {
+    TfIdfUtils.train(documents, debug);
+  } else {
+    BM25Utils.train(documents, debug);
+  }
 }
 
 const stringifyData = (data: any): string => {
@@ -92,28 +101,50 @@ const relatinatorIntegration = ({
     name: "astro-relatinator",
     hooks: {
       "astro:server:setup": async ({ server, logger }) => {
+        let debounceTimeout: NodeJS.Timeout | null = null;
+        const debounceMs = 500; // Debounce delay in milliseconds
         logger.info("relatinator server:setup");
 
         logger.info(
           `Training Relatinator using ${similarityMethod} on existing data...`
         );
-        await getInstance(similarityMethod);
-        await trainModel(paths, schema, debug);
+        if (similarityMethod === "tfidf") {
+          await TfIdfUtils.getInstance();
+        } else {
+          await BM25Utils.getInstance();
+        }
+        await trainModel(similarityMethod, paths, schema, debug);
         logger.info("Initial training done.");
 
-        server.watcher.on("all", async (eventName, filePath) => {
+        server.watcher.on("all", (eventName, filePath) => {
           if (!["add", "change"].includes(eventName)) {
             return;
           }
 
           if (path.extname(filePath).includes("md")) {
-            logger.info(
-              `Markdown file changed: ${filePath}; Re-training ${similarityMethod}...`
-            );
-            await getInstance(similarityMethod);
-            await trainModel(paths, schema, debug);
-          } else {
-            return;
+            // Clear existing timer if there is one
+            if (debounceTimeout) {
+              clearTimeout(debounceTimeout);
+            }
+
+            // Set a new timer
+            debounceTimeout = setTimeout(async () => {
+              logger.info(
+                `Debounced: Markdown file changed: ${filePath}; Re-training ${similarityMethod}...`
+              );
+              try {
+                // Reset the instance before re-training
+                if (similarityMethod === "tfidf") {
+                  await TfIdfUtils.resetInstance();
+                } else {
+                  await BM25Utils.resetInstance();
+                }
+                await trainModel(similarityMethod, paths, schema, debug);
+                logger.info("Debounced re-training complete.");
+              } catch (error) {
+                logger.error(`Error during debounced re-training: ${error}`);
+              }
+            }, debounceMs);
           }
         });
       },
@@ -123,13 +154,17 @@ const relatinatorIntegration = ({
         logger.info(
           `Training Relatinator using ${similarityMethod} on existing data...`
         );
-        await getInstance(similarityMethod);
-        await trainModel(paths, schema, debug);
+        if (similarityMethod === "tfidf") {
+          await TfIdfUtils.getInstance();
+        } else {
+          await BM25Utils.getInstance();
+        }
+        await trainModel(similarityMethod, paths, schema, debug);
         logger.info(`Training done.`);
       },
     },
   };
 };
 
-export { findRelated, getInstance } from "relatinator";
+export { TfIdfUtils, BM25Utils };
 export default relatinatorIntegration;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-relatinator",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Find related content in your Astro website or app",
   "author": "Darko Bozhinovski <dbozhinovski@gmail.com>",
   "license": "MIT",
@@ -31,12 +31,12 @@
     "@types/node": "^22.13.4",
     "astro": ">=5",
     "husky": "^9.1.7",
-    "vite": "^6.1.0"
+    "vite": "^6.1.1"
   },
   "dependencies": {
     "glob": "^11.0.1",
     "gray-matter": "^4.0.3",
-    "relatinator": "2.0.0"
+    "relatinator": "2.1.0"
   },
   "peerDependencies": {
     "astro": ">=5"