@webda/mongo 4.0.0-beta.2 → 4.0.0-beta.3

package/README.md

@@ -0,0 +1,118 @@
+# @webda/mongo module
+
+This module is part of Webda Application Framework that allows you to quickly develop applications with all modern prerequisites: Security, Extensibility, GraphQL, REST, CloudNative [https://webda.io](https://webda.io)
+
+<img src="https://webda.io/images/webda.svg" width="128" />
+
+![CI](https://github.com/loopingz/webda.io/workflows/CI/badge.svg)
+
+[![Join the chat at https://gitter.im/loopingz/webda](https://badges.gitter.im/loopingz/webda.svg)](https://gitter.im/loopingz/webda?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![codecov](https://codecov.io/gh/loopingz/webda.io/branch/main/graph/badge.svg?token=8N9DNM3K3O)](https://codecov.io/gh/loopingz/webda.io)
+[![SonarCloud.io](https://sonarcloud.io/api/project_badges/measure?project=loopingz_webda.io&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=loopingz_webda.io)
+![CodeQL](https://github.com/loopingz/webda.io/workflows/CodeQL/badge.svg)
+
+<!-- README_HEADER -->
+
+# @webda/mongodb
+
+> MongoDB-backed Store for Webda — persists any model to MongoDB using the JSONB document model, with full query, pagination, and update-condition support.
+
+## When to use it
+
+- You want a flexible document store for Webda models without a fixed schema (MongoDB's schema-less documents match Webda's JSON models naturally).
+- You are deploying on infrastructure that already runs MongoDB (Atlas, self-hosted, DocumentDB).
+- You need free-text indexes, geospatial queries, or aggregation pipelines alongside your Webda models.
+
+## Install
+
+```bash
+pnpm add @webda/mongodb
+```
+
+## Configuration
+
+```json
+{
+  "services": {
+    "userStore": {
+      "type": "MongoStore",
+      "model": "MyApp/User",
+      "collection": "users",
+      "database": "my-app"
+    }
+  }
+}
+```
+
+Set the connection URL via the `WEBDA_MONGO_URL` environment variable (recommended) or inline:
+
+```json
+{
+  "services": {
+    "userStore": {
+      "type": "MongoStore",
+      "mongoUrl": "mongodb+srv://user:pass@cluster.mongodb.net",
+      "collection": "users",
+      "database": "my-app"
+    }
+  }
+}
+```
+
+| Parameter | Type | Default | Required | Description |
+|---|---|---|---|---|
+| `mongoUrl` | string | `$WEBDA_MONGO_URL` | Yes | MongoDB connection string (falls back to `WEBDA_MONGO_URL` env variable) |
+| `collection` | string | — | Yes | MongoDB collection name to store model documents in |
+| `database` | string | — | No | MongoDB database name (uses default from connection string if omitted) |
+| `options` | object | `{}` | No | Additional `MongoClientOptions` passed to the driver |
+| `databaseOptions` | object | — | No | `DbOptions` passed to `client.db()` |
+
+## Usage
+
+```typescript
+import { CoreModel, Model, Expose } from "@webda/core";
+import { Bean, Inject } from "@webda/core";
+import { Store } from "@webda/core";
+
+@Model()
+export class User extends CoreModel {
+  @Expose() name: string;
+  @Expose() email: string;
+}
+
+// With MongoStore configured, all CoreModel CRUD is automatically backed by MongoDB:
+const user = new User();
+user.name = "Alice";
+user.email = "alice@example.com";
+await user.save();                          // inserts into MongoDB
+
+const found = await User.ref(user.uuid).get();   // fetch by UUID
+const results = await User.query("name = 'Alice'"); // filtered query
+await user.patch({ name: "Alice Smith" });        // partial update
+await user.delete();                              // hard delete
+```
+
+## Reference
+
+- API reference: see the auto-generated typedoc at `docs/pages/Modules/mongodb/`.
+- Source: [`packages/mongodb`](https://github.com/loopingz/webda.io/tree/main/packages/mongodb)
+- Related: [`@webda/postgres`](../postgres) for a SQL-backed alternative; [`@webda/aws`](../aws) for `DynamoStore`; [`@webda/core`](../core) for the `Store` base class and model CRUD API.
+
+<!-- README_FOOTER -->
+## Sponsors
+
+<!--
+Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor](mailto:sponsor@webda.io)
+-->
+
+Arize AI is a machine learning observability and model monitoring platform. It helps you visualize, monitor, and explain your machine learning models. [Learn more](https://arize.com)
+
+[<img src="https://arize.com/hubfs/arize/brand/arize-logomark-1.png" width="200">](https://arize.com)
+
+Loopingz is a software development company that provides consulting and development services. [Learn more](https://loopingz.com)
+
+[<img src="https://loopingz.com/images/logo.png" width="200">](https://loopingz.com)
+
+Tellae is an innovative consulting firm specialized in cities transportation issues. We provide our clients, both public and private, with solutions to support your strategic and operational decisions. [Learn more](https://tellae.fr)
+
+[<img src="https://tellae.fr/" width="200">](https://tellae.fr)

package/lib/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./mongodb.js";
+export * from "./mongodb.service.js";
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/lib/index.js

@@ -1,2 +1,2 @@
-export * from "./mongodb.js";
+export * from "./mongodb.service.js";
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/lib/mongodb.service.d.ts

@@ -0,0 +1,175 @@
+import { MemoryRepository, Store, StoreParameters } from "@webda/core";
+import type { ModelClass, Repository } from "@webda/core";
+import * as WebdaQL from "@webda/ql";
+import { Collection, Db, DbOptions, Document, MongoClient } from "mongodb";
+/**
+ * MongoDB store parameters
+ */
+export declare class MongoParameters extends StoreParameters {
+    /**
+     * Contains the URL to Mongo Server
+     *
+     * Will try to use WEBDA_MONGO_URL environment variable if not defined
+     */
+    mongoUrl?: string;
+    /**
+     * Additional options for Mongo connetion
+     *
+     * Should be typed with MongoClientOptions but not available due to bug in ts-json-schema-generator
+     * https://docs.mongodb.com/manual/reference/connection-string
+     */
+    options?: any;
+    /**
+     * Which collection to use
+     *
+     * All the models managed by the store share this collection, the `__type`
+     * field is used to differentiate them
+     */
+    collection: string;
+    /**
+     * Database to use, default to the one defined in the URL
+     */
+    database?: string;
+    /**
+     * Mongo Database Options
+     *
+     * @see https://www.npmjs.com/package/mongodb
+     */
+    databaseOptions?: DbOptions;
+    /**
+     * @override
+     * @param params - raw parameters
+     * @returns this
+     */
+    load(params?: any): this;
+}
+/**
+ * Get a mongodb query object from WebdaQL
+ * @param expression - the WebdaQL expression
+ * @returns the MongoDB filter
+ */
+export declare function mapExpression(expression: WebdaQL.Expression): any;
+/**
+ * MongoDB-backed repository for a single model class
+ *
+ * Every object is stored as a plain document with `_id` set to its primary key
+ * and `__type` set to its model identifier, so several models can share one
+ * collection. The inherited MemoryRepository helpers are only used for primary
+ * key and class filter computation.
+ */
+export declare class MongoRepository<T extends ModelClass> extends MemoryRepository<T> {
+    protected readonly getCollection: () => Promise<Collection<Document>>;
+    /**
+     * @param model - the model class
+     * @param pks - primary key field names
+     * @param getCollection - return the collection, connecting if needed
+     * @param separator - composite key separator
+     */
+    constructor(model: T, pks: string[], getCollection: () => Promise<Collection<Document>>, separator?: string);
+    /**
+     * Convert an object to the document stored in MongoDB
+     * @param item - the model instance or raw data
+     * @param key - the primary key
+     * @returns the document
+     */
+    protected toDocument(item: any, key: string): any;
+    /**
+     * Convert a stored document into a model instance
+     * @param doc - the MongoDB document
+     * @returns the model instance
+     */
+    protected fromDocument(doc: any): InstanceType<T>;
+    /**
+     * Return a filter for Mongo command
+     * @param key - the primary key
+     * @param conditionField - field to check
+     * @param condition - expected value
+     * @returns the filter
+     */
+    protected getFilter(key: string, conditionField?: any, condition?: any): any;
+    /** @override */
+    get(primaryKey: any): Promise<any>;
+    /** @override */
+    create(data: any, save?: boolean): Promise<any>;
+    /** @override */
+    update(data: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    patch(primaryKey: any, data: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    delete(primaryKey: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    exists(primaryKey: any): Promise<boolean>;
+    /** @override */
+    removeAttribute(primaryKey: any, attribute: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    incrementAttributes(primaryKey: any, info: any, conditionField?: any, condition?: any): Promise<void>;
+    /** @override */
+    upsertItemToCollection(primaryKey: any, collection: any, item: any, index?: number, itemWriteConditionField?: any, itemWriteCondition?: any): Promise<void>;
+    /** @override */
+    deleteItemFromCollection(primaryKey: any, collection: any, index: number, itemWriteConditionField?: any, itemWriteCondition?: any): Promise<void>;
+    /**
+     * Build the MongoDB filter restricting results to this model and its subclasses
+     *
+     * Documents without `__type` are considered as instance of the repository model
+     * @returns the class filter or undefined if the model has no metadata
+     */
+    protected getClassFilter(): any;
+    /** @override — translate the WebdaQL query to a MongoDB find */
+    query(query: string | any): Promise<{
+        results: InstanceType<T>[];
+        continuationToken?: string;
+    }>;
+    /**
+     * Name of the underlying collection, used in errors
+     * @returns the collection name
+     */
+    protected getCollectionName(): string;
+}
+/**
+ * Store Objects in MongoDB
+ *
+ * Parameters:
+ *   mongoUrl: 'mongodb://127.0.0.1:27017' // If not found try to read WEBDA_MONGO_URL env variable
+ *
+ * @WebdaModda
+ */
+export declare class MongoStore<K extends MongoParameters = MongoParameters> extends Store<K> {
+    /**
+     * Connect promise
+     */
+    protected _connectPromise: Promise<Collection<Document>>;
+    /**
+     * Client
+     */
+    _client: MongoClient;
+    _db: Db;
+    _collection: Collection<Document>;
+    /**
+     * Connect to MongoDB if not already connected
+     * @returns the collection
+     */
+    _connect(): Promise<Collection<Document>>;
+    /**
+     * @override
+     */
+    init(): Promise<this>;
+    /**
+     * @override
+     */
+    stop(): Promise<void>;
+    /**
+     * Build and return a MongoRepository for the given model
+     *
+     * The collection is resolved lazily so the repository can be registered
+     * before the store is connected.
+     * @param model - the model class
+     * @returns a repository backed by the store collection
+     */
+    getRepository<T extends ModelClass>(model: T): Repository<T>;
+    /**
+     * Remove every document from the collection (used in tests)
+     */
+    __clean(): Promise<void>;
+}
+export default MongoStore;
+//# sourceMappingURL=mongodb.service.d.ts.map

package/lib/mongodb.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongodb.service.d.ts","sourceRoot":"","sources":["../src/mongodb.service.ts"],"names":[],"mappings":"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"}