@storecraft/database-mongodb 1.0.13 → 1.0.15

package/README.md

@@ -8,7 +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`
+Also, official support for mongo-db as vector store.
 
 ```bash
 npm i @storecraft/database-mongodb
@@ -24,23 +24,19 @@ import { NodePlatform } from '@storecraft/core/platform/node';
 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'
+import { MongoVectorStore } from '@storecraft/database-mongodb/vector-store'
 
-const app = new App(
-  {
-    auth_admins_emails: ['admin@sc.com'],
-    auth_secret_access_token: 'auth_secret_access_token',
-    auth_secret_refresh_token: 'auth_secret_refresh_token'
-  }
-)
+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 })
+.withDatabase(new MongoDB({}))
+.withVectorStore(
+  new MongoVectorStore({ embedder: new OpenAIEmbedder() })
 )
 
 await app.init();
 await migrateToLatest(app.db, false);
+// cerate if not exists
+await app.vectorstore.createVectorIndex(false, false);
 
 const server = http.createServer(app.handler).listen(
   8000,
@@ -51,62 +47,6 @@ 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/{vector-search-extension.js → example-extension/vector-search-extension.js}

@@ -1,7 +1,10 @@
 /**
+ * an older demo for extending storecraft with vector search.
+ * DO NOT USE this. Use the our official `MongoVectorSearch` insteas
+ * 
  * @import {extension} from '@storecraft/core/extensions'
  */
-import { MongoDB } from './index.js';
+import { MongoDB } from '../index.js';
 /**
  * 
  * @typedef {object} Config

package/index.js

@@ -1,3 +1,10 @@
+/**
+ * @import { Config } from './types.public.js'
+ * @import { MongoClientOptions } from 'mongodb'
+ * @import { db_driver } from '@storecraft/core/database'
+ * @import { BaseType } from '@storecraft/core/api'
+ * @import { ENV } from '@storecraft/core'
+ */
 import { App } from '@storecraft/core';
 import { Collection, MongoClient, ServerApiVersion } from 'mongodb';
 import { impl as auth_users } from './src/con.auth_users.js';
@@ -15,66 +22,43 @@ import { impl as tags } from './src/con.tags.js';
 import { impl as templates } from './src/con.templates.js';
 import { impl as search } from './src/con.search.js';
 export { migrateToLatest } from './migrate.js';
+export { MongoVectorStore } from './vector-store/index.js';
 
-/**
- * @typedef {Partial<import('./types.public.d.ts').Config>} Config
- */
-
-/**
- * 
- * @param {string} uri 
- * @param {import('mongodb').MongoClientOptions} [options] 
- */
-const connect = async (uri, options) => {
-
-  options = options ?? {
-    ignoreUndefined: true,
-    serverApi: {
-      version: ServerApiVersion.v1,
-      strict: false,
-      deprecationErrors: true,
-
-    }
-  }
-  const client = new MongoClient(uri, options);
-
-  return client.connect();
-}
 
 /**
- * @typedef {import('@storecraft/core/database').db_driver} db_driver
- * 
- * 
  * @implements {db_driver}
  */
 export class MongoDB {
 
+  /** @satisfies {ENV<Config>} */
+  static EnvConfig = /** @type{const} */ ({
+    db_name: 'MONGODB_NAME',
+    url: 'MONGODB_URL',
+  });
+
   /** 
    * 
    * @type {boolean} 
    */ 
-  #_is_ready;
+  #is_ready;
 
   /** 
    * 
    * @type {App<any, any, any>} 
    */ 
-  #_app;
+  #app;
 
   /** 
    * 
    * @type {MongoClient} 
    */ 
-  #_mongo_client;
+  #mongo_client;
 
   /** 
    * 
    * @type {Config} 
    */ 
-  #_config;
-
-  // /** @type {db_driver["resources"]} */
-  // #_resources;
+  #config;
 
   /**
    * 
@@ -82,34 +66,35 @@ export class MongoDB {
    * env variables `MONGODB_URL` will be used for uri upon init later
    */
   constructor(config) {
-    this.#_is_ready = false;
-    this.#_config = config;
+    this.#is_ready = false;
+    this.#config = {
+      options: {
+        ignoreUndefined: true,
+        serverApi: {
+          version: ServerApiVersion.v1,
+          strict: false,
+          deprecationErrors: true,
+        }
+      },
+      ...config
+    };
   }
 
   /**
-   * 
-   * @param {App} app 
-   * 
-   * 
-   * @returns {Promise<this>}
+   * @type {db_driver["init"]}
    */
-  async init(app) {
+  init(app) {
     if(this.isReady)
       return this;
-    const c = this.#_config;
-    this.#_config = {
-      ...c, 
-      url: c?.url ?? app.platform.env.MONGODB_URL,
-      db_name: c?.db_name ?? app.platform.env.MONGODB_NAME ?? 'main'
-    }
-
-    this.#_mongo_client = await connect(
-      this.config.url,
-      this.config.options
-    );
-   
-    this.#_app = app;
+    const c = this.#config;
+    c.db_name ??= app.platform.env[MongoDB.EnvConfig.db_name];
+    c.url ??= app.platform.env[MongoDB.EnvConfig.url] ?? 'main';
 
+    if(!this.config.db_name || !this.config.url) {
+      throw new Error('MongoVectorStore::client() - missing url or db_name');
+    }
+    
+    this.#app = app;
     this.resources = {
       auth_users: auth_users(this),
       collections: collections(this),
@@ -127,7 +112,7 @@ export class MongoDB {
       search: search(this),
     }
     
-    this.#_is_ready = true; 
+    this.#is_ready = true; 
 
     return this;
   }
@@ -137,7 +122,7 @@ export class MongoDB {
     return true;
   }
 
-  get isReady() { return this.#_is_ready; }
+  get isReady() { return this.#is_ready; }
 
   throwIfNotReady() {
     if(!this.isReady)
@@ -157,7 +142,7 @@ export class MongoDB {
    * @description Get the `storecraft` app
    */
   get app() { 
-    return this.#_app; 
+    return this.#app; 
   }
 
   /**
@@ -165,7 +150,15 @@ export class MongoDB {
    * @description Get the native `mongodb` client
    */
   get mongo_client() {
-    return this.#_mongo_client;
+    if(!this.config.db_name || !this.config.url) {
+      throw new Error('MongoVectorStore::client() - missing url or db_name');
+    }
+      
+    this.#mongo_client = this.#mongo_client ?? new MongoClient(
+      this.config.url, this.config.options
+    );
+  
+    return this.#mongo_client;
   }
 
   /**
@@ -173,12 +166,12 @@ export class MongoDB {
    * @description Get the config object
    */
   get config() { 
-    return this.#_config; 
+    return this.#config; 
   }
 
   /**
    * 
-   * @template {import('@storecraft/core/api').BaseType} T
+   * @template {BaseType} T
    * 
    * 
    * @param {string} name 

package/jsconfig.json

@@ -7,6 +7,7 @@
   },
   "include": [
     "*", 
+    "vector-store/*", 
     "src/*", 
     "tests/*.js",
     "migrations/*",

package/migrate.js

@@ -22,6 +22,7 @@ export async function migrateToLatest(driver, destroy_db_upon_completion=true) {
 
   config.set(config_migrate);
 
+  // @ts-ignore
   driver.mongo_client.__db_driver = driver;
 
   const results = await up(

package/migrations/00001_seed_email_templates.js

@@ -14,6 +14,7 @@ export async function up(db, client) {
     await session.withTransaction(
       async (s) => {
         /** @type {MongoDB} */
+        // @ts-ignore
         const driver = client.__db_driver;
 
         for (const template of templates) {

package/migrations/00002_seed_email_templates.js

@@ -0,0 +1,36 @@
+import { Db, MongoClient } from 'mongodb';
+import { MongoDB } from '../index.js'
+import { templates } from '@storecraft/core/assets/seed-templates-v2.js'
+
+/**
+ * 
+ * @param {Db} db 
+ * @param {MongoClient} client 
+ */
+export async function up(db, client) {
+
+  const session = client.startSession();
+  try {
+    await session.withTransaction(
+      async (s) => {
+        /** @type {MongoDB} */
+        // @ts-ignore
+        const driver = client.__db_driver;
+
+        for (const template of templates) {
+          await driver.resources.templates.upsert(template, template.search);
+        }
+      }
+    );
+  } finally {
+    await session.endSession();
+  }
+}
+
+/**
+ * 
+ * @param {Db} db 
+ * @param {MongoClient} client 
+ */
+export async function down(db, client) {
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storecraft/database-mongodb",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Storecraft database driver for mongodb on node / bun / deno platform",
   "license": "MIT",
   "author": "Tomer Shalev (https://github.com/store-craft)",
@@ -24,6 +24,10 @@
       "import": "./index.js",
       "types": "./types.public.d.ts"
     },
+    "./vector-store": {
+      "import": "./vector-store/index.js",
+      "types": "./vector-store/types.d.ts"
+    },
     "./*": {
       "import": "./*"
     }
@@ -37,7 +41,7 @@
   "dependencies": {
     "@storecraft/core": "^1.0.0",
     "migrate-mongo": "^11.0.0",
-    "mongodb": "^6.3.0"
+    "mongodb": "^6.14.0"
   },
   "devDependencies": {
     "@types/migrate-mongo": "^10.0.4",

package/src/con.auth_users.js

@@ -1,14 +1,17 @@
+/**
+ * @import { db_auth_users as db_col } from '@storecraft/core/database'
+ * @import { AuthUserType } from '@storecraft/core/api'
+ */
+
 import { MongoDB } from '../index.js'
 import { Collection } from 'mongodb'
-import { objid_or_else_filter, sanitize_one, to_objid_safe } from './utils.funcs.js'
+import { 
+  objid_or_else_filter, sanitize_one, to_objid_safe 
+} from './utils.funcs.js'
 import { 
   count_regular, get_regular, list_regular, upsert_regular 
 } from './con.shared.js'
 
-/**
- * @typedef {import('@storecraft/core/database').db_auth_users} db_col
- */
-
 /**
  * @param {MongoDB} d 
  * 
@@ -32,8 +35,6 @@ const upsert = (driver) => upsert_regular(driver, col(driver));
 const get = (driver) => {
   return async (id_or_email) => {
     const filter = objid_or_else_filter(id_or_email, 'email');
-
-    /** @type {import('@storecraft/core/api').AuthUserType} */
     const res = await col(driver).findOne(
       filter
     );
@@ -51,8 +52,6 @@ const get = (driver) => {
 const getByEmail = (driver) => {
   return async (email) => {
     const filter = { email: email };
-
-    /** @type {import('@storecraft/core/api').AuthUserType} */
     const res = await col(driver).findOne(
       filter
     );
@@ -100,7 +99,6 @@ const remove = (driver) => {
  */
 const removeByEmail = (driver) => {
   return async (email) => {
-    /** @type {import('@storecraft/core/api').AuthUserType} */
     await col(driver).deleteOne(
       { email }
     );

package/src/con.collections.js

@@ -1,3 +1,10 @@
+/**
+ * @import { db_collections as db_col } from '@storecraft/core/database'
+ * @import { ProductType, VariantType } from '@storecraft/core/api'
+ * @import { WithRelations } from './utils.relations.js'
+ * @import { Filter } from 'mongodb'
+ */
+
 import { Collection } from 'mongodb'
 import { MongoDB } from '../index.js'
 import { count_regular, expand, get_regular, list_regular } from './con.shared.js'
@@ -11,10 +18,6 @@ import {
   update_entry_on_all_connection_of_relation 
 } from './utils.relations.js'
 
-/**
- * @typedef {import('@storecraft/core/database').db_collections} db_col
- */
-
 
 const transactionOptions = {
   readPreference: 'primary',
@@ -26,9 +29,7 @@ const transactionOptions = {
  * @param {MongoDB} d 
  * 
  * 
- * @returns {Collection<
- *  import('./utils.relations.js').WithRelations<db_col["$type_get"]>
- * >}
+ * @returns {Collection<WithRelations<db_col["$type_get"]>>}
  */
 const col = (d) => d.collection('collections');
 
@@ -175,7 +176,9 @@ const count = (driver) => count_regular(driver, col(driver));
 const list_collection_products = (driver) => {
   return async (handle_or_id, query) => {
 
-    const { filter: filter_query, sort, reverse_sign } = query_to_mongo(query);
+    const { 
+      filter: filter_query, sort, reverse_sign 
+    } = query_to_mongo(query);
 
     // console.log('query', query)
     // console.log('filter', JSON.stringify(filter_query, null, 2))
@@ -183,12 +186,8 @@ const list_collection_products = (driver) => {
     // console.log('expand', query?.expand)
     
     /**
-     * @type {import('mongodb').Filter<
-     *  import('./utils.relations.js').WithRelations<
-     *    import('@storecraft/core/api').ProductType | 
-     *    import('@storecraft/core/api').VariantType
-     *  >
-     * >}
+     * @type {Filter<WithRelations<ProductType | VariantType>>
+     * }
      */
     const filter = {
       $and: [

package/src/con.customers.js

@@ -1,3 +1,10 @@
+/**
+ * @import { db_customers as db_col } from '@storecraft/core/database'
+ * @import { OrderData } from '@storecraft/core/api'
+ * @import { WithRelations } from './utils.relations.js'
+ * @import { Filter } from 'mongodb'
+ */
+
 import { Collection, ObjectId } from 'mongodb'
 import { MongoDB } from '../index.js'
 import { count_regular, get_regular, list_regular, 
@@ -5,10 +12,6 @@ import { count_regular, get_regular, list_regular,
 import { isDef, sanitize_array, to_objid } from './utils.funcs.js'
 import { query_to_mongo } from './utils.query.js';
 
-/**
- * @typedef {import('@storecraft/core/database').db_customers} db_col
- */
-
 /**
  * @param {MongoDB} d 
  * 
@@ -122,13 +125,7 @@ const list_customer_orders = (driver) => {
     console.log('sort', sort)
     console.log('expand', query?.expand)
     
-    /**
-     * @type {import('mongodb').Filter<
-     *  import('./utils.relations.js').WithRelations<
-     *    import('@storecraft/core/api').OrderData
-     *  >
-     * >}
-     */
+    /** @type {Filter<WithRelations<OrderData>>} */
     const filter = {
       $and: [
         {'_relations.search': `customer:${customer_id}` },

package/src/con.discounts.js

@@ -1,3 +1,10 @@
+/**
+ * @import { db_discounts as db_col } from '@storecraft/core/database'
+ * @import { ProductType, VariantType } from '@storecraft/core/api'
+ * @import { WithRelations } from './utils.relations.js'
+ * @import { Filter } from 'mongodb'
+ */
+
 import { Collection } from 'mongodb'
 import { MongoDB } from '../index.js'
 import { 
@@ -18,11 +25,6 @@ import {
 } from './utils.relations.js'
 
 
-/**
- * @typedef {import('@storecraft/core/database').db_discounts} db_col
- */
-
-
 /**
  * @param {MongoDB} d 
  * 
@@ -208,14 +210,7 @@ const list_discount_products = (driver) => {
     // console.log('sort', sort)
     // console.log('expand', query?.expand)
     
-    /**
-     * @type {import('mongodb').Filter<
-     *  import('./utils.relations.js').WithRelations<
-     *    import('@storecraft/core/api').ProductType | 
-     *    import('@storecraft/core/api').VariantType
-     *  >
-     * >}
-     */
+    /** @type {Filter<WithRelations<ProductType | VariantType>>} */
     const filter = {
       $and: [
         { '_relations.search': `discount:${handle_or_id}` },

package/src/con.discounts.utils.js

@@ -1,12 +1,20 @@
+/**
+ * @import { 
+ *  DiscountType, FilterValue_p_in_price_range, FilterValue_p_not_in_collections, 
+ *  FilterValue_p_in_collections, FilterValue_p_not_in_tags, FilterValue_p_in_tags, 
+ *  FilterValue_p_in_products, FilterValue_p_not_in_products 
+ * } from '@storecraft/core/api'
+ */
+
 import { enums } from "@storecraft/core/api";
 import { to_objid_safe } from "./utils.funcs.js";
 
-/** @param {import("@storecraft/core/api").DiscountType} d */
+/** @param {DiscountType} d */
 const is_order_discount = d => {
   return (d.info.details.meta.id===enums.DiscountMetaEnum.order.id);
 }
 
-/** @param {import("@storecraft/core/api").DiscountType} d */
+/** @param {DiscountType} d */
 const is_automatic_discount = d => {
   return (d.application.id===enums.DiscountApplicationEnum.Auto.id);
 }
@@ -20,7 +28,7 @@ const extract_abs_number = v => {
  * for filtering.
  * 
  * 
- * @param {import("@storecraft/core/api").DiscountType} d 
+ * @param {DiscountType} d 
  */
 export const discount_to_mongo_conjunctions = d => {
   // discount has to be product discount + automatic + active + has filters
@@ -40,7 +48,7 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_in_products.op:
         {
-          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_in_products} */ (
+          const cast = /** @type {FilterValue_p_in_products} */ (
             filter.value ?? []
           );
           
@@ -51,7 +59,7 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_not_in_products.op:
         {
-          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_not_in_products} */(
+          const cast = /** @type {FilterValue_p_not_in_products} */(
             filter.value ?? []
           );
           
@@ -62,7 +70,7 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_in_tags.op:
         {
-          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_in_tags} */ (
+          const cast = /** @type {FilterValue_p_in_tags} */ (
             filter.value ?? []
           );
           
@@ -73,7 +81,7 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_not_in_tags.op:
         {
-          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_not_in_tags} */(
+          const cast = /** @type {FilterValue_p_not_in_tags} */(
             filter.value ?? []
           );
 
@@ -84,7 +92,7 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_in_collections.op:
         {
-          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_in_collections} */ (
+          const cast = /** @type {FilterValue_p_in_collections} */ (
             filter.value ?? []
           );
 
@@ -99,7 +107,7 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_not_in_collections.op:
         {
-          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_not_in_collections} */ (
+          const cast = /** @type {FilterValue_p_not_in_collections} */ (
             filter.value ?? []
           );
 
@@ -114,7 +122,7 @@ export const discount_to_mongo_conjunctions = d => {
         break;
       case enums.FilterMetaEnum.p_in_price_range.op:
         {
-          const cast = /** @type {import("@storecraft/core/api").FilterValue_p_in_price_range} */ (
+          const cast = /** @type {FilterValue_p_in_price_range} */ (
             {
               from: 0,
               to: Number.POSITIVE_INFINITY,