@pbkware/fielded-text-web 0.1.0

package/src/meta-serialization/utils/sequence-item-field-indices.ts

@@ -0,0 +1,76 @@
+import { CommaText } from '@pbkware/js-utils';
+import { FtMetaFieldList } from '../../meta/fields/ft-meta-field-list.js';
+import { FtMetaField } from '../../meta/fields/ft-meta-field.js';
+import { FtMetaSequence } from '../../meta/sequences/core/ft-meta-sequence.js';
+import { IntegerFloatMetaSerialization } from '../types/integer-float-meta-serialization.js';
+
+export namespace SequenceItemFieldIndexSerialization {
+  export interface SerializeUpToRedirectResult {
+    commaTextFieldIndices: string | undefined;
+    count: number;
+  }
+
+  export function serializeUpToRedirect(sequenceItem: FtMetaSequence, indexOrderedFieldList: FtMetaFieldList): SerializeUpToRedirectResult {
+    const itemList = sequenceItem.itemList;
+    const listCount = itemList.count;
+    const fieldIndices = new Array<number>(listCount);
+    let count = 0;
+    for (let i = 0; i < listCount; i++) {
+      const item = itemList.get(i);
+      if (item.redirectList.count > 0) {
+        break; // We can only use field indices
+      } else {
+        const field = item.field;
+        const index = indexOrderedFieldList.indexOf(field);
+        fieldIndices[count++] = index;
+      }
+    }
+    fieldIndices.length = count; // Trim to actual count
+
+    const commaTextFieldIndices = count > 0 ? CommaText.fromIntegerArray(fieldIndices) : undefined;
+
+    return {
+      commaTextFieldIndices,
+      count: count,
+    };
+  }
+
+  export function serializeField(field: FtMetaField, indexOrderedFieldList: FtMetaFieldList): string {
+    const index = indexOrderedFieldList.indexOf(field);
+    if (index < 0) {
+      throw new Error(`Field not found in field list: ${field.name}`);
+    } else {
+      const fieldIndex = IntegerFloatMetaSerialization.serialize(index, false);
+      if (fieldIndex === undefined) {
+        throw new Error(`Field index is undefined for field: ${field.name}`);
+      } else {
+        return fieldIndex;
+      }
+    }
+  }
+
+  export function deserializeField(
+    serializedFieldIndex: unknown,
+    resolvedOrderedFieldList: FtMetaFieldList,
+    warnings: string[],
+  ): FtMetaField | undefined {
+    if (serializedFieldIndex === undefined) {
+      warnings.push(`Undefined field index value`);
+      return undefined;
+    } else {
+      const fieldIndex = IntegerFloatMetaSerialization.deserialize(serializedFieldIndex, -1, false, warnings);
+      if (fieldIndex < 0) {
+        return undefined;
+      } else {
+        const field = resolvedOrderedFieldList.get(fieldIndex);
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (field === undefined) {
+          warnings.push(`Field not found at index ${fieldIndex} in field list`);
+          return undefined;
+        } else {
+          return field;
+        }
+      }
+    }
+  }
+}

package/src/sequences/core/ft-sequence-invokation-list.ts

@@ -0,0 +1,109 @@
+import { FtField } from '../../fields/instances/ft-field.js';
+import { FtSequenceInvokationDelay } from '../../types/enums/ft-sequence-invokation-delay.js';
+import { FtSequenceInvokation, FtSequenceRedirectDelegate } from './ft-sequence-invokation.js';
+import { FtSequence } from './ft-sequence.js';
+
+/**
+ * @public
+ */
+export class FtSequenceInvokationList {
+  sequenceRedirectEvent?: FtSequenceRedirectDelegate;
+
+  private list: FtSequenceInvokation[] = [];
+  private _count = 0;
+
+  get count(): number {
+    return this._count;
+  }
+
+  get predictCount(): number {
+    return this.list.length;
+  }
+
+  get(index: number): FtSequenceInvokation {
+    return this.list[index];
+  }
+
+  new(sequence: FtSequence, fieldIndex: number): FtSequenceInvokation {
+    const invokation = new FtSequenceInvokation(this._count, sequence, fieldIndex);
+    invokation.sequenceRedirectEvent = (field: FtField, seq: FtSequence | undefined, delay: FtSequenceInvokationDelay) => {
+      if (this.sequenceRedirectEvent) {
+        return this.sequenceRedirectEvent(field, seq, delay);
+      } else {
+        return FtField.NO_FIELDS_AFFECTED_INDEX;
+      }
+    };
+    this.list.push(invokation);
+    this._count = this.list.length;
+    return invokation;
+  }
+
+  clear(): void {
+    for (let i = 0; i < this._count; i++) {
+      this.list[i].sequenceRedirectEvent = undefined;
+    }
+    this.list = [];
+    this._count = 0;
+  }
+
+  trim(fromIndex: number): void {
+    if (fromIndex < this.list.length) {
+      for (let i = fromIndex; i < this._count; i++) {
+        this.list[i].sequenceRedirectEvent = undefined;
+      }
+      this.list = this.list.slice(0, fromIndex);
+      this._count = this.list.length;
+    }
+  }
+
+  tryPredictedNew(index: number, sequence: FtSequence, fieldIndex: number): FtSequenceInvokation | undefined {
+    if (index >= this.predictCount || index !== this._count) {
+      return undefined;
+    }
+
+    const predictedInvokation = this.list[index];
+
+    if (predictedInvokation.sequence !== sequence) {
+      return undefined;
+    }
+
+    if (predictedInvokation.startFieldIndex !== fieldIndex) {
+      return undefined;
+    }
+
+    predictedInvokation.restart(fieldIndex);
+    this._count++;
+    return predictedInvokation;
+  }
+
+  predictTrim(fromIndex: number): void {
+    for (let i = fromIndex; i < this._count; i++) {
+      this.list[i].sidelineFields();
+    }
+    this._count = fromIndex;
+  }
+
+  matches(other: FtSequenceInvokationList): boolean {
+    if (this._count !== other._count) {
+      return false;
+    }
+
+    for (let i = 0; i < this._count; i++) {
+      if (!this.list[i].matches(other.list[i])) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  assign(other: FtSequenceInvokationList): void {
+    this.clear();
+    for (let i = 0; i < other._count; i++) {
+      const otherInvokation = other.list[i];
+      const copyOfOtherInvokation = otherInvokation.createPreviousCopy();
+      this.list.push(copyOfOtherInvokation);
+    }
+    this._count = this.list.length;
+  }
+}

package/src/sequences/core/ft-sequence-invokation.ts

@@ -0,0 +1,166 @@
+import { FtFieldFactory } from '../../factory/ft-field-factory.js';
+import { FtField } from '../../fields/instances/ft-field.js';
+import { FtSequenceInvokationDelay } from '../../types/enums/ft-sequence-invokation-delay.js';
+import { FtSequence } from './ft-sequence.js';
+
+/**
+ * Delegate for sequence redirect events.
+ * @public
+ */
+export type FtSequenceRedirectDelegate = (field: FtField, sequence: FtSequence | undefined, delay: FtSequenceInvokationDelay) => number; // fieldsAffectedFromIndex
+
+/**
+ * Represents an invokation of a sequence during reading or writing.
+ * Manages the fields that make up an instance of a sequence pattern.
+ * @public
+ */
+export class FtSequenceInvokation {
+  sequenceRedirectEvent: FtSequenceRedirectDelegate | undefined;
+
+  private _index: number;
+  private _sequence: FtSequence;
+  private _startFieldIndex: number;
+  private _fieldList: FtField[];
+  private _fieldsSidelinedFromIndex: number;
+  private _redirectingField: FtField | undefined;
+
+  constructor(index: number, sequence: FtSequence, startFieldIndex: number) {
+    this._sequence = sequence;
+    this._startFieldIndex = startFieldIndex;
+    this._fieldList = [];
+    if (index < 0) {
+      // If index < 0, then sequence invokation that will only be used for creating previous copy.
+      // This will only be used for comparison of sequence invokations, so the sequence and start field index are sufficient for that.
+      // The field list will be empty in this case.
+      this._index = -1;
+      this._fieldList = [];
+      this._fieldsSidelinedFromIndex = 0;
+    } else {
+      this._index = index;
+
+      const sequenceItemCount = this._sequence.itemList.count;
+
+      for (let i = 0; i < sequenceItemCount; i++) {
+        const field = FtFieldFactory.createField(this, this._sequence.itemList.get(i));
+        field.index = this._startFieldIndex + i;
+        field.sequenceRedirectEvent = (aField, aSequence, delay) => this.handleSequenceRedirectEvent(aField, aSequence, delay);
+        this._fieldList.push(field);
+      }
+
+      this._fieldsSidelinedFromIndex = sequenceItemCount;
+    }
+  }
+
+  get index(): number {
+    return this._index;
+  }
+
+  get sequence(): FtSequence {
+    return this._sequence;
+  }
+
+  get startFieldIndex(): number {
+    return this._startFieldIndex;
+  }
+
+  get fieldCount(): number {
+    return this._fieldList.length;
+  }
+
+  get fieldsSidelinedFromIndex(): number {
+    return this._fieldsSidelinedFromIndex;
+  }
+
+  get redirectingField(): FtField | undefined {
+    return this._redirectingField;
+  }
+
+  getField(index: number): FtField {
+    return this._fieldList[index];
+  }
+
+  /** @internal */
+  createPreviousCopy(): FtSequenceInvokation {
+    return new FtSequenceInvokation(-1, this._sequence, this._startFieldIndex);
+  }
+
+  /** @internal */
+  matches(other: FtSequenceInvokation): boolean {
+    return this._sequence === other._sequence && this._startFieldIndex === other._startFieldIndex;
+  }
+
+  /** @internal */
+  resetFields(startFieldIndex: number): void {
+    this._startFieldIndex = startFieldIndex;
+    for (let i = 0; i < this._fieldList.length; i++) {
+      const field = this._fieldList[i];
+      field.index = this._startFieldIndex + i;
+      if (i >= this._fieldsSidelinedFromIndex) {
+        field.sidelined = false;
+      }
+      field.resetValue();
+    }
+  }
+
+  /** @internal */
+  sidelineFields(): void {
+    this.sidelineFieldsFrom(0);
+  }
+
+  /** @internal */
+  sidelineFieldsOverload(fromFieldIndex: number): void {
+    this.sidelineFieldsFrom(fromFieldIndex - this._startFieldIndex);
+  }
+
+  /** @internal */
+  unsidelineFields(): void {
+    for (let i = this._fieldsSidelinedFromIndex; i < this._fieldList.length; i++) {
+      const field = this._fieldList[i];
+      field.index = this._startFieldIndex + i;
+      field.sidelined = false;
+      field.resetValue();
+    }
+    this._fieldsSidelinedFromIndex = this._fieldList.length;
+  }
+
+  /** @internal */
+  restart(startFieldIndex: number): void {
+    this._startFieldIndex = startFieldIndex;
+    this.unsidelineFields();
+  }
+
+  private handleSequenceRedirectEvent(field: FtField, sequence: FtSequence | undefined, delay: FtSequenceInvokationDelay): number {
+    if (field !== this._redirectingField) {
+      if (sequence === undefined) {
+        return FtField.NO_FIELDS_AFFECTED_INDEX;
+      } else {
+        if (this.sequenceRedirectEvent !== undefined) {
+          return this.sequenceRedirectEvent(field, sequence, delay);
+        } else {
+          this._redirectingField = field;
+          return FtField.NO_FIELDS_AFFECTED_INDEX;
+        }
+      }
+    } else {
+      if (this.sequenceRedirectEvent !== undefined) {
+        return this.sequenceRedirectEvent(field, sequence, delay);
+      } else {
+        if (sequence === undefined) {
+          this._redirectingField = undefined;
+        }
+        return FtField.NO_FIELDS_AFFECTED_INDEX;
+      }
+    }
+  }
+
+  private sidelineFieldsFrom(fromIndex: number): void {
+    if (fromIndex >= this._fieldList.length) {
+      this._fieldsSidelinedFromIndex = this._fieldList.length; // none
+    } else {
+      for (let i = fromIndex; i < this._fieldList.length; i++) {
+        this._fieldList[i].sidelined = true;
+      }
+      this._fieldsSidelinedFromIndex = fromIndex;
+    }
+  }
+}

package/src/sequences/core/ft-sequence-item-list.ts

@@ -0,0 +1,40 @@
+import { FtSequenceItemFactory } from '../../factory/ft-sequence-item-factory.js';
+import { FtSequenceItem } from './ft-sequence-item.js';
+
+/**
+ * List of sequence items.
+ * @public
+ */
+export class FtSequenceItemList {
+  private _list: FtSequenceItem[] = [];
+
+  get count(): number {
+    return this._list.length;
+  }
+
+  /** @internal */
+  get capacity(): number {
+    return this._list.length;
+  }
+  set capacity(value: number) {
+    if (value > this._list.length) {
+      this._list.length = value;
+    }
+  }
+
+  get(index: number): FtSequenceItem {
+    return this._list[index];
+  }
+
+  /** @internal */
+  clear(): void {
+    this._list = [];
+  }
+
+  /** @internal */
+  new(): FtSequenceItem {
+    const item = FtSequenceItemFactory.createSequenceItem(this.count);
+    this._list.push(item);
+    return item;
+  }
+}

package/src/sequences/core/ft-sequence-item.ts

@@ -0,0 +1,59 @@
+import { FtFieldDefinitionList } from '../../fields/definitions/ft-field-definition-list.js';
+import { FtFieldDefinition } from '../../fields/definitions/ft-field-definition.js';
+import { FtMetaFieldList } from '../../meta/fields/ft-meta-field-list.js';
+import { FtMetaSequenceItem } from '../../meta/sequences/core/ft-meta-sequence-item.js';
+import { FtMetaSequenceList } from '../../meta/sequences/core/ft-meta-sequence-list.js';
+import { FtSequenceRedirectList } from '../redirects/ft-sequence-redirect-list.js';
+import { FtSequenceList } from './ft-sequence-list.js';
+
+/**
+ * Represents an item in a sequence.
+ * Each sequence item references a field definition and has optional redirects.
+ * @public
+ */
+export class FtSequenceItem {
+  private _index: number;
+  private _fieldDefinition: FtFieldDefinition | undefined;
+  private _redirectList: FtSequenceRedirectList;
+
+  constructor(index: number) {
+    this._index = index;
+    this._redirectList = new FtSequenceRedirectList();
+  }
+
+  get index(): number {
+    return this._index;
+  }
+
+  get fieldDefinition(): FtFieldDefinition | undefined {
+    return this._fieldDefinition;
+  }
+
+  get redirectList(): FtSequenceRedirectList {
+    return this._redirectList;
+  }
+
+  /** @internal */
+  loadMeta(metaSequenceItem: FtMetaSequenceItem, metaFieldList: FtMetaFieldList, fieldDefinitionList: FtFieldDefinitionList): void {
+    const fieldIdx = metaFieldList.indexOf(metaSequenceItem.field);
+    if (fieldIdx < 0) {
+      throw new Error(`MetaSequenceItem field "${metaSequenceItem.field.name}" not found in MetaFieldList`);
+    }
+    // fieldDefinitions are in same order as Meta Fields
+    this._fieldDefinition = fieldDefinitionList.get(fieldIdx);
+  }
+
+  /** @internal */
+  loadMetaSequenceRedirects(metaSequenceItem: FtMetaSequenceItem, metaSequenceList: FtMetaSequenceList, sequenceList: FtSequenceList): void {
+    for (let i = 0; i < metaSequenceItem.redirectList.count; i++) {
+      const metaRedirect = metaSequenceItem.redirectList.get(i);
+      const redirect = this._redirectList.new(metaRedirect.type);
+      redirect.loadMeta(metaRedirect, metaSequenceList, sequenceList);
+    }
+  }
+
+  /** @internal */
+  setFieldDefinition(definition: FtFieldDefinition): void {
+    this._fieldDefinition = definition;
+  }
+}

package/src/sequences/core/ft-sequence-list.ts

@@ -0,0 +1,73 @@
+import { FtSequenceFactory } from '../../factory/ft-sequence-factory.js';
+import { FtFieldDefinitionList } from '../../fields/definitions/ft-field-definition-list.js';
+import { FtSequence } from './ft-sequence.js';
+
+/**
+ * List of sequences.
+ * @public
+ */
+export class FtSequenceList {
+  private _list: FtSequence[] = [];
+
+  get count(): number {
+    return this._list.length;
+  }
+
+  /** @internal */
+  get capacity(): number {
+    return this._list.length;
+  }
+
+  set capacity(value: number) {
+    if (value > this._list.length) {
+      this._list.length = value;
+    }
+  }
+
+  get(index: number): FtSequence {
+    return this._list[index];
+  }
+
+  getByName(name: string): FtSequence {
+    const idx = this.indexOfName(name);
+    if (idx >= 0) {
+      return this._list[idx];
+    }
+    throw new Error(`FtSequence not found: ${name}`);
+  }
+
+  /** @internal */
+  clear(): void {
+    this._list = [];
+  }
+
+  /** @internal */
+  new(fieldDefinitionList?: FtFieldDefinitionList): FtSequence {
+    const sequence = FtSequenceFactory.createSequence(this.count);
+    if (fieldDefinitionList) {
+      sequence.loadRootFieldDefinitionList(fieldDefinitionList);
+    }
+    this._list.push(sequence);
+    return sequence;
+  }
+
+  indexOfName(name: string): number {
+    // Case-insensitive comparison matching C# FtMetaSequence.SameName
+    const lowerName = name.toLowerCase();
+    for (let i = 0; i < this.count; i++) {
+      if (this._list[i].name.toLowerCase() === lowerName) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  indexOfRoot(): number {
+    for (let i = 0; i < this.count; i++) {
+      if (this._list[i].root) {
+        return i;
+      }
+    }
+    return -1;
+  }
+}

package/src/sequences/core/ft-sequence.ts

@@ -0,0 +1,75 @@
+import { FtFieldDefinitionList } from '../../fields/definitions/ft-field-definition-list.js';
+import { FtMetaFieldList } from '../../meta/fields/ft-meta-field-list.js';
+import { FtMetaSequenceList } from '../../meta/sequences/core/ft-meta-sequence-list.js';
+import { FtMetaSequence } from '../../meta/sequences/core/ft-meta-sequence.js';
+import { FtSequenceItemList } from './ft-sequence-item-list.js';
+import { FtSequenceList } from './ft-sequence-list.js';
+
+/**
+ * Represents a sequence of fielded text items.
+ * A sequence defines a pattern of fields that can be repeated.
+ * @public
+ */
+export class FtSequence {
+  private static readonly AUTO_ROOT_NAME = 'AutoRoot';
+
+  private _index: number;
+  private _name = '';
+  private _root = false;
+  private _itemList: FtSequenceItemList;
+
+  constructor(index: number) {
+    this._index = index;
+    this._itemList = new FtSequenceItemList();
+  }
+
+  get index(): number {
+    return this._index;
+  }
+
+  get name(): string {
+    return this._name;
+  }
+
+  get root(): boolean {
+    return this._root;
+  }
+
+  get itemList(): FtSequenceItemList {
+    return this._itemList;
+  }
+
+  /** @internal */
+  setRoot(value: boolean): void {
+    this._root = value;
+  }
+
+  /** @internal */
+  loadMeta(metaSequence: FtMetaSequence, metaFieldList: FtMetaFieldList, fieldDefinitionList: FtFieldDefinitionList): void {
+    this._name = metaSequence.name;
+    this._root = metaSequence.root;
+
+    for (let i = 0; i < metaSequence.itemList.count; i++) {
+      const item = this._itemList.new();
+      item.loadMeta(metaSequence.itemList.get(i), metaFieldList, fieldDefinitionList);
+    }
+  }
+
+  /** @internal */
+  loadMetaSequenceRedirects(metaSequence: FtMetaSequence, metaSequenceList: FtMetaSequenceList, sequenceList: FtSequenceList): void {
+    for (let i = 0; i < this._itemList.count; i++) {
+      // Note that Sequence Items are in same order as MetaSequence Items
+      this._itemList.get(i).loadMetaSequenceRedirects(metaSequence.itemList.get(i), metaSequenceList, sequenceList);
+    }
+  }
+
+  /** @internal */
+  loadRootFieldDefinitionList(fieldDefinitionList: FtFieldDefinitionList): void {
+    this._name = FtSequence.AUTO_ROOT_NAME;
+    this._root = true;
+    for (let i = 0; i < fieldDefinitionList.count; i++) {
+      const item = this._itemList.new();
+      item.setFieldDefinition(fieldDefinitionList.get(i));
+    }
+  }
+}

package/src/sequences/redirects/ft-boolean-sequence-redirect.ts

@@ -0,0 +1,42 @@
+import { FtField } from '../../fields/instances/ft-field.js';
+import { FtMetaSequenceList } from '../../meta/sequences/core/ft-meta-sequence-list.js';
+import { FtBooleanMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-boolean-meta-sequence-redirect.js';
+import { FtSequenceRedirectType } from '../../types/enums/ft-sequence-redirect-type.js';
+import { FtSequenceList } from '../core/ft-sequence-list.js';
+import { FtSequenceRedirect } from './ft-sequence-redirect.js';
+
+/**
+ * Sequence redirect that triggers when a field equals a specific boolean value.
+ * @public
+ */
+export class FtBooleanSequenceRedirect extends FtSequenceRedirect {
+  static readonly TYPE = FtSequenceRedirectType.Boolean;
+
+  private _value = false;
+
+  constructor(index: number) {
+    super(index, FtBooleanSequenceRedirect.TYPE);
+  }
+
+  get value(): boolean {
+    return this._value;
+  }
+
+  checkTriggered(field: FtField): boolean {
+    if (field.isNull()) {
+      return false;
+    }
+    try {
+      return field.asRedirectBoolean === this._value;
+    } catch {
+      return false;
+    }
+  }
+
+  /** @internal */
+  override loadMeta(metaSequenceRedirect: FtBooleanMetaSequenceRedirect, metaSequenceList: FtMetaSequenceList, sequenceList: FtSequenceList): void {
+    super.loadMeta(metaSequenceRedirect, metaSequenceList, sequenceList);
+
+    this._value = metaSequenceRedirect.value;
+  }
+}

package/src/sequences/redirects/ft-case-insensitive-string-sequence-redirect.ts

@@ -0,0 +1,46 @@
+import { FtField } from '../../fields/instances/ft-field.js';
+import { FtMetaSequenceList } from '../../meta/sequences/core/ft-meta-sequence-list.js';
+import { FtCaseInsensitiveStringMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-case-insensitive-string-meta-sequence-redirect.js';
+import { FtSequenceRedirectType } from '../../types/enums/ft-sequence-redirect-type.js';
+import { FtSequenceList } from '../core/ft-sequence-list.js';
+import { FtSequenceRedirect } from './ft-sequence-redirect.js';
+
+/**
+ * Sequence redirect that triggers when a field equals a specific string value (case-insensitive).
+ * @public
+ */
+export class FtCaseInsensitiveStringSequenceRedirect extends FtSequenceRedirect {
+  static readonly TYPE = FtSequenceRedirectType.CaseInsensitiveString;
+
+  private _value = '';
+
+  constructor(index: number) {
+    super(index, FtCaseInsensitiveStringSequenceRedirect.TYPE);
+  }
+
+  get value(): string {
+    return this._value;
+  }
+
+  checkTriggered(field: FtField): boolean {
+    if (field.isNull()) {
+      return false;
+    }
+    try {
+      return field.asRedirectString.toLowerCase() === this._value.toLowerCase();
+    } catch {
+      return false;
+    }
+  }
+
+  /** @internal */
+  override loadMeta(
+    metaSequenceRedirect: FtCaseInsensitiveStringMetaSequenceRedirect,
+    metaSequenceList: FtMetaSequenceList,
+    sequenceList: FtSequenceList,
+  ): void {
+    super.loadMeta(metaSequenceRedirect, metaSequenceList, sequenceList);
+
+    this._value = metaSequenceRedirect.value;
+  }
+}