@storecraft/database-mongodb 1.0.11 → 1.0.13

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.13",
   "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/src/con.collections.js

@@ -73,6 +73,7 @@ const upsert = (driver) => {
             driver, 'collections', objid, data, session
           );
 
+        // @ts-ignore
         }, transactionOptions
       );
     
@@ -136,6 +137,7 @@ const remove = (driver) => {
             driver, 'collections', objid, session
           );
 
+        // @ts-ignore
         }, transactionOptions
       );
     } catch(e) {

package/src/con.customers.js

@@ -12,7 +12,6 @@ import { query_to_mongo } from './utils.query.js';
 /**
  * @param {MongoDB} d 
  * 
- * 
  * @returns {Collection<db_col["$type_get"]>}
  */
 const col = (d) => d.collection('customers');

package/src/con.discounts.utils.js

@@ -40,8 +40,9 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_in_products.op:
         {
-          /** @type {import("@storecraft/core/api").FilterValue_p_in_products} */
-          const cast = filter.value ?? [];
+          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_in_products} */ (
+            filter.value ?? []
+          );
           
           conjunctions.push(
             { handle: { $in: cast.map(it => it.handle) } }
@@ -50,8 +51,9 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_not_in_products.op:
         {
-          /** @type {import("@storecraft/core/api").FilterValue_p_not_in_products} */
-          const cast = filter.value ?? [];
+          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_not_in_products} */(
+            filter.value ?? []
+          );
           
           conjunctions.push(
             { handle: { $nin: cast.map(it => it.handle) } }
@@ -60,8 +62,9 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_in_tags.op:
         {
-          /** @type {import("@storecraft/core/api").FilterValue_p_in_tags} */
-          const cast = filter.value ?? [];
+          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_in_tags} */ (
+            filter.value ?? []
+          );
           
           conjunctions.push(
             { tags: { $in: cast } }
@@ -70,8 +73,9 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_not_in_tags.op:
         {
-          /** @type {import("@storecraft/core/api").FilterValue_p_not_in_tags} */
-          const cast = filter.value ?? [];
+          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_not_in_tags} */(
+            filter.value ?? []
+          );
 
           conjunctions.push(
             { tags: { $nin: cast } }
@@ -80,8 +84,9 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_in_collections.op:
         {
-          /** @type {import("@storecraft/core/api").FilterValue_p_in_collections} */
-          const cast = filter.value ?? [];
+          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_in_collections} */ (
+            filter.value ?? []
+          );
 
           conjunctions.push(
             { 
@@ -94,8 +99,9 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_not_in_collections.op:
         {
-          /** @type {import("@storecraft/core/api").FilterValue_p_not_in_collections} */
-          const cast = filter.value ?? [];
+          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_not_in_collections} */ (
+            filter.value ?? []
+          );
 
           conjunctions.push(
             { 
@@ -108,12 +114,13 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_in_price_range.op:
         {
-          /** @type {import("@storecraft/core/api").FilterValue_p_in_price_range} */
-          const cast = {
-            from: 0,
-            to: Number.POSITIVE_INFINITY,
-            ...(filter?.value ?? {})
-          };
+          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_in_price_range} */ (
+            {
+              from: 0,
+              to: Number.POSITIVE_INFINITY,
+              ...(filter?.value ?? {})
+            }
+          );
 
           const from = extract_abs_number(cast.from);
           const to = extract_abs_number(cast.to);

package/src/con.notifications.js

@@ -42,6 +42,7 @@ const upsertBulk = (driver) => {
     items = items.map(item => ({...item}));
     items.forEach(
       (item, ix) => {
+        // @ts-ignore
         item._id = to_objid(item.id);
         
         add_search_terms_relation_on(

package/src/con.search.js

@@ -102,25 +102,26 @@ export const quicksearch = (driver) => {
 
     const db = driver.mongo_client.db(driver.name);
     
-    /** @type {import('@storecraft/core/api').QuickSearchResource[]} */ 
-    const items = await db.collection(tables_filtered[0]).aggregate(
-      [
-        ...pipeline,
-        ...tables_filtered.slice(1).map(
-          t => (
-            {
-              $unionWith: {
-                coll: t,
-                pipeline: pipeline
+    
+    const items = /** @type {import('@storecraft/core/api').QuickSearchResource[]} */ (
+      await db.collection(tables_filtered[0]).aggregate(
+        [
+          ...pipeline,
+          ...tables_filtered.slice(1).map(
+            t => (
+              {
+                $unionWith: {
+                  coll: t,
+                  pipeline: pipeline
+                }
               }
-            }
+            )
           )
-        )
-      ], 
-      {
-        
-      }
-    ).toArray();
+        ], 
+        {
+        }
+      ).toArray()
+    );
 
 
     /** @type {import('@storecraft/core/api').QuickSearchResult} */

package/src/con.shared.js

@@ -11,15 +11,13 @@ import { add_search_terms_relation_on } from './utils.relations.js'
  * @template {import('@storecraft/core/api').BaseType} T
  * @template {import('@storecraft/core/api').BaseType} G
  * 
- * 
  * @param {MongoDB} driver 
  * @param {Collection<G>} col 
  * 
- * 
  * @returns {import('@storecraft/core/database').db_crud<T, G>["upsert"]}
- * 
  */
 export const upsert_regular = (driver, col) => {
+  
   return async (data, search_terms=[]) => {
 
     data = {...data};
@@ -194,8 +192,8 @@ export const get_regular = (driver, col) => {
  * should be instead
  * 
  * 
- * @template {import('@storecraft/core/api').idable} T
- * @template {import('@storecraft/core/api').idable} G
+ * @template {import('@storecraft/core/api').withOptionalID} T
+ * @template {import('@storecraft/core/api').withOptionalID} G
  * 
  * 
  * @param {MongoDB} driver 
@@ -278,7 +276,7 @@ export const list_regular = (driver, col) => {
 
     // console.log('reverse_sign', reverse_sign)
     // console.log('query', query)
-    // console.log('filter', JSON.stringify(filter, null, 2))
+    console.log('filter', JSON.stringify(filter, null, 2))
     // console.log('sort', sort)
     // console.log('expand', query?.expand)
 

package/src/utils.query.js

@@ -116,7 +116,7 @@ export const query_vql_to_mongo = root => {
  * Let's transform ids into mongo ids
  * 
  * 
- * @param {import("@storecraft/core/api").Tuple<string>} c a cursor record
+ * @param {import("@storecraft/core/api").Tuple<>} c a cursor record
  * 
  * 
  * @returns {[k: string, v: any]}
@@ -124,7 +124,7 @@ export const query_vql_to_mongo = root => {
 const transform = c => {
   if(c[0]!=='id') 
     return c;
-  return [ '_id', to_objid(c[1]) ];
+  return [ '_id', to_objid(String(c[1])) ];
 }
 
 /**

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;
+}