fix(mf-parser): provide getInfo advanced typings (#241)

Refs: #231 (comment)
Refs: #226

packages/isotopic-distribution/src/IsotopicDistribution.types.ts

@@ -1,4 +1,4 @@
-import type { IsotopesInfo, PartInfo } from 'mf-parser';
+import type { IsotopesInfo, PartInfo, GetInfoOptions } from 'mf-parser';
 
 /**
  * An object containing two arrays.
@@ -8,9 +8,10 @@ export interface XY {
   y: number[];
 }
 
-export interface IsotopicDistributionPart extends PartInfo {
+export interface IsotopicDistributionPart extends PartInfo<GetInfoOptions> {
   confidence: number;
   isotopesInfo: IsotopesInfo;
+  /** alias to monoisotopicMass */
   em: number;
 }
 

packages/mf-parser/src/MF.ts

@@ -0,0 +1,114 @@
+import type {
+  DisplayPart,
+  EA,
+  Element,
+  FlattenOptions,
+  Parts,
+} from './MF.types';
+import { MFInternal } from './MFInternal';
+import type {
+  GetInfoOptions,
+  GetInfoOptionsAllowed,
+  PartInfo,
+  PartInfoWithParts,
+} from './util/getInfo.types';
+import type { IsotopesInfo } from './util/getIsotopesInfo.types';
+
+export interface MFConstructorOptions {
+  ensureCase?: boolean;
+}
+
+export class MF {
+  private readonly internal: MFInternal;
+
+  constructor(mf: string, options: MFConstructorOptions = {}) {
+    this.internal = new MFInternal(mf, options);
+  }
+
+  /**
+   * Returns an array of objects with kind and value that can be used to easily
+   * display the molecular formula.
+   */
+  toDisplay(): DisplayPart[] {
+    return this.internal.toDisplay();
+  }
+
+  /**
+   * Returns a string that represents the molecular formula adding subscript and superscript in HTML.
+   */
+  toHtml(): string {
+    return this.internal.toHtml();
+  }
+
+  /**
+   * Returns a string that represents the molecular formula adding subscript and superscript
+   * using Unicode characters. This can not be parsed anymore so kind of dead end ...
+   */
+  toText(): string {
+    return this.internal.toText();
+  }
+
+  /**
+   * Similar to toText but returns a canonic string in which the atoms are sorted using the Hill system
+   */
+  toCanonicText(): string {
+    return this.internal.toCanonicText();
+  }
+
+  toParts(options?: { expand?: boolean }): Parts[] {
+    return this.internal.toParts(options);
+  }
+
+  /**
+   * Returns an object with the global MF, global charge, monoisotopic mass and mass
+   * as well as the same information for all the parts
+   */
+  getInfo<GIO extends GetInfoOptionsAllowed = GetInfoOptions>(
+    options?: GIO,
+  ): PartInfo<GIO> | PartInfoWithParts<GIO> {
+    return this.internal.getInfo(options);
+  }
+
+  /**
+   * Returns an object with the elemental analysis
+   */
+  getEA(): EA[] {
+    return this.internal.getEA();
+  }
+
+  /**
+   * Get the different elements for each part
+   */
+  getElements(): Element[] {
+    return this.internal.getElements();
+  }
+
+  /**
+   * Returns an array with each atom and isotopic composition
+   */
+  getIsotopesInfo(options = {}): IsotopesInfo | [] {
+    return this.internal.getIsotopesInfo(options);
+  }
+
+  /**
+   * Get a canonized parsable Molecule Formula
+   */
+  toMF(): string {
+    return this.internal.toMF();
+  }
+
+  /**
+   * Get a canonized MF
+   */
+  toNeutralMF(): string {
+    return this.internal.toNeutralMF();
+  }
+
+  canonize(): void {
+    return this.internal.canonize();
+  }
+
+  flatten(options?: FlattenOptions): string[] {
+    return this.internal.flatten(options);
+  }
+}

packages/mf-parser/src/MF.types.ts

@@ -0,0 +1,45 @@
+/**
+ * Temporary interface for incremental migrations to typescript
+ */
+
+/**
+ * approximately toDisplay return type
+ */
+export interface DisplayPart {
+  kind: string;
+  value: string;
+}
+
+/**
+ * approximately toParts return type
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Parts = any[];
+
+/**
+ * approximately getEA return type
+ */
+export interface EA {
+  element: string;
+  mass: number;
+  ratio: number;
+}
+
+/**
+ * approximately getElements return type
+ */
+export interface Element {
+  symbol: string;
+  number: number;
+  isotope?: number;
+}
+
+/**
+ * approximately flatten options type
+ */
+export interface FlattenOptions {
+  /** @default false */
+  groupIdentical: boolean;
+  /** @default 100000 */
+  limit: number;
+}

packages/mf-parser/src/MF.js → packages/mf-parser/src/MFInternal.js

@@ -19,7 +19,7 @@ import { toText } from './util/toText';
 /**
  * Class allowing to deal with molecular formula and derived information
  */
-export class MF {
+export class MFInternal {
   constructor(mf, options = {}) {
     if (options.ensureCase) {
       mf = ensureCase(mf);
@@ -52,7 +52,7 @@ export class MF {
 
   /**
    * Returns a string that represents the molecular formula adding subscript and superscript
-   * using unicode characters. This can not be parsed anymore so kind of dead end ...
+   * using Unicode characters. This can not be parsed anymore so kind of dead end ...
    * @returns {string}
    */
   toText() {
@@ -69,7 +69,7 @@ export class MF {
    */
   toCanonicText() {
     if (!this.cache.canonicText) {
-      this.cache.canonicText = new MF(this.toMF()).toText(this.cache.displayed);
+      this.cache.canonicText = new MFInternal(this.toMF()).toText();
     }
     return this.cache.canonicText;
   }
@@ -100,18 +100,19 @@ export class MF {
 
   /**
    * Returns an object with the elemental analysis
+   * @returns {*[]}
    */
-  getEA(options = {}) {
+  getEA() {
     if (!this.cache.ea) {
       this.toParts();
-      this.cache.ea = getEA(this.cache.parts, options);
+      this.cache.ea = getEA(this.cache.parts);
     }
     return this.cache.ea;
   }
 
   /**
    * Get the different elements for each part
-   * @returns an array
+   * @returns {*[]}
    */
   getElements() {
     if (!this.cache.elements) {
@@ -147,6 +148,7 @@ export class MF {
 
   /**
    * Get a canonized MF
+   * @returns {string}
    */
   toNeutralMF() {
     if (!this.cache.neutralMF) {