@pbkware/fielded-text-web 0.1.2 → 0.2.1

package/dist/fields/instances/ft-field.js

@@ -2,7 +2,9 @@ import { FtHeadingConstraint } from '../../types/enums/ft-heading-constraint.js'
 import { FtQuotedType } from '../../types/enums/ft-quoted-type.js';
 import { FtSequenceInvokationDelay } from '../../types/enums/ft-sequence-invokation-delay.js';
 import { FtSequenceRedirectType } from '../../types/enums/ft-sequence-redirect-type.js';
-import { FtUnreachableCaseError } from '../../types/errors/ft-internal-error.js';
+import { FtUnreachableCaseError } from '../../utils/ft-internal-error.js';
+import { FtFieldNullError } from './errors/ft-field-null-error.js';
+import { FtFieldTypeError } from './errors/ft-field-type-error.js';
 /**
  * Abstract base class for all field instances.
  * Fields represent runtime field values during reading or writing.
@@ -12,7 +14,7 @@ export class FtField {
     static NO_FIELDS_AFFECTED_INDEX = -1;
     static IGNORED_SEQUENCE_INVOKATION_DELAY = FtSequenceInvokationDelay.AfterSequence;
     sequenceRedirectEvent;
-    valueAssigned = false;
+    _valueAssigned = false;
     quoted = false;
     _index = 0;
     _definition;
@@ -29,7 +31,7 @@ export class FtField {
     _loadedLength = 0;
     _loadedRawOffset = 0;
     _loadedRawLength = 0;
-    _loadedValueText = '';
+    _valueText = '';
     constructor(sequenceInvokation, sequenceItem, valueTextNullTrimmable) {
         if (!sequenceItem.fieldDefinition) {
             throw new Error('SequenceItem must have a field definition');
@@ -86,11 +88,17 @@ export class FtField {
     get headings() {
         return this._headings;
     }
-    get valueAssigned_() {
-        return this.valueAssigned;
+    /**
+     * Indicates whether a value has been assigned to the field.
+     */
+    get valueAssigned() {
+        return this._valueAssigned;
     }
-    get loadedValueText() {
-        return this._loadedValueText;
+    /**
+     * The formatted text of the field value as loaded from the data or via {@link loadValueText}.
+     */
+    get valueText() {
+        return this._valueText;
     }
     // Properties delegating to definition
     get dataType() {
@@ -100,7 +108,7 @@ export class FtField {
         return this._definition.id;
     }
     get name() {
-        return this._definition.metaName;
+        return this._name;
     }
     get metaHeadings() {
         return this._definition.metaHeadings;
@@ -185,7 +193,7 @@ export class FtField {
     }
     /** @internal */
     get asRedirectString() {
-        return this.getAsNonNullValueText();
+        return this.formatValue();
     }
     /** @internal */
     get asRedirectBoolean() {
@@ -207,64 +215,182 @@ export class FtField {
     get asRedirectDecimal() {
         return this.getAsRedirectDecimal();
     }
-    // Public property accessors
-    get asValueText() {
-        return this.isNull() ? null : this.getAsNonNullValueText();
-    }
-    set asValueText(value) {
-        this.setAsValueText(value);
-    }
-    get asObject() {
-        return this.isNull() ? null : this.getAsNonNullObject();
+    /**
+     * The field value as an unspecified type.
+     *
+     * When setting the value, the actual type must be compatible with the field's expected type.
+     *
+     * @throws FtFieldNullError if the field is `null`.
+     */
+    get value() {
+        if (this.isNull()) {
+            throw new FtFieldNullError(`Field value is null: ${this.name}`);
+        }
+        else {
+            return this.getValue();
+        }
     }
-    set asObject(value) {
-        this.setAsObject(value);
+    set value(value) {
+        this.setValue(value);
     }
+    /**
+     * The field value as a string.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `String`.
+     * @throws FtFieldNullError if the field is `null`.
+     */
     get asString() {
-        return this.isNull() ? null : this.getAsNonNullString();
+        if (this.isNull()) {
+            throw new FtFieldNullError(`String field value is null: ${this.name}`);
+        }
+        else {
+            return this.getAsString();
+        }
     }
     set asString(value) {
         this.setAsString(value);
     }
+    /**
+     * The field value as a boolean.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `Boolean`.
+     * @throws FtFieldNullError if the field is `null`.
+     */
     get asBoolean() {
-        return this.getAsBoolean();
+        if (this.isNull()) {
+            throw new FtFieldNullError(`Boolean field value is null: ${this.name}`);
+        }
+        else {
+            return this.getAsBoolean();
+        }
     }
     set asBoolean(value) {
         this.setAsBoolean(value);
     }
+    /**
+     * The field value as an integer.
+  
+     * @throws FtFieldTypeError if the field is not of data type `Integer`.
+     * @throws FtFieldNullError if the field is `null`.
+     */
     get asInteger() {
-        return this.getAsInteger();
+        if (this.isNull()) {
+            throw new FtFieldNullError(`Integer field value is null: ${this.name}`);
+        }
+        else {
+            return this.getAsInteger();
+        }
     }
     set asInteger(value) {
         this.setAsInteger(value);
     }
+    /**
+     * The field value as a bigint.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `BigInt`.
+     * @throws FtFieldNullError if the field is `null`.
+     */
     get asBigInt() {
-        return this.getAsBigInt();
+        if (this.isNull()) {
+            throw new FtFieldNullError(`Integer field value is null: ${this.name}`);
+        }
+        else {
+            return this.getAsBigInt();
+        }
     }
     set asBigInt(value) {
         this.setAsBigInt(value);
     }
+    /**
+     * The field value as a float.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `Float`.
+     * @throws FtFieldNullError if the field is `null`.
+     */
     get asFloat() {
-        return this.getAsFloat();
+        if (this.isNull()) {
+            throw new FtFieldNullError(`Float field value is null: ${this.name}`);
+        }
+        else {
+            return this.getAsFloat();
+        }
     }
     set asFloat(value) {
         this.setAsFloat(value);
     }
+    /**
+     * The field value as a DateTime.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `DateTime`.
+     * @throws FtFieldNullError if the field is `null`.
+     */
     get asDateTime() {
-        return this.getAsDateTime();
+        if (this.isNull()) {
+            throw new FtFieldNullError(`DateTime field value is null: ${this.name}`);
+        }
+        else {
+            return this.getAsDateTime();
+        }
     }
     set asDateTime(value) {
         this.setAsDateTime(value);
     }
+    /**
+     * The field value as a number (decimal).
+     *
+     * @throws FtFieldTypeError if the field is not of data type `Decimal`.
+     * @throws FtFieldNullError if the field is `null`.
+     */
     get asDecimal() {
-        return this.getAsDecimal();
+        if (this.isNull()) {
+            throw new FtFieldNullError(`Decimal field value is null: ${this.name}`);
+        }
+        else {
+            return this.getAsDecimal();
+        }
     }
     set asDecimal(value) {
         this.setAsDecimal(value);
     }
-    // Nullable property accessors
+    /**
+     * The field value as an unspecified type or null.
+  
+     * Use with caution, as this bypasses type safety. Ensure that the value being set is compatible with the field's expected type.
+     */
+    get nullableValue() {
+        return this.isNull() ? null : this.getValue();
+    }
+    set nullableValue(value) {
+        if (value === null) {
+            this.setNull();
+        }
+        else {
+            this.setValue(value);
+        }
+    }
+    /**
+     * The field value as a string or null.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `String`.
+     */
+    get asNullableString() {
+        return this.isNull() ? null : this.getAsString();
+    }
+    set asNullableString(value) {
+        if (value === null) {
+            this.setNull();
+        }
+        else {
+            this.setAsString(value);
+        }
+    }
+    /**
+     * The field value as a boolean or null.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `Boolean`.
+     */
     get asNullableBoolean() {
-        return this.isNull() ? null : this.asBoolean;
+        return this.isNull() ? null : this.getAsBoolean();
     }
     set asNullableBoolean(value) {
         if (value === null) {
@@ -274,8 +400,13 @@ export class FtField {
             this.setAsBoolean(value);
         }
     }
+    /**
+     * The field value as an integer or null.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `BigInt`.
+     */
     get asNullableInteger() {
-        return this.isNull() ? null : this.asInteger;
+        return this.isNull() ? null : this.getAsInteger();
     }
     set asNullableInteger(value) {
         if (value === null) {
@@ -285,8 +416,13 @@ export class FtField {
             this.setAsInteger(value);
         }
     }
+    /**
+     * The field value as a bigint or null.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `BigInt`.
+     */
     get asNullableBigInt() {
-        return this.isNull() ? null : this.asBigInt;
+        return this.isNull() ? null : this.getAsBigInt();
     }
     set asNullableBigInt(value) {
         if (value === null) {
@@ -296,8 +432,13 @@ export class FtField {
             this.setAsBigInt(value);
         }
     }
+    /**
+     * The field value as a float or null.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `Float`.
+     */
     get asNullableFloat() {
-        return this.isNull() ? null : this.asFloat;
+        return this.isNull() ? null : this.getAsFloat();
     }
     set asNullableFloat(value) {
         if (value === null) {
@@ -307,8 +448,13 @@ export class FtField {
             this.setAsFloat(value);
         }
     }
+    /**
+     * The field value as a Date or null.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `DateTime`.
+     */
     get asNullableDateTime() {
-        return this.isNull() ? null : this.asDateTime;
+        return this.isNull() ? null : this.getAsDateTime();
     }
     set asNullableDateTime(value) {
         if (value === null) {
@@ -318,8 +464,13 @@ export class FtField {
             this.setAsDateTime(value);
         }
     }
+    /**
+     * The field value as a number (decimal) or null.
+     *
+     * @throws FtFieldTypeError if the field is not of data type `Decimal`.
+     */
     get asNullableDecimal() {
-        return this.isNull() ? null : this.asDecimal;
+        return this.isNull() ? null : this.getAsDecimal();
     }
     set asNullableDecimal(value) {
         if (value === null) {
@@ -329,69 +480,115 @@ export class FtField {
             this.setAsDecimal(value);
         }
     }
-    // Null handling
+    /**
+     * Checks if the field value is null.
+     * @returns True if the field value is null, false otherwise.
+     */
     isNull() {
         return this._valueIsNull;
     }
+    /**
+     * Sets the field value to null.
+     *
+     * Checks for sequence redirects that may be triggered by setting the field to null.
+     *
+     * @returns If this setting of field to null caused a sequence redirect, returns the index of the first field affected by the redirect. If no redirect occurred, returns FtField.NO_FIELDS_AFFECTED_INDEX.
+     * @throws Error if the field is constant and cannot be set to null.
+     */
     setNull() {
         if (this.constant) {
             throw new Error(`Cannot set constant field "${this.name}" to null`);
         }
         else {
             this._valueIsNull = true;
-            this.valueAssigned = true;
+            this._valueAssigned = true;
             return this.checkNullSequenceRedirect(); // returns fieldsAffectedFromIndex
         }
     }
+    /**
+     * Loads the field value from its formatted text representation.
+     * @param valueText - Formatted text representation of field value. Formatting only includes data type formatting and not text formatting such as quoting, padding, truncating etc.
+     */
+    loadValueText(valueText) {
+        this._valueText = valueText;
+        this.loadValueFromText(valueText);
+    }
+    /**
+     * Loads the field headings from an array of strings.
+     *
+     * The headings are loaded according to the field's heading constraint. See {@link loadHeading} for more information.
+     *
+     * @param value - An array of headings. The length of the array should be equal to {@link headingCount}. Extra headings are ignored and missing headings are set to empty strings.
+     */
     loadHeadings(value) {
-        for (let i = 0; i < value.length; i++) {
+        const valueCount = value.length;
+        for (let i = 0; i < valueCount; i++) {
             this.loadHeading(i, value[i]);
         }
+        const headingCount = this._headings.length;
+        if (valueCount < headingCount) {
+            for (let i = valueCount; i < headingCount; i++) {
+                this.loadHeading(i, '');
+            }
+        }
     }
+    /**
+     * Loads a heading into one of the field's heading lines.
+     *
+     * The heading is loaded according to the field's heading constraint.
+     *
+     * @param idx - Index of the heading to load.
+     * @param headingText - Text of the heading.
+     */
     loadHeading(idx, headingText) {
-        switch (this._definition.headingConstraint) {
-            case FtHeadingConstraint.None:
-                this._headings[idx] = headingText;
-                break;
-            case FtHeadingConstraint.AllConstant:
-                if (headingText !== this._headings[idx]) {
-                    throw new Error(`Heading constraint violation: AllConstant at index ${idx} in field ${this.name}`);
-                }
-                break;
-            case FtHeadingConstraint.MainConstant:
-                if (idx !== this._definition.mainHeadingIndex) {
+        if (idx >= 0 && idx < this._headings.length) {
+            switch (this._definition.headingConstraint) {
+                case FtHeadingConstraint.None:
                     this._headings[idx] = headingText;
-                }
-                else {
+                    break;
+                case FtHeadingConstraint.AllConstant:
                     if (headingText !== this._headings[idx]) {
-                        throw new Error(`Heading constraint violation: MainConstant in field ${this.name}`);
+                        throw new Error(`Heading constraint violation: AllConstant at index ${idx} in field ${this.name}`);
                     }
-                }
-                break;
-            case FtHeadingConstraint.NameConstant:
-                if (idx !== this._definition.mainHeadingIndex) {
-                    this._headings[idx] = headingText;
-                }
-                else {
-                    if (headingText.toLowerCase() === this._definition.metaName.toLowerCase()) {
+                    break;
+                case FtHeadingConstraint.MainConstant:
+                    if (idx !== this._definition.mainHeadingIndex) {
                         this._headings[idx] = headingText;
                     }
                     else {
-                        throw new Error(`Heading constraint violation: NameConstant in field ${this.name}`);
+                        if (headingText !== this._headings[idx]) {
+                            throw new Error(`Heading constraint violation: MainConstant in field ${this.name}`);
+                        }
                     }
-                }
-                break;
-            case FtHeadingConstraint.NameIsMain:
-                this._headings[idx] = headingText;
-                if (idx === this._definition.mainHeadingIndex) {
-                    this._name = headingText;
-                }
-                break;
-            default:
-                throw new FtUnreachableCaseError('FLH30773', this._definition.headingConstraint);
+                    break;
+                case FtHeadingConstraint.NameConstant:
+                    if (idx !== this._definition.mainHeadingIndex) {
+                        this._headings[idx] = headingText;
+                    }
+                    else {
+                        if (headingText.toLowerCase() === this._definition.metaName.toLowerCase()) {
+                            this._headings[idx] = headingText;
+                        }
+                        else {
+                            throw new Error(`Heading constraint violation: NameConstant in field ${this.name}`);
+                        }
+                    }
+                    break;
+                case FtHeadingConstraint.NameIsMain:
+                    this._headings[idx] = headingText;
+                    if (idx === this._definition.mainHeadingIndex) {
+                        this._name = headingText;
+                    }
+                    break;
+                default:
+                    throw new FtUnreachableCaseError('FLH30773', this._definition.headingConstraint);
+            }
         }
     }
-    /** @internal */
+    /**
+     * Checks if setting the field to null triggers a sequence redirect.
+     * @internal
+     */
     checkNullSequenceRedirect() {
         if (this._sequenceRedirectList.count > 0 && !this._sidelined) {
             let redirected = false;
@@ -417,7 +614,7 @@ export class FtField {
         if (!this.constant) {
             this._valueIsNull = true;
         }
-        this.valueAssigned = false;
+        this._valueAssigned = false;
     }
     // Loading methods (used by parsers)
     /** @internal */
@@ -429,10 +626,10 @@ export class FtField {
     }
     /** @internal */
     loadDelimitedValue(valueText, quoted) {
-        this._loadedValueText = valueText;
+        this._valueText = valueText;
         try {
             if (quoted) {
-                this.loadNonNullValue(valueText);
+                this.loadValueFromText(valueText);
             }
             else {
                 if (this._valueTextNullTrimmable) {
@@ -441,18 +638,18 @@ export class FtField {
                         this.loadNullValue();
                     }
                     else {
-                        this.loadNonNullValue(valueText);
+                        this.loadValueFromText(valueText);
                     }
                 }
                 else {
                     if (valueText.length !== 0) {
-                        this.loadNonNullValue(valueText);
+                        this.loadValueFromText(valueText);
                     }
                     else {
                         switch (this.valueQuotedType) {
                             case FtQuotedType.Never:
                             case FtQuotedType.Optional:
-                                this.loadNonNullValue(valueText);
+                                this.loadValueFromText(valueText);
                                 break;
                             case FtQuotedType.Always:
                                 this.loadNullValue();
@@ -470,13 +667,13 @@ export class FtField {
     }
     /** @internal */
     loadFixedWidthValue(valueText) {
-        this._loadedValueText = valueText;
+        this._valueText = valueText;
         if (valueText === this._definition.fixedWidthNullValueText) {
             this.loadNullValue();
         }
         else {
             try {
-                this.loadNonNullValue(valueText);
+                this.loadValueFromText(valueText);
             }
             catch (e) {
                 throw new Error(`Error loading fixed-width value for field ${this.name}: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
@@ -487,7 +684,7 @@ export class FtField {
     loadNullValue() {
         if (!this.constant) {
             this._valueIsNull = true;
-            this.valueAssigned = true;
+            this._valueAssigned = true;
             this.checkNullSequenceRedirect();
         }
         else {
@@ -496,20 +693,6 @@ export class FtField {
             }
         }
     }
-    /**
-     * Get the field value as text (for writing). Public accessor for protected method.
-     * @internal
-     */
-    getValueText() {
-        return this.getAsNonNullValueText();
-    }
-    /**
-     * Check if the field value has been assigned. Public accessor for protected property.
-     * @internal
-     */
-    isValueAssigned() {
-        return this.valueAssigned;
-    }
     // get dataTypeName(): string {
     //   return this._definition.dataTypeName;
     // }
@@ -524,38 +707,47 @@ export class FtField {
     clearNonConstantNull() {
         this._valueIsNull = false;
     }
-    setAsNonNullValueText(newValue) {
-        try {
-            this.loadNonNullValue(newValue);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to set field "${this.name}" value: ${message}`, { cause: error });
-        }
+    getAsString() {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsString`);
     }
-    setAsValueText(newValue) {
-        if (newValue === null) {
-            this.setNull();
-        }
-        else {
-            this.setAsNonNullValueText(newValue);
-        }
+    getAsBoolean() {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsBoolean`);
     }
-    setAsObject(newValue) {
-        if (newValue === null || newValue === undefined) {
-            this.setNull();
-        }
-        else {
-            this.setAsNonNullObject(newValue);
-        }
+    getAsInteger() {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsInteger`);
     }
-    setAsString(newValue) {
-        if (newValue === null) {
-            this.setNull();
-        }
-        else {
-            this.setAsNonNullString(newValue);
-        }
+    getAsBigInt() {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsBigInt`);
+    }
+    getAsFloat() {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsFloat`);
+    }
+    getAsDateTime() {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsDateTime`);
+    }
+    getAsDecimal() {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsDecimal`);
+    }
+    setAsString(_newValue) {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsString`);
+    }
+    setAsBoolean(_newValue) {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsBoolean`);
+    }
+    setAsInteger(_newValue) {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsInteger`);
+    }
+    setAsBigInt(_newValue) {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsBigInt`);
+    }
+    setAsFloat(_newValue) {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsFloat`);
+    }
+    setAsDateTime(_newValue) {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsDateTime`);
+    }
+    setAsDecimal(_newValue) {
+        throw new FtFieldTypeError(`Field ${this.name} does not support AsDecimal`);
     }
 }
 //# sourceMappingURL=ft-field.js.map