@elaraai/east-node-io 0.0.1-beta.1 → 0.0.1-beta.11

package/dist/nosql/mongodb.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * MongoDB platform functions for East Node IO.
+ *
+ * Provides MongoDB document database operations for East programs,
+ * including find, insert, update, and delete operations with BSON-compatible values.
+ *
+ * @packageDocumentation
+ */
+import { DictType, StringType, IntegerType, ArrayType, OptionType, NullType } from "@elaraai/east";
+import type { PlatformFunction } from "@elaraai/east/internal";
+/**
+ * BSON document type (dictionary mapping strings to BSON values).
+ *
+ * Used for MongoDB documents in queries, inserts, and updates.
+ */
+export declare const BsonDocumentType: DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>;
+/**
+ * Connects to a MongoDB server.
+ *
+ * Creates a connection to a MongoDB server and returns an opaque handle
+ * for use in document operations.
+ *
+ * @param config - MongoDB connection configuration
+ * @returns Connection handle (opaque string)
+ *
+ * @throws {EastError} When connection fails (location: "mongodb_connect")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType } from "@elaraai/east";
+ * import { NoSQL } from "@elaraai/east-node-io";
+ *
+ * const testConnect = East.function([], StringType, $ => {
+ *     const config = $.let({
+ *         uri: "mongodb://localhost:27017",
+ *         database: "myapp",
+ *         collection: "users",
+ *     });
+ *     const conn = $.let(NoSQL.MongoDB.connect(config));
+ *     $(NoSQL.MongoDB.close(conn));
+ *     return $.return(conn);
+ * });
+ *
+ * const compiled = East.compileAsync(testConnect.toIR(), NoSQL.MongoDB.Implementation);
+ * const handle = await compiled();  // Returns connection handle string
+ * ```
+ */
+export declare const mongodb_connect: import("@elaraai/east").AsyncPlatformDefinition<[import("@elaraai/east").StructType<{
+    uri: StringType;
+    database: StringType;
+    collection: StringType;
+}>], StringType>;
+/**
+ * Finds a single document in MongoDB.
+ *
+ * Searches for a document matching the query object.
+ * Returns None if no document is found.
+ *
+ * @param handle - Connection handle from mongodb_connect()
+ * @param query - Query object to match documents
+ * @returns Option containing the document, or None if not found
+ *
+ * @throws {EastError} When operation fails (location: "mongodb_find_one")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, OptionType, variant } from "@elaraai/east";
+ * import { NoSQL } from "@elaraai/east-node-io";
+ *
+ * const findUser = East.function([StringType], OptionType(NoSQL.MongoDB.Types.BsonDocument), ($, username) => {
+ *     const config = $.let({
+ *         uri: "mongodb://localhost:27017",
+ *         database: "myapp",
+ *         collection: "users",
+ *     });
+ *     const conn = $.let(NoSQL.MongoDB.connect(config));
+ *     const query = $.let(new Map([["username", variant('String', username)]]), NoSQL.MongoDB.Types.BsonDocument);
+ *     const user = $.let(NoSQL.MongoDB.findOne(conn, query));
+ *     $(NoSQL.MongoDB.close(conn));
+ *     return $.return(user);
+ * });
+ *
+ * const compiled = East.compileAsync(findUser.toIR(), NoSQL.MongoDB.Implementation);
+ * await compiled("alice");  // variant('some', document) or variant('none', null)
+ * ```
+ */
+export declare const mongodb_find_one: import("@elaraai/east").AsyncPlatformDefinition<[StringType, DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>], OptionType<DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>>>;
+/**
+ * Finds multiple documents in MongoDB.
+ *
+ * Searches for documents matching the query object with optional
+ * limit and skip for pagination.
+ *
+ * @param handle - Connection handle from mongodb_connect()
+ * @param query - Query object to match documents
+ * @param options - Find options (limit, skip)
+ * @returns Array of matching documents
+ *
+ * @throws {EastError} When operation fails (location: "mongodb_find_many")
+ *
+ * @example
+ * ```ts
+ * import { East, ArrayType, variant } from "@elaraai/east";
+ * import { NoSQL } from "@elaraai/east-node-io";
+ *
+ * const findAllUsers = East.function([], ArrayType(NoSQL.MongoDB.Types.BsonDocument), $ => {
+ *     const config = $.let({
+ *         uri: "mongodb://localhost:27017",
+ *         database: "myapp",
+ *         collection: "users",
+ *     });
+ *     const conn = $.let(NoSQL.MongoDB.connect(config));
+ *     const query = $.let(new Map(), NoSQL.MongoDB.Types.BsonDocument);
+ *     const options = $.let({ limit: variant('some', 10n), skip: variant('none', null) });
+ *     const users = $.let(NoSQL.MongoDB.findMany(conn, query, options));
+ *     $(NoSQL.MongoDB.close(conn));
+ *     return $.return(users);
+ * });
+ *
+ * const compiled = East.compileAsync(findAllUsers.toIR(), NoSQL.MongoDB.Implementation);
+ * await compiled();  // [doc1, doc2, ...]
+ * ```
+ */
+export declare const mongodb_find_many: import("@elaraai/east").AsyncPlatformDefinition<[StringType, DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>, import("@elaraai/east").StructType<{
+    limit: OptionType<IntegerType>;
+    skip: OptionType<IntegerType>;
+}>], ArrayType<DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>>>;
+/**
+ * Inserts a document into MongoDB.
+ *
+ * Inserts a new document into the collection.
+ * Returns the inserted document's _id as a string.
+ *
+ * @param handle - Connection handle from mongodb_connect()
+ * @param document - Document to insert
+ * @returns The inserted document's _id
+ *
+ * @throws {EastError} When operation fails (location: "mongodb_insert_one")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, variant } from "@elaraai/east";
+ * import { NoSQL } from "@elaraai/east-node-io";
+ *
+ * const createUser = East.function([StringType, StringType], StringType, ($, username, email) => {
+ *     const config = $.let({
+ *         uri: "mongodb://localhost:27017",
+ *         database: "myapp",
+ *         collection: "users",
+ *     });
+ *     const conn = $.let(NoSQL.MongoDB.connect(config));
+ *     const document = $.let(new Map([
+ *         ["username", variant('String', username)],
+ *         ["email", variant('String', email)],
+ *     ]), NoSQL.MongoDB.Types.BsonDocument);
+ *     const id = $.let(NoSQL.MongoDB.insertOne(conn, document));
+ *     $(NoSQL.MongoDB.close(conn));
+ *     return $.return(id);
+ * });
+ *
+ * const compiled = East.compileAsync(createUser.toIR(), NoSQL.MongoDB.Implementation);
+ * await compiled("alice", "alice@example.com");  // "507f1f77bcf86cd799439011"
+ * ```
+ */
+export declare const mongodb_insert_one: import("@elaraai/east").AsyncPlatformDefinition<[StringType, DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>], StringType>;
+/**
+ * Updates a document in MongoDB.
+ *
+ * Updates a single document matching the query with the update operations.
+ * Returns the number of documents modified (0 or 1).
+ *
+ * @param handle - Connection handle from mongodb_connect()
+ * @param query - Query object to match document
+ * @param update - Update operations object
+ * @returns Number of documents modified
+ *
+ * @throws {EastError} When operation fails (location: "mongodb_update_one")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, IntegerType, variant } from "@elaraai/east";
+ * import { NoSQL } from "@elaraai/east-node-io";
+ *
+ * const updateEmail = East.function([StringType, StringType], IntegerType, ($, username, newEmail) => {
+ *     const config = $.let({
+ *         uri: "mongodb://localhost:27017",
+ *         database: "myapp",
+ *         collection: "users",
+ *     });
+ *     const conn = $.let(NoSQL.MongoDB.connect(config));
+ *     const query = $.let(new Map([["username", variant('String', username)]]), NoSQL.MongoDB.Types.BsonDocument);
+ *     const update = $.let(new Map([["email", variant('String', newEmail)]]), NoSQL.MongoDB.Types.BsonDocument);
+ *     const modified = $.let(NoSQL.MongoDB.updateOne(conn, query, update));
+ *     $(NoSQL.MongoDB.close(conn));
+ *     return $.return(modified);
+ * });
+ *
+ * const compiled = East.compileAsync(updateEmail.toIR(), NoSQL.MongoDB.Implementation);
+ * await compiled("alice", "newemail@example.com");  // 1n (updated) or 0n (not found)
+ * ```
+ */
+export declare const mongodb_update_one: import("@elaraai/east").AsyncPlatformDefinition<[StringType, DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>, DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>], IntegerType>;
+/**
+ * Deletes a document from MongoDB.
+ *
+ * Deletes a single document matching the query object.
+ * Returns the number of documents deleted (0 or 1).
+ *
+ * @param handle - Connection handle from mongodb_connect()
+ * @param query - Query object to match document
+ * @returns Number of documents deleted
+ *
+ * @throws {EastError} When operation fails (location: "mongodb_delete_one")
+ *
+ * @example
+ * ```ts
+ * import { East, StringType, IntegerType, variant } from "@elaraai/east";
+ * import { NoSQL } from "@elaraai/east-node-io";
+ *
+ * const deleteUser = East.function([StringType], IntegerType, ($, username) => {
+ *     const config = $.let({
+ *         uri: "mongodb://localhost:27017",
+ *         database: "myapp",
+ *         collection: "users",
+ *     });
+ *     const conn = $.let(NoSQL.MongoDB.connect(config));
+ *     const query = $.let(new Map([["username", variant('String', username)]]), NoSQL.MongoDB.Types.BsonDocument);
+ *     const deleted = $.let(NoSQL.MongoDB.deleteOne(conn, query));
+ *     $(NoSQL.MongoDB.close(conn));
+ *     return $.return(deleted);
+ * });
+ *
+ * const compiled = East.compileAsync(deleteUser.toIR(), NoSQL.MongoDB.Implementation);
+ * await compiled("alice");  // 1n (deleted) or 0n (not found)
+ * ```
+ */
+export declare const mongodb_delete_one: import("@elaraai/east").AsyncPlatformDefinition<[StringType, DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>], IntegerType>;
+/**
+ * Deletes multiple documents from MongoDB.
+ *
+ * Deletes all documents matching the query object.
+ * Returns the number of documents deleted.
+ *
+ * @param handle - Connection handle from mongodb_connect()
+ * @param query - Query object to match documents (empty query matches all)
+ * @returns Number of documents deleted
+ *
+ * @throws {EastError} When operation fails (location: "mongodb_delete_many")
+ *
+ * @internal
+ */
+export declare const mongodb_delete_many: import("@elaraai/east").AsyncPlatformDefinition<[StringType, DictType<StringType, import("@elaraai/east").RecursiveType<import("@elaraai/east").EastType>>], IntegerType>;
+/**
+ * Closes a MongoDB connection.
+ *
+ * Closes the MongoDB connection and releases all resources.
+ *
+ * @param handle - Connection handle from mongodb_connect()
+ * @returns Null on success
+ *
+ * @throws {EastError} When handle is invalid (location: "mongodb_close")
+ *
+ * @example
+ * ```ts
+ * import { East, NullType } from "@elaraai/east";
+ * import { NoSQL } from "@elaraai/east-node-io";
+ *
+ * const cleanup = East.function([], NullType, $ => {
+ *     const config = $.let({
+ *         uri: "mongodb://localhost:27017",
+ *         database: "myapp",
+ *         collection: "users",
+ *     });
+ *     const conn = $.let(NoSQL.MongoDB.connect(config));
+ *     // ... do work ...
+ *     $(NoSQL.MongoDB.close(conn));
+ *     return $.return(null);
+ * });
+ *
+ * const compiled = East.compileAsync(cleanup.toIR(), NoSQL.MongoDB.Implementation);
+ * await compiled();
+ * ```
+ */
+export declare const mongodb_close: import("@elaraai/east").AsyncPlatformDefinition<[StringType], NullType>;
+/**
+ * Closes all active MongoDB connections.
+ *
+ * Utility function for test cleanup. Closes all open connection handles,
+ * useful for ensuring cleanup even when tests fail.
+ *
+ * @returns Null on success
+ *
+ * @internal
+ */
+export declare const mongodb_close_all: import("@elaraai/east").AsyncPlatformDefinition<[], NullType>;
+/**
+ * Node.js implementation of MongoDB platform functions.
+ *
+ * Pass this to East.compileAsync() to enable MongoDB operations.
+ */
+export declare const MongoDBImpl: PlatformFunction[];
+//# sourceMappingURL=mongodb.d.ts.map

package/dist/nosql/mongodb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongodb.d.ts","sourceRoot":"","sources":["../../src/nosql/mongodb.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAQ,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAA8E,MAAM,eAAe,CAAC;AAErL,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM/D;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,+FAAsC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe;;;;gBAAiF,CAAC;AAE9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,gBAAgB,yQAAiH,CAAC;AAE/I;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,iBAAiB;;;8GAAuI,CAAC;AAEtK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,kBAAkB,0KAAiG,CAAC;AAEjI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,kBAAkB,0QAAoH,CAAC;AAEpJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,kBAAkB,2KAAkG,CAAC;AAElI;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,mBAAmB,2KAAmG,CAAC;AAEpI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,aAAa,yEAAwE,CAAC;AAEnG;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,+DAAwD,CAAC;AAqEvF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,gBAAgB,EA+NzC,CAAC"}