@pbkware/fielded-text-web 0.1.0

package/src/api/ft-reader.ts

@@ -0,0 +1,106 @@
+import { FtMeta } from '../meta/ft-meta.js';
+import { FtSerializationReader } from '../serialization/ft-serialization-reader.js';
+import { FtStringReader, FtTextReader } from '../serialization/ft-text-reader.js';
+
+/**
+ * High-level reader for fielded text files.
+ * Provides a convenient API for reading CSV and other delimited/fixed-width text.
+ * This is a thin wrapper around SerializationReader with simpler constructors.
+ * @public
+ */
+export class FtReader extends FtSerializationReader {
+  /**
+   * Create a reader with or without metadata.
+   * If metadata is provided, it will be loaded immediately. If not, you must call loadMeta() before reading.
+   * You must call open() before reading.
+   * @param meta - The metadata defining the file structure
+   */
+  constructor(meta?: FtMeta);
+
+  /**
+   * Create a reader with metadata and input text.
+   * You must call open() before reading.
+   * @param meta - The metadata defining the file structure
+   * @param input - The text content to read
+   * @param immediatelyReadHeader - Whether to automatically read header lines (default: true)
+   */
+  // eslint-disable-next-line @typescript-eslint/unified-signatures
+  constructor(meta: FtMeta, input: string, immediatelyReadHeader?: boolean);
+
+  /**
+   * Create a reader with metadata and a TextReader.
+   * @param meta - The metadata defining the file structure
+   * @param textReader - The TextReader to read from
+   * @param immediatelyReadHeader - Whether to automatically read header lines (default: true)
+   */
+  // eslint-disable-next-line @typescript-eslint/unified-signatures
+  constructor(meta: FtMeta, textReader: FtTextReader, immediatelyReadHeader?: boolean);
+
+  /**
+   * Create a reader with input text but no metadata.
+   * You must call loadMeta() before reading.
+   * @param input - The text content to read
+   * @param immediatelyReadHeader - Whether to automatically read header lines (default: true)
+   */
+  constructor(input: string, immediatelyReadHeader?: boolean);
+
+  /**
+   * Create a reader with a TextReader but no metadata.
+   * You must call loadMeta() before reading.
+   * @param textReader - The TextReader to read from
+   * @param immediatelyReadHeader - Whether to automatically read header lines (default: true)
+   */
+  constructor(textReader: FtTextReader, immediatelyReadHeader?: boolean);
+
+  constructor(
+    metaOrInputOrTextReader?: FtMeta | string | FtTextReader,
+    inputOrTextReaderOrImmediatelyReadHeader?: string | FtTextReader | boolean,
+    immediatelyReadHeader = true,
+  ) {
+    super();
+
+    if (metaOrInputOrTextReader instanceof FtMeta) {
+      // Constructor with meta
+      this.loadMeta(metaOrInputOrTextReader);
+
+      if (typeof inputOrTextReaderOrImmediatelyReadHeader === 'string') {
+        // FtReader(meta, input, immediatelyReadHeader)
+        this.open(inputOrTextReaderOrImmediatelyReadHeader, immediatelyReadHeader);
+      } else if (
+        inputOrTextReaderOrImmediatelyReadHeader &&
+        typeof inputOrTextReaderOrImmediatelyReadHeader === 'object' &&
+        'read' in inputOrTextReaderOrImmediatelyReadHeader
+      ) {
+        // FtReader(meta, textReader, immediatelyReadHeader)
+        this.open(inputOrTextReaderOrImmediatelyReadHeader, immediatelyReadHeader);
+      } else {
+        // FtReader(meta) - just reset, no open
+        this.reset();
+      }
+    } else if (typeof metaOrInputOrTextReader === 'string') {
+      // FtReader(input, immediatelyReadHeader)
+      const shouldReadHeader = typeof inputOrTextReaderOrImmediatelyReadHeader === 'boolean' ? inputOrTextReaderOrImmediatelyReadHeader : true;
+      this.open(metaOrInputOrTextReader, shouldReadHeader);
+    } else if (metaOrInputOrTextReader && typeof metaOrInputOrTextReader === 'object' && 'read' in metaOrInputOrTextReader) {
+      // FtReader(textReader, immediatelyReadHeader)
+      const shouldReadHeader = typeof inputOrTextReaderOrImmediatelyReadHeader === 'boolean' ? inputOrTextReaderOrImmediatelyReadHeader : true;
+      this.open(metaOrInputOrTextReader, shouldReadHeader);
+    }
+  }
+
+  /**
+   * Open the reader with a text string.
+   * @param textReaderOrText - Text reader or string providing the data to read
+   * @param immediatelyReadHeader - Whether to automatically read header lines (default: true)
+   */
+  override open(textReaderOrText: FtTextReader | string, immediatelyReadHeader = true): void {
+    let textReader: FtTextReader;
+    if (typeof textReaderOrText === 'string') {
+      // String input - create StringReader
+      textReader = new FtStringReader(textReaderOrText);
+    } else {
+      textReader = textReaderOrText;
+    }
+    super.open(textReader, immediatelyReadHeader);
+  }
+}

package/src/api/ft-serialization.ts

@@ -0,0 +1,216 @@
+import { FtFieldDefinitionList } from '../fields/definitions/ft-field-definition-list.js';
+import { FtFieldList } from '../fields/instances/ft-field-list.js';
+import { FtMeta } from '../meta/ft-meta.js';
+import { FtSequenceInvokationList } from '../sequences/core/ft-sequence-invokation-list.js';
+import { FtSequenceInvokation } from '../sequences/core/ft-sequence-invokation.js';
+import { FtSequenceList } from '../sequences/core/ft-sequence-list.js';
+import { FtSequence } from '../sequences/core/ft-sequence.js';
+import { FtTextWriter } from '../serialization/ft-text-writer.js';
+import { SerializationCore } from '../serialization/serialization-core.js';
+import { FtSubstitutionList } from '../substitutions/ft-substitution-list.js';
+import { FtFieldHeadingReadyEventArgs } from '../types/events/ft-field-heading-ready-event-args.js';
+import { FtFieldValueReadyEventArgs } from '../types/events/ft-field-value-ready-event-args.js';
+import { FtHeadingLineFinishedEventArgs } from '../types/events/ft-heading-line-finished-event-args.js';
+import { FtHeadingLineStartedEventArgs } from '../types/events/ft-heading-line-started-event-args.js';
+import { FtRecordFinishedEventArgs } from '../types/events/ft-record-finished-event-args.js';
+import { FtRecordStartedEventArgs } from '../types/events/ft-record-started-event-args.js';
+import { FtSequenceRedirectedEventArgs } from '../types/events/ft-sequence-redirected-event-args.js';
+import { FtReader } from './ft-reader.js';
+import { FtWriterSettings } from './ft-writer-settings.js';
+import { FtWriter } from './ft-writer.js';
+
+/**
+ * Exception thrown to abort serialization from an event handler.
+ * @public
+ */
+export class FtAbortSerializationException extends Error {
+  constructor(message?: string) {
+    super(message || 'Serialization aborted');
+    this.name = 'FtAbortSerializationException';
+  }
+}
+
+/**
+ * High-level API for event-driven serialization and deserialization of fielded text.
+ * Simplifies reading and writing by hooking into field and record events.
+ * @public
+ */
+export class FtSerialization {
+  static readonly VERSION_MAJOR = SerializationCore.VersionMajor;
+  static readonly VERSION_MINOR = SerializationCore.VersionMinor;
+  static readonly PREFIX_SPACE_CHAR = SerializationCore.PrefixSpaceChar;
+
+  // Event hooks
+  onFieldHeadingReadReady: ((args: FtFieldHeadingReadyEventArgs) => void) | undefined = undefined;
+  onFieldHeadingWriteReady: ((args: FtFieldHeadingReadyEventArgs) => void) | undefined = undefined;
+  onFieldValueReadReady: ((args: FtFieldValueReadyEventArgs) => void) | undefined = undefined;
+  onFieldValueWriteReady: ((args: FtFieldValueReadyEventArgs) => void) | undefined = undefined;
+  onHeadingLineStarted: ((args: FtHeadingLineStartedEventArgs) => void) | undefined = undefined;
+  onHeadingLineFinished: ((args: FtHeadingLineFinishedEventArgs) => void) | undefined = undefined;
+  onRecordStarted: ((args: FtRecordStartedEventArgs) => void) | undefined = undefined;
+  onRecordFinished: ((args: FtRecordFinishedEventArgs) => void) | undefined = undefined;
+  onSequenceRedirected: ((args: FtSequenceRedirectedEventArgs) => void) | undefined = undefined;
+
+  private _meta: FtMeta;
+  private _core: SerializationCore | undefined = undefined;
+
+  constructor(meta: FtMeta) {
+    this._meta = meta;
+  }
+
+  //  Proxied properties from core
+  get fieldDefinitionList(): FtFieldDefinitionList | undefined {
+    return this._core?.fieldDefinitionList;
+  }
+
+  get fieldList(): FtFieldList | undefined {
+    return this._core?.fieldList;
+  }
+
+  get substitutionList(): FtSubstitutionList | undefined {
+    return this._core?.substitutionList;
+  }
+
+  get sequenceList(): FtSequenceList | undefined {
+    return this._core?.sequenceList;
+  }
+
+  get sequenceInvokationList(): FtSequenceInvokationList | undefined {
+    return this._core?.sequenceInvokationList;
+  }
+
+  get rootSequence(): FtSequence | undefined {
+    return this._core?.rootSequence;
+  }
+
+  get rootFieldCount(): number {
+    return this._core?.rootFieldCount || 0;
+  }
+
+  get rootSequenceInvokation(): FtSequenceInvokation | undefined {
+    return this._core?.rootSequenceInvokation;
+  }
+
+  get recordCount(): number {
+    return this._core?.recordCount || 0;
+  }
+
+  get tableCount(): number {
+    return this._core?.tableCount || 0;
+  }
+
+  /**
+   * Read all records from a reader, invoking events for each field and record.
+   * @param reader - The reader to deserialize from
+   */
+  deserialize(reader: FtReader): void;
+
+  /**
+   * Read all records from text input, invoking events for each field and record.
+   * @param input - The text content to deserialize
+   */
+  deserialize(input: string): void;
+
+  deserialize(readerOrInput: FtReader | string): void {
+    const reader = typeof readerOrInput === 'string' ? new FtReader(this._meta, readerOrInput) : readerOrInput;
+
+    this.setCore(reader);
+
+    while (reader.read()) {
+      // Events are fired during read()
+    }
+  }
+
+  /**
+   * Write records until aborted by throwing FtAbortSerializationException from an event handler.
+   * @param writer - The writer to serialize to
+   */
+  serialize(writer: FtWriter): void;
+
+  /**
+   * Write records until aborted by throwing FtAbortSerializationException from an event handler.
+   * @param output - The TextWriter to serialize to
+   * @param settings - Optional writer settings
+   */
+  serialize(output: FtTextWriter, settings?: FtWriterSettings): void;
+
+  serialize(writerOrOutput: FtWriter | FtTextWriter, settings?: FtWriterSettings): void {
+    const writer = writerOrOutput instanceof FtWriter ? writerOrOutput : new FtWriter(this._meta, writerOrOutput, settings);
+
+    this.setCore(writer);
+
+    try {
+      while (true) {
+        writer.write();
+        // The only way out is to throw FtAbortSerializationException in an event handler
+      }
+    } catch (e) {
+      if (e instanceof FtAbortSerializationException) {
+        // Normal exit
+      } else {
+        throw e;
+      }
+    } finally {
+      writer.close();
+    }
+  }
+
+  private setCore(core: SerializationCore): void {
+    this._core = core;
+
+    // Wire up event handlers
+    core.onFieldHeadingReadReady = (args) => {
+      if (this.onFieldHeadingReadReady) {
+        this.onFieldHeadingReadReady(args);
+      }
+    };
+
+    core.onFieldHeadingWriteReady = (args) => {
+      if (this.onFieldHeadingWriteReady) {
+        this.onFieldHeadingWriteReady(args);
+      }
+    };
+
+    core.onFieldValueReadReady = (args) => {
+      if (this.onFieldValueReadReady) {
+        this.onFieldValueReadReady(args);
+      }
+    };
+
+    core.onFieldValueWriteReady = (args) => {
+      if (this.onFieldValueWriteReady) {
+        this.onFieldValueWriteReady(args);
+      }
+    };
+
+    core.onHeadingLineStarted = (args) => {
+      if (this.onHeadingLineStarted) {
+        this.onHeadingLineStarted(args);
+      }
+    };
+
+    core.onHeadingLineFinished = (args) => {
+      if (this.onHeadingLineFinished) {
+        this.onHeadingLineFinished(args);
+      }
+    };
+
+    core.onRecordStarted = (args) => {
+      if (this.onRecordStarted) {
+        this.onRecordStarted(args);
+      }
+    };
+
+    core.onRecordFinished = (args) => {
+      if (this.onRecordFinished) {
+        this.onRecordFinished(args);
+      }
+    };
+
+    core.onSequenceRedirected = (args) => {
+      if (this.onSequenceRedirected) {
+        this.onSequenceRedirected(args);
+      }
+    };
+  }
+}

package/src/api/ft-writer-settings.ts

@@ -0,0 +1,76 @@
+import { FtMetaSerializerOptions } from '../meta-serialization/format/meta-serializer-options.js';
+import { FtMetaReferenceType } from '../types/enums/ft-meta-reference-type.js';
+import { FtMetaSerializationFormat } from '../types/enums/ft-meta-serialization-format.js';
+
+/**
+ * Settings for writing fielded text streams.
+ * @public
+ */
+export interface FtWriterSettings {
+  /**
+   * Whether to write the |!Fielded Text^| declaration header.
+   */
+  declared?: boolean;
+
+  /**
+   * Type of meta reference to write.
+   */
+  metaReferenceType?: FtMetaReferenceType;
+
+  /**
+   * Meta reference (file path or URL).
+   */
+  metaReference?: string;
+
+  /**
+   * Format of embedded meta to write.
+   */
+  embeddedMetaFormat?: FtMetaSerializationFormat;
+
+  /**
+   * Whether to include explicit index attributes for fields in embedded meta.
+   */
+  embeddedMetaExplicitIndices?: boolean;
+
+  /**
+   * Whether to indent embedded XML metadata.
+   */
+  embeddedMetaIndent?: boolean;
+
+  /**
+   * Characters to use for indenting embedded XML metadata.
+   */
+  embeddedMetaIndentChars?: string;
+
+  /**
+   * Whether to write XML attributes on separate lines.
+   */
+  embeddedMetaNewLineOnAttributes?: boolean;
+}
+
+/** @public */
+export namespace FtWriterSettings {
+  export const DEFAULT_DECLARED = false;
+  export const DEFAULT_META_REFERENCE_TYPE = FtMetaReferenceType.None;
+  export const DEFAULT_META_REFERENCE = '';
+  export const DEFAULT_EMBEDDED_META_FORMAT = FtMetaSerializationFormat.XML;
+  export const DEFAULT_EMBEDDED_META_EXPLICIT_INDICES = FtMetaSerializerOptions.DEFAULT_EXPLICIT_INDICES;
+  export const DEFAULT_EMBEDDED_META_INDENT = FtMetaSerializerOptions.DEFAULT_INDENT;
+  export const DEFAULT_EMBEDDED_META_INDENT_CHARS = FtMetaSerializerOptions.DEFAULT_INDENT_CHARS;
+  export const DEFAULT_EMBEDDED_META_NEW_LINE_ON_ATTRIBUTES = FtMetaSerializerOptions.DEFAULT_NEW_LINE_ON_ATTRIBUTES;
+
+  export function loadMetaSerializerOptions(settings: FtWriterSettings, options: Partial<FtMetaSerializerOptions>): void {
+    if (options.explicitIndices !== undefined) {
+      settings.embeddedMetaExplicitIndices = options.explicitIndices;
+    }
+    if (options.indent !== undefined) {
+      settings.embeddedMetaIndent = options.indent;
+    }
+    if (options.indentChars !== undefined) {
+      settings.embeddedMetaIndentChars = options.indentChars;
+    }
+    if (options.newLineOnAttributes !== undefined) {
+      settings.embeddedMetaNewLineOnAttributes = options.newLineOnAttributes;
+    }
+  }
+}

package/src/api/ft-writer.ts

@@ -0,0 +1,26 @@
+import { FtMeta } from '../meta/ft-meta.js';
+import { FtSerializationWriter } from '../serialization/ft-serialization-writer.js';
+import { FtTextWriter } from '../serialization/ft-text-writer.js';
+import { FtWriterSettings } from './ft-writer-settings.js';
+
+/**
+ * High-level writer for fielded text files.
+ * Provides a convenient API for writing CSV and other delimited/fixed-width text.
+ * This is a thin wrapper around SerializationWriter with simpler constructors.
+ * @public
+ */
+export class FtWriter extends FtSerializationWriter {
+  /**
+   * Create a writer with metadata and output writer.
+   * @param meta - The metadata defining the file structure
+   * @param textWriter - The FtTextWriter to write to. If not provided, FtWriter will be created but not opened (you must call open() before writing).
+   * @param settings - Optional writer settings
+   */
+  constructor(meta: FtMeta, textWriter?: FtTextWriter, settings?: FtWriterSettings) {
+    super(meta);
+
+    if (textWriter) {
+      this.open(textWriter, settings);
+    }
+  }
+}

package/src/factory/ft-field-factory.ts

@@ -0,0 +1,94 @@
+import { FtBooleanFieldDefinition } from '../fields/definitions/ft-boolean-field-definition.js';
+import { FtDateTimeFieldDefinition } from '../fields/definitions/ft-date-time-field-definition.js';
+import { FtDecimalFieldDefinition } from '../fields/definitions/ft-decimal-field-definition.js';
+import { FtFieldDefinition } from '../fields/definitions/ft-field-definition.js';
+import { FtFloatFieldDefinition } from '../fields/definitions/ft-float-field-definition.js';
+import { FtIntegerFieldDefinition } from '../fields/definitions/ft-integer-field-definition.js';
+import { FtStringFieldDefinition } from '../fields/definitions/ft-string-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';
+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 { FtBooleanMetaField } from '../meta/fields/ft-boolean-meta-field.js';
+import { FtDateTimeMetaField } from '../meta/fields/ft-date-time-meta-field.js';
+import { FtDecimalMetaField } from '../meta/fields/ft-decimal-meta-field.js';
+import { FtFloatMetaField } from '../meta/fields/ft-float-meta-field.js';
+import { FtIntegerMetaField } from '../meta/fields/ft-integer-meta-field.js';
+import type { FtMetaField } from '../meta/fields/ft-meta-field.js';
+import { FtStringMetaField } from '../meta/fields/ft-string-meta-field.js';
+import { FtSequenceInvokation } from '../sequences/core/ft-sequence-invokation.js';
+import { FtSequenceItem } from '../sequences/core/ft-sequence-item.js';
+import { FtDataType } from '../types/enums/ft-data-type.js';
+import { FtUnreachableCaseError } from '../types/errors/ft-internal-error.js';
+
+/**
+ * Factory for creating field instances based on their definitions.
+ * @public
+ */
+export class FtFieldFactory {
+  static createFieldDefinition(dataType: FtDataType, index: number): FtFieldDefinition {
+    switch (dataType) {
+      case FtDataType.String:
+        return new FtStringFieldDefinition(index);
+      case FtDataType.Boolean:
+        return new FtBooleanFieldDefinition(index);
+      case FtDataType.Integer:
+        return new FtIntegerFieldDefinition(index);
+      case FtDataType.Float:
+        return new FtFloatFieldDefinition(index);
+      case FtDataType.Decimal:
+        return new FtDecimalFieldDefinition(index);
+      case FtDataType.DateTime:
+        return new FtDateTimeFieldDefinition(index);
+      default:
+        throw new FtUnreachableCaseError('FFCFD34499', dataType);
+    }
+  }
+
+  static createField(sequenceInvokation: FtSequenceInvokation, sequenceItem: FtSequenceItem): FtField {
+    const definition = sequenceItem.fieldDefinition;
+    if (!definition) {
+      throw new Error('SequenceItem must have a field definition');
+    }
+
+    // Create field based on data type
+    switch (definition.dataType) {
+      case FtDataType.String:
+        return new FtStringField(sequenceInvokation, sequenceItem, definition as FtStringFieldDefinition);
+      case FtDataType.Boolean:
+        return new FtBooleanField(sequenceInvokation, sequenceItem, definition as FtBooleanFieldDefinition);
+      case FtDataType.Integer:
+        return new FtIntegerField(sequenceInvokation, sequenceItem, definition as FtIntegerFieldDefinition);
+      case FtDataType.Float:
+        return new FtFloatField(sequenceInvokation, sequenceItem, definition as FtFloatFieldDefinition);
+      case FtDataType.Decimal:
+        return new FtDecimalField(sequenceInvokation, sequenceItem, definition as FtDecimalFieldDefinition);
+      case FtDataType.DateTime:
+        return new FtDateTimeField(sequenceInvokation, sequenceItem, definition as FtDateTimeFieldDefinition);
+      default:
+        throw new FtUnreachableCaseError('FFCFD34499', definition.dataType);
+    }
+  }
+
+  static createMetaField(dataType: FtDataType, headingCount: number): FtMetaField {
+    switch (dataType) {
+      case FtDataType.String:
+        return new FtStringMetaField(headingCount);
+      case FtDataType.Boolean:
+        return new FtBooleanMetaField(headingCount);
+      case FtDataType.Integer:
+        return new FtIntegerMetaField(headingCount);
+      case FtDataType.Float:
+        return new FtFloatMetaField(headingCount);
+      case FtDataType.Decimal:
+        return new FtDecimalMetaField(headingCount);
+      case FtDataType.DateTime:
+        return new FtDateTimeMetaField(headingCount);
+      default:
+        throw new FtUnreachableCaseError('FFCMF34499', dataType);
+    }
+  }
+}

package/src/factory/ft-meta-constructor.ts

@@ -0,0 +1,16 @@
+import { FtMeta } from '../meta/ft-meta.js';
+
+/**
+ * Base constructor class for creating FtMeta instances.
+ * Can be extended to provide custom meta creation logic.
+ * @public
+ */
+export class FtMetaConstructor {
+  /**
+   * Create a new FtMeta instance.
+   * Override this method in derived classes to provide custom initialization.
+   */
+  createMeta(): FtMeta {
+    return new FtMeta();
+  }
+}

package/src/factory/ft-meta-factory.ts

@@ -0,0 +1,34 @@
+import { FtMeta } from '../meta/ft-meta.js';
+import { FtMetaConstructor } from './ft-meta-constructor.js';
+
+/**
+ * Factory for creating FtMeta instances.
+ * Provides a global constructor that can be replaced to customize meta creation.
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+export class FtMetaFactory {
+  private static _constructor: FtMetaConstructor = new FtMetaConstructor();
+
+  /**
+   * Get the current meta constructor.
+   */
+  static getConstructor(): FtMetaConstructor {
+    return FtMetaFactory._constructor;
+  }
+
+  /**
+   * Set a custom meta constructor.
+   * Use this to provide custom initialization logic for all meta instances.
+   */
+  static setConstructor(value: FtMetaConstructor): void {
+    FtMetaFactory._constructor = value;
+  }
+
+  /**
+   * Create a new FtMeta instance using the current constructor.
+   */
+  static createMeta(): FtMeta {
+    return FtMetaFactory._constructor.createMeta();
+  }
+}

package/src/factory/ft-sequence-constructor.ts

@@ -0,0 +1,11 @@
+import { FtSequence } from '../sequences/core/ft-sequence.js';
+
+/**
+ * Constructor for creating sequence instances.
+ * @public
+ */
+export class FtSequenceConstructor {
+  createSequence(index: number): FtSequence {
+    return new FtSequence(index);
+  }
+}

package/src/factory/ft-sequence-factory.ts

@@ -0,0 +1,22 @@
+import { FtSequence } from '../sequences/core/ft-sequence.js';
+import { FtSequenceConstructor } from './ft-sequence-constructor.js';
+
+/**
+ * Factory for creating sequences.
+ * @public
+ */
+export class FtSequenceFactory {
+  private static _constructor: FtSequenceConstructor = new FtSequenceConstructor();
+
+  static getConstructor(): FtSequenceConstructor {
+    return FtSequenceFactory._constructor;
+  }
+
+  static setConstructor(value: FtSequenceConstructor): void {
+    FtSequenceFactory._constructor = value;
+  }
+
+  static createSequence(index: number): FtSequence {
+    return FtSequenceFactory._constructor.createSequence(index);
+  }
+}

package/src/factory/ft-sequence-item-constructor.ts

@@ -0,0 +1,11 @@
+import { FtSequenceItem } from '../sequences/core/ft-sequence-item.js';
+
+/**
+ * Constructor for creating sequence item instances.
+ * @public
+ */
+export class FtSequenceItemConstructor {
+  createSequenceItem(index: number): FtSequenceItem {
+    return new FtSequenceItem(index);
+  }
+}

package/src/factory/ft-sequence-item-factory.ts

@@ -0,0 +1,22 @@
+import { FtSequenceItem } from '../sequences/core/ft-sequence-item.js';
+import { FtSequenceItemConstructor } from './ft-sequence-item-constructor.js';
+
+/**
+ * Factory for creating sequence items.
+ * @public
+ */
+export class FtSequenceItemFactory {
+  private static _constructor: FtSequenceItemConstructor = new FtSequenceItemConstructor();
+
+  static getConstructor(): FtSequenceItemConstructor {
+    return FtSequenceItemFactory._constructor;
+  }
+
+  static setConstructor(value: FtSequenceItemConstructor): void {
+    FtSequenceItemFactory._constructor = value;
+  }
+
+  static createSequenceItem(index: number): FtSequenceItem {
+    return FtSequenceItemFactory._constructor.createSequenceItem(index);
+  }
+}

package/src/factory/ft-sequence-redirect-constructor.ts

@@ -0,0 +1,19 @@
+import { FtSequenceRedirect } from '../sequences/redirects/ft-sequence-redirect.js';
+import { FtSequenceRedirectType } from '../types/enums/ft-sequence-redirect-type.js';
+
+/**
+ * Abstract base class for sequence redirect constructors.
+ * @public
+ */
+export abstract class FtSequenceRedirectConstructor {
+  get sequenceRedirectType(): FtSequenceRedirectType {
+    return this.getSequenceRedirectType();
+  }
+
+  get sequenceRedirectTypeName(): string {
+    return this.sequenceRedirectType;
+  }
+
+  abstract createSequenceRedirect(index: number): FtSequenceRedirect;
+  protected abstract getSequenceRedirectType(): FtSequenceRedirectType;
+}