@pbkware/fielded-text-web 0.1.0 → 0.2.1

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

@@ -1,15 +1,9 @@
 import { FtWriterSettings } from '../api/ft-writer-settings.js';
 import { FtFieldDefinition } from '../fields/definitions/ft-field-definition.js';
-import { FtBooleanField } from '../fields/instances/ft-boolean-field.js';
-import { FtDateTimeField } from '../fields/instances/ft-date-time-field.js';
-import { FtDecimalField } from '../fields/instances/ft-decimal-field.js';
+// eslint-disable-next-line import-x/no-cycle
 import { FtField } from '../fields/instances/ft-field.js';
-import { FtFloatField } from '../fields/instances/ft-float-field.js';
-import { FtIntegerField } from '../fields/instances/ft-integer-field.js';
-import { FtStringField } from '../fields/instances/ft-string-field.js';
 import { FtXmlMetaSerialization } from '../meta-serialization/format/ft-xml-meta-serialization.js';
 import { FtMeta } from '../meta/ft-meta.js';
-import { FtDataType } from '../types/enums/ft-data-type.js';
 import { FtEndOfLineAutoWriteType } from '../types/enums/ft-end-of-line-auto-write-type.js';
 import { FtEndOfLineType } from '../types/enums/ft-end-of-line-type.js';
 import { FtLastLineEndedType } from '../types/enums/ft-last-line-ended-type.js';
@@ -18,19 +12,19 @@ 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';
-import { FtSerializationError } from '../types/errors/ft-serialization-error.js';
-import { FtSerializationException } from '../types/errors/ft-serialization-exception.js';
+import { FtUnreachableCaseError } from '../utils/ft-internal-error.js';
 import { FtDeclaredParametersFormatter } from './formatting/ft-declared-parameters-formatter.js';
 import { FtDeclaredParameters } from './ft-declared-parameters.js';
+import { FtSerializationCore } from './ft-serialization-core.js';
+import { FtSerializationErrorCode } from './ft-serialization-error-code.js';
+import { FtSerializationError } from './ft-serialization-error.js';
 import { FtTextWriter } from './ft-text-writer.js';
-import { SerializationCore } from './serialization-core.js';
 
 /**
  * Writer for fielded text streams. Coordinates all writing logic.
  * @public
  */
-export class FtSerializationWriter extends SerializationCore {
+export class FtSerializationWriter extends FtSerializationCore {
   private static readonly DECLARATION_LINE2_BEFORE_COMMENT_CHARS = ' ';
   private static readonly EMBEDDED_META_BEFORE_COMMENT_CHARS = ' ';
 
@@ -100,7 +94,7 @@ export class FtSerializationWriter extends SerializationCore {
    */
   writeHeader(): void {
     if (this._headerWritten) {
-      throw new FtSerializationException(FtSerializationError.HeaderAlreadyWritten, 'Header already written');
+      throw new FtSerializationError(FtSerializationErrorCode.HeaderAlreadyWritten, 'Header already written');
     }
 
     if (this._settings?.declared) {
@@ -142,106 +136,145 @@ export class FtSerializationWriter extends SerializationCore {
   }
 
   /**
-   * Set a field value by index.
+   * Set a field value by index. Accepts `null` to set the field to null.
+   *
+   * @param idx - The 0-based index of the field to set.
+   * @param value - The value to set for the field. Can be `null` to set the field to null.
+   *
+   * @throws FtTypeError if the value being set is not of the field's expected type.
    */
-  setFieldValue(idx: number, value: unknown): void {
-    this.fieldList.get(idx).asObject = value;
+  setFieldValue(idx: number, value: FtField.Value | null): void {
+    this.fieldList.get(idx).nullableValue = value;
   }
 
   /**
    * Set a field value by name.
+   *
+   * @param name - The name of the field to set.
+   * @param value - The value to set for the field. Can be `null` to set the field to null.
+   *
+   * @throws FtTypeError if the value being set is not of the field's expected type.
    */
-  setFieldValueByName(name: string, value: unknown): void {
+  setFieldValueByName(name: string, value: FtField.Value | null): void {
     const field = this.fieldList.getByName(name);
     if (!field) {
       throw new Error(`Field not found: ${name}`);
     }
-    field.asObject = value;
+    field.nullableValue = value;
   }
 
   /**
    * Set a field to null.
+   *
+   * @param idx - The 0-based index of the field to set.
    */
   setNull(idx: number): void {
     this.fieldList.get(idx).setNull();
   }
 
+  /**
+   * Set a field to null.
+   *
+   * @param name - The name of the field to set.
+   */
+  setNullByName(name: string): void {
+    const field = this.fieldList.getByName(name);
+    if (!field) {
+      throw new Error(`Field not found: ${name}`);
+    }
+    field.setNull();
+  }
+
   /**
    * Set a boolean field.
+   *
+   * @param idx - The 0-based index of the field to set.
+   * @param value - The value to set for the field. Can be `null` to set the field to null.
    */
-  setBoolean(idx: number, value: boolean): void {
+  setBoolean(idx: number, value: boolean | null): void {
     const field = this.fieldList.get(idx);
-    if (field.dataType !== FtDataType.Boolean) {
-      throw new Error(`Invalid cast: field ${idx} is not boolean`);
-    }
-    (field as FtBooleanField).value = value;
+    field.asNullableBoolean = value;
   }
 
   /**
-   * Set a date/time field.
+   * Set a DateTime field's value.
+   *
+   * @param idx - The 0-based index of the field to set.
+   * @param value - The value to set for the field. Can be `null` to set the field to null.
    */
-  setDateTime(idx: number, value: Date): void {
+  setDateTime(idx: number, value: Date | null): void {
     const field = this.fieldList.get(idx);
-    if (field.dataType !== FtDataType.DateTime) {
-      throw new Error(`Invalid cast: field ${idx} is not datetime`);
-    }
-    (field as FtDateTimeField).value = value;
+    field.asNullableDateTime = value;
   }
 
   /**
    * Set a decimal field.
+   *
+   * @param idx - The 0-based index of the field to set.
+   * @param value - The value to set for the field. Can be `null` to set the field to null.
    */
-  setDecimal(idx: number, value: number): void {
+  setDecimal(idx: number, value: number | null): void {
     const field = this.fieldList.get(idx);
-    if (field.dataType !== FtDataType.Decimal) {
-      throw new Error(`Invalid cast: field ${idx} is not decimal`);
-    }
-    (field as FtDecimalField).value = value;
+    field.asNullableDecimal = value;
   }
 
   /**
    * Set a float field.
+   *
+   * @param idx - The 0-based index of the field to set.
+   * @param value - The value to set for the field. Can be `null` to set the field to null.
    */
-  setFloat(idx: number, value: number): void {
+  setFloat(idx: number, value: number | null): void {
     const field = this.fieldList.get(idx);
-    if (field.dataType !== FtDataType.Float) {
-      throw new Error(`Invalid cast: field ${idx} is not float`);
-    }
-    (field as FtFloatField).value = value;
+    field.asNullableFloat = value;
   }
 
   /**
    * Set an integer field.
+   *
+   * @param idx - The 0-based index of the field to set.
+   * @param value - The value to set for the field. Can be `null` to set the field to null.
    */
-  setInteger(idx: number, value: number | bigint): void {
+  setInteger(idx: number, value: number | bigint | null): void {
     const field = this.fieldList.get(idx);
-    if (field.dataType !== FtDataType.Integer) {
-      throw new Error(`Invalid cast: field ${idx} is not integer`);
+    switch (typeof value) {
+      case 'bigint':
+        field.asBigInt = value;
+        break;
+      case 'number':
+        field.asInteger = value;
+        break;
+      default:
+        field.setNull();
+        break;
     }
-    (field as FtIntegerField).value = typeof value === 'bigint' ? value : BigInt(value);
   }
 
   /**
    * Set a string field.
+   *
+   * @param idx - The 0-based index of the field to set.
+   * @param value - The value to set for the field. Can be `null` to set the field to null.
    */
-  setString(idx: number, value: string): void {
+  setString(idx: number, value: string | null): void {
     const field = this.fieldList.get(idx);
-    if (field.dataType !== FtDataType.String) {
-      throw new Error(`Invalid cast: field ${idx} is not string`);
-    }
-    (field as FtStringField).value = value;
+    field.asNullableString = value;
   }
 
   /**
    * Set multiple field values.
+   *
+   * @param values - An array of values to set for the fields. The length of the array must not exceed the number of fields. Array elements can be null to set the corresponding field to null.
+   *
+   * @throws FtTypeError if any of the values being set is not of the corresponding field's expected type.
    */
-  setValues(values: unknown[]): void {
+  setValues(values: (FtField.Value | null)[]): void {
     if (values.length > this.fieldCount) {
       throw new Error(`Values length ${values.length} exceeds field count ${this.fieldCount}`);
     }
 
     for (let i = 0; i < values.length; i++) {
-      this.fieldList.get(i).asObject = values[i];
+      this.fieldList.get(i).nullableValue = values[i];
     }
   }
 
@@ -322,15 +355,15 @@ export class FtSerializationWriter extends SerializationCore {
       case FtEndOfLineType.Char:
         return this.endOfLineChar;
       case FtEndOfLineType.CrLf:
-        return SerializationCore.CarriageReturnLineFeedString;
+        return FtSerializationCore.CarriageReturnLineFeedString;
       case FtEndOfLineType.Auto:
         switch (this.endOfLineAutoWriteType) {
           case FtEndOfLineAutoWriteType.CrLf:
-            return SerializationCore.CarriageReturnLineFeedString;
+            return FtSerializationCore.CarriageReturnLineFeedString;
           case FtEndOfLineAutoWriteType.Cr:
-            return SerializationCore.CarriageReturnChar;
+            return FtSerializationCore.CarriageReturnChar;
           case FtEndOfLineAutoWriteType.Lf:
-            return SerializationCore.LineFeedChar;
+            return FtSerializationCore.LineFeedChar;
           case FtEndOfLineAutoWriteType.Local:
             return '\n'; // Use platform default
           default:
@@ -373,8 +406,8 @@ export class FtSerializationWriter extends SerializationCore {
       switch (this.endOfLineType) {
         case FtEndOfLineType.Auto:
         case FtEndOfLineType.CrLf:
-          searchChars.push(SerializationCore.CarriageReturnChar);
-          searchChars.push(SerializationCore.LineFeedChar);
+          searchChars.push(FtSerializationCore.CarriageReturnChar);
+          searchChars.push(FtSerializationCore.LineFeedChar);
           break;
         case FtEndOfLineType.Char:
           searchChars.push(this.endOfLineChar);
@@ -413,12 +446,12 @@ export class FtSerializationWriter extends SerializationCore {
     }
 
     const parameters = new FtDeclaredParameters();
-    parameters.setVersion(SerializationCore.VersionMajor, SerializationCore.VersionMinor);
+    parameters.setVersion(FtSerializationCore.VersionMajor, FtSerializationCore.VersionMinor);
     const metaReferenceType = this._settings.metaReferenceType ?? FtWriterSettings.DEFAULT_META_REFERENCE_TYPE;
     const metaReference = this._settings.metaReference ?? FtWriterSettings.DEFAULT_META_REFERENCE;
     parameters.setMetaReference(metaReferenceType, metaReference);
 
-    this.writeComment(SerializationCore.Signature + ' ' + FtDeclaredParametersFormatter.toSignatureLineText(parameters), '');
+    this.writeComment(FtSerializationCore.Signature + ' ' + FtDeclaredParametersFormatter.toSignatureLineText(parameters), '');
     this.writeComment(FtDeclaredParametersFormatter.toLine2Text(parameters), FtSerializationWriter.DECLARATION_LINE2_BEFORE_COMMENT_CHARS);
   }
 
@@ -481,7 +514,7 @@ export class FtSerializationWriter extends SerializationCore {
       }
 
       if (field.headingWritePrefixSpace) {
-        this._writer?.write(SerializationCore.PrefixSpaceChar);
+        this._writer?.write(FtSerializationCore.PrefixSpaceChar);
       }
 
       if (fieldQuoted) {
@@ -532,7 +565,7 @@ export class FtSerializationWriter extends SerializationCore {
       if (field.isNull()) {
         this._writer?.write(field.definition.fixedWidthNullValueText);
       } else {
-        const valueText = field.getValueText();
+        const valueText = field.formatValue();
         const rawText = this.encodeFixedWidthValueText(valueText, field);
         this._writer?.write(rawText);
       }
@@ -540,7 +573,7 @@ export class FtSerializationWriter extends SerializationCore {
       if (field.isNull()) {
         this._writer?.write('');
       } else {
-        const valueText = field.getValueText();
+        const valueText = field.formatValue();
 
         let fieldQuoted: boolean;
         switch (field.valueQuotedType) {
@@ -562,7 +595,7 @@ export class FtSerializationWriter extends SerializationCore {
         }
 
         if (field.valueWritePrefixSpace) {
-          this._writer?.write(SerializationCore.PrefixSpaceChar);
+          this._writer?.write(FtSerializationCore.PrefixSpaceChar);
         }
 
         if (fieldQuoted) {
@@ -578,7 +611,7 @@ export class FtSerializationWriter extends SerializationCore {
       }
     }
 
-    if (!field.constant && !field.isValueAssigned()) {
+    if (!field.constant && !field.valueAssigned) {
       // Field was not assigned a value, check null sequence redirects
       if (!field.isNull()) {
         throw new Error('Field value not assigned');
@@ -752,7 +785,7 @@ export class FtSerializationWriter extends SerializationCore {
       case FtTruncateType.NullChar:
         return nullChar.repeat(definition.width);
       case FtTruncateType.Exception:
-        throw new FtSerializationException(FtSerializationError.FieldTruncated, `Text truncation: ${text}`);
+        throw new FtSerializationError(FtSerializationErrorCode.FieldTruncated, `Text truncation: ${text}`);
       default:
         throw new FtUnreachableCaseError('SWCTTT22117', truncateType);
     }

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

@@ -1,11 +1,11 @@
 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 { FtAssertError, FtUnreachableCaseError } from '../utils/ft-internal-error.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';
+import { FtSerializationCore } from './ft-serialization-core.js';
+import { FtSerializationErrorCode } from './ft-serialization-error-code.js';
+import { FtSerializationError } from './ft-serialization-error.js';
 
 const State = {
   Out: 'Out',
@@ -23,7 +23,7 @@ type State = (typeof State)[keyof typeof State];
  * @internal
  */
 export class HeadingLineRecordParser {
-  private readonly _core: SerializationCore;
+  private readonly _core: FtSerializationCore;
   private readonly _charReader: CharReader;
   private readonly _headingLines: boolean;
 
@@ -38,7 +38,7 @@ export class HeadingLineRecordParser {
   private _startPosition = -1;
   private _ignoreExtraCharsStartPosition = -1;
 
-  constructor(core: SerializationCore, charReader: CharReader, forHeadingLines: boolean) {
+  constructor(core: FtSerializationCore, charReader: CharReader, forHeadingLines: boolean) {
     this._core = core;
     this._charReader = charReader;
     this._headingLines = forHeadingLines;
@@ -109,11 +109,11 @@ export class HeadingLineRecordParser {
         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 error = this._headingLines ? FtSerializationErrorCode.HeadingLineTooManyFields : FtSerializationErrorCode.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);
+          throw new FtSerializationError(error, message);
         }
         this.parseChar(aChar);
         break;
@@ -206,11 +206,11 @@ export class HeadingLineRecordParser {
 
     if (this._fieldCount < this._core.fieldList.count) {
       if (!this._core.allowIncompleteRecords) {
-        const error = this._headingLines ? FtSerializationError.HeadingLineNotEnoughFields : FtSerializationError.RecordNotEnoughFields;
+        const error = this._headingLines ? FtSerializationErrorCode.HeadingLineNotEnoughFields : FtSerializationErrorCode.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);
+        throw new FtSerializationError(error, message);
       } else {
         for (let i = this._fieldCount; i < this._core.fieldList.count; i++) {
           const field = this._core.fieldList.get(i);

package/src/serialization/line-parser.ts

@@ -1,5 +1,5 @@
 import { FtEndOfLineType } from '../types/enums/ft-end-of-line-type.js';
-import { FtAssertError, FtUnreachableCaseError } from '../types/errors/ft-internal-error.js';
+import { FtAssertError, FtUnreachableCaseError } from '../utils/ft-internal-error.js';
 import { CharReader } from './char-reader.js';
 
 const FtLineState = {

package/src/serialization/{ft-text-reader.ts → text-reader/ft-string-reader.ts}

@@ -1,27 +1,4 @@
-/**
- * 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;
-}
+import type { FtTextReader } from './ft-text-reader.js';
 
 /**
  * A TextReader implementation that reads from a string.

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

@@ -0,0 +1,24 @@
+/**
+ * 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;
+}

package/src/types/enums/ft-heading-constraint.ts

@@ -2,10 +2,15 @@
  * @public
  */
 export const FtHeadingConstraint = {
+  /** No constraings on headings */
   None: 'None',
+  /** All headings in the data must match the headings specified in the Meta */
   AllConstant: 'AllConstant',
+  /** The heading in the main heading line in the data must match the corresponding heading specified in the Meta */
   MainConstant: 'MainConstant',
+  /** The heading in the main heading line in the data must case-insensitively match the field's name */
   NameConstant: 'NameConstant',
+  /** The field's name is set to the heading in the main heading line in the data */
   NameIsMain: 'NameIsMain',
 } as const;