Exact Mass Database Manager (emdb)

Common errors

• ReferenceError: require is not defined

  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`.
  fix Replace `const emdb = require('emdb');` with `import emdb from 'emdb';` to use the ESM syntax.

• TypeError: emdb.Util.MF is not a constructor

  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`.
  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`.

• TypeError: emdb.Util.Peptide.sequenceToMF is not a function

  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`.
  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.

Warnings

• breaking 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.
  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`.
• gotcha 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.
  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).
• gotcha 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.
  Fix: Access all utilities through the default `emdb` import: `import emdb from 'emdb'; const mf = new emdb.Util.MF(...);`

Install

• npm install emdb npm
• yarn add emdb yarn
• pnpm add emdb pnpm

Imports

• emdb
  wrong:

  const emdb = require('emdb');

  correct:

  import emdb from 'emdb';

  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.
• emdb.Util.MF
  wrong:

  import { MF } from 'emdb';
  const mf = new MF('C6H6');

  correct:

  import emdb from 'emdb';
  const mf = new emdb.Util.MF('C6H6');

  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.
• emdb.Util.Peptide.sequenceToMF
  wrong:

  import { Peptide } from 'emdb';
  const peptideMF = Peptide.sequenceToMF('AAA');

  correct:

  import emdb from 'emdb';
  const peptideMF = emdb.Util.Peptide.sequenceToMF('AAA');

  Methods for peptide sequence manipulation are accessed via `emdb.Util.Peptide`. Direct import of `Peptide` is not supported.
• emdb.Util.Nucleotide.mfFromSequence
  wrong:

  import { Nucleotide } from 'emdb';
  const dnaMF = Nucleotide.mfFromSequence('GATTACA', { kind: 'dna' });

  correct:

  import emdb from 'emdb';
  const dnaMF = emdb.Util.Nucleotide.mfFromSequence('GATTACA', { kind: 'dna' });

  Nucleotide utilities are similarly nested under `emdb.Util.Nucleotide` and require accessing them through the default `emdb` import.

Quickstart

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.

import emdb from 'emdb';

// 1. Initialize the EMDB manager and load a test database
const dbManager = emdb;
dbManager.loadTest(); // Loads a database named 'test' with MFs from C1 to C100

console.log('Test database loaded. Number of entries (approx):', Object.keys(dbManager.db.test).length);

// 2. Use the Molecular Formula utility to parse and get information
const mfParser = new dbManager.Util.MF('C6H6O');
console.log('MF Parser info for C6H6O:', mfParser.getInfo());

// 3. Generate a molecular formula from a peptide sequence
const peptideSequence = 'VALINE';
const peptideMF = dbManager.Util.Peptide.sequenceToMF(peptideSequence);
console.log(`Molecular formula for peptide '${peptideSequence}': ${peptideMF}`);

// 4. Generate a molecular formula from a DNA nucleotide sequence
const dnaSequence = 'GATTACA';
const dnaMF = dbManager.Util.Nucleotide.mfFromSequence(dnaSequence, { kind: 'dna', circular: false });
console.log(`Molecular formula for DNA sequence '${dnaSequence}': ${dnaMF}`);

// 5. Example of loading a database from an array of molecular formulas
const customMFs = ['C2H4O2', 'C3H8O'];
dbManager.fromArray(customMFs, { database: 'myCustomDB' });
console.log('Custom database loaded. Entries:', dbManager.db.myCustomDB);