{"id":25040,"library":"bson-transpilers","title":"bson-transpilers","description":"Source-to-source compiler for BSON document expressions, converting between shell input and multiple output languages (Java, C#, Node.js, Python, Ruby, Go). Current stable version is 3.3.5. Developed by MongoDB for Compass, it uses ANTLR for parsing. The shell output is disabled and only intended for legacy mongo shell, not mongosh. Python support was removed but remains in an older commit. The library supports both Query and Pipeline modes, and can generate import statements automatically. It is the primary tool for converting MongoDB shell syntax to driver code in different languages, with error codes and line/column details for syntax errors.","status":"active","version":"3.3.5","language":"javascript","source_language":"en","source_url":"https://github.com/mongodb-js/compass","tags":["javascript"],"install":[{"cmd":"npm install bson-transpilers","lang":"bash","label":"npm"},{"cmd":"yarn add bson-transpilers","lang":"bash","label":"yarn"},{"cmd":"pnpm add bson-transpilers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for ANTLR-generated parser and lexer","package":"antlr4","optional":false}],"imports":[{"note":"The package uses CommonJS and does not export ESM. The default export is the transpiler object. Named imports are not available.","wrong":"import transpiler from 'bson-transpilers';","symbol":"transpiler","correct":"const transpiler = require('bson-transpilers');"},{"note":"The API is transpiler[inputLang][outputLang].compile(string). Input and output languages are required. Common mistake is swapping them.","wrong":"transpiler.java.shell.compile(code)  // wrong order","symbol":"transpiler.shell.java.compile","correct":"const result = transpiler.shell.java.compile(code);"},{"note":"getImports requires two arguments: mode ('Query' or 'Pipeline') and driverSyntax (boolean). Missing them leads to undefined behavior.","wrong":"transpiler.shell.java.getImports();  // missing mode and driverSyntax arguments","symbol":"transpiler.shell.java.getImports","correct":"const imports = transpiler.shell.java.getImports('Query', true);"},{"note":"Error objects have custom properties: code (number), line (number), column (number), symbol (string). Not all errors have line/column.","wrong":"","symbol":"errors","correct":"} catch (error) { console.log(error.code, error.line, error.column); }"}],"quickstart":{"code":"const transpiler = require('bson-transpilers');\n\nconst inputLanguage = 'shell';\nconst outputLanguage = 'java';\nconst codeString = `{ item: \"book\", qty: Int32(10), tags: [\"red\", \"blank\"], dim_cm: [14, Int32(\"81\")] }`;\n\ntry {\n  const compiled = transpiler[inputLanguage][outputLanguage].compile(codeString);\n  console.log(compiled);\n  // Output: new Document(\"item\", \"book\").append(\"qty\", 10).append(\"tags\", Arrays.asList(\"red\", \"blank\")).append(\"dim_cm\", Arrays.asList(14L, 81)))\n  \n  const imports = transpiler[inputLanguage][outputLanguage].getImports('Query', true);\n  console.log(imports);\n  // Output: import java.util.Arrays;\n  // import org.bson.Document;\n} catch (error) {\n  console.error(`Error ${error.code}: ${error.message}`);\n  if (error.line) console.error(`at line ${error.line}, column ${error.column}`);\n}","lang":"javascript","description":"Demonstrates basic usage: compile a BSON document from shell to Java, and generate necessary import statements."},"warnings":[{"fix":"Use shell as input only; do not use output language 'shell'. Consider outputting JavaScript (node) for mongosh compatibility.","message":"Shell output is disabled and only compatible with legacy mongo shell, not mongosh.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"If you need Python output, use an older version (<=2.x) or reference the removed code at https://github.com/mongodb-js/compass/tree/80cf701e44cd966207f956fac69e8233861b1cd5/packages/bson-transpilers.","message":"Python support has been removed from the package in recent versions.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always call getImports with mode ('Query' or 'Pipeline') and driverSyntax (boolean).","message":"The getImports function requires two arguments (mode and driverSyntax). Omitting them will not throw but may return undefined or incorrect imports.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure input language is lowercase and matches exactly: 'shell', 'javascript' (or 'node'?). Check documentation for supported values.","message":"Input language is case-sensitive. Use 'shell', not 'Shell' or 'SHELL'.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'npm install bson-transpilers' and ensure you are using require (not import) in CommonJS context.","cause":"Package not installed or wrong import path.","error":"Cannot find module 'bson-transpilers'"},{"fix":"Check that input is one of 'shell', 'javascript' and output is one of 'java', 'csharp', 'node', 'ruby', 'go'. Do not use 'python' (removed) or 'shell' (deprecated).","cause":"Invalid input or output language string, or the combination is not supported.","error":"transpiler[input][output] is not a function"},{"fix":"Validate the input code string. Use shell-compatible BSON literal syntax, e.g., { field: value } with proper Int32(), ObjectId(), etc.","cause":"Syntax error in the BSON expression – possibly missing braces, quotes, or invalid types.","error":"Error: line 1:0 mismatched input '{' expecting ..."},{"fix":"Ensure the package is up to date (npm install bson-transpilers@latest) and that the output language is listed in supported outputs.","cause":"Output language 'java' might not be installed or supported in this version.","error":"TypeError: transpiler.shell.java.getImports is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}