types: Refactoring and code redesign

Mit diesem Commit wird script.bash nicht mehr als Git Hook sondern als npm-Skript (hier als npm run build hinterlegt) ausgeführt. Ein neuer Ordnername unter ./scripts wurde gewählt und das Programm wurde generell bisschen schlanker gemacht. Guard Clauses und Sicherheitsabfragen (z.B. ob der classes Ordner existiert usw.) bleiben, um das Programmverhalten besser steuern zu können.

Autovervollständigung

Um die Typdeklarationen für ./classes, matter.js und p5.js für Hochschulprojekte nutzen zu können, geht man einfach wie folgt vor:

Kopiere den Order @types und die Datei jsconfig.json
Füge diese Dateien in der obersten Ordnerebene (root) Deines Projekts ein

Ergebnis

Wenn alles kopiert wurde, kann die Projektstruktur folgendermaßen aussehen. Man sieht, dass sich der @types-Ordner und die jsconfig.json auf der obersten Ordnerebene befinden. Dadurch wird es später auch möglich sein, u.a. auch vererbte Attribute und Methoden zwischen den Klassen aus classes in der Autovervollständigung angezeigt zu bekommen.

$ tree .
.
├── @types
│   ├── classes
│   ├── matter-js
│   └── p5
├── README.md
├── classes
│   ├── Ball.js
│   ├── Block.js
│   ├── BlockCore.js
│   ├── BlocksFromSVG.js
│   ├── Chain.js
│   ├── Magnet.js
│   ├── Mouse.js
│   ├── Parts.js
│   ├── Polygon.js
│   ├── PolygonFromPoints.js
│   ├── PolygonFromSVG.js
│   └── Stack.js
├── jsconfig.json
├── libraries
│   ├── decomp.min.js
│   ├── helpers.js
│   ├── matter-attractors.js
│   ├── matter-wrap.js
│   ├── matter.js
│   ├── matter.min.js
│   ├── p5.js
│   ├── p5.min.js
│   ├── p5.sound.js
│   ├── p5.sound.js.map
│   ├── p5.sound.min.js
│   ├── p5.sound.min.js.map
│   └── pathseg.js
└── src
    ├── favicon.ico
    ├── index.html
    ├── js
    │   ├── index.js
    └── styles.css

Hi @ron-mandic, hab's mir eben angeschaut und auch ein paar Sachen geändert. Finde es immernoch etwas zu komplex ... bekomme auch einen Fehler ... bitte nochmal schauen. Fragen:

Wieso wird im process nochmal ein npm install gemacht?
Wieso nicht einfach eine gängige Umgebung (zsh) und eine Folder-Struktur vorgeben? Wenn es es keinen classes folder gibt, dann halt crash etc.

Last login: Mon Jun 19 08:56:19 on ttys000
$ npm run generate-types

> generate-types
> ./scripts/generate-types.bash

Info: Shell and script environment
$0: ./scripts/generate-types.bash
$$: 19466
$SHELL: /bin/zsh

1. Create type declaration files in @types ...
2. Create index.d.ts in @types ...
3. Clean up individual type declaration files ...
4. Create a new subdirectory called ./@types/classes ...
5. Install and extract type declaration files for p5.js and matter.js ...

npm ERR! code ETARGET
npm ERR! notarget No matching version found for @types/matter-js@0.19.0.
npm ERR! notarget In most cases you or one of your dependencies are requesting
npm ERR! notarget a package version that doesn't exist.

npm ERR! A complete log of this run can be found in: /Users/bene/.npm/_logs/2023-06-19T07_22_28_527Z-debug-0.log

Error: There was an error installing the type declarations for matter.js due to version 0.19.0
Warning: Installing the latest available version instead ...

up to date, audited 34 packages in 1s

2 packages are looking for funding
  run `npm fund` for details

3 high severity vulnerabilities

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

up to date, audited 34 packages in 2s

2 packages are looking for funding
  run `npm fund` for details

3 high severity vulnerabilities

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

Success: Installation was completed

Hallo Bene, vielen Dank erstmal für den Kommentar und den Output wegen des Fehlerberichts. Ich werde diesen Fall nochmal ausführlich in meiner Doku auf Notion erwähnen und hier auf GitHub genauer ausführen. Zu den einzelnen Fragen:

1) Wieso wird im process nochmal ein npm install gemacht?

npm install kommt im Skript vor, um für die lokalen Libraries matter.js und p5.js in ./libraries die dazugehörigen .d.ts-Files passend zur Version (hier v1.6.0 für p5.js und 0.19.0 für matter.js) von npm (vgl. z.B. @types/matter.js) herunterzuladen.

Jetzt zu deinem Fehlerbericht: Viele der Typdeklarationen sind vielleicht noch nicht auf die neuste Version der Libraries geupdated worden - und matter.js 0.19.0 ist schon seit dem 16. Februar veröffentlicht. Das Programm versucht Versionen herunterzuladen, die es faktisch nicht gibt. Und anscheinend wird der Fehlerbericht von dem Skript noch nicht sicher abgefangen.

a) Was meldet npm?

So lautet der Fehlerbericht, wenn npm versucht, Types von einer Versionsnummer herunterzuladen, die es aber noch nicht gibt, weil die Community hinter DefinitelyTyped diese Types noch nicht aktualisiert hat.

npm ERR! code ETARGET
npm ERR! notarget No matching version found for @types/matter-js@0.19.0.
npm ERR! notarget In most cases you or one of your dependencies are requesting
npm ERR! notarget a package version that doesn't exist.

npm ERR! A complete log of this run can be found in: /Users/bene/.npm/_logs/2023-06-19T07_22_28_527Z-debug-0.log

b) Was meldet unser Skriptprogramm?

So meldet das Skriptprogramm, dass es bei der angeforderten Version (z.B. für matter.js 0.19.0, obwohl erst 0.18.5 verfügbar ist) keine Types online gibt. Es wird jetzt nun npm i @types/matter-js anstatt npm i @types/matter-js@0.19.0 ausgeführt, um die zuletzt verfügbaren Types (z.B. 0.18.5 für matter.js) herunterzuladen.

Error: There was an error installing the type declarations for matter.js due to version 0.19.0
Warning: Installing the latest available version instead ...

c) Welche Alternative gibt es?

Es gäbe die Möglichkeit, mit dts-gen eigenständig Types für matter.js und p5.js zu generieren, so ähnlich wie ich das auch für ./classes bereits mache. Aber das ist nicht immer zuverlässig und das würde ich selber der Community und den Entwickler:innen überlassen.

Wie lautet jetzt mein Vorgehen?

Ich versuche eine Funktion zu implementieren, dass man aus dem Remote-Repo die neuste Versionsnummer abfrägt und mit der lokalen Version der Library vergleicht. Je nach Fall sollen dann versionsunabhängig Types heruntergeladen werden - auch wenn es bedeutet, dass Library und Types evtl. nicht 1:1 matchen, was ein Abstrich wäre.

2) Wieso nicht einfach eine gängige Umgebung (zsh) und eine Folder-Struktur vorgeben? Wenn es es keinen classes folder gibt, dann halt crash etc.

Ich habe gesehen, dass du zwei Kopien von dem Skript gemacht hast. In generate-types.bash werde ich nun Überarbeitungen vornehmen, die die Bedingungen lockern werden. Zurzeit prüft das Programm Folgendes ab:

Wird als Shell sh verwendet? (Wenn die Umgebung auf sh eingestellt ist, bricht das Programm trotz forcierten Abbruchs noch nicht ab)
Gibt es einen ./classes-Ordner?
Gibt es JavaScript-Dateien in dem ./classes-Ordner? (ähnlich wie das vorherige, mit dem Unterschied, dass der Befehl npx typescript ... auch problemlos durchlaufen kann)
Gibt es eine package.json bzw. package-lock.json? (Werden als Dateien gebraucht, um npm ausführen zu können)

Du merkst, dass viele dieser Edge Cases bei uns höchstwahrscheinlich nie zutreffen, weil angenommen jede:r von uns bash bzw. zsh verwendet oder weil ./classes immer existieren wird - es sei denn, der Ordner wird eines Tages umbenannt. Das habe ich nur implementiert, um das Programm für immer noch mögliche Edge Cases robuster und unanfällig zu machen. Die kann ich aber mit rausnehmen für generate-types.bash, um die Komplexität des Programms weiter zu reduzieren und die Umgebung für uns simpler zu machen.

3) Outro

Ich hoffe, dass ich damit deine Fragen so gut es geht klären konnte. Ich nehme mir fürs Nächste vor, dieses Versionsmatching besser aufzubauen und werde auch die Edge Cases zu Programmbeginn entfernen, wenn es der Fall ist, dass wir alle dieselbe oder ähnliche Umgebung haben d.h.

bash oder zsh
Skript unter macOS und Linux (Windows zurzeit nicht möglich)
...

Was das Versionsmatching für d.ts und .js-Files angeht, könnte dies an sich auch wegfallen. Meine Einschätzung ist aber die, dass es noch sinnvoll ist, um wirklich sicherzustellen, dass später in VSCode alle Autovervollständigungen und Vorschläge auch wirklich zu der verwendeten Libraryversion gemacht werden.

Hi @ron-mandic, danke für deine Erklärung. Nein ich wäre dafür nur ein einziges Script zu haben, siehe meinen Commit. Plz pull. Außerdem wäre ich dafür die types Abhängigkeiten in der package.json selber händisch pflegen und die npm install Logic komplett aus generate-types.bash zu nehmen, dann wären wir fertig und würden uns den Rest sparen. OK? Falls ja nochmal aufräumen (es ist total ok wenn nicht alle Edge Cases abgefangen werden) ... und wir wären durch.

  "devDependencies": {
    "@types/matter-js": "^0.18.5",
    "@types/p5": "^1.6.2",
  }

Hallo @b-g, ich habe soeben die Changes gepusht, die du gerne noch haben wolltest. Damit wären dann folgende Sachen implementiert:

[x] Es werden keine Aufrufe mehr mit npm i ... ausgeführt
[x] Es werden nur noch die p5.js-Types aus den node_modules entnommen und zur Nutzung lokal nach oben geschoben

Darüber hinaus habe ich durch weitere Recherchen herausgefunden, dass matter.js von Haus aus Typdeklarationen mitführt in seinem Quellcode. Das bedeutet, dass wir eine Dev-Dependency weniger haben zum Maintainen. In Zukunft muss also nur noch npm i --save-dev @types/p5@<version> in der Konsole manuell ausgeführt werden, bevor man ./scripts/generate-types.bash ausführt.

Gruß, Ron

@ron-mandic Danke!! Merged! Yay!

b-g / p5-matter-examples