textcontrol-promises

@sinc-gmbh/textcontrol-promises wraps the TX TextControl callback-based JavaScript API into a modern Promise + async-iterator API with full TypeScript type definitions.

Architecture

┌─────────────────────────────────────────────────────┐
│  Consumer App                                        │
│  import { TextControlContext } from                  │
│    "@sinc-gmbh/textcontrol-promises"                 │
└────────────────────┬────────────────────────────────┘
                     │  async/await, typed
┌────────────────────▼────────────────────────────────┐
│  lib/  (@sinc-gmbh/textcontrol-promises)             │
│  TextControlContext → generated base + hand-written  │
│  Collection (async-iterable)                         │
│  lib/types/  (TypeScript declarations)               │
└────────────────────┬────────────────────────────────┘
                     │  callbacks
┌────────────────────▼────────────────────────────────┐
│  TX TextControl SDK                                  │
│  Loaded at runtime via WebSocket                     │
│  window.TXTextControl (vendor, untyped)              │
└─────────────────────────────────────────────────────┘

Installation

yarn add @sinc-gmbh/textcontrol-promises
# or
npm install @sinc-gmbh/textcontrol-promises

TypeScript — global type setup

Create types/global.d.ts in your project:

import { TXTextControlTypeDefinition } from "@sinc-gmbh/textcontrol-promises";
declare global {
    var TXTextControl: typeof TXTextControlTypeDefinition;
}

JSDoc — type import in plain JS

/** @import {TXTextControlTypeDefinition as TXTextControl} from "@sinc-gmbh/textcontrol-promises" */

Code examples

Initialize the editor

import { TextControlContext } from "@sinc-gmbh/textcontrol-promises";

const txContext = new TextControlContext();

await txContext.initialize(
    {
        containerID: "editor",
        webSocketURL: websocketUrl,
        editorSettings: { culture: "de-DE", uiCulture: "de-DE" },
        replaceContainer: true,
    },
    resourceUrl  // points to /GetResource?name=tx-document-editor.min.js
);

await txContext.untilTextControlLoaded();  // resolves when TextControlLoaded fires

Async iterator over a collection

for await (const field of txContext.editableRegions) {
    const user = await field.userName;   // cached getter — one API call max
    console.log(user);
}

Property caching — read and write

Hand-written wrapper classes expose JS getter properties so you can await obj.name instead of await obj.getName(). The value is fetched lazily and cached for the lifetime of the object.

const field = /* a TextField instance */;

// First access calls the TX API; subsequent reads return the cached Promise.
const name = await field.name;

// Setter updates the TX API and pre-populates the cache optimistically.
await field.setName('NewFieldName');
const updated = await field.name;  // returns 'NewFieldName' without a second API call

The underlying getName() / setName() methods from the generated base remain available if you prefer explicit calls.

Wrap a native TX object

import { Table } from "@sinc-gmbh/textcontrol-promises";

const table = new Table(txNativeTableObject);
const rows = await table.rows.count();

Repository structure

textcontrol-promises/
├── lib/
│   ├── src/
│   │   ├── TextControlContext.js       hand-written public class
│   │   ├── generated/                  auto-generated Promise-wrapping base classes
│   │   ├── Collection.js               async-iterable base for TX collections
│   │   ├── ApplicationField.js         hand-written wrapper classes (one per TX obj)
│   │   └── helper/                     RequestHelper, waitUntil, CallbackType, …
│   ├── types/
│   │   ├── TXTextControlTypeDefinition.d.ts   main barrel export
│   │   ├── objects/                    one .d.ts per TX API class
│   │   ├── args/                       EventArgs shapes
│   │   ├── enums/                      TX enum constants
│   │   ├── callbacks/                  callback signature types
│   │   └── helper/                     EventMap, TabNameType
│   ├── index.js
│   └── index.d.ts
├── tools/
│   ├── scraper/                        Playwright BFS crawler + d.ts differ/patcher
│   └── generator/                      ts-morph Promise-wrapper code generator
├── tests/
│   ├── AGENT_PROFILE.md
│   ├── testsets/
│   └── testcases/
└── demo/                               local integration test app

Development tooling

| Tool | Purpose | Docs | |---|---|---| | tools/scraper | Scrape TX docs, diff against d.ts, patch stubs | Scraper wiki | | tools/generator | Generate Promise-wrapper base classes from d.ts | Generator wiki |

See also:

• Architecture
• Type System
• Maintenance Workflow
• Testing

Generated API docs

https://sinc-gmbh.github.io/textcontrol-promises

License

Copyright (c) 2023 SINC GmbH. All rights reserved. Licensed under the MIT license.