massbank 0.0.2 → 0.1.0

package/src/parser/field-parsers.ts

@@ -0,0 +1,237 @@
+import type { Record } from '../record.js';
+
+import type { IFieldParser } from './interfaces.js';
+
+/**
+ * Base class for field parsers
+ */
+abstract class BaseFieldParser implements IFieldParser {
+  abstract canParse(key: string): boolean;
+  abstract parse(key: string, value: string, record: Record): void;
+}
+
+/**
+ * Header field parser
+ */
+export class HeaderFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    const headerFields = [
+      'ACCESSION',
+      'RECORD_TITLE',
+      'DATE',
+      'AUTHORS',
+      'LICENSE',
+      'COPYRIGHT',
+      'PUBLICATION',
+      'PROJECT',
+      'COMMENT',
+      'DEPRECATED',
+    ];
+    return headerFields.includes(key);
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'ACCESSION':
+        record.ACCESSION = value;
+        break;
+      case 'RECORD_TITLE':
+        record.RECORD_TITLE = value;
+        break;
+      case 'DATE':
+        record.DATE = value;
+        break;
+      case 'AUTHORS':
+        record.AUTHORS = value;
+        break;
+      case 'LICENSE':
+        record.LICENSE = value;
+        break;
+      case 'COPYRIGHT':
+        record.COPYRIGHT = value;
+        break;
+      case 'PUBLICATION':
+        record.PUBLICATION = value;
+        break;
+      case 'PROJECT':
+        record.PROJECT = value;
+        break;
+      case 'COMMENT':
+        if (!record.COMMENT) {
+          record.COMMENT = [];
+        }
+        record.COMMENT.push(value);
+        break;
+      case 'DEPRECATED':
+        record.DEPRECATED = value;
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Compound (CH$) field parser
+ */
+export class CompoundFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return key.startsWith('CH$');
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'CH$NAME':
+        if (!record.CH$NAME) {
+          record.CH$NAME = [];
+        }
+        record.CH$NAME.push(value);
+        break;
+      case 'CH$COMPOUND_CLASS':
+        record.CH$COMPOUND_CLASS = value;
+        break;
+      case 'CH$FORMULA':
+        record.CH$FORMULA = value;
+        break;
+      case 'CH$EXACT_MASS':
+        record.CH$EXACT_MASS = value;
+        break;
+      case 'CH$SMILES':
+        record.CH$SMILES = value;
+        break;
+      case 'CH$IUPAC':
+        record.CH$IUPAC = value;
+        break;
+      case 'CH$LINK':
+        if (!record.CH$LINK) {
+          record.CH$LINK = [];
+        }
+        record.CH$LINK.push(value);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Analytical conditions (AC$) field parser
+ */
+export class AnalyticalConditionsFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return key.startsWith('AC$');
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'AC$INSTRUMENT':
+        record.AC$INSTRUMENT = value;
+        break;
+      case 'AC$INSTRUMENT_TYPE':
+        record.AC$INSTRUMENT_TYPE = value;
+        break;
+      case 'AC$MASS_SPECTROMETRY':
+        if (!record.AC$MASS_SPECTROMETRY) {
+          record.AC$MASS_SPECTROMETRY = [];
+        }
+        record.AC$MASS_SPECTROMETRY.push(value);
+        break;
+      case 'AC$CHROMATOGRAPHY':
+        if (!record.AC$CHROMATOGRAPHY) {
+          record.AC$CHROMATOGRAPHY = [];
+        }
+        record.AC$CHROMATOGRAPHY.push(value);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Mass spectrometry (MS$) field parser
+ */
+export class MassSpectrometryFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return key.startsWith('MS$');
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'MS$FOCUSED_ION':
+        if (!record.MS$FOCUSED_ION) {
+          record.MS$FOCUSED_ION = [];
+        }
+        record.MS$FOCUSED_ION.push(value);
+        break;
+      case 'MS$DATA_PROCESSING':
+        if (!record.MS$DATA_PROCESSING) {
+          record.MS$DATA_PROCESSING = [];
+        }
+        record.MS$DATA_PROCESSING.push(value);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Peak (PK$) field parser (non-table fields)
+ */
+export class PeakFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return (
+      key.startsWith('PK$') && key !== 'PK$PEAK' && key !== 'PK$ANNOTATION'
+    );
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'PK$SPLASH':
+        record.PK$SPLASH = value;
+        break;
+      case 'PK$NUM_PEAK': {
+        const numPeak = Number.parseInt(value, 10);
+        if (Number.isNaN(numPeak)) {
+          throw new Error(`Invalid PK$NUM_PEAK value: ${value}`);
+        }
+        record.PK$NUM_PEAK = numPeak;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Species (SP$) field parser
+ */
+export class SpeciesFieldParser extends BaseFieldParser {
+  canParse(key: string): boolean {
+    return key.startsWith('SP$');
+  }
+
+  parse(key: string, value: string, record: Record): void {
+    switch (key) {
+      case 'SP$SCIENTIFIC_NAME':
+        record.SP$SCIENTIFIC_NAME = value;
+        break;
+      case 'SP$LINEAGE':
+        record.SP$LINEAGE = value;
+        break;
+      case 'SP$LINK':
+        if (!record.SP$LINK) {
+          record.SP$LINK = [];
+        }
+        record.SP$LINK.push(value);
+        break;
+      case 'SP$SAMPLE':
+        record.SP$SAMPLE = value;
+        break;
+      default:
+        break;
+    }
+  }
+}

package/src/parser/index.ts

@@ -0,0 +1,8 @@
+export { RecordParser, createParser, parseRecord } from './record-parser.js';
+export { ParseException } from './exceptions.js';
+export type {
+  IFieldParser,
+  IRecordParser,
+  ITableParser,
+} from './interfaces.js';
+export { PositionUtils } from './position-utils.js';

package/src/parser/interfaces.ts

@@ -0,0 +1,56 @@
+import type { Record } from '../record.js';
+
+/**
+ * Interface for parsing MassBank records
+ */
+export interface IRecordParser {
+  /**
+   * Parse a MassBank record string into a Record object
+   * @param text - The MassBank record text
+   * @returns The parsed Record object
+   * @throws {import('./exceptions.js').ParseException} if parsing fails
+   */
+  parse(text: string): Record;
+}
+
+/**
+ * Interface for parsing field values
+ */
+export interface IFieldParser {
+  /**
+   * Check if this parser can handle the given key
+   */
+  canParse(key: string): boolean;
+
+  /**
+   * Parse the field value
+   */
+  parse(key: string, value: string, record: Record): void;
+}
+
+/**
+ * Interface for parsing table data (peaks, annotations)
+ */
+export interface ITableParser {
+  /**
+   * Check if this parser can handle the given key
+   */
+  canParse(key: string): boolean;
+
+  /**
+   * Parse table data starting from the given line index
+   * @param key - The field key
+   * @param lines - All lines
+   * @param startIndex - Index of first data line (header is at startIndex - 1)
+   * @param record - Record to populate
+   * @param headerLine - The full header line (e.g., "PK$ANNOTATION: m/z ion")
+   * @returns The number of lines consumed
+   */
+  parse(
+    key: string,
+    lines: string[],
+    startIndex: number,
+    record: Record,
+    headerLine?: string,
+  ): number;
+}

package/src/parser/position-utils.ts

@@ -0,0 +1,130 @@
+import type { ParseError } from '../types.js';
+
+/**
+ * Utility functions for position calculations
+ * Handle position/line/column calculations
+ */
+export const PositionUtils = {
+  /**
+   * Get character position from line and column (both 1-based).
+   * Converts 1-based line/column to a 0-based character offset in the text.
+   * @param text - The full text being parsed (used to determine actual newline lengths)
+   * @param lineIndex - Line number (1-based)
+   * @param column - Column number (1-based)
+   * @returns 0-based character position in the original text
+   */
+  getPosition(text: string, lineIndex: number, column: number): number {
+    // Convert 1-based line/column to 0-based for internal calculation
+    const zeroBasedLine = lineIndex - 1;
+    const zeroBasedColumn = column - 1;
+
+    // Match lines with their actual newline separators to get correct lengths
+    const lineRegex = /^(?<content>.*?)(?<newline>\r\n|\r|\n|$)/gm;
+    let match: RegExpExecArray | null;
+    let offset = 0;
+    let currentLine = 0;
+
+    while ((match = lineRegex.exec(text)) !== null) {
+      if (currentLine === zeroBasedLine) {
+        // Found the target line, add the column offset
+        return offset + zeroBasedColumn;
+      }
+
+      const lineContent = match.groups?.content ?? '';
+      const newlineSeparator = match.groups?.newline ?? '';
+
+      // Move offset past the line content and its newline separator
+      offset += lineContent.length + newlineSeparator.length;
+      currentLine++;
+
+      // If we've processed all text, break to avoid infinite loop
+      if (
+        newlineSeparator === '' ||
+        match.index + match[0].length >= text.length
+      ) {
+        break;
+      }
+    }
+
+    // If we didn't find the line, return the current offset plus column
+    return offset + zeroBasedColumn;
+  },
+
+  /**
+   * Create a ParseError from a 0-based character position.
+   * Converts the position to 1-based line and column numbers.
+   * Clamps position to valid range [0, text.length] to ensure correct line/column calculation.
+   * @param text - The full text being parsed
+   * @param position - 0-based character offset in the text
+   * @param message - Error message describing the problem
+   * @returns ParseError with 1-based line and column
+   */
+  createParseError(
+    text: string,
+    position: number,
+    message: string,
+  ): ParseError {
+    // Clamp position to valid range to prevent invalid line/column calculation
+    const clampedPosition = Math.max(0, Math.min(position, text.length));
+
+    // Delegate to getLineColumn to avoid duplicating logic
+    const { line, column } = this.getLineColumn(text, clampedPosition);
+
+    return {
+      position: clampedPosition,
+      message,
+      line,
+      column,
+    };
+  },
+
+  /**
+   * Get line and column from a 0-based character position.
+   * Converts the position to 1-based line and column numbers.
+   * Clamps position to valid range [0, text.length] and correctly handles the last line.
+   * @param text - The full text being parsed
+   * @param position - 0-based character offset in the text
+   * @returns Object with 1-based line and column
+   */
+  getLineColumn(
+    text: string,
+    position: number,
+  ): { line: number; column: number } {
+    // Clamp position to valid range [0, text.length]
+    const clampedPosition = Math.max(0, Math.min(position, text.length));
+
+    // Match lines with their actual newline separators to get correct lengths
+    // This regex captures line content followed by the newline (CRLF, LF, or CR)
+    const lineRegex = /^(?<content>.*?)(?<newline>\r\n|\r|\n|$)/gm;
+    let match: RegExpExecArray | null;
+    let offset = 0;
+    let lineNumber = 1;
+
+    while ((match = lineRegex.exec(text)) !== null) {
+      const lineContent = match.groups?.content ?? '';
+      const newlineSeparator = match.groups?.newline ?? '';
+      const lineEndOffset = offset + lineContent.length;
+
+      // Check if the position is within this line's content
+      if (clampedPosition <= lineEndOffset) {
+        const column = clampedPosition - offset + 1; // 1-based
+        return { line: lineNumber, column };
+      }
+
+      // Move offset past the line content and its newline separator
+      offset = lineEndOffset + newlineSeparator.length;
+      lineNumber++;
+
+      // If we've processed all text, break to avoid infinite loop
+      if (
+        newlineSeparator === '' ||
+        match.index + match[0].length >= text.length
+      ) {
+        break;
+      }
+    }
+
+    // Fallback for empty text or edge cases: return line 1, column 1
+    return { line: 1, column: 1 };
+  },
+};

package/src/parser/record-parser.ts

@@ -0,0 +1,155 @@
+import type { Record } from '../record.js';
+
+import { ParseException } from './exceptions.js';
+import {
+  AnalyticalConditionsFieldParser,
+  CompoundFieldParser,
+  HeaderFieldParser,
+  MassSpectrometryFieldParser,
+  PeakFieldParser,
+  SpeciesFieldParser,
+} from './field-parsers.js';
+import type {
+  IFieldParser,
+  IRecordParser,
+  ITableParser,
+} from './interfaces.js';
+import { PositionUtils } from './position-utils.js';
+import { AnnotationTableParser, PeakTableParser } from './table-parsers.js';
+
+/**
+ * Main MassBank record parser
+ * responsible for parsing
+ * Uses interfaces for field/table parsers
+ * Easy to extend with new parsers
+ */
+export class RecordParser implements IRecordParser {
+  private readonly fieldParsers: IFieldParser[];
+  private readonly tableParsers: ITableParser[];
+
+  constructor() {
+    // Initialize parsers (could be injected via DI in the future)
+    this.fieldParsers = [
+      new HeaderFieldParser(),
+      new CompoundFieldParser(),
+      new AnalyticalConditionsFieldParser(),
+      new MassSpectrometryFieldParser(),
+      new PeakFieldParser(),
+      new SpeciesFieldParser(),
+    ];
+
+    this.tableParsers = [new PeakTableParser(), new AnnotationTableParser()];
+  }
+
+  /**
+   * Parse a MassBank record string into a Record object
+   * @param text
+   */
+  parse(text: string): Record {
+    const lines = text.split(/\r?\n/);
+    const record: Record = {
+      ACCESSION: '',
+    };
+
+    let i = 0;
+
+    while (i < lines.length) {
+      const line = lines[i];
+      if (!line) {
+        i++;
+        continue;
+      }
+
+      const trimmed = line.trim();
+
+      // Skip empty lines
+      if (trimmed === '') {
+        i++;
+        continue;
+      }
+
+      // Check for record terminator
+      if (trimmed === '//') {
+        break;
+      }
+
+      // Parse key-value pairs
+      const colonIndex = line.indexOf(':');
+      if (colonIndex === -1) {
+        // Line without colon is invalid unless we're in a table context
+        // (which is handled by table parsers before we get here)
+        throw new ParseException(
+          PositionUtils.createParseError(
+            text,
+            PositionUtils.getPosition(text, i + 1, 1),
+            'Invalid line format: expected "KEY: value" or table data',
+          ),
+        );
+      }
+
+      const key = line.slice(0, Math.max(0, colonIndex)).trim();
+      const value = line.slice(Math.max(0, colonIndex + 1)).trim();
+
+      // Try table parsers first (they handle multi-line data)
+      const tableParser = this.tableParsers.find((p) => p.canParse(key));
+      if (tableParser) {
+        const headerLine = line; // Current line is the header
+        i++; // Skip header line
+        const linesConsumed = tableParser.parse(
+          key,
+          lines,
+          i,
+          record,
+          headerLine,
+        );
+        i += linesConsumed;
+        continue;
+      }
+
+      // Try field parsers
+      const fieldParser = this.fieldParsers.find((p) => p.canParse(key));
+      if (fieldParser) {
+        try {
+          fieldParser.parse(key, value, record);
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : 'Unknown parsing error';
+          throw new ParseException(
+            PositionUtils.createParseError(
+              text,
+              PositionUtils.getPosition(text, i + 1, colonIndex + 2),
+              message,
+            ),
+          );
+        }
+      }
+
+      i++;
+    }
+
+    if (!record.ACCESSION) {
+      throw new ParseException(
+        PositionUtils.createParseError(text, 0, 'ACCESSION field is required'),
+      );
+    }
+
+    return record;
+  }
+}
+
+/**
+ * Factory function to create a parser instance
+ * Follows Factory Pattern
+ */
+export function createParser(): IRecordParser {
+  return new RecordParser();
+}
+
+/**
+ * Convenience function to parse a record
+ * @param text
+ */
+export function parseRecord(text: string): Record {
+  const parser = createParser();
+  return parser.parse(text);
+}