@pbkware/fielded-text-web 0.1.0

package/src/serialization/ft-text-reader.ts

@@ -0,0 +1,64 @@
+/**
+ * Interface for reading characters from a text source.
+ * Mirrors .NET's TextReader for compatibility with C# implementation.
+ * @public
+ */
+export interface FtTextReader {
+  /**
+   * Reads the next character from the text reader and advances the character position by one character.
+   * @returns The character read as a number (charCode), or -1 if the end of the text has been reached.
+   */
+  read(): number;
+}
+
+/**
+ * Namespace merged with TextReader interface to provide static constants.
+ * @public
+ */
+export namespace FtTextReader {
+  /**
+   * Value returned by read() when the end of the text reader has been reached.
+   * Matches .NET's TextReader behavior.
+   */
+  export const EofReadResult = -1;
+}
+
+/**
+ * A TextReader implementation that reads from a string.
+ * @public
+ */
+export class FtStringReader implements FtTextReader {
+  private _text: string;
+  private _position: number;
+
+  /**
+   * Creates a new FtStringReader.
+   * @param text - The string to read from.
+   */
+  constructor(text: string) {
+    this._text = text;
+    this._position = 0;
+  }
+
+  /**
+   * Reads the next character from the string and advances the character position by one.
+   * @returns The character read as a number (charCode), or -1 if the end of the string has been reached.
+   */
+  read(): number {
+    if (this._position >= this._text.length) {
+      return -1;
+    }
+
+    const charCode = this._text.charCodeAt(this._position);
+    this._position++;
+    return charCode;
+  }
+
+  /**
+   * Closes the FtStringReader and releases resources.
+   */
+  close(): void {
+    this._text = '';
+    this._position = 0;
+  }
+}

package/src/serialization/ft-text-writer.ts

@@ -0,0 +1,61 @@
+/**
+ * Writer interface for outputting text.
+ * @public
+ */
+export interface FtTextWriter {
+  write(text: string): void;
+  flush(): void;
+}
+
+/**
+ * Simple text writer that accumulates to a string array.
+ * @public
+ */
+export class FtStringWriter implements FtTextWriter {
+  private _parts: string[] = [];
+
+  write(text: string): void {
+    this._parts.push(text);
+  }
+
+  flush(): void {
+    // No-op for string writer
+  }
+
+  toString(): string {
+    return this._parts.join('');
+  }
+
+  clear(): void {
+    this._parts = [];
+  }
+
+  close(): void {
+    this.clear();
+  }
+}
+
+/**
+ * Callback-based text writer for simple output accumulation.
+ * @public
+ */
+export class FtCallbackTextWriter implements FtTextWriter {
+  constructor(
+    private readonly callback: (text: string) => void,
+    private readonly closeCallback?: () => void,
+  ) {}
+
+  write(text: string): void {
+    this.callback(text);
+  }
+
+  flush(): void {
+    // No-op
+  }
+
+  close(): void {
+    if (this.closeCallback) {
+      this.closeCallback();
+    }
+  }
+}

package/src/serialization/heading-line-record-parser.ts

@@ -0,0 +1,285 @@
+import { FtField } from '../fields/instances/ft-field.js';
+import { FtAssertError, FtUnreachableCaseError } from '../types/errors/ft-internal-error.js';
+import { FtSerializationError } from '../types/errors/ft-serialization-error.js';
+import { FtSerializationException } from '../types/errors/ft-serialization-exception.js';
+import { CharReader } from './char-reader.js';
+import { DelimitedFieldParser } from './delimited-field-parser.js';
+import { FixedWidthFieldParser } from './fixed-width-field-parser.js';
+import { SerializationCore } from './serialization-core.js';
+
+const State = {
+  Out: 'Out',
+  InOutField: 'InOutField',
+  InDelimitedField: 'InDelimitedField',
+  InFixedWidthField: 'InFixedWidthField',
+  OutIgnoreChars: 'OutIgnoreChars',
+} as const;
+
+type State = (typeof State)[keyof typeof State];
+
+/**
+ * Parses a single heading or data record line.
+ * Uses DelimitedFieldParser or FixedWidthFieldParser depending on field type.
+ * @internal
+ */
+export class HeadingLineRecordParser {
+  private readonly _core: SerializationCore;
+  private readonly _charReader: CharReader;
+  private readonly _headingLines: boolean;
+
+  private readonly _delimitedFieldParser: DelimitedFieldParser;
+  private readonly _fixedWidthFieldParser: FixedWidthFieldParser;
+
+  private _index = -1;
+  private _state: State = State.Out;
+  private _fieldCount = 0;
+  private _activeField: FtField | undefined = undefined;
+
+  private _startPosition = -1;
+  private _ignoreExtraCharsStartPosition = -1;
+
+  constructor(core: SerializationCore, charReader: CharReader, forHeadingLines: boolean) {
+    this._core = core;
+    this._charReader = charReader;
+    this._headingLines = forHeadingLines;
+
+    this._delimitedFieldParser = new DelimitedFieldParser(core, charReader, forHeadingLines);
+    this._fixedWidthFieldParser = new FixedWidthFieldParser(core, charReader, forHeadingLines);
+  }
+
+  get activeField(): FtField | undefined {
+    return this._activeField;
+  }
+
+  get fieldCount(): number {
+    return this._fieldCount;
+  }
+
+  getActiveFieldIndex(): number {
+    switch (this._state) {
+      case State.Out:
+      case State.OutIgnoreChars:
+        return -1;
+      default:
+        return this._fieldCount - 1;
+    }
+  }
+
+  getIgnoreExtraCharsLinePosition(): number {
+    if (this._ignoreExtraCharsStartPosition < 0) {
+      return -1;
+    } else {
+      return this._ignoreExtraCharsStartPosition - this._startPosition;
+    }
+  }
+
+  isEndOfLineToBeEmbedded(): boolean {
+    if (this._state === State.InDelimitedField) {
+      return this._delimitedFieldParser.isEndOfLineToBeEmbedded();
+    } else {
+      return false;
+    }
+  }
+
+  /**
+   * Start parsing a new record.
+   */
+  start(index: number): void {
+    if (this._state !== State.Out) {
+      throw new Error(`Unexpected RecordParser Start State: ${this._state}`);
+    }
+
+    this._index = index;
+    this._fieldCount = 0;
+    this._state = State.InOutField;
+
+    this._startPosition = this._charReader.position;
+    this._ignoreExtraCharsStartPosition = -1;
+  }
+
+  /**
+   * Parse a single character.
+   */
+  parseChar(aChar: string): void {
+    switch (this._state) {
+      case State.Out:
+        throw new Error('HeadingLineRecordParser parseChar called in Out state');
+
+      case State.InOutField:
+        if (this._fieldCount < this._core.fieldList.count) {
+          this.enterField(this._core.fieldList.get(this._fieldCount));
+        } else {
+          const error = this._headingLines ? FtSerializationError.HeadingLineTooManyFields : FtSerializationError.RecordTooManyFields;
+          const message = this._headingLines
+            ? `Heading line has too many fields. Expected ${this._core.fieldList.count}`
+            : `Record has too many fields. Expected ${this._core.fieldList.count}`;
+          throw new FtSerializationException(error, message);
+        }
+        this.parseChar(aChar);
+        break;
+
+      case State.InFixedWidthField: {
+        const previousFieldFinished = this._fixedWidthFieldParser.parseChar(aChar);
+        if (previousFieldFinished) {
+          if (!this._core.seeking) {
+            this.loadFixedWidthHeadingValue();
+          }
+
+          this.exitActiveField();
+
+          if (this._fieldCount < this._core.fieldList.count || !this._core.ignoreExtraChars) {
+            this._state = State.InOutField;
+          } else {
+            this._state = State.OutIgnoreChars;
+            this._ignoreExtraCharsStartPosition = this._charReader.position;
+          }
+          this.parseChar(aChar);
+        }
+        break;
+      }
+
+      case State.InDelimitedField: {
+        const fieldFinished = this._delimitedFieldParser.parseChar(aChar);
+        if (fieldFinished) {
+          // aChar was delimiter
+          if (!this._core.seeking) {
+            this.loadDelimitedHeadingValue();
+          }
+
+          this.exitActiveField();
+
+          if (this._fieldCount < this._core.fieldList.count || !this._core.ignoreExtraChars) {
+            this._state = State.InOutField;
+          } else {
+            this._state = State.OutIgnoreChars;
+            this._ignoreExtraCharsStartPosition = this._charReader.position;
+          }
+        }
+        break;
+      }
+
+      case State.OutIgnoreChars:
+        // nothing to do
+        break;
+
+      default:
+        throw new FtUnreachableCaseError('HLRPPC44556', this._state);
+    }
+  }
+
+  /**
+   * Finish parsing the record.
+   */
+  finish(): void {
+    switch (this._state) {
+      case State.Out:
+        // nothing to do
+        break;
+
+      case State.InOutField:
+        this._state = State.Out;
+        break;
+
+      case State.InFixedWidthField:
+        if (!this._core.seeking) {
+          this.loadFixedWidthHeadingValue();
+        }
+        this.exitActiveField();
+        this._state = State.Out;
+        break;
+
+      case State.InDelimitedField:
+        if (!this._core.seeking) {
+          this.loadDelimitedHeadingValue();
+        }
+        this.exitActiveField();
+        this._state = State.Out;
+        break;
+
+      case State.OutIgnoreChars:
+        this._state = State.Out;
+        break;
+
+      default:
+        throw new FtUnreachableCaseError('HLRPF44556', this._state);
+    }
+
+    if (this._fieldCount < this._core.fieldList.count) {
+      if (!this._core.allowIncompleteRecords) {
+        const error = this._headingLines ? FtSerializationError.HeadingLineNotEnoughFields : FtSerializationError.RecordNotEnoughFields;
+        const message = this._headingLines
+          ? `Heading line has not enough fields. Got ${this._fieldCount}, expected ${this._core.fieldList.count}`
+          : `Record has not enough fields. Got ${this._fieldCount}, expected ${this._core.fieldList.count}`;
+        throw new FtSerializationException(error, message);
+      } else {
+        for (let i = this._fieldCount; i < this._core.fieldList.count; i++) {
+          const field = this._core.fieldList.get(i);
+          field.loadPosition(-1, -1, -1, -1);
+          if (this._headingLines) {
+            field.loadHeading(this._index, '');
+          } else {
+            field.loadNullValue();
+          }
+        }
+      }
+    }
+  }
+
+  private loadFixedWidthHeadingValue(): void {
+    if (this._activeField === undefined) {
+      throw new Error('Active field is null');
+    }
+
+    if (this._headingLines) {
+      this._fixedWidthFieldParser.loadFieldHeading(this._index);
+      this._core.fireFieldHeadingReadReady(this._activeField, this._index);
+    } else {
+      this._fixedWidthFieldParser.loadFieldValue();
+      this._core.fireFieldValueReadReady(this._activeField, this._index);
+    }
+  }
+
+  private loadDelimitedHeadingValue(): void {
+    if (this._activeField === undefined) {
+      throw new Error('Active field is null');
+    }
+
+    if (this._headingLines) {
+      this._delimitedFieldParser.loadFieldHeading(this._index);
+      this._core.fireFieldHeadingReadReady(this._activeField, this._index);
+    } else {
+      this._delimitedFieldParser.loadFieldValue();
+      this._core.fireFieldValueReadReady(this._activeField, this._index);
+    }
+  }
+
+  private enterField(field: FtField): void {
+    this._activeField = field;
+    this._fieldCount++;
+    if (this._activeField.fixedWidth) {
+      this._state = State.InFixedWidthField;
+      this._fixedWidthFieldParser.enterField(this._activeField);
+    } else {
+      this._state = State.InDelimitedField;
+      this._delimitedFieldParser.enterField(this._activeField);
+    }
+  }
+
+  private exitActiveField(): void {
+    switch (this._state) {
+      case State.InFixedWidthField:
+        this._fixedWidthFieldParser.exitField();
+        break;
+      case State.InDelimitedField:
+        this._delimitedFieldParser.exitField();
+        break;
+      case State.InOutField:
+      case State.Out:
+      case State.OutIgnoreChars:
+        throw new FtAssertError(`Unsupported state in exitActiveField: ${this._state}`);
+      default:
+        throw new FtUnreachableCaseError('HLRPEAF44558', this._state);
+    }
+    this._activeField = undefined;
+  }
+}

package/src/serialization/line-parser.ts

@@ -0,0 +1,231 @@
+import { FtEndOfLineType } from '../types/enums/ft-end-of-line-type.js';
+import { FtAssertError, FtUnreachableCaseError } from '../types/errors/ft-internal-error.js';
+import { CharReader } from './char-reader.js';
+
+const FtLineState = {
+  Out: 'Out',
+  In: 'In',
+  InNextTextOut: 'InNextTextOut',
+  InTextOut: 'InTextOut',
+  InPendingNextLineFeed: 'InPendingNextLineFeed',
+} as const;
+
+type FtLineState = (typeof FtLineState)[keyof typeof FtLineState];
+
+/**
+ * @public
+ */
+export const LineEndedType = {
+  Not: 'Not',
+  Initiated: 'Initiated',
+  Continued: 'Continued',
+} as const;
+
+/**
+ * @public
+ */
+export type LineEndedType = (typeof LineEndedType)[keyof typeof LineEndedType];
+
+/**
+ * Parses characters into lines with end-of-line awareness.
+ * Manages line state and handles different end-of-line types.
+ * @internal
+ */
+export class LineParser {
+  private static readonly CarriageReturnChar = CharReader.CarriageReturnChar;
+  private static readonly LineFeedChar = CharReader.LineFeedChar;
+  private static readonly CarriageReturnLineFeedString = CharReader.CarriageReturnLineFeedString;
+
+  private _charReader: CharReader;
+  private _endOfLineType: FtEndOfLineType;
+  private _endOfLineChar: string;
+
+  private _textLineCount = 0;
+  private _textLineLength = 0;
+  private _lineCount = 0;
+  private _lineLength = 0;
+  private _inLineState: FtLineState = FtLineState.Out;
+
+  constructor(charReader: CharReader, endOfLineType: FtEndOfLineType, endOfLineChar: string) {
+    this._charReader = charReader;
+    this._endOfLineType = endOfLineType;
+    this._endOfLineChar = endOfLineChar;
+  }
+
+  get lineCount(): number {
+    return this._lineCount;
+  }
+
+  get lineLength(): number {
+    return this._lineLength;
+  }
+
+  get inLine(): boolean {
+    return this._inLineState !== FtLineState.Out;
+  }
+
+  /**
+   * Update the end-of-line configuration.
+   */
+  setEndOfLine(endOfLineType: FtEndOfLineType, endOfLineChar: string): void {
+    this._endOfLineType = endOfLineType;
+    this._endOfLineChar = endOfLineChar;
+  }
+
+  /**
+   * Reset the line parser state.
+   */
+  reset(): void {
+    this._textLineCount = 0;
+    this._textLineLength = 0;
+    this._lineCount = 0;
+    this._lineLength = 0;
+    this._inLineState = FtLineState.Out;
+  }
+
+  /**
+   * Parse a single character and update line state.
+   * @param aChar The character to parse.
+   * @param endOfLineToBeEmbedded Whether end-of-line should be embedded (not treated as line break).
+   * @returns The line ended type.
+   */
+  parseChar(aChar: string, endOfLineToBeEmbedded: boolean): LineEndedType {
+    let lineEndedType: LineEndedType;
+
+    switch (this._inLineState) {
+      case FtLineState.InNextTextOut:
+        // Assert: aChar === LineFeedChar && endOfLineToBeEmbedded
+        this._inLineState = FtLineState.InTextOut;
+        lineEndedType = LineEndedType.Not;
+        break;
+
+      case FtLineState.InTextOut:
+        this._textLineCount++;
+        this._textLineLength = 0;
+        this._inLineState = FtLineState.In;
+        lineEndedType = this.parseInChar(aChar, endOfLineToBeEmbedded);
+        break;
+
+      case FtLineState.In:
+        lineEndedType = this.parseInChar(aChar, endOfLineToBeEmbedded);
+        break;
+
+      case FtLineState.InPendingNextLineFeed:
+        // Assert: aChar === LineFeedChar && !endOfLineToBeEmbedded
+        this._inLineState = FtLineState.Out;
+        lineEndedType = LineEndedType.Continued;
+        break;
+
+      case FtLineState.Out:
+        this._lineCount++;
+        this._lineLength = 0;
+        this._textLineCount++;
+        this._textLineLength = 0;
+        this._inLineState = FtLineState.In;
+        lineEndedType = this.parseInChar(aChar, endOfLineToBeEmbedded);
+        break;
+
+      default:
+        throw new FtUnreachableCaseError('LPPC54122', this._inLineState);
+    }
+
+    this._lineLength++;
+    this._textLineLength++;
+
+    return lineEndedType;
+  }
+
+  /**
+   * Exit the current line state.
+   */
+  exitLine(): void {
+    if (!this.inLine) {
+      throw new FtAssertError('LPPEL54124', 'LineParser.exitLine() called when not In Line');
+    }
+    this._inLineState = FtLineState.Out;
+  }
+
+  /**
+   * Add a blank line to the count.
+   */
+  addBlankLine(): void {
+    this._textLineCount++;
+    this._textLineLength = 0;
+    this._lineCount++;
+    this._lineLength = 0;
+  }
+
+  private parseInChar(aChar: string, embedEndOfLine: boolean): LineEndedType {
+    const crChar = LineParser.CarriageReturnChar;
+    const lfChar = LineParser.LineFeedChar;
+
+    switch (this._endOfLineType) {
+      case FtEndOfLineType.Auto:
+        switch (aChar) {
+          case crChar:
+            if (embedEndOfLine) {
+              if (this._charReader.peekNextIsLineFeed()) {
+                this._inLineState = FtLineState.InNextTextOut;
+              } else {
+                this._inLineState = FtLineState.InTextOut;
+              }
+              return LineEndedType.Not;
+            } else {
+              this._inLineState = this._charReader.peekNextIsLineFeed() ? FtLineState.InPendingNextLineFeed : FtLineState.Out;
+              return LineEndedType.Initiated;
+            }
+
+          case lfChar:
+            if (embedEndOfLine) {
+              this._inLineState = FtLineState.InTextOut;
+              return LineEndedType.Not;
+            } else {
+              this._inLineState = FtLineState.Out;
+              return LineEndedType.Initiated;
+            }
+
+          default:
+            this._lineLength++;
+            this._textLineLength++;
+            return LineEndedType.Not;
+        }
+
+      case FtEndOfLineType.CrLf:
+        if (aChar !== crChar) {
+          return LineEndedType.Not;
+        } else {
+          if (embedEndOfLine) {
+            if (this._charReader.peekNextIsLineFeed()) {
+              this._inLineState = FtLineState.InNextTextOut;
+            } else {
+              this._inLineState = FtLineState.InTextOut;
+            }
+            return LineEndedType.Not;
+          } else {
+            if (!this._charReader.peekNextIsLineFeed()) {
+              return LineEndedType.Not;
+            } else {
+              this._inLineState = FtLineState.InPendingNextLineFeed;
+              return LineEndedType.Initiated;
+            }
+          }
+        }
+
+      case FtEndOfLineType.Char:
+        if (aChar !== this._endOfLineChar) {
+          return LineEndedType.Not;
+        } else {
+          if (embedEndOfLine) {
+            this._inLineState = FtLineState.InTextOut;
+            return LineEndedType.Not;
+          } else {
+            this._inLineState = FtLineState.Out;
+            return LineEndedType.Initiated;
+          }
+        }
+
+      default:
+        throw new FtUnreachableCaseError('LPPIC54123', this._endOfLineType);
+    }
+  }
+}