User/bna/2024 01 (#5)

* feat: async reverse iterator for collection (#93247)

* fix: add comments and format

* feat: update tx types definition

* feat: add init and awaiter functions (#96187)

* build: update versionnumber
chore: update yarn, include tx types
feat: add jsdoc

* fix: jsdoc with better-docs and no type error

* fix: docs path

* feat: add waitUntil with retryCount

* fix: make resource path configurable

---------

Co-authored-by: Björn Nast <bjoern.nast@sinc.de>

.devcontainer/devcontainer.json

@@ -0,0 +1,34 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/javascript-node
+{
+
+	"name": "Node.js",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/javascript-node:1-20-bullseye",
+	"runArgs": ["--name", "TX_PROMISES_devcontainer"],
+	"features": {
+		"ghcr.io/devcontainers/features/git:1": {}
+	},
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"ritwickdey.LiveServer"
+			]
+		}
+	}
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "yarn install",
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.yarnrc.yml

@@ -0,0 +1,3 @@
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-4.0.2.cjs

jsdoc.conf.json

@@ -0,0 +1,28 @@
+{
+    "plugins": [
+        "node_modules/better-docs/typescript"
+    ],
+    "recurseDepth": 10,
+    "source": {
+        "include": [
+            "src"
+        ],
+        "includePattern": ".+\\.(js|ts)$"
+    },
+    "sourceType": "module",
+    "tags": {
+        "allowUnknownTags": true,
+        "dictionaries": [
+            "jsdoc",
+            "closure"
+        ]
+    },
+    "templates": {
+        "cleverLinks": false,
+        "monospaceLinks": false
+    },
+    "opts": {
+        "destination": "./docs/",
+        "template": "node_modules/better-docs"
+    }
+}

package.json

@@ -1,12 +1,15 @@
 {
   "name": "@sinc-gmbh/textcontrol-promises",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
-    "dts": "npm-dts generate"
+    "dts": "npm-dts generate -L debug",
+    "jsdocumentation": "jsdoc -c jsdoc.conf.json"
   },
   "devDependencies": {
+    "better-docs": "^2.7.3",
+    "jsdoc": "^4.0.2",
     "npm-dts": "^1.3.12",
     "typescript": "^5.0.4"
   },
@@ -15,5 +18,6 @@
   "description": "Wraps TXTextControl Callback API to work with Objects and Promises.",
   "publishConfig": {
     "@sinc-gmbh:registry": "https://npm.pkg.github.com"
-  }
+  },
+  "packageManager": "yarn@4.0.2"
 }

src/ApplicationField.js

@@ -7,6 +7,10 @@ export class ApplicationField {
 
     /** @type {string=} */
     #name;
+    /** 
+     *  @property name
+     *  @type {string=} 
+     */
     get name() { return this.#name; }
 
     /** @type {string=} */
@@ -52,6 +56,8 @@ export class ApplicationField {
 
     /**
      * Sets the name of a text field
+     * @public
+     * @method
      * @param {string} name
      * @returns {Promise<void>}
      */
@@ -65,6 +71,7 @@ export class ApplicationField {
 
     /**
      * Sets the field's parameters
+     * @public
      * @param {Array<string>} parameters
      * @returns {Promise<void>}
      */

src/Collection.js

@@ -12,13 +12,13 @@ export class Collection {
     */
     _txCollection;
 
-    /** @type {(txItem:T)=>T} */
+    /** @type {function(T):T} */
     #wrapItem;
 
     /**
      * Wrapper für TXTextControl.Collection
      * @param {any} txCollection 
-     * @param {(txItem:T)=>T} wrapItem
+     * @param {function(T):T} wrapItem
      */
     constructor(txCollection, wrapItem) {
         this._txCollection = txCollection;
@@ -43,10 +43,23 @@ export class Collection {
         }
     }
 
+    /**
+     * iterates the collection in reverse  
+     * use in for await 
+     * @returns {AsyncGenerator<Awaited<T>, void, unknown>}
+     */
+    async *reverse() {
+        var count = await this.getCount() - 1;
+        for (let i = count; i > -1; i++) {
+            let value = await this.elementAt(i);
+            yield value;
+        }
+    }
+
     /**
      * Executes a callback function for each element
      * @public
-     * @param {( item: T, index: number, itemCount: number ) => void} forEachCallback 
+     * @param {function(T, number, number ):void} forEachCallback 
      * @returns {Promise<void>}
      * @deprecated may use "for await" instead forEachCallback
      */

src/TextControlContext.js

@@ -1,39 +1,39 @@
 import { SubTextPartCollection } from "./SubTextPartCollection";
 import { Selection } from "./Selection";
 import { TableCollection } from "./TableCollection";
-import { CallbackType, RequestHelper } from "./helper/module";
+import { CallbackType, RequestHelper, waitUntil } from "./helper/module";
 import { ApplicationFieldCollection } from "./ApplicationFieldCollection";
 import { FormFieldCollection } from "./FormFieldCollection";
 import { EditableRegionCollection } from "./EditableRegionCollection";
 import { InputPosition } from "./InputPosition";
 
+/** @class */
 export class TextControlContext {
+    /**
+     * indicates if TXTextControl is ready
+     * @type {boolean}
+     */
+    #isTextControlLoaded = false;
+
     /** @type {Selection} */
-    // @ts-ignore
     get selection() { return new Selection(TXTextControl.selection); }
 
     /** @type {TableCollection} */
-    // @ts-ignore
     get tables() { return new TableCollection(TXTextControl.tables); }
 
     /** @type {SubTextPartCollection} */
-    // @ts-ignore
     get subTextParts() { return new SubTextPartCollection(TXTextControl.subTextParts); }
 
     /** @type {ApplicationFieldCollection} */
-    // @ts-ignore
     get applicationFields() { return new ApplicationFieldCollection(TXTextControl.applicationFields); }
 
     /** @type {FormFieldCollection} */
-    // @ts-ignore
     get formFields() { return new FormFieldCollection(TXTextControl.formFields); }
 
     /** @type {EditableRegionCollection} */
-    // @ts-ignore
     get editableRegions() { return new EditableRegionCollection(TXTextControl.editableRegions); }
- 
+
     /** @type {InputPosition} */
-    // @ts-ignore
     get inputPosition() { return new InputPosition(TXTextControl.inputPosition); }
 
     //#region functions
@@ -45,7 +45,6 @@ export class TextControlContext {
      * @returns {Promise<any>} LoadDocumentCallbackData
      */
     async load(streamType, base64Data, loadSettings) {
-        // @ts-ignore
         return RequestHelper.Promise(TXTextControl.load,
             streamType,
             base64Data,
@@ -61,7 +60,6 @@ export class TextControlContext {
      * @returns {Promise<any>} SaveDocumentResult
      */
     async save(streamType, saveSettings) {
-        // @ts-ignore
         return RequestHelper.Promise(TXTextControl.save,
             streamType,
             CallbackType.SaveDocumentResultCallback,
@@ -75,13 +73,63 @@ export class TextControlContext {
      * @param {any} textFieldPosition: TextFieldPosition
      * @returns {Promise<void>}
      */
-    async setInputPositionByTextPosition(textPosition, textFieldPosition){
-         // @ts-ignore
+    async setInputPositionByTextPosition(textPosition, textFieldPosition) {
         return RequestHelper.Promise(TXTextControl.setInputPositionByTextPosition,
-            textPosition, 
-            textFieldPosition, 
-            CallbackType.EmptyRequestCallback, 
+            textPosition,
+            textFieldPosition,
+            CallbackType.EmptyRequestCallback,
+            CallbackType.ErrorCallback);
+    }
+
+    /**
+     * Sets the component render mode.
+     * @param {TXTextControl.ComponentRenderMode} value
+     */
+    async setRenderMode(value) {
+        return RequestHelper.Promise(TXTextControl.setRenderMode,
+            value,
+            CallbackType.EmptyRequestCallback,
             CallbackType.ErrorCallback);
     }
+
+    /**
+     * Initializes the document editor
+     * @param {TXTextControl.ComponentSettings} componentSettings
+     * @param {string} [jsResourceFilePath="/GetResource?name=tx-document-editor.min.js"] 
+     * @returns {Promise<void>}
+     */
+    async init(componentSettings, jsResourceFilePath="/GetResource?name=tx-document-editor.min.js") {
+        return new Promise(async (resolve, reject) => {
+            if (this.#isTextControlLoaded) resolve();
+
+            let txDocumentEditorResourceUrl = new URL(jsResourceFilePath, componentSettings.webSocketURL);
+
+            //load tx resource and await global object to be defined
+            var script = document.createElement('script');
+            script.setAttribute('src', txDocumentEditorResourceUrl.href);
+            document.head.appendChild(script);
+            await this.#txTextControlNotUndefined();
+            //init document editor
+            TXTextControl.addEventListener('textControlLoaded', () => {
+                this.#isTextControlLoaded = true;
+                resolve();
+            });
+            TXTextControl.init(componentSettings);
+        });
+    }
+
+    /**
+     * waits until TXTextControlLoaded
+     * @returns {Promise<void>}
+     */
+    async isReady() {
+        return waitUntil(() => this.#isTextControlLoaded, 20);
+    }
+    //#endregion
+
+    //#region private functions
+    async #txTextControlNotUndefined() {
+        return waitUntil(() => "TXTextControl" in window, 20);
+    }
     //#endregion
 }

src/helper/module.js

@@ -1,3 +1,4 @@
 export { CallbackType } from './CallbackType';
 export { CallbackHelper } from './CallbackHelper';
 export { RequestHelper } from './RequestHelper';
+export { timeout, waitUntil } from './timeout';

src/helper/timeout.js

@@ -0,0 +1,30 @@
+/**
+* waits a certain amount if milliseconds until promise is resolved
+* @param {number} ms 
+* @returns {Promise<void>}
+*/
+export async function timeout(ms) {
+    return new Promise((resolve, reject) => {
+        setTimeout(resolve, ms);
+    });
+}
+
+/**
+ * waits in 500ms intervals until condition is true or retryCount is reached.
+ * @param {function():boolean} condition 
+ * @param {number} [retryCount=-1] set this to prevent infinit loop worst case
+ * @param {number} [ms=500] time in milliseconds to wait in each intervall
+ * @returns {Promise<void>}
+ */
+export async function waitUntil(condition, retryCount=-1, ms=500){
+    return new Promise(async (resolve,reject)=>{
+        while(!condition){
+            if(retryCount == 0) reject();
+            else {
+                await timeout(ms);
+                if(retryCount > 0) retryCount--;
+            }
+        }
+        resolve();
+    });
+}

tsconfig.json

@@ -1,7 +1,10 @@
 {
-  "include": ["**/*.js"],
+  "include": [
+    "**/*.js",
+    "**/*.d.ts"
+  ],
   "compilerOptions": {
-    "module": "ES6",
+    "module": "NodeNext",
     "target": "ESNext",
     "moduleResolution": "nodenext",
     "strict": true,
@@ -10,6 +13,7 @@
     "emitDeclarationOnly": true,
     "allowJs": true,
     "checkJs": true,
-    "removeComments": true
+    "removeComments": true,
+    "types": []
   }
-}
+}