better docs, ide-tool-utils as ts, es6 and es5

jsteuer

2020-02-05 17ae81f04074ad5b2fdbb21f221e33e69b425e53

better docs, ide-tool-utils as ts, es6 and es5

 .gitignore

@@ -1,4 +1,6 @@
docs/
node_modules/
.nyc_output/
coverage/
coverage/
.cache/
dist/

 CHANGELOG.md

@@ -2,13 +2,19 @@
Änderungen der API werden hier dokumentiert.


## [Unreleased]
## [3.0.0] - 2020-02-05
### Added
-   Dokumentation zu einem Werkzeug kann nun über die Werkzeug-Deklaration verlinkt werden
### Changed
-   `./dist/es6/`   Ausgabeverzeichnis: Hilfsfunktionen als ES6 JavaScript Dateien zur
                    Verwendung in Kombination mit einem Build-System oder modernem Browser.
-   `./dist/lib/`   Ausgabeverzeichnis: Hilfsfunktionen als Standalone ES5 Bibliothek 
                    zur direkten Verwendung als lokale Kopie
### Fixed
-   Beim Einbinden dieses npm Pakets stehen Typdefinitionen automatisch in der verwendeten
    Entwicklungsumgebung zur Verfügung
### Removed

-   `mathcoach-api.d.ts` entfällt. `./src/MathCoach.ts` spezifiziert nun die öffentliche 
    MathCoach IDE API. 

## [2.0.1] - 2019-12-21 
### Fixed

 README.md

@@ -1,5 +1,5 @@

# MathCoach IDE API <small>`Version 2.0.1`</small>
# MathCoach IDE API <small>`Version 3.0.0`</small>

In diesem Paket ([Das Gitblit Repository findet sich hier](https://newton.htwsaar.de/gitblit/summary/mathcoach!mathcoach-ide-api.git)) 
ist die öffentliche Schnittstelle zur MathCoach Entwicklungsumgebung (IDE) definiert. Mithilfe 
@@ -16,12 +16,12 @@
## Idee 
Grundlegende Idee ist, dass ein externes Werkzeug nahtlos in die MathCoach IDE integriert werden 
kann. Bestimmte Dateien werden anhand ihrer Dateiendung mit dem Werkzeug verknüpft, sodass der
Benutzer das passende Werkzeug durch einen einfache Klick im Dateie-Explorer starten kann. Diese 
Datei wird im folgenden Kontext-Datei genannt und soll dazu dienen das interene Datenmodell (also
Benutzer das passende Werkzeug durch einen einfache Klick im Datei-Explorer starten kann. Diese 
Datei wird im folgenden *Kontext-Datei* genannt und soll dazu dienen, das interene Datenmodell (also
alle Informationen, die der Benutzer im Werkzeug angibt) zu speichern. Das Werkzeug soll das gespeicherte 
Datenmodell zu einem späteren Zeitpunkt wieder laden können.

Ein Werkzeug kann beispielsweise MathCoach-Aufgabe (Groovy-Datei) generieren. Weitere Funktionalitäten
Ein Werkzeug kann beispielsweise MathCoach-Aufgaben (Groovy-Datei) generieren. Weitere Funktionalitäten
der IDE - beispielsweise das Starten der generierten Aufgabe in der Aufgaben-Vorschau der IDE - sind 
ebenfalls für den Werkzeugentwickler verfügbar.

@@ -40,7 +40,7 @@
auf `HTML`, `JavaScript` und `CSS` gesetzt werden. Außerdem muss das Werkzeug unter 
der Domain des jeweiligen MathCoach-Servers erreichbar sein. Zur Entwicklungszeit legt man das Werkzeug 
dazu im www-Verzeichnis ab. Die von der IDE bereitgestellte `ide-lib.js` Bibliothek 
muss eingebunden werden. 
muss eingebunden werden.

    <script src="/mathcoach/ui/ide/ide-lib.js"/> 

@@ -94,7 +94,7 @@
-   Sich initialisieren. Es ist sinnvoll, dass das Werkzeug mit einem beispielhaften
    Datenmodell inititalisiert wird.
-   Das interne Datenmodell in die Kontext-Datei schreiben 
-   Die zugehörige Aufgabe generieren. Siehe auch `contextFileToExerciseFile` weiter unten.
-   Die zugehörige Aufgabe generieren. Siehe auch `contextFileToExerciseFile` in der [Dokumentation der Hilfsfunktionen](./modules/helpers.html).

Andernfalls kann das zuvor gespeichertes Datenmodell aus der Kontext-Datei in den 
Editor geladen werden. Anschließend sollte die generierten Aufgaben in der Vorschau gestartet werden, sodass der 
@@ -130,32 +130,73 @@

  

### Hilfsunktionen für Werkzeug-Entwickler
### Hilfsunktionen für Werkzeug-Entwickler (IDE-Tool-Utils)

[Dokumentation der Hilfsfunktionen](./modules/helpers.html)

Dieses Paket beinhaltet zusätzlich Hilfsfunktionen für Werkzeug-Entwickler. Diese sind aktuell
in `TypeScript` implementiert und können bei Bedarf auch zukünftig als ES6-JavaScript 
bereitgestellt werden. Zum Einbinden der Funktionen wird demzufolge ein Build-System 
vorausgesetzt. Keine der Hilfsfunktionen wird durch die `ide-lib.js` ausgeliefert!

Beispielsweise werden diese wie folgt eingebunden und genutzt:

    import { Helpers } from "@mathcoach/ide-api";
    Helpers.enableOfflineUsageIfNecessary()
 
Dieses Paket beinhaltet zusätzlich Hilfsfunktionen (auch IDE-Tool-Utils genannt) für 
Werkzeug-Entwickler. Diese sind aktuell in `TypeScript` implementiert, liegen jedoch 
auch als ES6-JavaScript und Standalone-Bibliothek zur direkten Verwendung vor. Keine der 
Hilfsfunktionen wird durch die `ide-lib.js` ausgeliefert!

> **Hinweis**: Hilfunktionen ohne Build-System bereitzustellen gestaltet sich schwierig und
> bringt große Nachteile mit sich:
> - Als reine JavaScript-Datei - platziert auf einem Server - ist die die 
>   Offline-Fähigkeit (siehe `Helpers.enableOfflineUsageIfNecessary()`) von Werkzeugen nicht 
>   gewährleistet. 
>   gewährleistet, da eine Internetverbindung zum Zugriff notwendig ist.
> - Werden Dateien oder Code-Ausschnitte von Hand kopiert, muss der Werkzeug-Entwickler sich
>   um das Aktualisieren kümmern. 
> 
> Ein möglicher Kompromiss wäre die Hilsfunktionen als reine JavaScript-Datei (ES5 oder ES6) 
> bereitzustellen und eine Kopie mit dem Werkezug auszuliefern. Der aktuelle Ansatz bettet 
> Hilfsfunktionen durch den Build-Prozess in das Werkzeug ein.
> Als Kompromiss werden die Hilsfunktionen als reine JavaScript-Datei (ES5 oder ES6) 
> bereitgestellt, sodass diese auch ohne TypeScript nutzbar sind.

Die IDE-Tool-Utils können wie folgt genutzt werden

#### Build-System mit TypeScript (empfohlen)

Das Paket `@mathcaoch/ide-api` muss als npm-Abhängikeit in der `package.json` des Werkzeugs
angegeben werden. Fortan können die in TypeScript implementierten Hilfsfunktionen - aber 
auch die Schnittstellen der IDE-API - komfortabel verwendet werden. Eine bestmögliche Typsicherheit ist 
gegeben.

    import { Helpers, MathCoach } from "@mathcoach/ide-api";
    Helpers.enableOfflineUsageIfNecessary()
    ...
    const file:MathCoach.File = await MC.ide.getContextFile()
 

#### Build-System ES6+ JavaScript

Das Paket `@mathcaoch/ide-api` muss als npm-Abhängikeit in der `package.json` des Werkzeugs
angegeben werden. Fortan können die in ES6 JavaScript vorliegenden Hilfsfunktionen 
verwendet werden. Die Entwicklungsumgebung sollte grundlegende Hilfen (Autovervollständigung und eingebettete Dokumentation) anbieten.

    import { Helpers } from "@mathcoach/ide-api/dist/es6"
    Helpers.enableOfflineUsageIfNecessary();
    ...
    const file = await MC.ide.getContextFile();
 

#### Standalone

Die Hilfsfunktionen liegen als eigenständige Bibliothek vor ( siehe 
`./dist/lib/mathcoach-ide-tool-utils.js`). Diese muss händisch kopiert, in das Werkzeug 
eingebunden und mit ihm ausgeliefert werden. Über die globale Variable `MC_IDE_TOOL_UTILS` 
können die Hilfsfunktionen angesprochen werden. Die verwendete Entwicklungsumgebung kann
in der Regel nur wenig Unterstütztung anbieten (siehe auch *Typdefinition auch ohne Build-System nutzen*).

    // tool.html
    <script src="/mathcoach/ui/ide/ide-lib.js"/> 
    <script src="mathcoach-ide-tool-utils.js"/> 
    <script src="tool.js"/> 

    // tool.js
    const { Helpers } = MC_IDE_TOOL_UTILS;
    Helpers.enableOfflineUsageIfNecessary();
    ...
    const file = await MC.ide.getContextFile();




### Beispiele
@@ -203,14 +244,14 @@
        ...
    }
 
Der Git-Repo URL kann man eine Versionsnummer anhängen (z.B. `".../mathcoach/mathcoach-ide-api.git#2.0.0"` 
für Version `2.0.0`), sodass die API falls notwendig versioniert [(Semantic Versioning)](https://semver.org/lang/de/) w
erden kann. 
Der Git-Repo URL kann man eine Versionsnummer anhängen (z.B. `".../mathcoach/mathcoach-ide-api.git#3.0.0"` 
für Version `3.0.0`), sodass die API, falls notwendig, versioniert [(Semantic Versioning)](https://semver.org/lang/de/) werden kann. Verfügbare Versionen sind Git-Tags und können in der Weboberfläche des Git-Repositories
oder über die Konsole (`git tag --list`) eingesehen werden. 

Nun können Hilfsfunktionen (in TypeScript) wie folgt eingebunden werden.  

    import { Helpers } from "@mathcoach/ide-api";
 

Die Typedefinition sollte automatisch verfügbar sein, sodass der Umgang mit der 
IDE API (Einstiegspunkt ist die globale Variable `MC`) durch eine Entwicklungsumgebung 
wie Visual Studio Code unterstützt wird. Falls nicht, muss man die Typdefinition händisch 
@@ -224,7 +265,7 @@
Kommentar (Triple-Slash Directive) an den Anfang der JavaScript-Datei platziert 
werden (`path` falls nötig anpassen): 

    /// <reference path="../node_modules/@mathcoach/ide-api/mathcoach-api.d.ts"/>
    /// <reference path="../node_modules/@mathcoach/ide-api/dist/es6/MathCoach.d.ts"/>

Dies sorgt dafür, dass Visual Studio Code Autovervollständigung samt Dokumentation der 
IDE API anbieten kann. Sollte es bei Verwendung von TypeScript notwendig sein, kann man eine

 examples/README.md

@@ -1,3 +1,3 @@
# Beispiele
-   `example-ide`: 
    Entwickeln eines externen Werkzeuges in der MathCoach-IDE 
-   `example-standalone`: 
    Entwickeln eines externen Werkzeuges in der MathCoach-IDE 

 examples/example-standalone/MyEditor/editor.html

File was renamed from examples/example-ide/MyEditor/editor.html
@@ -24,6 +24,12 @@
    </ul>

    <script src="/mathcoach/ui/ide/api/ide-lib.js"></script>
    <!-- 
        Falls gewünscht: "mathcoach-ide-tool-utils.js" aus "/dist/lib/"
        in dieses Verzeichnis kopieren und einbinden.

        <script src="mathcoach-ide-tool-utils.js"></script> 
    -->
    <script src="./editor.js"></script>
</body>
</html>

 examples/example-standalone/MyEditor/editor.js

File was renamed from examples/example-ide/MyEditor/editor.js
@@ -1,3 +1,9 @@

// // Falls mathcoach-ide-tool-utils.js eingebunden wurde
// const { Helpers } = MC_IDE_TOOL_UTILS;
// Helpers.enableOfflineUsageIfNecessary(); // Hilfsfunktion verwenden


(async function () {  
    const isReady = typeof MC !== "undefined" ? await MC.isReady() : false;
    if(!isReady){

 examples/example-standalone/README.md

 examples/example-standalone/code_completion.png

 package-lock.json

Diff too large

 package.json

@@ -1,39 +1,51 @@
{
  "name": "@mathcoach/ide-api",
  "version": "2.0.1",
  "version": "3.0.0",
  "description": "API zur MathCoach IDE",
  "main": "./src/index.ts",
  "types": "dist/es6/index.d.ts",
  "directories": {
    "example": "examples"
  },
  "devDependencies": {
    "ava": "^2.4.0",
    "nyc": "^14.1.1",
    "rimraf": "^3.0.0",
    "ts-node": "^8.5.4",
    "typedoc": "^0.15.5"
    "ava": "^3.2.0",
    "nyc": "^15.0.0",
    "parcel": "^1.12.4",
    "rimraf": "^3.0.1",
    "ts-node": "^8.6.2",
    "tsconfig-paths": "^3.9.0",
    "typedoc": "^0.16.9"
  },
  "scripts": {
    "clean": "rimraf dist/ && rimraf docs/",
    "test": "nyc ava",
    "build": "npm run clean  && npm run build-docs",
    "build-docs": "typedoc mathcoach-api.d.ts src/ --out docs/ --mode file --hideGenerator --theme minimal --includeDeclarations --excludeExternals --media ./media"
    "build": "npm run clean  && npm run build-docs && npm run build-utils-es6 && npm run build-utils-lib",
    "build-docs": "typedoc src/ --out docs/ --mode file --hideGenerator --theme minimal --includeDeclarations --excludeExternals --media ./media",
    "build-utils-es6": "npx tsc --project tsconfig-es6.json",
    "build-utils-lib": "parcel build src/index.ts --target node --bundle-node-modules --global MC_IDE_TOOL_UTILS --out-dir dist/lib --out-file mathcoach-ide-tool-utils.js --public-url ./"
  },
  "author": "jsteuer",
  "license": "",
  "ava": {
    "compileEnhancements": false,
    "files": [
      "./test/**/*.spec.ts"
    ],
    "extensions": [
      "ts"
    ],
    "require": [
      "ts-node/register"
    ]
      "ts-node/register/transpile-only",
      "tsconfig-paths/register"
    ],
    "concurrency": 5,
    "failFast": true,
    "failWithoutAssertions": false,
    "tap": false,
    "verbose": true
  },
  "nyc": {
    "include": [
      "src/**/*.ts",
      "src/**/*.tsx"
      "src/**/*.ts"
    ],
    "exclude": [
      "**/*.d.ts"
@@ -43,7 +55,7 @@
      ".tsx"
    ],
    "require": [
      "ts-node/register"
      "ts-node/register/transpile-only"
    ],
    "reporter": [
      "text-summary",

 src/Helpers.ts

@@ -1,6 +1,5 @@
/// <reference path="../mathcoach-api.d.ts"/>


import { MathCoach } from "./MathCoach"; 
 
/**
 * Hilfsfunktionen für Werkzeug-Entwickler. Diese werden nicht durch die `ide-lib.js` 
 * ausgeliefert!
@@ -191,7 +190,7 @@
            const value = this.items.get(key);
            return value ? value : null;
        }
        key(index: number): string | null {
        key(_index: number): string | null {
            throw new Error("InMemoryStorage: key function is not implemented now");
        }
        removeItem(key: string): void {

 src/MathCoach.ts

File was renamed from mathcoach-api.d.ts
@@ -1,9 +1,13 @@
/**
 * Wenn die Bibliothek zur Erweiterung der IDE eingebunden (`ide-lib.js`) wurde,
 * steht diese globale Variable mit Zugang zur öffentlichen Schnittstelle
 * zur Verfügung.
 */
declare const MC: MathCoach.Api;
declare global {
    /**
     * Wenn die Bibliothek zur Erweiterung der IDE eingebunden (`ide-lib.js`) wurde,
     * steht diese globale Variable mit Zugang zur öffentlichen Schnittstelle
     * zur Verfügung.
     */
    const MC: MathCoach.Api;
}



/**
 * Der MathCoach-Namensraum ist die Sammelstelle für alle öffentlichen Schnittstellen.
@@ -12,15 +16,24 @@
 * Als Einstiegspunkt dient das interface `MathCoach.Api` - eine Implementierung dieser Schnittstelle
 * wird von der IDE (siehe `ide-lib.js`) bereitgestellt und kann über die globale Variable 
 * `MC` zugegriffen werden. 
 * 
 * Beispiel:
 * 
 *     const isReady = await MC.ide.isReady(); // true oder false
 */
declare namespace MathCoach {
export namespace MathCoach {

    /** 
     * Als Einstiegspunkt dient das interface `MathCoach.Api` - eine Implementierung dieser Schnittstelle
     * wird von der IDE (siehe `ide-lib.js`) bereitgestellt und kann über die globale Variable 
     * `MC` zugegriffen werden. 
     * 
     * 
     * Beispiel:
     * 
     *     const isReady = await MC.ide.isReady(); // true oder false
     */
    interface Api {
    export interface Api {
        /**
         * Die Schnittstelle zur Entwicklungsumgebung (IDE) von MathCoach. 
         */
@@ -55,7 +68,7 @@
    /**
    * Schnittstelle zur IDE von MathCoach
    */
    interface IdeApi {
    export interface IdeApi {
        /**
         * Gibt den Namen des aktuellen Benutzers zurück, der mit dem Werkzeug arbeitet.
         * 
@@ -86,7 +99,7 @@
    /**
     * Schnittstelle zur Navigation der Vorschau
     */
    interface NavigatorApi {
    export interface NavigatorApi {
        /**
         * Navigiert die Vorschau zu einem Link.
         * 
@@ -117,7 +130,7 @@
    /**
     * Schnittstelle zum Dateisystem
     */
    interface FileSystemApi {
    export interface FileSystemApi {
        /**
         * Liest eine Datei und gibt den Textinhalt zurück. 
         * 
@@ -155,7 +168,7 @@
     * Siehe auch: `MC.ide.getContextFile()`
     * 
     */
    interface File {
    export interface File {
        /**
         * Name des Besitzers. Hinweis: Der Besitzter kann vom angemeldeten
         * Benutzer abweichen (z.B. wenn das Teilen von Inhalten zukünftig unterstützt wird)

 src/index.ts

@@ -1 +1,2 @@
export * from "./Helpers"
export * from "./MathCoach"
export * from "./Helpers"

 test/Helpers.spec.ts

@@ -1,6 +1,8 @@
import test, { ExecutionContext } from "ava";

import { Helpers } from "../src/Helpers";
import { Helpers } from "@mathcoach-ide-api";
import { MathCoach } from "@mathcoach-ide-api";


test("Helpers.contextFileToExerciseFile works as expected", t => {
    t.deepEqual(
@@ -22,13 +24,13 @@
})

test("Helpers.contextFileToExerciseFile check params", t => {
    const expectedErrorMessage = "no valid file reference given, expected object like {owner:'demo', part:'vfs'|'www', path: '/...'}"
    t.throws(() => Helpers.contextFileToExerciseFile(null as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile("null" as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: 1, part: 2, path: 3 } as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: "", part: "vfs", path: "/aufgabe.tool.json" } as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: "demo", part: "xxx", path: "/aufgabe.tool.json" } as any), expectedErrorMessage);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: "demo", part: "vfs", path: "notAbsolute.tool.json" } as any), expectedErrorMessage);
    const expected = { message: "no valid file reference given, expected object like {owner:'demo', part:'vfs'|'www', path: '/...'}" }
    t.throws(() => Helpers.contextFileToExerciseFile(null as any), expected);
    t.throws(() => Helpers.contextFileToExerciseFile("null" as any), expected);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: 1, part: 2, path: 3 } as any), expected);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: "", part: "vfs", path: "/aufgabe.tool.json" } as any), expected);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: "demo", part: "xxx", path: "/aufgabe.tool.json" } as any), expected);
    t.throws(() => Helpers.contextFileToExerciseFile({ owner: "demo", part: "vfs", path: "notAbsolute.tool.json" } as any), expected);
})

test("Helpers.isFile", t => {

 tsconfig-es6.json

New file
@@ -0,0 +1,24 @@
{
  "compilerOptions": {
    "target": "es6",
    "module": "es6",
    "moduleResolution": "node",
    "sourceMap": true,
    "declaration": true,
    "lib": [
      "es2016",
      "dom"
    ],
    "rootDir": "src",
    "outDir": "dist/es6",
    "baseUrl": ".",
    "strict": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }, 
  "include": [
    "src"
  ]
}

 tsconfig.json

@@ -1,13 +1,29 @@
{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "target": "es5",
    "declaration": true,
    "outDir": "./dist",
    "moduleResolution": "node",
    "sourceMap": true,
    "lib": [
      "DOM",
      "ES2016"
      "es2016",
      "dom"
    ],
    "strict": true
  } 
    "rootDir": ".",
    "outDir": "dist",
    "baseUrl": ".",
    "paths": {
      "@mathcoach-ide-api": [
        "src"
      ],
    },
    "strict": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  },
  "include": [
    "src",
    "test"
  ]
}