@pbkware/fielded-text-web 0.1.0

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

@@ -0,0 +1,48 @@
+import { FtField } from '../../fields/instances/ft-field.js';
+import { FtMetaSequenceList } from '../../meta/sequences/core/ft-meta-sequence-list.js';
+import { FtDateMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-date-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's date component equals a specific date value (time ignored).
+ * @public
+ */
+export class FtDateSequenceRedirect extends FtSequenceRedirect {
+  static readonly TYPE = FtSequenceRedirectType.Date;
+
+  private _value: Date = new Date(0);
+
+  constructor(index: number) {
+    super(index, FtDateSequenceRedirect.TYPE);
+  }
+
+  get value(): Date {
+    return this._value;
+  }
+
+  checkTriggered(field: FtField): boolean {
+    if (field.isNull()) {
+      return false;
+    }
+    try {
+      const fieldDate = field.asRedirectDateTime;
+      // Compare only the date portion (ignore time)
+      return (
+        fieldDate.getFullYear() === this._value.getFullYear() &&
+        fieldDate.getMonth() === this._value.getMonth() &&
+        fieldDate.getDate() === this._value.getDate()
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  /** @internal */
+  override loadMeta(metaSequenceRedirect: FtDateMetaSequenceRedirect, metaSequenceList: FtMetaSequenceList, sequenceList: FtSequenceList): void {
+    super.loadMeta(metaSequenceRedirect, metaSequenceList, sequenceList);
+
+    this._value = metaSequenceRedirect.value;
+  }
+}

package/src/sequences/redirects/ft-exact-date-time-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 { FtExactDateTimeMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-exact-date-time-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 exactly equals a specific datetime value.
+ * @public
+ */
+export class FtExactDateTimeSequenceRedirect extends FtSequenceRedirect {
+  static readonly TYPE = FtSequenceRedirectType.ExactDateTime;
+
+  private _value: Date = new Date(0);
+
+  constructor(index: number) {
+    super(index, FtExactDateTimeSequenceRedirect.TYPE);
+  }
+
+  get value(): Date {
+    return this._value;
+  }
+
+  checkTriggered(field: FtField): boolean {
+    if (field.isNull()) {
+      return false;
+    }
+    try {
+      return field.asRedirectDateTime.getTime() === this._value.getTime();
+    } catch {
+      return false;
+    }
+  }
+
+  /** @internal */
+  override loadMeta(
+    metaSequenceRedirect: FtExactDateTimeMetaSequenceRedirect,
+    metaSequenceList: FtMetaSequenceList,
+    sequenceList: FtSequenceList,
+  ): void {
+    super.loadMeta(metaSequenceRedirect, metaSequenceList, sequenceList);
+
+    this._value = metaSequenceRedirect.value;
+  }
+}

package/src/sequences/redirects/ft-exact-decimal-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 { FtExactDecimalMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-exact-decimal-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 exactly equals a specific decimal value.
+ * @public
+ */
+export class FtExactDecimalSequenceRedirect extends FtSequenceRedirect {
+  static readonly TYPE = FtSequenceRedirectType.ExactDecimal;
+
+  private _value = 0;
+
+  constructor(index: number) {
+    super(index, FtExactDecimalSequenceRedirect.TYPE);
+  }
+
+  get value(): number {
+    return this._value;
+  }
+
+  checkTriggered(field: FtField): boolean {
+    if (field.isNull()) {
+      return false;
+    }
+    try {
+      return field.asRedirectDecimal === this._value;
+    } catch {
+      return false;
+    }
+  }
+
+  /** @internal */
+  override loadMeta(
+    metaSequenceRedirect: FtExactDecimalMetaSequenceRedirect,
+    metaSequenceList: FtMetaSequenceList,
+    sequenceList: FtSequenceList,
+  ): void {
+    super.loadMeta(metaSequenceRedirect, metaSequenceList, sequenceList);
+
+    this._value = metaSequenceRedirect.value;
+  }
+}

package/src/sequences/redirects/ft-exact-float-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 { FtExactFloatMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-exact-float-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 exactly equals a specific float (number) value.
+ * @public
+ */
+export class FtExactFloatSequenceRedirect extends FtSequenceRedirect {
+  static readonly TYPE = FtSequenceRedirectType.ExactFloat;
+
+  private _value = 0;
+
+  constructor(index: number) {
+    super(index, FtExactFloatSequenceRedirect.TYPE);
+  }
+
+  get value(): number {
+    return this._value;
+  }
+
+  checkTriggered(field: FtField): boolean {
+    if (field.isNull()) {
+      return false;
+    }
+    try {
+      return field.asRedirectFloat === this._value;
+    } catch {
+      return false;
+    }
+  }
+
+  /** @internal */
+  override loadMeta(
+    metaSequenceRedirect: FtExactFloatMetaSequenceRedirect,
+    metaSequenceList: FtMetaSequenceList,
+    sequenceList: FtSequenceList,
+  ): void {
+    super.loadMeta(metaSequenceRedirect, metaSequenceList, sequenceList);
+
+    this._value = metaSequenceRedirect.value;
+  }
+}

package/src/sequences/redirects/ft-exact-integer-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 { FtExactIntegerMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-exact-integer-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 exactly equals a specific integer value.
+ * @public
+ */
+export class FtExactIntegerSequenceRedirect extends FtSequenceRedirect {
+  static readonly TYPE = FtSequenceRedirectType.ExactInteger;
+
+  private _value = 0n;
+
+  constructor(index: number) {
+    super(index, FtExactIntegerSequenceRedirect.TYPE);
+  }
+
+  get value(): bigint {
+    return this._value;
+  }
+
+  checkTriggered(field: FtField): boolean {
+    if (field.isNull()) {
+      return false;
+    }
+    try {
+      return field.asRedirectInteger === this._value;
+    } catch {
+      return false;
+    }
+  }
+
+  /** @internal */
+  override loadMeta(
+    metaSequenceRedirect: FtExactIntegerMetaSequenceRedirect,
+    metaSequenceList: FtMetaSequenceList,
+    sequenceList: FtSequenceList,
+  ): void {
+    super.loadMeta(metaSequenceRedirect, metaSequenceList, sequenceList);
+
+    this._value = metaSequenceRedirect.value;
+  }
+}

package/src/sequences/redirects/ft-exact-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 { FtExactStringMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-exact-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 exactly equals a specific string value (case-sensitive).
+ * @public
+ */
+export class FtExactStringSequenceRedirect extends FtSequenceRedirect {
+  static readonly TYPE = FtSequenceRedirectType.ExactString;
+
+  private _value = '';
+
+  constructor(index: number) {
+    super(index, FtExactStringSequenceRedirect.TYPE);
+  }
+
+  get value(): string {
+    return this._value;
+  }
+
+  checkTriggered(field: FtField): boolean {
+    if (field.isNull()) {
+      return false;
+    }
+    try {
+      return field.asRedirectString === this._value;
+    } catch {
+      return false;
+    }
+  }
+
+  /** @internal */
+  override loadMeta(
+    metaSequenceRedirect: FtExactStringMetaSequenceRedirect,
+    metaSequenceList: FtMetaSequenceList,
+    sequenceList: FtSequenceList,
+  ): void {
+    super.loadMeta(metaSequenceRedirect, metaSequenceList, sequenceList);
+
+    this._value = metaSequenceRedirect.value;
+  }
+}

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

@@ -0,0 +1,27 @@
+import { FtField } from '../../fields/instances/ft-field.js';
+import { FtMetaSequenceList } from '../../meta/sequences/core/ft-meta-sequence-list.js';
+import { FtNullMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-null-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 is null.
+ * @public
+ */
+export class FtNullSequenceRedirect extends FtSequenceRedirect {
+  static readonly TYPE = FtSequenceRedirectType.Null;
+
+  constructor(index: number) {
+    super(index, FtNullSequenceRedirect.TYPE);
+  }
+
+  checkTriggered(field: FtField): boolean {
+    return field.isNull();
+  }
+
+  /** @internal */
+  override loadMeta(metaSequenceRedirect: FtNullMetaSequenceRedirect, metaSequenceList: FtMetaSequenceList, sequenceList: FtSequenceList): void {
+    super.loadMeta(metaSequenceRedirect, metaSequenceList, sequenceList);
+  }
+}

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

@@ -0,0 +1,42 @@
+import { FtSequenceRedirectFactory } from '../../factory/ft-sequence-redirect-factory.js';
+import { FtSequenceRedirectType } from '../../types/enums/ft-sequence-redirect-type.js';
+import { FtSequenceRedirect } from './ft-sequence-redirect.js';
+
+/**
+ * List of sequence redirects for a sequence item.
+ * @public
+ */
+export class FtSequenceRedirectList {
+  private _items: FtSequenceRedirect[] = [];
+
+  get count(): number {
+    return this._items.length;
+  }
+
+  /** @internal */
+  get capacity(): number {
+    return this._items.length;
+  }
+  set capacity(value: number) {
+    // TypeScript arrays grow dynamically, but we can pre-allocate
+    if (value > this._items.length) {
+      this._items.length = value;
+    }
+  }
+
+  get(index: number): FtSequenceRedirect {
+    return this._items[index];
+  }
+
+  /** @internal */
+  clear(): void {
+    this._items = [];
+  }
+
+  /** @internal */
+  new(type: FtSequenceRedirectType): FtSequenceRedirect {
+    const redirect = FtSequenceRedirectFactory.createSequenceRedirect(this.count, type);
+    this._items.push(redirect);
+    return redirect;
+  }
+}

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

@@ -0,0 +1,68 @@
+import { FtField } from '../../fields/instances/ft-field.js';
+import type { FtMetaSequenceList } from '../../meta/sequences/core/ft-meta-sequence-list.js';
+import type { FtMetaSequenceRedirect } from '../../meta/sequences/redirects/ft-meta-sequence-redirect.js';
+import { FtSequenceInvokationDelay } from '../../types/enums/ft-sequence-invokation-delay.js';
+import { FtSequenceRedirectType } from '../../types/enums/ft-sequence-redirect-type.js';
+import type { FtSequenceList } from '../core/ft-sequence-list.js';
+import { FtSequence } from '../core/ft-sequence.js';
+
+/**
+ * Abstract base class for sequence redirects.
+ * Redirects determine when to switch from one sequence to another based on field values.
+ * These are the runtime instances that use metadata definitions to perform actual redirections.
+ * @public
+ */
+export abstract class FtSequenceRedirect {
+  private _index: number;
+  private _type: FtSequenceRedirectType;
+  private _sequence: FtSequence | undefined;
+  private _invokationDelay: FtSequenceInvokationDelay;
+
+  protected constructor(index: number, type: FtSequenceRedirectType) {
+    this._index = index;
+    this._type = type;
+    this._invokationDelay = FtSequenceInvokationDelay.AfterSequence;
+  }
+
+  get index(): number {
+    return this._index;
+  }
+
+  get type(): FtSequenceRedirectType {
+    return this._type;
+  }
+
+  // get typeName(): string {
+  //   return FtSequenceRedirectTypeInfo.toName(this._type);
+  // }
+
+  get sequence(): FtSequence | undefined {
+    return this._sequence;
+  }
+
+  get invokationDelay(): FtSequenceInvokationDelay {
+    return this._invokationDelay;
+  }
+
+  /** @internal */
+  loadMeta(metaSequenceRedirect: FtMetaSequenceRedirect, metaSequenceList: FtMetaSequenceList, sequenceList: FtSequenceList): void {
+    this._type = metaSequenceRedirect.type;
+    this._invokationDelay = metaSequenceRedirect.invokationDelay;
+
+    if (metaSequenceRedirect.sequence) {
+      const sequenceIdx = metaSequenceList.indexOf(metaSequenceRedirect.sequence);
+      if (sequenceIdx < 0) {
+        throw new Error(`MetaSequenceRedirect sequence "${metaSequenceRedirect.sequence.name}" not found in MetaSequenceList`);
+      }
+      // sequenceList are in same order as Meta Sequence List
+      this._sequence = sequenceList.get(sequenceIdx);
+    }
+  }
+
+  /**
+   * Check if this redirect is triggered based on the field's current state.
+   * @param field - The field to check
+   * @returns true if redirect should be triggered
+   */
+  abstract checkTriggered(field: FtField): boolean;
+}

package/src/serialization/char-reader.ts

@@ -0,0 +1,203 @@
+import { FtUnreachableCaseError } from '../types/errors/ft-internal-error.js';
+import { FtTextReader } from './ft-text-reader.js';
+
+const State = {
+  Read: 'Read',
+  SignaturePeekReread: 'SignaturePeekReread',
+  SignaturePeekRereadThenEof: 'SignaturePeekRereadThenEof',
+  TextReaderPeeked: 'TextReaderPeeked',
+  EofPeeked: 'EofPeeked',
+  Eof: 'Eof',
+} as const;
+
+type State = (typeof State)[keyof typeof State];
+
+/**
+ * Low-level character reader with buffering and peek support.
+ * Wraps a TextReader source and provides character-by-character reading.
+ * @internal
+ */
+export class CharReader {
+  static readonly Signature = '|!Fielded Text^|';
+  static readonly LegacySignature = '|>Fielded Text<|';
+  static readonly CarriageReturnChar = '\x0D';
+  static readonly LineFeedChar = '\x0A';
+  static readonly CarriageReturnLineFeedString = '\x0D\x0A';
+
+  private _textReader: FtTextReader | undefined = undefined;
+  private _position = -1;
+  private _state: State = State.Read;
+  private _signaturePeekBuffer = '';
+  private _signaturePeekBufferPosition = 0;
+  private _peekedChar = -1;
+
+  get position(): number {
+    return this._position;
+  }
+
+  get isClosed(): boolean {
+    return this._textReader === undefined;
+  }
+
+  get textReader(): FtTextReader | undefined {
+    return this._textReader;
+  }
+
+  /**
+   * Set the TextReader source for reading.
+   * @param textReader The TextReader to read from.
+   */
+  setTextReader(textReader: FtTextReader): void {
+    this.close();
+
+    this._textReader = textReader;
+    this._state = State.Read;
+    this._signaturePeekBuffer = '';
+    this._signaturePeekBufferPosition = 0;
+    this._position = -1;
+  }
+
+  /**
+   * Close the reader.
+   */
+  close(): void {
+    if (this._textReader !== undefined) {
+      this._textReader = undefined;
+    }
+  }
+
+  /**
+   * Read the next character.
+   * @returns The character code point, or EofReadResult if at end.
+   */
+  read(): number {
+    switch (this._state) {
+      case State.Read: {
+        const readResult = this._textReader?.read() ?? FtTextReader.EofReadResult;
+        this._position++;
+        if (readResult !== FtTextReader.EofReadResult) {
+          return readResult;
+        } else {
+          this._state = State.Eof;
+          return FtTextReader.EofReadResult;
+        }
+      }
+
+      case State.SignaturePeekReread:
+      case State.SignaturePeekRereadThenEof: {
+        const aChar = this._signaturePeekBuffer.charCodeAt(this._signaturePeekBufferPosition);
+        this._signaturePeekBufferPosition++;
+        if (this._signaturePeekBufferPosition === this._signaturePeekBuffer.length) {
+          this._state = this._state === State.SignaturePeekRereadThenEof ? State.EofPeeked : State.Read;
+        }
+        this._position++;
+        return aChar;
+      }
+
+      case State.TextReaderPeeked: {
+        const peekResult = this._peekedChar;
+        this._state = State.Read;
+        this._position++;
+        return peekResult;
+      }
+
+      case State.EofPeeked:
+        this._position++;
+        this._state = State.Eof;
+        return FtTextReader.EofReadResult;
+
+      case State.Eof:
+        return FtTextReader.EofReadResult;
+
+      default:
+        throw new FtUnreachableCaseError('CRR34490', this._state);
+    }
+  }
+
+  /**
+   * Peek ahead for the signature string.
+   * Checks if the stream starts with the FieldedText signature.
+   * @returns The signature if found, undefined otherwise.
+   */
+  peekSignature(): string | undefined {
+    if (this._state !== State.Read) {
+      throw new Error('CharReader.peekSignature not in Read state');
+    }
+
+    let result: string | undefined = undefined;
+    let activeSignature = CharReader.Signature;
+    this._signaturePeekBuffer = '';
+
+    do {
+      const readCharAsInt = this._textReader?.read() ?? FtTextReader.EofReadResult;
+
+      if (readCharAsInt === FtTextReader.EofReadResult) {
+        this._state = this._signaturePeekBuffer.length === 0 ? State.EofPeeked : State.SignaturePeekRereadThenEof;
+      } else {
+        const readChar = String.fromCharCode(readCharAsInt);
+        this._signaturePeekBuffer += readChar;
+
+        if (this._signaturePeekBuffer.length > 1) {
+          // Check if we should switch to legacy signature (at position 1, char is '>')
+          if (this._signaturePeekBuffer.length === 2 && readChar === CharReader.LegacySignature[1]) {
+            activeSignature = CharReader.LegacySignature;
+          }
+
+          if (readChar !== activeSignature[this._signaturePeekBuffer.length - 1]) {
+            this._state = State.SignaturePeekReread;
+          } else {
+            if (this._signaturePeekBuffer.length === activeSignature.length) {
+              result = activeSignature;
+              this._state = State.SignaturePeekReread;
+            }
+          }
+        }
+      }
+    } while (this._state === State.Read);
+
+    this._signaturePeekBufferPosition = 0;
+    return result;
+  }
+
+  /**
+   * Peek at the next character without consuming it.
+   * @returns The character code point, or EofReadResult if at end.
+   */
+  peek(): number {
+    switch (this._state) {
+      case State.Read: {
+        const readChar = this._textReader?.read() ?? FtTextReader.EofReadResult;
+        if (readChar === FtTextReader.EofReadResult) {
+          this._state = State.EofPeeked;
+          return FtTextReader.EofReadResult;
+        } else {
+          this._peekedChar = readChar;
+          this._state = State.TextReaderPeeked;
+          return this._peekedChar;
+        }
+      }
+
+      case State.SignaturePeekReread:
+      case State.SignaturePeekRereadThenEof:
+        return this._signaturePeekBuffer.charCodeAt(this._signaturePeekBufferPosition);
+
+      case State.TextReaderPeeked:
+        return this._peekedChar;
+
+      case State.EofPeeked:
+      case State.Eof:
+        return FtTextReader.EofReadResult;
+
+      default:
+        throw new FtUnreachableCaseError('CRP34499', this._state);
+    }
+  }
+
+  /**
+   * Check if the next character is a line feed.
+   * @returns True if the next character is \n, false otherwise.
+   */
+  peekNextIsLineFeed(): boolean {
+    return this.peek() === CharReader.LineFeedChar.charCodeAt(0);
+  }
+}