{"id":43629,"library":"pivotql-compiler-mongodb","title":"PivotQL MongoDB Compiler","description":"Compiles PivotQL ASTs into MongoDB query objects. This library is part of the PivotQL ecosystem, a DSL for filtering and querying data structures. Current stable version is 0.4.2, released as an alpha. It is designed for Node.js environments that use MongoDB. Key differentiators: allows writing expressive, SQL-like filter syntax that gets transpiled into MongoDB's native query language. Minimal dependencies; relies on the PivotQL parser and MongoDB driver. Suitable for APIs where user-defined filters need to be safely converted to MongoDB queries.","status":"active","version":"0.4.2","language":"javascript","source_language":"en","source_url":"git://github.com/jrmi/pivotql","tags":["javascript","query","ast","dsl","unist","mongodb"],"install":[{"cmd":"npm install pivotql-compiler-mongodb","lang":"bash","label":"npm"},{"cmd":"yarn add pivotql-compiler-mongodb","lang":"bash","label":"yarn"},{"cmd":"pnpm add pivotql-compiler-mongodb","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Parses PivotQL expression strings into ASTs required by this compiler","package":"pivotql-parser-expression","optional":false}],"imports":[{"note":"Package is ESM-only; commonjs require will fail.","wrong":"const compile = require('pivotql-compiler-mongodb')","symbol":"compile","correct":"import { compile } from 'pivotql-compiler-mongodb'"},{"note":"compile is a named export, not default.","wrong":"import compile from 'pivotql-compiler-mongodb'","symbol":"compile","correct":"import { compile } from 'pivotql-compiler-mongodb'"},{"note":"parse is from the parser package, not the compiler.","wrong":"import { compile } from 'pivotql-parser-expression'","symbol":"parse (from pivotql-parser-expression)","correct":"import { parse } from 'pivotql-parser-expression'"}],"quickstart":{"code":"import { parse } from 'pivotql-parser-expression';\nimport { compile } from 'pivotql-compiler-mongodb';\n\nconst query = '( height <= 20 or favorites.color == \"green\" ) and firstname in [\"john\", \"doug\"]';\nconst ast = parse(query);\nconst queryMongo = compile(ast);\nconsole.log(JSON.stringify(queryMongo));\n// {\"$and\":[{\"$or\":[{\"height\":{\"$lte\":20}},{\"favorites.color\":\"green\"}]},{\"firstname\":{\"$in\":[\"john\",\"doug\"]}}]}\n","lang":"typescript","description":"Parses a PivotQL expression string into an AST and compiles it to a MongoDB query object."},"warnings":[{"fix":"Always parse your query string with the pivotql-parser-expression first, then pass the result to compile.","message":"The compile function expects an AST object, not a string. Passing a string throws a silent error.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use ES module import syntax or set type: \"module\" in package.json.","message":"Package is ESM-only. Using CommonJS require will result in a runtime error.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Pin to exact version and test upgrades carefully.","message":"Alpha version (0.4.2). API may change without major version bump.","severity":"deprecated","affected_versions":"<1.0.0"},{"fix":"Avoid field keys containing dots; they will be treated as nested path separators.","message":"Field paths like 'favorites.color' are interpreted as dot notation. The compiler does not automatically handle nested objects with dots in keys.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"search_vec":"'0.4.2':31 'allow':47 'alpha':35 'api':76 'ast':6,92 'compil':3,4 'convert':86 'current':27 'data':25 'defin':80 'depend':65 'design':38 'differenti':46 'driver':73 'dsl':20,93 'ecosystem':18 'environ':41 'express':49 'filter':22,53,81 'get':56 'javascript':90 'key':45 'languag':63 'librari':12 'like':52 'minim':64 'mongodb':2,8,44,59,72,88,95 'nativ':61 'need':82 'node.js':40 'object':10 'parser':70 'part':14 'pivotql':1,5,17,69 'queri':9,24,62,89,91 'releas':32 'reli':66 'safe':85 'sql':51 'sql-like':50 'stabl':28 'structur':26 'suitabl':74 'syntax':54 'transpil':57 'unist':94 'use':43 'user':79 'user-defin':78 'version':29 'write':48","created_at":"2026-06-05T17:00:43.064395+00:00","updated_at":"2026-06-05T17:00:43.064395+00:00","problems":[{"fix":"Create a custom declaration file (e.g., globals.d.ts) with `declare module 'pivotql-compiler-mongodb';`","cause":"Package does not ship TypeScript definitions. TypeScript users see this error when importing.","error":"Cannot find module 'pivotql-compiler-mongodb' or its corresponding type declarations."},{"fix":"Use `import { compile } from 'pivotql-compiler-mongodb'` correctly.","cause":"Importing the package incorrectly (e.g., using default import instead of named import).","error":"TypeError: compile is not a function"},{"fix":"Ensure package version >=0.4.0 and use ESM import. If using bundler, check resolve config.","cause":"If mistakenly finding a CommonJS build, but package is ESM-only.","error":"The requested module 'pivotql-compiler-mongodb' is a CommonJS module, which may not support all module.exports as ESM."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/jrmi/pivotql#readme","github":"git://github.com/jrmi/pivotql","docs":null,"changelog":null,"pypi":null,"npm":"pivotql-compiler-mongodb","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}