sdf-parser 7.0.5 → 8.0.0

package/src/parse.ts

@@ -0,0 +1,227 @@
+import { ensureString } from 'ensure-string';
+
+import { getEntriesBoundaries } from './getEntriesBoundaries.ts';
+import type { LabelInfo } from './util/getMolecule.ts';
+import { getMolecule } from './util/getMolecule.ts';
+
+/**
+ * A parsed SDF molecule entry. The `molfile` field contains the raw molfile
+ * string. Additional fields are populated from the SDF `> <field>` sections.
+ */
+export interface Molecule {
+  /** The raw V2000/V3000 molfile block. */
+  molfile: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [label: string]: any;
+}
+
+/**
+ * Options for the {@link parse} function.
+ */
+export interface ParseOptions {
+  /**
+   * Modifier functions applied to field values after parsing. The function
+   * receives the raw string value and may return a transformed value. Returning
+   * `undefined` or `null` removes the field from the molecule.
+   */
+  modifiers?: Record<string, (value: string) => unknown>;
+  /**
+   * Callback functions called for each field value. The callbacks are stored
+   * on the label info and available in statistics.
+   */
+  forEach?: Record<string, (value: unknown) => void>;
+  /**
+   * When `true`, numeric string values are automatically converted to numbers.
+   * @default true
+   */
+  dynamicTyping?: boolean;
+  /**
+   * End-of-line character. Auto-detected from the file content when not set.
+   * @default '\n'
+   */
+  eol?: string;
+  /**
+   * When `true`, normalises all `\r\n` and `\r` sequences to `\n` before
+   * parsing. Useful for SDF files with mixed or Windows-style line endings.
+   * @default false
+   */
+  mixedEOL?: boolean;
+  /**
+   * Only include fields whose names appear in this list.
+   * When combined with `exclude`, the field must satisfy both constraints.
+   */
+  include?: string[];
+  /**
+   * Exclude fields whose names appear in this list.
+   * When combined with `include`, the field must satisfy both constraints.
+   */
+  exclude?: string[];
+  /**
+   * A predicate function to filter molecules. Only molecules for which this
+   * function returns `true` are included in the result.
+   */
+  filter?: (molecule: Molecule) => boolean;
+}
+
+/**
+ * Statistics for a single SDF field label, as returned in
+ * {@link ParseResult.statistics}.
+ */
+export interface LabelStatistic {
+  /** Field label name. */
+  label: string;
+  /** Number of molecules that contain this field. */
+  counter: number;
+  /** Whether all parsed values are numeric. */
+  isNumeric: boolean;
+  /** Whether this field is included in the output (not excluded). */
+  keep: boolean;
+  /** Minimum numeric value, only set when `isNumeric` is `true`. */
+  minValue?: number;
+  /** Maximum numeric value, only set when `isNumeric` is `true`. */
+  maxValue?: number;
+  /** Whether every molecule in the result contains this field. */
+  always: boolean;
+}
+
+/**
+ * Return value of the {@link parse} function.
+ */
+export interface ParseResult {
+  /** Wall-clock time taken to parse, in milliseconds. */
+  time: number;
+  /** Parsed molecule entries. */
+  molecules: Molecule[];
+  /** Sorted list of all field label names found in the file. */
+  labels: string[];
+  /** Per-label statistics. */
+  statistics: LabelStatistic[];
+}
+
+/**
+ * Synchronously parse an SDF file into an array of molecule objects.
+ * @param sdf - The SDF content as a string, `ArrayBuffer`, or `ArrayBufferView`.
+ * @param options - Parsing options.
+ * @returns A {@link ParseResult} containing molecules and statistics.
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs';
+ * import { parse } from 'sdf-parser';
+ *
+ * const sdf = readFileSync('compounds.sdf', 'utf8');
+ * const { molecules, statistics } = parse(sdf);
+ * ```
+ */
+export function parse(sdf: unknown, options: ParseOptions = {}): ParseResult {
+  options = { ...options };
+  if (options.modifiers === undefined) options.modifiers = {};
+  if (options.forEach === undefined) options.forEach = {};
+  if (options.dynamicTyping === undefined) options.dynamicTyping = true;
+
+  // ensureString converts ArrayBuffer/ArrayBufferView to string
+  const sdfString = ensureString(sdf as Parameters<typeof ensureString>[0]);
+  if (typeof sdfString !== 'string') {
+    throw new TypeError('Parameter "sdf" must be a string');
+  }
+
+  if (options.eol === undefined) {
+    options.eol = '\n';
+    if (options.mixedEOL) {
+      // Normalize all line endings to \n
+      // We work on a local variable so no issue here
+    } else {
+      // Note: new Set(string) creates a Set of individual characters.
+      // '\r\n' is two characters so header.has('\r\n') would always be false.
+      // This preserves the original detection behaviour.
+      const header = new Set(sdfString.slice(0, 1000));
+      if (header.has('\r\n' as unknown as string)) {
+        options.eol = '\r\n';
+      } else if (header.has('\r')) {
+        options.eol = '\r';
+      }
+    }
+  }
+
+  let workingSdf = sdfString;
+  if (options.mixedEOL) {
+    workingSdf = workingSdf.replaceAll('\r\n', '\n');
+    workingSdf = workingSdf.replaceAll('\r', '\n');
+  }
+
+  const eol = options.eol;
+  const modifiers = options.modifiers;
+  const forEachMap = options.forEach;
+  const dynamicTyping = options.dynamicTyping;
+
+  const entriesBoundaries = getEntriesBoundaries(workingSdf, `${eol}$$$$`, eol);
+  const molecules: Molecule[] = [];
+  const labels: Record<string, LabelInfo> = {};
+  const start = Date.now();
+
+  for (const boundary of entriesBoundaries) {
+    const sdfPart = workingSdf.slice(...boundary);
+    if (sdfPart.length < 40) continue;
+    const currentLabels: string[] = [];
+    const molecule = getMolecule(sdfPart, labels, currentLabels, {
+      eol,
+      dynamicTyping,
+      modifiers,
+      forEach: forEachMap,
+      include: options.include,
+      exclude: options.exclude,
+    });
+    if (!molecule) continue;
+    if (!options.filter || options.filter(molecule)) {
+      molecules.push(molecule);
+      for (const label of currentLabels) {
+        labels[label].counter++;
+      }
+    }
+  }
+
+  // Convert all numeric fields and compute min/max
+  for (const label in labels) {
+    const currentLabel = labels[label];
+    if (currentLabel.isNumeric) {
+      currentLabel.minValue = Infinity;
+      currentLabel.maxValue = -Infinity;
+      for (const molecule of molecules) {
+        if (molecule[label]) {
+          const value = Number.parseFloat(molecule[label]);
+          molecule[label] = value;
+          if (value > (currentLabel.maxValue ?? -Infinity)) {
+            currentLabel.maxValue = value;
+          }
+          if (value < (currentLabel.minValue ?? Infinity)) {
+            currentLabel.minValue = value;
+          }
+        }
+      }
+    }
+  }
+
+  for (const key in labels) {
+    labels[key].always = labels[key].counter === molecules.length;
+  }
+
+  const statistics: LabelStatistic[] = [];
+  for (const key in labels) {
+    const info = labels[key];
+    statistics.push({
+      label: key,
+      counter: info.counter,
+      isNumeric: info.isNumeric,
+      keep: info.keep,
+      minValue: info.minValue,
+      maxValue: info.maxValue,
+      always: info.always ?? false,
+    });
+  }
+
+  return {
+    time: Date.now() - start,
+    molecules,
+    labels: Object.keys(labels),
+    statistics,
+  };
+}

package/src/util/getMolecule.ts

@@ -0,0 +1,107 @@
+import type { Molecule } from '../parse.ts';
+
+/**
+ * Internal per-label tracking information used during parsing.
+ */
+export interface LabelInfo {
+  /** Number of molecules that contain this label. */
+  counter: number;
+  /**
+   * Whether all seen values for this label are numeric.
+   * Starts as `true` when `dynamicTyping` is enabled.
+   */
+  isNumeric: boolean;
+  /** Whether this label is included in molecule output (not excluded). */
+  keep: boolean;
+  /** Minimum numeric value (set after all molecules are parsed). */
+  minValue?: number;
+  /** Maximum numeric value (set after all molecules are parsed). */
+  maxValue?: number;
+  /** Whether every molecule in the result contains this label. Set after parsing. */
+  always?: boolean;
+  /** Optional modifier function applied to the raw string value. */
+  modifier?: (value: string) => unknown;
+  /** Optional callback stored for this label (for statistics). */
+  forEach?: (value: unknown) => void;
+}
+
+/** Options consumed by {@link getMolecule} (a resolved subset of ParseOptions). */
+export interface GetMoleculeOptions {
+  eol: string;
+  dynamicTyping: boolean;
+  include?: string[];
+  exclude?: string[];
+  modifiers: Record<string, (value: string) => unknown>;
+  forEach: Record<string, (value: unknown) => void>;
+}
+
+/**
+ * Parse a single SDF entry string into a molecule object.
+ * @param sdfPart - A single SDF record (everything before the `$$$$` line).
+ * @param labels - Shared label tracking object, mutated in place.
+ * @param currentLabels - Array to collect label names found in this entry.
+ * @param options - Resolved parse options.
+ * @returns The molecule object, or `undefined` if the entry is too short.
+ */
+export function getMolecule(
+  sdfPart: string,
+  labels: Record<string, LabelInfo>,
+  currentLabels: string[],
+  options: GetMoleculeOptions,
+): Molecule | undefined {
+  const { eol, dynamicTyping, include, exclude, modifiers, forEach } = options;
+  const parts = sdfPart.split(`${eol}>`);
+  if (parts.length === 0 || parts[0].length <= 5) return undefined;
+  const molecule: Molecule = { molfile: parts[0] + eol };
+
+  for (let j = 1; j < parts.length; j++) {
+    const lines = parts[j].split(eol);
+    const from = lines[0].indexOf('<');
+    const to = lines[0].indexOf('>');
+    const label = lines[0].slice(from + 1, to);
+    currentLabels.push(label);
+
+    if (!labels[label]) {
+      labels[label] = {
+        counter: 0,
+        isNumeric: dynamicTyping,
+        keep: false,
+      };
+      if (!exclude?.includes(label) && (!include || include.includes(label))) {
+        labels[label].keep = true;
+        if (modifiers[label]) labels[label].modifier = modifiers[label];
+        if (forEach[label]) labels[label].forEach = forEach[label];
+      }
+    }
+
+    if (labels[label].keep) {
+      for (let k = 1; k < lines.length - 1; k++) {
+        if (molecule[label]) {
+          molecule[label] = `${molecule[label] as string}${eol}${lines[k]}`;
+        } else {
+          molecule[label] = lines[k];
+        }
+      }
+
+      if (labels[label].modifier) {
+        const modifiedValue = labels[label].modifier(molecule[label]);
+        if (modifiedValue === undefined || modifiedValue === null) {
+          // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+          delete molecule[label];
+        } else {
+          molecule[label] = modifiedValue;
+        }
+      }
+
+      if (
+        labels[label].isNumeric &&
+        (!Number.isFinite(+(molecule[label] as string)) ||
+          (molecule[label] as string).match(/^0[0-9]/))
+      ) {
+        labels[label].isNumeric = false;
+      }
+    }
+  }
+
+  return molecule;
+}

package/src/MolfileStream.js

@@ -1,35 +0,0 @@
-export class MolfileStream extends TransformStream {
-  #buffer = '';
-
-  constructor() {
-    super({
-      transform: (chunk, controller) => {
-        this.#buffer += chunk;
-        let begin = 0;
-        let index = 0;
-        while ((index = this.#buffer.indexOf('$$$$', index)) !== -1) {
-          // we need to check if the delimiter '\n' is in the current buffer
-          // if it is not we need to wait for the next chunk
-          const endOfDelimiter = this.#buffer.indexOf('\n', index);
-          if (endOfDelimiter === -1) {
-            index = begin;
-            break;
-          }
-          const eolLength = this.#buffer[endOfDelimiter - 1] === '\r' ? 2 : 1;
-          // need to remove the last eol because we will split on eol+'>' in getMolecule
-          if (index - eolLength - begin > 40) {
-            controller.enqueue(this.#buffer.slice(begin, index - eolLength));
-          }
-          index = endOfDelimiter + eolLength;
-          begin = index;
-        }
-        this.#buffer = this.#buffer.slice(begin);
-      },
-      flush: (controller) => {
-        if (this.#buffer && this.#buffer.length > 40) {
-          controller.enqueue(this.#buffer);
-        }
-      },
-    });
-  }
-}

package/src/getEntriesBoundaries.js

@@ -1,28 +0,0 @@
-/**
- *
- * @param {*} string
- * @param {*} substring
- * @param {*} eol
- * @returns
- */
-export function getEntriesBoundaries(string, substring, eol) {
-  const res = [];
-  let previous = 0;
-  let next = 0;
-  while (next !== -1) {
-    next = string.indexOf(substring, previous);
-    if (next !== -1) {
-      res.push([previous, next]);
-      const nextMatch = string.indexOf(eol, next + substring.length);
-      if (nextMatch === -1) {
-        next = -1;
-      } else {
-        previous = nextMatch + eol.length;
-        next = previous;
-      }
-    } else {
-      res.push([previous, string.length]);
-    }
-  }
-  return res;
-}

package/src/index.js

@@ -1,3 +0,0 @@
-export * from './parse';
-export * from './iterator';
-export * from './MolfileStream';

package/src/iterator.js

@@ -1,59 +0,0 @@
-import { parseString } from 'dynamic-typing';
-
-import { MolfileStream } from './MolfileStream.js';
-
-/**
- *  Parse a SDF file as an iterator
- * @param {ReadableStream} readStream - SDF file to parse
- * @param {object} [options={}] - iterator options
- * @param {Function} [options.filter] - Callback allowing to filter the molecules
- * @param {string} [options.eol='\n'] - End of line character
- * @param {boolean} [options.dynamicTyping] - Dynamically type the data
- * @yields {object} - Molecule object
- */
-export async function* iterator(readStream, options = {}) {
-  const { eol = '\n', dynamicTyping = true } = options;
-
-  const moleculeStream = readStream.pipeThrough(new MolfileStream({ eol }));
-  for await (const entry of moleculeStream) {
-    const molecule = getMolecule(entry, {
-      eol,
-      dynamicTyping,
-    });
-    if (!options.filter || options.filter(molecule)) {
-      yield molecule;
-    }
-  }
-}
-
-/**
- * Convert a SDF part to an object
- * @param {string} sdfPart - text containing the molfile
- * @param {object} options - options
- * @param {string} options.eol - end of line character
- * @param {boolean} options.dynamicTyping - Dynamically type the data (create numbers and booleans)
- * @returns
- */
-function getMolecule(sdfPart, options) {
-  const { eol, dynamicTyping } = options;
-  let parts = sdfPart.split(`${eol}>`);
-  if (parts.length === 0 || parts[0].length <= 5) return;
-  let molecule = { molfile: parts[0] + eol };
-  for (let j = 1; j < parts.length; j++) {
-    let lines = parts[j].split(eol);
-    let from = lines[0].indexOf('<');
-    let to = lines[0].indexOf('>');
-    let label = lines[0].slice(from + 1, to);
-    for (let k = 1; k < lines.length - 1; k++) {
-      if (molecule[label]) {
-        molecule[label] += eol + lines[k];
-      } else {
-        molecule[label] = lines[k];
-      }
-    }
-    if (dynamicTyping) {
-      molecule[label] = parseString(molecule[label]);
-    }
-  }
-  return molecule;
-}

package/src/parse.js

@@ -1,112 +0,0 @@
-import { ensureString } from 'ensure-string';
-
-import { getEntriesBoundaries } from './getEntriesBoundaries';
-import { getMolecule } from './util/getMolecule';
-/**
- *  Parse a SDF file
- * @param {string|ArrayBuffer|Uint8Array} sdf - SDF file to parse
- * @param {object} [options={}]
- * @param {string[]} [options.include] - List of fields to include
- * @param {string[]} [options.exclude] - List of fields to exclude
- * @param {Function} [options.filter] - Callback allowing to filter the molecules
- * @param {boolean} [options.dynamicTyping] - Dynamically type the data
- * @param {object} [options.modifiers] - Object containing callbacks to apply on some specific fields
- * @param {boolean} [options.mixedEOL=false] - Set to true if you know there is a mixture between \r\n and \n
- * @param {string} [options.eol] - Specify the end of line character. Default will be the one found in the file
- * @returns {object} - Object containing the molecules, the labels and the statistics
- */
-export function parse(sdf, options = {}) {
-  options = { ...options };
-  if (options.modifiers === undefined) options.modifiers = {};
-  if (options.forEach === undefined) options.forEach = {};
-  if (options.dynamicTyping === undefined) options.dynamicTyping = true;
-
-  sdf = ensureString(sdf);
-  if (typeof sdf !== 'string') {
-    throw new TypeError('Parameter "sdf" must be a string');
-  }
-
-  if (options.eol === undefined) {
-    options.eol = '\n';
-    if (options.mixedEOL) {
-      sdf = sdf.replaceAll('\r\n', '\n');
-      sdf = sdf.replaceAll('\r', '\n');
-    } else {
-      // we will find the delimiter in order to be much faster and not use regular expression
-      let header = new Set(sdf.slice(0, 1000));
-      if (header.has('\r\n')) {
-        options.eol = '\r\n';
-      } else if (header.has('\r')) {
-        options.eol = '\r';
-      }
-    }
-  }
-
-  let entriesBoundaries = getEntriesBoundaries(
-    sdf,
-    `${options.eol}$$$$`,
-    options.eol,
-  );
-  let molecules = [];
-  let labels = {};
-
-  let start = Date.now();
-
-  for (let i = 0; i < entriesBoundaries.length; i++) {
-    let sdfPart = sdf.slice(...entriesBoundaries[i]);
-    if (sdfPart.length < 40) continue;
-    let currentLabels = [];
-    const molecule = getMolecule(sdfPart, labels, currentLabels, options);
-    if (!molecule) continue;
-    if (!options.filter || options.filter(molecule)) {
-      molecules.push(molecule);
-      // only now we can increase the counter
-      for (let j = 0; j < currentLabels.length; j++) {
-        labels[currentLabels[j]].counter++;
-      }
-    }
-  }
-  // all numeric fields should be converted to numbers
-  for (let label in labels) {
-    let currentLabel = labels[label];
-    if (currentLabel.isNumeric) {
-      currentLabel.minValue = Infinity;
-      currentLabel.maxValue = -Infinity;
-      for (let j = 0; j < molecules.length; j++) {
-        if (molecules[j][label]) {
-          let value = Number.parseFloat(molecules[j][label]);
-          molecules[j][label] = value;
-          if (value > currentLabel.maxValue) {
-            currentLabel.maxValue = value;
-          }
-          if (value < currentLabel.minValue) {
-            currentLabel.minValue = value;
-          }
-        }
-      }
-    }
-  }
-
-  // we check that a label is in all the records
-  for (let key in labels) {
-    if (labels[key].counter === molecules.length) {
-      labels[key].always = true;
-    } else {
-      labels[key].always = false;
-    }
-  }
-
-  let statistics = [];
-  for (let key in labels) {
-    let statistic = labels[key];
-    statistic.label = key;
-    statistics.push(statistic);
-  }
-
-  return {
-    time: Date.now() - start,
-    molecules,
-    labels: Object.keys(labels),
-    statistics,
-  };
-}

package/src/util/getMolecule.js

@@ -1,63 +0,0 @@
-/**
- * Parse the molfile and the properties with > < labels >
- * @param {string} sdfPart
- * @param {*} labels
- * @param {*} currentLabels
- * @param {object} options
- * @returns
- */
-export function getMolecule(sdfPart, labels, currentLabels, options) {
-  let parts = sdfPart.split(`${options.eol}>`);
-  if (parts.length === 0 || parts[0].length <= 5) return;
-  let molecule = { molfile: parts[0] + options.eol };
-  for (let j = 1; j < parts.length; j++) {
-    let lines = parts[j].split(options.eol);
-    let from = lines[0].indexOf('<');
-    let to = lines[0].indexOf('>');
-    let label = lines[0].slice(from + 1, to);
-    currentLabels.push(label);
-    if (!labels[label]) {
-      labels[label] = {
-        counter: 0,
-        isNumeric: options.dynamicTyping,
-        keep: false,
-      };
-      if (
-        (!options.exclude || !options.exclude.includes(label)) &&
-        (!options.include || options.include.includes(label))
-      ) {
-        labels[label].keep = true;
-        if (options.modifiers[label]) {
-          labels[label].modifier = options.modifiers[label];
-        }
-        if (options.forEach[label]) {
-          labels[label].forEach = options.forEach[label];
-        }
-      }
-    }
-    if (labels[label].keep) {
-      for (let k = 1; k < lines.length - 1; k++) {
-        if (molecule[label]) {
-          molecule[label] += options.eol + lines[k];
-        } else {
-          molecule[label] = lines[k];
-        }
-      }
-      if (labels[label].modifier) {
-        let modifiedValue = labels[label].modifier(molecule[label]);
-        if (modifiedValue === undefined || modifiedValue === null) {
-          delete molecule[label];
-        } else {
-          molecule[label] = modifiedValue;
-        }
-      }
-      if (
-        labels[label].isNumeric &&
-        (!Number.isFinite(+molecule[label]) || molecule[label].match(/^0[0-9]/))
-      ) {
-        labels[label].isNumeric = false;
-      }
-    }
-  }
-  return molecule;
-}