mongo-query-dsl 1.0.0

package/examples/usage.ts

@@ -0,0 +1,190 @@
+import { NoQL } from "../src/index";
+
+/**
+ * Example usage of the MongoDB Query DSL
+ *
+ * This file demonstrates both JSON and DSL query syntax
+ *
+ * IMPORTANT: This is an example file. To run it, you need:
+ * 1. A running MongoDB instance
+ * 2. Sample data loaded into your database
+ * 3. Update the connection string below
+ */
+
+async function main() {
+  // Connect to MongoDB
+  const connectionString =
+    process.env.MONGODB_URI || "mongodb://localhost:27017";
+  const noql = await NoQL.connect(connectionString);
+
+  console.log("MongoDB Query DSL Examples\n");
+  console.log("=".repeat(50));
+
+  // Example 1: Simple JSON Query
+  console.log("\n1. Simple JSON Query - Get document by _id");
+  console.log("-".repeat(50));
+
+  const jsonQuery1 = {
+    output: "value" as const,
+    start: {
+      collection: "documents",
+      db: "myDb",
+      where: { _id: "doc_123" },
+    },
+    steps: [{ type: "get" as const, fields: ["title", "content"] }],
+  };
+
+  const result1 = await noql.executeJson(jsonQuery1);
+  console.log("Query:", JSON.stringify(jsonQuery1, null, 2));
+  console.log("Result:", JSON.stringify(result1, null, 2));
+
+  // Example 2: JSON Query with LOOKUP
+  console.log("\n2. JSON Query with LOOKUP step");
+  console.log("-".repeat(50));
+
+  const jsonQuery2 = {
+    output: "document" as const,
+    start: {
+      collection: "documents",
+      db: "myDb",
+      where: { _id: "doc_123" },
+    },
+    steps: [
+      {
+        type: "lookup" as const,
+        collection: "users",
+        db: "myDb",
+        by: "userId",
+      },
+      { type: "get" as const, fields: ["name", "email"] },
+    ],
+  };
+
+  const result2 = await noql.executeJson(jsonQuery2);
+  console.log("Query:", JSON.stringify(jsonQuery2, null, 2));
+  console.log("Result:", JSON.stringify(result2, null, 2));
+
+  // Example 3: JSON Query with Dynamic Lookups
+  console.log("\n3. JSON Query with Dynamic Lookups (using :prefixed values)");
+  console.log("-".repeat(50));
+
+  const jsonQuery3 = {
+    output: "trace" as const,
+    start: {
+      collection: "documents",
+      db: "myDb",
+      where: { _id: "doc_123" },
+    },
+    steps: [
+      {
+        type: "lookup" as const,
+        collection: "parentCollection",
+        db: "myDb",
+        by: "parentId",
+      },
+      {
+        type: "get" as const,
+        fields: ["ownerId", "ownerType", "ownerSource"],
+      },
+      {
+        type: "lookup" as const,
+        collection: ":ownerType",
+        db: ":ownerSource",
+        by: "ownerId",
+      },
+      { type: "get" as const, fields: ["salesId", "name"] },
+    ],
+  };
+
+  const result3 = await noql.executeJson(jsonQuery3);
+  console.log("Query:", JSON.stringify(jsonQuery3, null, 2));
+  console.log("Result:", JSON.stringify(result3, null, 2));
+
+  // Example 4: DSL Query - Simple
+  console.log("\n4. DSL Query - Simple");
+  console.log("-".repeat(50));
+
+  const dslQuery1 = `
+FROM documents IN myDb WHERE _id = "doc_123"
+-> GET title, content
+  `.trim();
+
+  const result4 = await noql.executeDSL(dslQuery1);
+  console.log("DSL:", dslQuery1);
+  console.log("Result:", JSON.stringify(result4, null, 2));
+
+  // Example 5: DSL Query - With LOOKUP
+  console.log("\n5. DSL Query - With LOOKUP");
+  console.log("-".repeat(50));
+
+  const dslQuery2 = `
+FROM documents IN myDb WHERE _id = "doc_123"
+-> LOOKUP users IN myDb BY userId
+-> GET name, email
+  `.trim();
+
+  const result5 = await noql.executeDSL(dslQuery2);
+  console.log("DSL:", dslQuery2);
+  console.log("Result:", JSON.stringify(result5, null, 2));
+
+  // Example 6: DSL Query - With Dynamic Lookups and Trace
+  console.log("\n6. DSL Query - With Dynamic Lookups and Trace");
+  console.log("-".repeat(50));
+
+  const dslQuery3 = `
+WITH output: "trace"
+FROM documents IN myDb WHERE _id = "doc_123"
+-> LOOKUP parentCollection IN myDb BY parentId
+-> GET ownerId, ownerType, ownerSource
+-> LOOKUP :ownerType IN :ownerSource BY ownerId
+-> GET salesId, name
+  `.trim();
+
+  const result6 = await noql.executeDSL(dslQuery3);
+  console.log("DSL:", dslQuery3);
+  console.log("Result:", JSON.stringify(result6, null, 2));
+
+  // Example 7: DSL Query - With WHERE conditions
+  console.log("\n7. DSL Query - With WHERE conditions in LOOKUP");
+  console.log("-".repeat(50));
+
+  const dslQuery4 = `
+FROM documents IN myDb WHERE _id = "doc_123"
+-> LOOKUP users IN myDb BY userId WHERE status = "active" AND verified = true
+-> GET name, email
+  `.trim();
+
+  const result7 = await noql.executeDSL(dslQuery4);
+  console.log("DSL:", dslQuery4);
+  console.log("Result:", JSON.stringify(result7, null, 2));
+
+  // Example 8: Parse DSL without executing
+  console.log("\n8. Parse DSL (without executing)");
+  console.log("-".repeat(50));
+
+  const dslToParse = `
+WITH output: "document"
+FROM documents IN myDb WHERE _id = "doc_123"
+-> LOOKUP users IN myDb BY userId
+-> GET name, email
+  `.trim();
+
+  const parsedQuery = noql.parseDSL(dslToParse);
+  console.log("DSL:", dslToParse);
+  console.log("Parsed to JSON:", JSON.stringify(parsedQuery, null, 2));
+
+  // Close connection
+  await noql.close();
+  console.log("\n" + "=".repeat(50));
+  console.log("Connection closed");
+}
+
+// Run examples
+if (require.main === module) {
+  main().catch((error) => {
+    console.error("Error running examples:", error);
+    process.exit(1);
+  });
+}
+
+export { main };

package/jest.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+    '!src/examples/**',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "mongo-query-dsl",
+  "version": "1.0.0",
+  "description": "A domain-specific language (DSL) for traversing and querying MongoDB documents with dynamic lookups",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "example": "npm run build && node dist/examples/usage.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "keywords": [
+    "mongodb",
+    "dsl",
+    "query",
+    "lookup",
+    "traverse"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "mongodb": "^6.3.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.10.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.3.0"
+  }
+}