astro-relatinator 2.0.1 → 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

@@ -101,6 +101,8 @@ 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(
@@ -114,23 +116,35 @@ const relatinatorIntegration = ({
         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}...`
-            );
-            if (similarityMethod === "tfidf") {
-              await TfIdfUtils.getInstance();
-            } else {
-              await BM25Utils.getInstance();
+            // Clear existing timer if there is one
+            if (debounceTimeout) {
+              clearTimeout(debounceTimeout);
             }
-            await trainModel(similarityMethod, paths, schema, debug);
-          } else {
-            return;
+
+            // 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);
           }
         });
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-relatinator",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Find related content in your Astro website or app",
   "author": "Darko Bozhinovski <dbozhinovski@gmail.com>",
   "license": "MIT",
@@ -36,7 +36,7 @@
   "dependencies": {
     "glob": "^11.0.1",
     "gray-matter": "^4.0.3",
-    "relatinator": "2.0.1"
+    "relatinator": "2.1.0"
   },
   "peerDependencies": {
     "astro": ">=5"