@pbkware/fielded-text-web 0.1.0

package/src/serialization/fixed-width-field-parser.ts

@@ -0,0 +1,220 @@
+import { FtField } from '../fields/instances/ft-field.js';
+import { FtPadCharType } from '../types/enums/ft-pad-char-type.js';
+import { FtAssertError, FtUnreachableCaseError } from '../types/errors/ft-internal-error.js';
+import { CharReader } from './char-reader.js';
+import { SerializationCore } from './serialization-core.js';
+
+const State = {
+  WaitingLeftEndOfValue: 'WaitingLeftEndOfValue',
+  LeftPadding: 'LeftPadding',
+  NoMorePadding: 'NoMorePadding',
+  WaitingRightEndOfValue: 'WaitingRightEndOfValue',
+  WaitingRightPadding: 'WaitingRightPadding',
+  RightPadding: 'RightPadding',
+  RestIsPadding: 'RestIsPadding',
+} as const;
+
+type State = (typeof State)[keyof typeof State];
+
+/**
+ * Parser for fixed-width fields.
+ * Handles padding (left/right), end-of-value characters, and width validation.
+ * @internal
+ */
+export class FixedWidthFieldParser {
+  private readonly _headings: boolean;
+  private readonly _charReader: CharReader;
+  private readonly _core: SerializationCore;
+  private _textBuilder: string[] = [];
+
+  private _state: State = State.NoMorePadding;
+  private _field: FtField | undefined = undefined;
+  private _position = -1;
+  private _fieldLength = 0;
+  private _rawOffset = -1;
+  private _rawLength = 0;
+
+  // Cached field values
+  private _fieldWidth = 0;
+  private _fieldLeftPad = false;
+  private _fieldPadCharType: FtPadCharType = FtPadCharType.Auto;
+  private _fieldEndOfValueChar = '';
+  private _fieldPadChar = '';
+  private _rightPaddingCharCount = 0;
+
+  constructor(core: SerializationCore, charReader: CharReader, forHeadings: boolean) {
+    this._headings = forHeadings;
+    this._charReader = charReader;
+    this._core = core;
+  }
+
+  /**
+   * Enter a new field for parsing.
+   */
+  enterField(field: FtField): void {
+    this._field = field;
+
+    // Cache field values
+    this._fieldWidth = field.width;
+
+    if (this._headings) {
+      this._fieldLeftPad = field.definition_.headingLeftPad;
+      this._fieldPadCharType = field.headingPadCharType;
+      this._fieldEndOfValueChar = field.headingEndOfValueChar;
+      this._fieldPadChar = field.headingPadChar;
+    } else {
+      this._fieldLeftPad = field.definition_.valueLeftPad;
+      this._fieldPadCharType = field.valuePadCharType;
+      this._fieldEndOfValueChar = field.valueEndOfValueChar;
+      this._fieldPadChar = field.valuePadChar;
+    }
+
+    if (this._fieldLeftPad) {
+      if (this._fieldPadCharType === FtPadCharType.EndOfValue) {
+        this._state = State.WaitingLeftEndOfValue;
+      } else {
+        this._state = State.LeftPadding;
+      }
+    } else {
+      if (this._fieldPadCharType === FtPadCharType.EndOfValue) {
+        this._state = State.WaitingRightEndOfValue;
+      } else {
+        this._state = State.WaitingRightPadding;
+      }
+    }
+
+    this._textBuilder = [];
+    this._position = this._charReader.position;
+    this._fieldLength = 0;
+    this._rawOffset = 0;
+    this._rawLength = 0;
+    this._rightPaddingCharCount = 0;
+  }
+
+  /**
+   * Exit the current field.
+   */
+  exitField(): void {
+    this._textBuilder = [];
+    this._field = undefined;
+  }
+
+  /**
+   * Parse a single character.
+   * @param aChar The character to parse.
+   * @returns True if the previous field is finished (width reached), false otherwise.
+   */
+  parseChar(aChar: string): boolean {
+    if (this._fieldLength >= this._fieldWidth) {
+      return true;
+    } else {
+      this._fieldLength++;
+
+      switch (this._state) {
+        case State.WaitingLeftEndOfValue:
+          if (aChar !== this._fieldEndOfValueChar) {
+            this._textBuilder.push(aChar); // May not encounter any EndOfValue char
+          } else {
+            this._textBuilder = [];
+            this._rawOffset = this._fieldLength;
+            this._state = State.NoMorePadding;
+          }
+          break;
+
+        case State.LeftPadding:
+          if (aChar !== this._fieldPadChar) {
+            this._textBuilder.push(aChar);
+            this._rawOffset = this._fieldLength - 1;
+            this._state = State.NoMorePadding;
+          }
+          break;
+
+        case State.NoMorePadding:
+          this._textBuilder.push(aChar);
+          break;
+
+        case State.WaitingRightEndOfValue:
+          if (aChar !== this._fieldEndOfValueChar) {
+            this._textBuilder.push(aChar); // May not encounter any EndOfValue char
+          } else {
+            this._state = State.RestIsPadding;
+          }
+          break;
+
+        case State.WaitingRightPadding:
+          if (aChar !== this._fieldPadChar) {
+            this._textBuilder.push(aChar);
+          } else {
+            this._rightPaddingCharCount = 1;
+            this._state = State.RightPadding;
+          }
+          break;
+
+        case State.RightPadding:
+          if (aChar === this._fieldPadChar) {
+            this._rightPaddingCharCount++;
+          } else {
+            // Prematurely identified right padding previous start. Still not started
+            this._textBuilder.push(this._fieldPadChar.repeat(this._rightPaddingCharCount));
+            this._textBuilder.push(aChar);
+            this._rightPaddingCharCount = 0;
+            this._state = State.WaitingRightPadding;
+          }
+          break;
+
+        case State.RestIsPadding:
+          // Ignore remaining characters
+          break;
+
+        default:
+          throw new FtUnreachableCaseError('FWFPPC93358', this._state);
+      }
+
+      return false;
+    }
+  }
+
+  /**
+   * Load the parsed heading into the field.
+   */
+  loadFieldHeading(headingLineIndex: number): void {
+    if (!this._field) {
+      throw new Error('No field to load heading into');
+    }
+    const headingText = this.finishText();
+    this._field.loadPosition(this._position, this._fieldLength, this._rawOffset, this._rawLength);
+    this._field.loadHeading(headingLineIndex, headingText);
+  }
+
+  /**
+   * Load the parsed value into the field.
+   */
+  loadFieldValue(): void {
+    if (!this._field) {
+      throw new Error('No field to load value into');
+    }
+    const valueText = this.finishText();
+    this._field.loadPosition(this._position, this._fieldLength, this._rawOffset, this._rawLength);
+    this._field.loadFixedWidthValue(valueText);
+  }
+
+  private finishText(): string {
+    this._rawLength = this._textBuilder.length;
+
+    if (this._fieldLength < this._fieldWidth) {
+      const errorType = this._headings ? 'HeadingWidthNotReached' : 'ValueWidthNotReached';
+      throw new FtAssertError(
+        'FWFPFTR22115',
+        `${errorType}: Field width not reached in field ${this._field?.name ?? 'unknown'}: expected ${this._fieldWidth}, got ${this._fieldLength}`,
+      );
+    } else if (this._fieldLength > this._fieldWidth) {
+      const errorType = this._headings ? 'HeadingWidthExceeded' : 'ValueWidthExceeded';
+      throw new FtAssertError(
+        'FWFPFTR22116',
+        `${errorType}: Field width exceeded in field ${this._field?.name ?? 'unknown'}: expected ${this._fieldWidth}, got ${this._fieldLength}`,
+      );
+    } else {
+      return this._textBuilder.join('');
+    }
+  }
+}

package/src/serialization/formatting/ft-boolean-field-formatter.ts

@@ -0,0 +1,114 @@
+import { FtMetaDefaults } from '../../meta/ft-meta-defaults.js';
+import { FtBooleanStyles } from '../../types/enums/ft-boolean-styles.js';
+import { FtFieldFormatter } from './ft-field-formatter.js';
+
+/**
+ * Formatter for boolean fields.
+ * Supports various parsing styles including case sensitivity, partial matching, and more.
+ * @public
+ */
+export class FtBooleanFieldFormatter extends FtFieldFormatter {
+  private _falseText: string = FtMetaDefaults.BooleanField.FalseText;
+  private _trueText: string = FtMetaDefaults.BooleanField.TrueText;
+  private _styles: FtBooleanStyles = FtMetaDefaults.BooleanField.Styles;
+
+  get falseText(): string {
+    return this._falseText;
+  }
+
+  set falseText(value: string) {
+    this._falseText = value;
+  }
+
+  get trueText(): string {
+    return this._trueText;
+  }
+
+  set trueText(value: string) {
+    this._trueText = value;
+  }
+
+  get styles(): FtBooleanStyles {
+    return this._styles;
+  }
+
+  set styles(value: FtBooleanStyles) {
+    this._styles = value;
+  }
+
+  toText(value: boolean): string {
+    return value ? this._trueText : this._falseText;
+  }
+
+  parse(text: string): boolean {
+    if (this.compareText(text, this._trueText)) {
+      return true;
+    } else {
+      if ((this._styles & FtBooleanStyles.FalseIfNotMatchTrue) !== 0) {
+        return false;
+      } else {
+        if (this.compareText(text, this._falseText)) {
+          return false;
+        } else {
+          throw new Error(`Boolean parse failed: text '${text}' does not match '${this._trueText}' or '${this._falseText}'`);
+        }
+      }
+    }
+  }
+
+  private compareText(text: string, stateText: string): boolean {
+    if (stateText === '') {
+      if (text === '') {
+        return true;
+      } else {
+        return (this._styles & FtBooleanStyles.IgnoreTrailingChars) !== 0;
+      }
+    } else {
+      if (text === '') {
+        return false;
+      } else {
+        const ignoreCase = (this._styles & FtBooleanStyles.IgnoreCase) !== 0;
+
+        if ((this._styles & FtBooleanStyles.MatchFirstCharOnly) !== 0) {
+          // Match only the first character
+          const textChar = ignoreCase ? this.toUpperCaseChar(text[0]) : text[0];
+          const stateChar = ignoreCase ? this.toUpperCaseChar(stateText[0]) : stateText[0];
+          return textChar === stateChar;
+        } else {
+          // Full or partial match
+          if ((this._styles & FtBooleanStyles.IgnoreTrailingChars) === 0) {
+            // Exact match required
+            if (ignoreCase) {
+              return text.toUpperCase() === stateText.toUpperCase();
+            } else {
+              return text === stateText;
+            }
+          } else {
+            // Match prefix, ignore trailing characters
+            const textLength = text.length;
+            const stateTextLength = stateText.length;
+            if (textLength < stateTextLength) {
+              return false;
+            } else {
+              const adjustedText = textLength === stateTextLength ? text : text.substring(0, stateTextLength);
+
+              if (ignoreCase) {
+                return adjustedText.toUpperCase() === stateText.toUpperCase();
+              } else {
+                return adjustedText === stateText;
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  private toUpperCaseChar(char: string): string {
+    // Use culture-aware character case conversion if culture is available
+    if (this.culture) {
+      return this.culture.toUpperChar(char);
+    }
+    return char.toUpperCase();
+  }
+}

package/src/serialization/formatting/ft-date-time-field-formatter.ts

@@ -0,0 +1,61 @@
+import { DotNetDateTimeFormatter, DotNetDateTimeStyles } from '@pbkware/dot-net-date-number-formatting';
+import { FtMetaDefaults } from '../../meta/ft-meta-defaults.js';
+import { FtFieldFormatter } from './ft-field-formatter.js';
+
+/**
+ * Formatter for DateTime fields using .NET-compatible formatting.
+ * Implementation delegates to DotNetDateTimeFormatter from dot-net-date-number-formatting package.
+ * @public
+ */
+export class FtDateTimeFieldFormatter extends FtFieldFormatter {
+  private _format: string = FtMetaDefaults.DateTimeField.Format;
+  private _styles: DotNetDateTimeStyles = FtMetaDefaults.DateTimeField.Styles;
+  private _formatter: DotNetDateTimeFormatter = new DotNetDateTimeFormatter();
+
+  constructor() {
+    super();
+    // Initialize formatter with default format
+    const result = this._formatter.trySetFormat(this._format);
+    if (!result.isOk()) {
+      throw new Error(`Failed to set default datetime format: ${this._format}`);
+    }
+  }
+
+  get format(): string {
+    return this._format;
+  }
+
+  set format(value: string) {
+    this._format = value;
+    const result = this._formatter.trySetFormat(value);
+    if (!result.isOk()) {
+      throw new Error(`Invalid datetime format: ${value}`);
+    }
+  }
+
+  get styles(): DotNetDateTimeStyles {
+    return this._styles;
+  }
+
+  set styles(value: DotNetDateTimeStyles) {
+    this._styles = value;
+  }
+
+  toText(value: Date): string {
+    if (this.culture) {
+      this._formatter.localeSettings = this.culture;
+    }
+    return this._formatter.toString(value);
+  }
+
+  parse(text: string): Date {
+    if (this.culture) {
+      this._formatter.localeSettings = this.culture;
+    }
+    const result = this._formatter.tryFromString(text);
+    if (!result.isOk()) {
+      throw new Error(`Failed to parse datetime: ${text}`);
+    }
+    return result.value;
+  }
+}

package/src/serialization/formatting/ft-decimal-field-formatter.ts

@@ -0,0 +1,52 @@
+import { DotNetDecimalFormatter, DotNetNumberStyles } from '@pbkware/dot-net-date-number-formatting';
+import { FtMetaDefaults } from '../../meta/ft-meta-defaults.js';
+import { FtFieldFormatter } from './ft-field-formatter.js';
+
+/**
+ * Formatter for decimal fields using .NET-compatible formatting.
+ * Implementation delegates to DotNetDecimalFormatter from dot-net-date-number-formatting package.
+ * @public
+ */
+export class FtDecimalFieldFormatter extends FtFieldFormatter {
+  private _styles: DotNetNumberStyles = FtMetaDefaults.DecimalField.Styles;
+  private _format: string = FtMetaDefaults.DecimalField.Format;
+  private _formatter: DotNetDecimalFormatter = new DotNetDecimalFormatter();
+
+  get styles(): DotNetNumberStyles {
+    return this._styles;
+  }
+
+  set styles(value: DotNetNumberStyles) {
+    this._styles = value;
+  }
+
+  get format(): string {
+    return this._format;
+  }
+
+  set format(value: string) {
+    this._format = value;
+    const result = this._formatter.trySetFormat(value);
+    if (!result.isOk()) {
+      throw new Error(`Invalid decimal format: ${value}`);
+    }
+  }
+
+  toText(value: number): string {
+    if (this.culture) {
+      this._formatter.localeSettings = this.culture;
+    }
+    return this._formatter.toString(value);
+  }
+
+  parse(text: string): number {
+    if (this.culture) {
+      this._formatter.localeSettings = this.culture;
+    }
+    const result = this._formatter.tryFromString(text);
+    if (!result.isOk()) {
+      throw new Error(`Failed to parse decimal: ${text}`);
+    }
+    return result.value;
+  }
+}

package/src/serialization/formatting/ft-declared-parameters-formatter.ts

@@ -0,0 +1,60 @@
+import { FtDeclaredParameterRec, FtDeclaredParameters } from '../ft-declared-parameters.js';
+
+/**
+ * Formatter for declared parameters in .ftx file headers.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+export class FtDeclaredParametersFormatter {
+  private static readonly NAME_VALUE_SEPARATOR = '=';
+  private static readonly QUOTE_CHAR = '"';
+  private static readonly DOUBLE_QUOTE_STRING = '""';
+  private static readonly SPACE_CHARACTER = ' ';
+
+  /**
+   * Format the signature line (first declaration line with version).
+   */
+  static toSignatureLineText(parameters: FtDeclaredParameters): string {
+    const versionRecResult = parameters.tryGetVersionRec();
+    if (!versionRecResult.success) {
+      throw new Error('Version not specified in declared parameters');
+    }
+
+    const recArray: FtDeclaredParameterRec[] = [versionRecResult.rec];
+    return FtDeclaredParametersFormatter.toText(recArray);
+  }
+
+  /**
+   * Format the second declaration line (all parameters except version).
+   */
+  static toLine2Text(parameters: FtDeclaredParameters): string {
+    const recs = parameters.getAllRecsExceptVersion();
+    return FtDeclaredParametersFormatter.toText(recs);
+  }
+
+  /**
+   * Convert parameter records to text format.
+   */
+  private static toText(recs: FtDeclaredParameterRec[]): string {
+    const parts: string[] = [];
+    for (let i = 0; i < recs.length; i++) {
+      const rec = recs[i];
+      if (rec.name.includes(FtDeclaredParametersFormatter.NAME_VALUE_SEPARATOR)) {
+        throw new Error(`Parameter name contains separator character: ${rec.name}`);
+      }
+
+      const value = rec.value.replace(FtDeclaredParametersFormatter.QUOTE_CHAR, FtDeclaredParametersFormatter.DOUBLE_QUOTE_STRING);
+
+      if (i > 0) {
+        parts.push(FtDeclaredParametersFormatter.SPACE_CHARACTER);
+      }
+      parts.push(rec.name);
+      parts.push(FtDeclaredParametersFormatter.NAME_VALUE_SEPARATOR);
+      parts.push(FtDeclaredParametersFormatter.QUOTE_CHAR);
+      parts.push(value);
+      parts.push(FtDeclaredParametersFormatter.QUOTE_CHAR);
+    }
+
+    return parts.join('');
+  }
+}

package/src/serialization/formatting/ft-field-formatter.ts

@@ -0,0 +1,18 @@
+import { DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';
+
+/**
+ * Abstract base class for all field formatters.
+ * Concrete formatters handle type-specific formatting and parsing.
+ * @public
+ */
+export abstract class FtFieldFormatter {
+  private _culture: DotNetLocaleSettings | undefined;
+
+  get culture(): DotNetLocaleSettings | undefined {
+    return this._culture;
+  }
+
+  set culture(value: DotNetLocaleSettings | undefined) {
+    this._culture = value;
+  }
+}

package/src/serialization/formatting/ft-float-field-formatter.ts

@@ -0,0 +1,52 @@
+import { DotNetFloatFormatter, DotNetNumberStyles } from '@pbkware/dot-net-date-number-formatting';
+import { FtMetaDefaults } from '../../meta/ft-meta-defaults.js';
+import { FtFieldFormatter } from './ft-field-formatter.js';
+
+/**
+ * Formatter for float (number) fields using .NET-compatible formatting.
+ * Implementation delegates to DotNetFloatFormatter from dot-net-date-number-formatting package.
+ * @public
+ */
+export class FtFloatFieldFormatter extends FtFieldFormatter {
+  private _styles: DotNetNumberStyles = FtMetaDefaults.FloatField.Styles;
+  private _format: string = FtMetaDefaults.FloatField.Format;
+  private _formatter: DotNetFloatFormatter = new DotNetFloatFormatter();
+
+  get styles(): DotNetNumberStyles {
+    return this._styles;
+  }
+
+  set styles(value: DotNetNumberStyles) {
+    this._styles = value;
+  }
+
+  get format(): string {
+    return this._format;
+  }
+
+  set format(value: string) {
+    this._format = value;
+    const result = this._formatter.trySetFormat(value);
+    if (!result.isOk()) {
+      throw new Error(`Invalid float format: ${value}`);
+    }
+  }
+
+  toText(value: number): string {
+    if (this.culture) {
+      this._formatter.localeSettings = this.culture;
+    }
+    return this._formatter.toString(value);
+  }
+
+  parse(text: string): number {
+    if (this.culture) {
+      this._formatter.localeSettings = this.culture;
+    }
+    const result = this._formatter.tryFromString(text);
+    if (!result.isOk()) {
+      throw new Error(`Failed to parse float: ${text}`);
+    }
+    return result.value;
+  }
+}

package/src/serialization/formatting/ft-integer-field-formatter.ts

@@ -0,0 +1,53 @@
+import { DotNetIntegerFormatter, DotNetNumberStyles } from '@pbkware/dot-net-date-number-formatting';
+import { FtMetaDefaults } from '../../meta/ft-meta-defaults.js';
+import { FtFieldFormatter } from './ft-field-formatter.js';
+
+/**
+ * Formatter for integer (long) fields using .NET-compatible formatting.
+ * Implementation delegates to DotNetIntegerFormatter from dot-net-date-number-formatting package.
+ * @public
+ */
+export class FtIntegerFieldFormatter extends FtFieldFormatter {
+  private _styles: DotNetNumberStyles = FtMetaDefaults.IntegerField.Styles;
+  private _format: string = FtMetaDefaults.IntegerField.Format;
+  private _formatter: DotNetIntegerFormatter = new DotNetIntegerFormatter();
+
+  get styles(): DotNetNumberStyles {
+    return this._styles;
+  }
+
+  set styles(value: DotNetNumberStyles) {
+    this._styles = value;
+  }
+
+  get format(): string {
+    return this._format;
+  }
+
+  set format(value: string) {
+    this._format = value;
+    const result = this._formatter.trySetFormat(value);
+    if (!result.isOk()) {
+      throw new Error(`Invalid integer format: ${value}`);
+    }
+  }
+
+  toText(value: bigint | number): string {
+    const bigintValue = typeof value === 'bigint' ? value : BigInt(value);
+    if (this.culture) {
+      this._formatter.localeSettings = this.culture;
+    }
+    return this._formatter.toString(bigintValue);
+  }
+
+  parse(text: string): bigint {
+    if (this.culture) {
+      this._formatter.localeSettings = this.culture;
+    }
+    const result = this._formatter.tryFromString(text);
+    if (!result.isOk()) {
+      throw new Error(`Failed to parse integer: ${text}`);
+    }
+    return result.value;
+  }
+}

package/src/serialization/formatting/ft-string-field-formatter.ts

@@ -0,0 +1,15 @@
+import { FtFieldFormatter } from './ft-field-formatter.js';
+
+/**
+ * Formatter for string fields.
+ * @public
+ */
+export class FtStringFieldFormatter extends FtFieldFormatter {
+  toText(value: string): string {
+    return value;
+  }
+
+  parse(text: string): string {
+    return text;
+  }
+}

package/src/serialization/formatting/index.ts

@@ -0,0 +1,7 @@
+export { FtBooleanFieldFormatter } from './ft-boolean-field-formatter.js';
+export { FtDateTimeFieldFormatter } from './ft-date-time-field-formatter.js';
+export { FtDecimalFieldFormatter } from './ft-decimal-field-formatter.js';
+export { FtFieldFormatter } from './ft-field-formatter.js';
+export { FtFloatFieldFormatter } from './ft-float-field-formatter.js';
+export { FtIntegerFieldFormatter } from './ft-integer-field-formatter.js';
+export { FtStringFieldFormatter } from './ft-string-field-formatter.js';