@storecraft/database-mongodb 1.0.11 → 1.0.12

package/README.md

@@ -8,6 +8,7 @@
 [![MongoDB](https://github.com/store-craft/storecraft/actions/workflows/test.database-mongodb.yml/badge.svg)](https://github.com/store-craft/storecraft/actions/workflows/test.database-mongodb.yml)
 
 Official `mongodb` driver for `StoreCraft` on **Node.js** / **Deno** / **Bun** platforms.
+Also, an example of [Semantic Vector Search](https://www.mongodb.com/developer/products/atlas/semantic-search-mongodb-atlas-vector-search/) extension at `@storecraft/database-mongodb/vector-search-extension`
 
 ```bash
 npm i @storecraft/database-mongodb
@@ -20,8 +21,10 @@ import 'dotenv/config';
 import http from "node:http";
 import { App } from '@storecraft/core'
 import { NodePlatform } from '@storecraft/core/platform/node';
-import { MongoDB, migrateToLatest } from '@storecraft/database-mongodb'
+import { MongoDB } from '@storecraft/database-mongodb'
+import { migrateToLatest } from '@storecraft/database-mongodb/migrate.js'
 import { NodeLocalStorage } from '@storecraft/core/storage/node'
+import { MongoVectorSearch } from '@storecraft/database-mongodb/vector-search-extension'
 
 const app = new App(
   {
@@ -32,6 +35,9 @@ const app = new App(
 )
 .withPlatform(new NodePlatform())
 .withDatabase(new MongoDB({ db_name: 'test', url: '...', options: {}}))
+.withExtensions(
+  'mongo-vector-search': new MongoVectorSearch({ openai_key: process.env.OPENAI })
+)
 
 await app.init();
 await migrateToLatest(app.db, false);
@@ -45,6 +51,63 @@ const server = http.createServer(app.handler).listen(
 
 ```
 
+## (Recommended) setup semantic/ai vector search extension for products
+
+1. in [Atlas](https://cloud.mongodb.com/) dashboard, create a vector index (call it `vector_index`) for `products` collection:
+
+```json
+{
+  "fields": [
+    {
+      "numDimensions": 1536,
+      "path": "embedding",
+      "similarity": "cosine",
+      "type": "vector"
+    }
+  ]
+}
+```
+
+2. Now, every upserted product will be eligible for semantic search by it's title + description.
+3. The extension is publicly available via HTTP (`POST` request)
+```js
+await fetch(
+  'http://localhost:8000/api/extensions/mongo-vector-search/search',
+  {
+    method: 'POST',
+    body: JSON.stringify(
+      {
+        query: 'I am interested in Nintendo related clothing, such as shirts',
+        limit: 1
+      }
+    )
+  }
+)
+```
+
+returns `ProductType[]` array
+
+```json
+[
+  {
+    "title": "Super Mario T Shirt",
+    "handle": "super-mario-t-shirt",
+    "description": "This Super mario shirt is XL size and 
+    features a colorful print of Lugi and Mario.",
+    "media": [
+        "storage://images/super-mario-shirt_1738686680944_w_819_h_460.jpeg"
+    ],
+    "price": 100,
+    "qty": 1,
+    "active": true,
+    "id": "pr_67a240e4000000d34bcf0743",
+    "created_at": "2025-02-04T16:31:32.909Z",
+    "updated_at": "2025-02-04T16:58:25.286Z"
+  }
+]
+```
+
+
 ```text
 Author: Tomer Shalev <tomer.shalev@gmail.com>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storecraft/database-mongodb",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Storecraft database driver for mongodb on node / bun / deno platform",
   "license": "MIT",
   "author": "Tomer Shalev (https://github.com/store-craft)",
@@ -19,6 +19,15 @@
   "type": "module",
   "main": "index.js",
   "types": "./types.public.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./types.public.d.ts"
+    },
+    "./*": {
+      "import": "./*"
+    }
+  },
   "scripts": {
     "database-mongodb:test": "node ./tests/runner.test.js",
     "test": "npm run database-mongodb:test",

package/vector-search-extension.js

@@ -0,0 +1,110 @@
+/**
+ * @import {extension} from '@storecraft/core/extensions'
+ */
+import { MongoDB } from './index.js';
+/**
+ * 
+ * @typedef {object} Config
+ * @property {string} openai_key OpenAI key
+ */
+
+/**
+ * @implements {extension<Config>}
+ */
+export class MongoVectorSearch {
+  /** @param {Config} config  */
+  constructor(config) {
+    this.config = config
+  }
+
+  info = {
+    name: 'Mongo Vector Search',
+  }
+
+  /** @type {extension["onInit"]} */
+  onInit = (app) => {
+    this.app = app;
+    
+    app.pubsub.on(
+      'products/upsert',
+      async (evt) => {
+        const product = evt.payload.current;
+        // @ts-ignore
+        product.embedding = await embed_text(
+          `This product's title is ${product.title}, it's price is 
+          ${product.price} and has the following description 
+          ${product.description}`
+        );
+        console.log('Update Product ' + product.handle);
+      }
+    )
+  }
+
+  /** @type {extension["invokeAction"]} */
+  invokeAction = (handle) => {
+
+    if (handle==='search') {
+      /** @param {{query: string, limit:number}} args */
+      return async (args) => {
+
+        const db = (/** @type {MongoDB} */ (this.app.db));
+
+        return db.collection('products').aggregate(
+          [
+            {
+              "$vectorSearch": {
+                queryVector: await embed_text(
+                  args.query, this.config.openai_key
+                ),
+                path: "embedding",
+                exact: true,
+                limit: args.limit ?? 1,
+                index: "vector_index",
+              },
+            },
+            {
+              "$project": {
+                embedding: 0, _relations: 0, _id: 0
+              }
+            }
+          ],
+        ).toArray();
+
+      }
+    }
+  }
+
+}
+
+
+/**
+ * 
+ * @param {string} text 
+ * @param {string} openai_key
+ * @returns {Promise<number[]>} 1536 vector
+ */
+export const embed_text = async (text = 'hello', openai_key) => {
+
+  const r = await fetch(
+    'https://api.openai.com/v1/embeddings',
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${openai_key}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(
+        {
+          input: text,
+          model: 'text-embedding-3-small',
+          encoding_format: 'float',
+          dimensions: 1536
+        }
+      )
+    }
+  );
+
+  const json = await r.json();
+
+  return json.data?.[0]?.embedding;
+}