@pbkware/fielded-text-web 0.1.0

package/src/fields/definitions/ft-field-definition.ts

@@ -0,0 +1,276 @@
+import { DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';
+import { FtMetaField } from '../../meta/fields/ft-meta-field.js';
+import { FtMetaDefaults } from '../../meta/ft-meta-defaults.js';
+import { FtFieldFormatter } from '../../serialization/formatting/ft-field-formatter.js';
+import { FtDataType } from '../../types/enums/ft-data-type.js';
+import { FtHeadingConstraint } from '../../types/enums/ft-heading-constraint.js';
+import { FtPadAlignment } from '../../types/enums/ft-pad-alignment.js';
+import { FtPadCharType } from '../../types/enums/ft-pad-char-type.js';
+import { FtQuotedType } from '../../types/enums/ft-quoted-type.js';
+import { FtTruncateType } from '../../types/enums/ft-truncate-type.js';
+import { FtUnreachableCaseError } from '../../types/errors/ft-internal-error.js';
+
+const InternalError = {
+  FtFieldFieldDefinition_LoadMeta_UnsupportedHeadingPadAlignment: 'FtFieldFieldDefinition_LoadMeta_UnsupportedHeadingPadAlignment',
+  FtFieldFieldDefinition_LoadMeta_UnsupportedValuePadAlignment: 'FtFieldFieldDefinition_LoadMeta_UnsupportedValuePadAlignment',
+} as const;
+
+type InternalError = (typeof InternalError)[keyof typeof InternalError];
+
+/**
+ * Abstract base class for all field definitions.
+ * Field definitions hold metadata and configuration for fields in fielded text.
+ * @public
+ */
+export abstract class FtFieldDefinition {
+  readonly dataType: FtDataType;
+  readonly valueType: string; // TypeScript doesn't have Type like C#, so we use string description
+  readonly autoLeftPad: boolean;
+
+  protected readonly formatter: FtFieldFormatter;
+
+  private _index: number;
+  private _id: number | undefined = undefined;
+  private _metaName: string = FtMetaDefaults.Field.Name;
+  private _metaHeadings: string[] = [];
+  private _mainHeadingIndex: number = FtMetaDefaults.Root.MainHeadingLineIndex;
+  private _culture: DotNetLocaleSettings | undefined = undefined;
+  private _fixedWidth: boolean = FtMetaDefaults.Field.FixedWidth;
+  private _width: number = FtMetaDefaults.Field.Width;
+  private _constant: boolean = FtMetaDefaults.Field.Constant;
+  private _null: boolean = FtMetaDefaults.Field.Null;
+
+  // Value formatting properties
+  private _valueQuotedType: FtQuotedType = FtMetaDefaults.Field.ValueQuotedType;
+  private _valueAlwaysWriteOptionalQuote: boolean = FtMetaDefaults.Field.ValueAlwaysWriteOptionalQuote;
+  private _valueWritePrefixSpace: boolean = FtMetaDefaults.Field.ValueWritePrefixSpace;
+  private _valuePadAlignment: FtPadAlignment = FtMetaDefaults.Field.ValuePadAlignment;
+  private _valuePadCharType: FtPadCharType = FtMetaDefaults.Field.ValuePadCharType;
+  private _valuePadChar: string = FtMetaDefaults.Field.ValuePadChar;
+  private _valueTruncateType: FtTruncateType = FtMetaDefaults.Field.ValueTruncateType;
+  private _valueTruncateChar: string = FtMetaDefaults.Field.ValueTruncateChar;
+  private _valueEndOfValueChar: string = FtMetaDefaults.Field.ValueEndOfValueChar;
+  private _valueNullChar: string = FtMetaDefaults.Field.ValueNullChar;
+
+  // Heading formatting properties
+  private _headingConstraint: FtHeadingConstraint = FtMetaDefaults.Field.RootOverriding.HeadingConstraint; // Note that field cannot override heading constraint
+  private _headingQuotedType: FtQuotedType = FtMetaDefaults.Field.RootOverriding.HeadingQuotedType;
+  private _headingAlwaysWriteOptionalQuote: boolean = FtMetaDefaults.Field.RootOverriding.HeadingAlwaysWriteOptionalQuote;
+  private _headingWritePrefixSpace: boolean = FtMetaDefaults.Field.RootOverriding.HeadingWritePrefixSpace;
+  private _headingPadAlignment: FtPadAlignment = FtMetaDefaults.Field.RootOverriding.HeadingPadAlignment;
+  private _headingPadCharType: FtPadCharType = FtMetaDefaults.Field.RootOverriding.HeadingPadCharType;
+  private _headingPadChar: string = FtMetaDefaults.Field.RootOverriding.HeadingPadChar;
+  private _headingTruncateType: FtTruncateType = FtMetaDefaults.Field.RootOverriding.HeadingTruncateType;
+  private _headingTruncateChar: string = FtMetaDefaults.Field.RootOverriding.HeadingTruncateChar;
+  private _headingEndOfValueChar: string = FtMetaDefaults.Field.RootOverriding.HeadingEndOfValueChar;
+
+  private _autoPadChar = ' ';
+
+  private _headingLeftPad = false;
+  private _valueLeftPad = false;
+  private _fixedWidthNullValueText = '';
+
+  protected constructor(dataType: FtDataType, valueType: string, formatter: FtFieldFormatter, autoLeftPad: boolean, index: number) {
+    this.dataType = dataType;
+    this.valueType = valueType;
+    this.formatter = formatter;
+    this.autoLeftPad = autoLeftPad;
+    this._index = index;
+  }
+
+  // Public properties
+  get index(): number {
+    return this._index;
+  }
+  get id(): number | undefined {
+    return this._id;
+  }
+  get metaName(): string {
+    return this._metaName;
+  }
+  get metaHeadings(): string[] {
+    return this._metaHeadings;
+  }
+  get metaHeadingCount(): number {
+    return this._metaHeadings.length;
+  }
+  get mainHeadingIndex(): number {
+    return this._mainHeadingIndex;
+  }
+  get culture(): DotNetLocaleSettings | undefined {
+    return this._culture;
+  }
+  get fixedWidth(): boolean {
+    return this._fixedWidth;
+  }
+  get width(): number {
+    return this._width;
+  }
+  get constant(): boolean {
+    return this._constant;
+  }
+  get null(): boolean {
+    return this._null;
+  }
+
+  get valueQuotedType(): FtQuotedType {
+    return this._valueQuotedType;
+  }
+  get valueAlwaysWriteOptionalQuote(): boolean {
+    return this._valueAlwaysWriteOptionalQuote;
+  }
+  get valueWritePrefixSpace(): boolean {
+    return this._valueWritePrefixSpace;
+  }
+  get valuePadAlignment(): FtPadAlignment {
+    return this._valuePadAlignment;
+  }
+  get valuePadCharType(): FtPadCharType {
+    return this._valuePadCharType;
+  }
+  get valuePadChar(): string {
+    return this._valuePadChar;
+  }
+  get valueTruncateType(): FtTruncateType {
+    return this._valueTruncateType;
+  }
+  get valueTruncateChar(): string {
+    return this._valueTruncateChar;
+  }
+  get valueEndOfValueChar(): string {
+    return this._valueEndOfValueChar;
+  }
+  get valueNullChar(): string {
+    return this._valueNullChar;
+  }
+
+  get headingConstraint(): FtHeadingConstraint {
+    return this._headingConstraint;
+  }
+  get headingQuotedType(): FtQuotedType {
+    return this._headingQuotedType;
+  }
+  get headingAlwaysWriteOptionalQuote(): boolean {
+    return this._headingAlwaysWriteOptionalQuote;
+  }
+  get headingWritePrefixSpace(): boolean {
+    return this._headingWritePrefixSpace;
+  }
+  get headingPadAlignment(): FtPadAlignment {
+    return this._headingPadAlignment;
+  }
+  get headingPadCharType(): FtPadCharType {
+    return this._headingPadCharType;
+  }
+  get headingPadChar(): string {
+    return this._headingPadChar;
+  }
+  get headingTruncateType(): FtTruncateType {
+    return this._headingTruncateType;
+  }
+  get headingTruncateChar(): string {
+    return this._headingTruncateChar;
+  }
+  get headingEndOfValueChar(): string {
+    return this._headingEndOfValueChar;
+  }
+
+  get autoPadChar(): string {
+    return this._autoPadChar;
+  }
+  get headingLeftPad(): boolean {
+    return this._headingLeftPad;
+  }
+  get valueLeftPad(): boolean {
+    return this._valueLeftPad;
+  }
+  get fixedWidthNullValueText(): string {
+    return this._fixedWidthNullValueText;
+  }
+
+  /**
+   * Load metadata from a meta field.
+   * @param metaField - The meta field containing configuration
+   * @param myCulture - The culture settings for formatting
+   * @param myMainHeadingIndex - Index of the main heading
+   */
+  loadMeta(metaField: FtMetaField, myCulture: DotNetLocaleSettings | undefined, myMainHeadingIndex: number): void {
+    this._id = metaField.id;
+    this._metaName = metaField.name;
+    this._metaHeadings = [...metaField.headings];
+    this._mainHeadingIndex = myMainHeadingIndex;
+    this._culture = myCulture;
+    this._fixedWidth = metaField.fixedWidth;
+    this._width = metaField.width;
+    this._constant = metaField.constant;
+    this._null = metaField.null;
+
+    this._valueQuotedType = metaField.valueQuotedType;
+    this._valueAlwaysWriteOptionalQuote = metaField.valueAlwaysWriteOptionalQuote;
+    this._valueWritePrefixSpace = metaField.valueWritePrefixSpace;
+    this._valuePadAlignment = metaField.valuePadAlignment;
+    this._valuePadCharType = metaField.valuePadCharType;
+    this._valuePadChar = metaField.valuePadChar;
+    this._valueTruncateType = metaField.valueTruncateType;
+    this._valueTruncateChar = metaField.valueTruncateChar;
+    this._valueEndOfValueChar = metaField.valueEndOfValueChar;
+    this._valueNullChar = metaField.valueNullChar;
+
+    this._headingConstraint = metaField.headingConstraint;
+    this._headingQuotedType = metaField.headingQuotedType;
+    this._headingAlwaysWriteOptionalQuote = metaField.headingAlwaysWriteOptionalQuote;
+    this._headingWritePrefixSpace = metaField.headingWritePrefixSpace;
+    this._headingPadAlignment = metaField.headingPadAlignment;
+    this._headingPadCharType = metaField.headingPadCharType;
+    this._headingPadChar = metaField.headingPadChar;
+    this._headingTruncateType = metaField.headingTruncateType;
+    this._headingTruncateChar = metaField.headingTruncateChar;
+    this._headingEndOfValueChar = metaField.headingEndOfValueChar;
+
+    this.formatter.culture = this._culture;
+
+    // Set meta name in headings if required
+    if (
+      (this._headingConstraint === FtHeadingConstraint.NameIsMain || this._headingConstraint === FtHeadingConstraint.NameConstant) &&
+      myMainHeadingIndex >= 0 &&
+      myMainHeadingIndex < this.metaHeadingCount
+    ) {
+      this._metaHeadings[myMainHeadingIndex] = this._metaName;
+    }
+
+    // Calculate heading left pad
+    switch (this._headingPadAlignment) {
+      case FtPadAlignment.Left:
+        this._headingLeftPad = true;
+        break;
+      case FtPadAlignment.Right:
+        this._headingLeftPad = false;
+        break;
+      case FtPadAlignment.Auto:
+        this._headingLeftPad = this.autoLeftPad;
+        break;
+      default:
+        throw new FtUnreachableCaseError('FDLM30915', this._headingPadAlignment);
+    }
+
+    // Calculate value left pad
+    switch (this._valuePadAlignment) {
+      case FtPadAlignment.Left:
+        this._valueLeftPad = true;
+        break;
+      case FtPadAlignment.Right:
+        this._valueLeftPad = false;
+        break;
+      case FtPadAlignment.Auto:
+        this._valueLeftPad = this.autoLeftPad;
+        break;
+      default:
+        throw new FtUnreachableCaseError('FDLM30911', this._valuePadAlignment);
+    }
+
+    // Build fixed width null value text
+    if (this._fixedWidth) {
+      this._fixedWidthNullValueText = this._valueNullChar.repeat(this._width);
+    }
+  }
+}

package/src/fields/definitions/ft-float-field-definition.ts

@@ -0,0 +1,43 @@
+import { DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';
+import { FtFloatMetaField } from '../../meta/fields/ft-float-meta-field.js';
+import { FtFloatFieldFormatter } from '../../serialization/formatting/ft-float-field-formatter.js';
+import { FtDataType } from '../../types/enums/ft-data-type.js';
+import { FtGenericFieldDefinition } from './ft-generic-field-definition.js';
+
+/**
+ * Field definition for float (number) fields.
+ * @public
+ */
+export class FtFloatFieldDefinition extends FtGenericFieldDefinition<number> {
+  static readonly AUTO_LEFT_PAD = true;
+
+  declare protected formatter: FtFloatFieldFormatter;
+
+  constructor(index: number) {
+    const formatter = new FtFloatFieldFormatter();
+    super(FtDataType.Float, 'number', formatter, FtFloatFieldDefinition.AUTO_LEFT_PAD, index);
+  }
+
+  get format(): string {
+    return this.formatter.format;
+  }
+
+  get styles(): number {
+    return this.formatter.styles;
+  }
+
+  override loadMeta(metaField: FtFloatMetaField, myCulture: DotNetLocaleSettings | undefined, myMainHeadingIndex: number): void {
+    super.loadMeta(metaField, myCulture, myMainHeadingIndex);
+
+    this.formatter.format = metaField.format;
+    this.formatter.styles = metaField.styles;
+  }
+
+  getValueText(value: number): string {
+    return this.formatter.toText(value);
+  }
+
+  parseValueText(text: string): number {
+    return this.formatter.parse(text);
+  }
+}

package/src/fields/definitions/ft-generic-field-definition.ts

@@ -0,0 +1,49 @@
+import { DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';
+import { FtMetaField } from '../../meta/fields/ft-meta-field.js';
+import { FtFieldDefinition } from './ft-field-definition.js';
+
+/**
+ * Generic base class for field definitions with typed values.
+ * Extends FtFieldDefinition to add type-specific value handling.
+ * @public
+ */
+export abstract class FtGenericFieldDefinition<T> extends FtFieldDefinition {
+  private _value!: T;
+
+  get value(): T {
+    return this._value;
+  }
+
+  /**
+   * Load metadata from a meta field.
+   * @param metaField - The meta field containing configuration
+   * @param myCulture - The culture settings for formatting
+   * @param myMainHeadingIndex - Index of the main heading
+   */
+  override loadMeta(metaField: FtMetaField, myCulture: DotNetLocaleSettings | undefined, myMainHeadingIndex: number): void {
+    super.loadMeta(metaField, myCulture, myMainHeadingIndex);
+
+    // Load constant value if applicable
+    // The concrete generic meta field subclass will have typed value
+    if (metaField.constant && !metaField.null) {
+      const genericMetaField = metaField;
+      if ('value' in genericMetaField) {
+        this._value = genericMetaField.value as T;
+      }
+    }
+  }
+
+  /**
+   * Convert a typed value to its text representation.
+   * @param value - The value to convert
+   * @returns The text representation
+   */
+  abstract getValueText(value: T): string;
+
+  /**
+   * Parse text into a typed value.
+   * @param text - The text to parse
+   * @returns The parsed value
+   */
+  abstract parseValueText(text: string): T;
+}

package/src/fields/definitions/ft-integer-field-definition.ts

@@ -0,0 +1,44 @@
+import { DotNetLocaleSettings } from '@pbkware/dot-net-date-number-formatting';
+import { FtIntegerMetaField } from '../../meta/fields/ft-integer-meta-field.js';
+import { FtIntegerFieldFormatter } from '../../serialization/formatting/ft-integer-field-formatter.js';
+import { FtDataType } from '../../types/enums/ft-data-type.js';
+import { FtGenericFieldDefinition } from './ft-generic-field-definition.js';
+
+/**
+ * Field definition for integer (bigint) fields.
+ * In TypeScript we use bigint for precision but also support number.
+ * @public
+ */
+export class FtIntegerFieldDefinition extends FtGenericFieldDefinition<bigint> {
+  static readonly AUTO_LEFT_PAD = true;
+
+  declare protected formatter: FtIntegerFieldFormatter;
+
+  constructor(index: number) {
+    const formatter = new FtIntegerFieldFormatter();
+    super(FtDataType.Integer, 'bigint', formatter, FtIntegerFieldDefinition.AUTO_LEFT_PAD, index);
+  }
+
+  get format(): string {
+    return this.formatter.format;
+  }
+
+  get styles(): number {
+    return this.formatter.styles;
+  }
+
+  override loadMeta(metaField: FtIntegerMetaField, myCulture: DotNetLocaleSettings | undefined, myMainHeadingIndex: number): void {
+    super.loadMeta(metaField, myCulture, myMainHeadingIndex);
+
+    this.formatter.format = metaField.format;
+    this.formatter.styles = metaField.styles;
+  }
+
+  getValueText(value: bigint): string {
+    return this.formatter.toText(value);
+  }
+
+  parseValueText(text: string): bigint {
+    return this.formatter.parse(text);
+  }
+}

package/src/fields/definitions/ft-string-field-definition.ts

@@ -0,0 +1,26 @@
+import { FtStringFieldFormatter } from '../../serialization/formatting/ft-string-field-formatter.js';
+import { FtDataType } from '../../types/enums/ft-data-type.js';
+import { FtGenericFieldDefinition } from './ft-generic-field-definition.js';
+
+/**
+ * Field definition for string fields.
+ * @public
+ */
+export class FtStringFieldDefinition extends FtGenericFieldDefinition<string> {
+  static readonly AUTO_LEFT_PAD = false;
+
+  declare protected formatter: FtStringFieldFormatter;
+
+  constructor(index: number) {
+    const formatter = new FtStringFieldFormatter();
+    super(FtDataType.String, 'string', formatter, FtStringFieldDefinition.AUTO_LEFT_PAD, index);
+  }
+
+  getValueText(value: string): string {
+    return this.formatter.toText(value);
+  }
+
+  parseValueText(text: string): string {
+    return this.formatter.parse(text);
+  }
+}

package/src/fields/instances/ft-boolean-field.ts

@@ -0,0 +1,49 @@
+import { FtSequenceInvokation } from '../../sequences/core/ft-sequence-invokation.js';
+import { FtSequenceItem } from '../../sequences/core/ft-sequence-item.js';
+import { FtBooleanStyles } from '../../types/enums/ft-boolean-styles.js';
+import { FtBooleanFieldDefinition } from '../definitions/ft-boolean-field-definition.js';
+import { FtGenericField } from './ft-generic-field.js';
+
+/**
+ * Field for boolean values.
+ * @public
+ */
+export class FtBooleanField extends FtGenericField<boolean> {
+  private static readonly VALUE_TEXT_NULL_TRIMMABLE = true;
+
+  constructor(sequenceInvokation: FtSequenceInvokation, sequenceItem: FtSequenceItem, definition: FtBooleanFieldDefinition) {
+    super(sequenceInvokation, sequenceItem, FtBooleanField.VALUE_TEXT_NULL_TRIMMABLE, definition);
+  }
+
+  override get definition(): FtBooleanFieldDefinition {
+    return super.definition_ as FtBooleanFieldDefinition;
+  }
+
+  get falseText(): string {
+    return this.definition.falseText;
+  }
+
+  get trueText(): string {
+    return this.definition.trueText;
+  }
+
+  get styles(): FtBooleanStyles {
+    return this.definition.styles;
+  }
+
+  get nullableValue(): boolean | null {
+    return this.isNull() ? null : this.value;
+  }
+
+  set nullableValue(value: boolean | null) {
+    if (value === null) {
+      this.setNull();
+    } else {
+      this.value = value;
+    }
+  }
+
+  protected isValueEqual(left: boolean, right: boolean): boolean {
+    return left === right;
+  }
+}

package/src/fields/instances/ft-date-time-field.ts

@@ -0,0 +1,44 @@
+import { FtSequenceInvokation } from '../../sequences/core/ft-sequence-invokation.js';
+import { FtSequenceItem } from '../../sequences/core/ft-sequence-item.js';
+import { FtDateTimeFieldDefinition } from '../definitions/ft-date-time-field-definition.js';
+import { FtGenericField } from './ft-generic-field.js';
+
+/**
+ * Field for DateTime values.
+ * @public
+ */
+export class FtDateTimeField extends FtGenericField<Date> {
+  private static readonly VALUE_TEXT_NULL_TRIMMABLE = true;
+
+  constructor(sequenceInvokation: FtSequenceInvokation, sequenceItem: FtSequenceItem, definition: FtDateTimeFieldDefinition) {
+    super(sequenceInvokation, sequenceItem, FtDateTimeField.VALUE_TEXT_NULL_TRIMMABLE, definition);
+  }
+
+  override get definition(): FtDateTimeFieldDefinition {
+    return super.definition_ as FtDateTimeFieldDefinition;
+  }
+
+  get format(): string {
+    return this.definition.format;
+  }
+
+  get styles(): number {
+    return this.definition.styles;
+  }
+
+  get nullableValue(): Date | null {
+    return this.isNull() ? null : this.value;
+  }
+
+  set nullableValue(value: Date | null) {
+    if (value === null) {
+      this.setNull();
+    } else {
+      this.value = value;
+    }
+  }
+
+  protected isValueEqual(left: Date, right: Date): boolean {
+    return left.getTime() === right.getTime();
+  }
+}

package/src/fields/instances/ft-decimal-field.ts

@@ -0,0 +1,44 @@
+import { FtSequenceInvokation } from '../../sequences/core/ft-sequence-invokation.js';
+import { FtSequenceItem } from '../../sequences/core/ft-sequence-item.js';
+import { FtDecimalFieldDefinition } from '../definitions/ft-decimal-field-definition.js';
+import { FtGenericField } from './ft-generic-field.js';
+
+/**
+ * Field for decimal values.
+ * @public
+ */
+export class FtDecimalField extends FtGenericField<number> {
+  private static readonly VALUE_TEXT_NULL_TRIMMABLE = true;
+
+  constructor(sequenceInvokation: FtSequenceInvokation, sequenceItem: FtSequenceItem, definition: FtDecimalFieldDefinition) {
+    super(sequenceInvokation, sequenceItem, FtDecimalField.VALUE_TEXT_NULL_TRIMMABLE, definition);
+  }
+
+  override get definition(): FtDecimalFieldDefinition {
+    return super.definition_ as FtDecimalFieldDefinition;
+  }
+
+  get format(): string {
+    return this.definition.format;
+  }
+
+  get styles(): number {
+    return this.definition.styles;
+  }
+
+  get nullableValue(): number | null {
+    return this.isNull() ? null : this.value;
+  }
+
+  set nullableValue(value: number | null) {
+    if (value === null) {
+      this.setNull();
+    } else {
+      this.value = value;
+    }
+  }
+
+  protected isValueEqual(left: number, right: number): boolean {
+    return left === right;
+  }
+}

package/src/fields/instances/ft-field-list.ts

@@ -0,0 +1,68 @@
+import { FtField } from './ft-field.js';
+
+/**
+ * @public
+ */
+export class FtFieldList {
+  private list: FtField[] = [];
+
+  get count(): number {
+    return this.list.length;
+  }
+
+  get(index: number): FtField {
+    return this.list[index];
+  }
+
+  getByName(name: string): FtField | undefined {
+    const idx = this.indexOfName(name);
+    if (idx >= 0) {
+      return this.list[idx];
+    }
+    return undefined;
+  }
+
+  indexOf(field: FtField): number {
+    return this.list.indexOf(field);
+  }
+
+  indexOfName(name: string): number {
+    // Try case-sensitive first
+    for (let i = 0; i < this.list.length; i++) {
+      if (this.list[i].name === name) {
+        return i;
+      }
+    }
+
+    // Try case-insensitive
+    const lowerName = name.toLowerCase();
+    for (let i = 0; i < this.list.length; i++) {
+      if (this.list[i].name.toLowerCase() === lowerName) {
+        return i;
+      }
+    }
+
+    return -1;
+  }
+
+  indexOfId(id: number): number {
+    for (let i = 0; i < this.list.length; i++) {
+      if (this.list[i].id === id) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  clear(): void {
+    this.list = [];
+  }
+
+  trim(fromIndex: number): void {
+    this.list = this.list.slice(0, fromIndex);
+  }
+
+  add(field: FtField): void {
+    this.list.push(field);
+  }
+}