{"id":16347,"library":"emdb","title":"Exact Mass Database Manager (emdb)","description":"emdb is a JavaScript/TypeScript library designed for managing and querying databases of molecular formulas, primarily focused on exact mass calculations in cheminformatics. It is part of the larger 'mass-tools' monorepo maintained by cheminfo. The library is currently stable at version 7.56.0 (as of April 2026), demonstrating a rapid release cadence with multiple updates often shipped monthly, indicating very active development. Key functionalities include loading various predefined chemical databases (e.g., test, KnapSack, commercial, contaminants), creating custom molecular formula databases from structured arrays or Google Sheets, and providing robust utility modules for generating molecular formulas from peptide or nucleotide sequences. It enhances cheminformatics applications by offering precise mass calculations and comprehensive molecular formula manipulation, including detailed information such as exact mass, molecular weight, charge, OCL (Open Chemistry Libre), and mass spectrometry filter data.","status":"active","version":"3.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/cheminfo/mass-tools","tags":["javascript","typescript"],"install":[{"cmd":"npm install emdb","lang":"bash","label":"npm"},{"cmd":"yarn add emdb","lang":"bash","label":"yarn"},{"cmd":"pnpm add emdb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For modern TypeScript and ES Module (ESM) environments, use the default import. While the README shows CommonJS `require` examples, it might cause compatibility issues in pure ESM projects.","wrong":"const emdb = require('emdb');","symbol":"emdb","correct":"import emdb from 'emdb';"},{"note":"Utility classes like `MF` are nested under the default export's `Util` property. They are not top-level named exports and cannot be directly imported.","wrong":"import { MF } from 'emdb';\nconst mf = new MF('C6H6');","symbol":"emdb.Util.MF","correct":"import emdb from 'emdb';\nconst mf = new emdb.Util.MF('C6H6');"},{"note":"Methods for peptide sequence manipulation are accessed via `emdb.Util.Peptide`. Direct import of `Peptide` is not supported.","wrong":"import { Peptide } from 'emdb';\nconst peptideMF = Peptide.sequenceToMF('AAA');","symbol":"emdb.Util.Peptide.sequenceToMF","correct":"import emdb from 'emdb';\nconst peptideMF = emdb.Util.Peptide.sequenceToMF('AAA');"},{"note":"Nucleotide utilities are similarly nested under `emdb.Util.Nucleotide` and require accessing them through the default `emdb` import.","wrong":"import { Nucleotide } from 'emdb';\nconst dnaMF = Nucleotide.mfFromSequence('GATTACA', { kind: 'dna' });","symbol":"emdb.Util.Nucleotide.mfFromSequence","correct":"import emdb from 'emdb';\nconst dnaMF = emdb.Util.Nucleotide.mfFromSequence('GATTACA', { kind: 'dna' });"}],"quickstart":{"code":"import emdb from 'emdb';\n\n// 1. Initialize the EMDB manager and load a test database\nconst dbManager = emdb;\ndbManager.loadTest(); // Loads a database named 'test' with MFs from C1 to C100\n\nconsole.log('Test database loaded. Number of entries (approx):', Object.keys(dbManager.db.test).length);\n\n// 2. Use the Molecular Formula utility to parse and get information\nconst mfParser = new dbManager.Util.MF('C6H6O');\nconsole.log('MF Parser info for C6H6O:', mfParser.getInfo());\n\n// 3. Generate a molecular formula from a peptide sequence\nconst peptideSequence = 'VALINE';\nconst peptideMF = dbManager.Util.Peptide.sequenceToMF(peptideSequence);\nconsole.log(`Molecular formula for peptide '${peptideSequence}': ${peptideMF}`);\n\n// 4. Generate a molecular formula from a DNA nucleotide sequence\nconst dnaSequence = 'GATTACA';\nconst dnaMF = dbManager.Util.Nucleotide.mfFromSequence(dnaSequence, { kind: 'dna', circular: false });\nconsole.log(`Molecular formula for DNA sequence '${dnaSequence}': ${dnaMF}`);\n\n// 5. Example of loading a database from an array of molecular formulas\nconst customMFs = ['C2H4O2', 'C3H8O'];\ndbManager.fromArray(customMFs, { database: 'myCustomDB' });\nconsole.log('Custom database loaded. Entries:', dbManager.db.myCustomDB);","lang":"typescript","description":"Demonstrates loading a test database, using the MF utility, generating molecular formulas from peptide and nucleotide sequences, and creating a custom database from an array."},"warnings":[{"fix":"It is crucial to review the comprehensive changelog on GitHub for `cheminfo/mass-tools` when upgrading from older major versions to understand all breaking changes. Always install the latest stable version for new projects: `npm install emdb@latest`.","message":"The package version provided in the prompt (3.5.0) is severely outdated. The `emdb` package is currently at version 7.56.0 (as of April 2026), being actively developed as part of the `mass-tools` monorepo. Significant API changes and breaking modifications are highly probable between versions 3.x and 7.x, even if not explicitly detailed in the provided truncated changelog.","severity":"breaking","affected_versions":">=3.x <7.x"},{"fix":"Always prefer `import emdb from 'emdb';` for the main library and access its utilities via `emdb.Util.XYZ`. Ensure your `tsconfig.json` and `package.json` are correctly configured for your chosen module system (e.g., `\"type\": \"module\"` in `package.json` for ESM).","message":"The examples in the `emdb` README predominantly use CommonJS `require()` syntax. While `emdb` is likely distributed with both CJS and ESM entry points, using `require()` directly may lead to `ReferenceError: require is not defined` errors in pure ES Module (ESM) environments or modern TypeScript projects configured for ESM outputs.","severity":"gotcha","affected_versions":">=7.0.0"},{"fix":"Access all utilities through the default `emdb` import: `import emdb from 'emdb'; const mf = new emdb.Util.MF(...);`","message":"All specialized utility classes and methods (e.g., `MF`, `Peptide`, `Nucleotide`, `IsotopicDistribution`) are nested within the `Util` property of the default `emdb` export. Attempting to destructure these or import them directly as named exports (e.g., `import { MF } from 'emdb';`) will result in runtime errors as they are not exported at the top level.","severity":"gotcha","affected_versions":">=3.x"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Replace `const emdb = require('emdb');` with `import emdb from 'emdb';` to use the ESM syntax.","cause":"This error occurs when CommonJS `require()` syntax is used in an ES Module (ESM) context, such as a `.mjs` file or a Node.js project with `\"type\": \"module\"` in its `package.json`.","error":"ReferenceError: require is not defined"},{"fix":"Verify that `emdb` is correctly imported as a default export (`import emdb from 'emdb';`) and that `emdb.Util.MF` is properly accessed and instantiated using `new`.","cause":"This typically indicates that `emdb.Util.MF` is `undefined` or not correctly resolved as a class. Common causes include an incorrect import of `emdb` itself, or trying to access `MF` directly as a named export instead of through `emdb.Util`.","error":"TypeError: emdb.Util.MF is not a constructor"},{"fix":"Ensure `emdb` is imported as the default export and that `Util` and `Peptide` are correctly accessed as properties: `emdb.Util.Peptide.sequenceToMF(...)`. Double-check method casing and arguments.","cause":"The `sequenceToMF` method or the `emdb.Util.Peptide` object itself is `undefined`, usually due to an incorrect import path or an attempt to directly import `Peptide`.","error":"TypeError: emdb.Util.Peptide.sequenceToMF is not a function"}],"ecosystem":"npm"}