# tb-harmony-modern-ts

This repository is a project template that allows you to code in modern TypeScript for ToonBoom Harmony.

## Example script

```ts
function* recursiveIterNodes(n: string): Generator<string> {
  yield n;
  if (node.isGroup(n)) {
    for (let i = 0; i < node.numberOfSubNodes(n); i++) {
      yield* recursiveIterNodes(node.subNode(n, i));
    }
  }
}

function main() {
  const nodes = Array.from(recursiveIterNodes(node.root()));

  for (const node of nodes) {
    console.log(node);
  }
}

main();
```

## Why

You can script in two ways for ToonBoom Harmony: either with [Python](https://docs.toonboom.com/help/harmony-24/scripting/pythonmodule/index.html) or [QtScript](https://docs.toonboom.com/help/harmony-24/scripting/script/index.html) (JavaScript).

[QtScript](https://doc.qt.io/archives/qt-5.15/qtscript-index.html) (scripting engine part of the Qt framework) is an old JavaScript dialect that is based on the [ECMAScript 3.0 standard](https://www-archive.mozilla.org/js/language/e262-3.pdf), therefore it lacks features like modules, modern syntax, arrow functions, etc...

Today we have [TypeScript](https://www.typescriptlang.org/) which is a superset of JavaScript with syntax for types, ES modules, async/await and more but how can we use those?

## How

### TypeScript and type definitions

We can code in TypeScript but in order to use Harmony's QtScript API, we need type definitions (`.d.ts` files describing the types).

Luckily for us, Bryan Fordney made scripts to generate them: [tba-types](https://github.com/bryab/tba-types) (Typescript definitions for Toon Boom Harmony and Storyboard Pro)

### Modules and imports

In Harmony's QtScript you can import code from another file in two ways:

#### `include`

```js
include("module.js");
```

Which include the whole script into the current one, therefore polluting the current namespace.

#### `exports`

```js
// function.js
exports.test = function test() {
  MessageLog.trace("test");
};
```

```js
// main.js
var module = require("./function.js");
module.test();
```

Which is a [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) "like" custom implementation from ToonBoom without the same semantics. It's also used to define [ToonBoom packages](https://docs.toonboom.com/help/harmony-24/scripting/extended/index.html#create_package) by exporting a `configure` function from a `configure.js` file.

-> In today's modern JavaScript, the official standard package format is [ECMAScript modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) (or ESM/ES6 modules) with `import`/`export`.