@msay2/tspoet v3.0.11-beta01

TSPoet

TSPoet est une bibliothèque TS/JS pour générer des fichiers source .ts

La génération de fichier .ts pourras vous être utile lors d’exécution de processus en générant du code TypeScript (par exemple : lors d’une exécution d’une commande NPM).

Installation

Mise à jour importante

• Version en cours: 3.0.11-beta01

Les fichiers 7z commençant par l'expression _latest[...].7z à l'emplacement ./node_modules/@msay2/tspoet/ sont les anciennes versions de TSPoet ainsi que la version courante

Supprimer le dossier lib et décompresser le dossier voulut

Un fichier 7z de la version en cours de production est livré pour les éventuelles erreurs de supressions ou pour revenir à la version courante.

Le développement de TSPoet est très lent pour la simple raison que je ne reçois aucune demande d'amélioration et/ou d'information, de ce fait je ne peux savoir si cette bibliothèque convient (dans l'ensemble) ou pas

Les seules améliorations qui sont apportées à TSPoet sont les améliorations que JE constate, je pense que « Pas de nouvelles égal Bonnes nouvelles » 😏

Le language TypeScript est assez riche et n'est pas vraiment (je vulgarise) "Conventionnelle", vous pouvez développer des projets TypeScript/JavaScript de plusieurs façons, il y en a pas qu'une seule façon de mettre sur pied des projets Web JavaScript/TypeScript, JavaScript est un langage assez "ennouer" et retranscrire tous ces noeuds n'est pas un but à atteindre pour TSPoet.

TSPoet est une bibliothèque minimaliste, seulement un assistant pour créer des objets TypeScript. (si possible) TSPoet vous permettra de créer votre propre architecture TypeScript

Si vous avez des idées d'améliorations, des suggestions, n'hésitez pas à me contacter sur mon adresse Gmail oa.msay2@gmail.com

👋🏽 Bonne journée/soirée/nuit.

Si vous êtes sur une version antérieure à la version 3.0.9-beta, veuillez jeter un oeil au journal des modifications et au didacticiel.

La version 3.0.9-beta est une grosse mise à jour qui ajoute, supprime et renomme beaucoup d'éléments.

3.0.11-beta01

• Aucune amélioration apportée, seulement le fichier README.md est changé

3.0.11-beta

• Fichiers *.d.ts mis à jour (petite correction).

3.0.10-beta

• Corrections mineures.

3.0.9-beta

• Cette version permet de créer des classes imbriquées.
• Suppression des objets TSObject, TSVariable et TypeName.
• Ajout de nouveaux objets TSField et ObjectName.
• Suppression des méthodes TSType.Builder.addImport, TSPoet.writeInFile, TSPoet.createFileStream, TSType.customElementBuilder et TSType.declarableBuilder
• TSPoet instaure maintenant une convention générique des noms d'accès aux générateurs d'éléments, TSExemple.exempleBuilder, TSCornichon.cornichonBuilder, TSPokemon.pokemonBuilder ...etc.
• Tous les objets utilisant le nom de méthode transtypeTo change de nom pour cast.
• L'objet TSAnnotation est maintenant déprécié, il sera probablement supprimé dans la prochaine ou quelques mises à jour.
• Amélioration du générateur de lignes de codes. (Grosse amélioration, d'où la version Bêta)
• Amélioration de l'objet Modifier

3.0.6-beta

• Amélioration du générateur de lignes de codes (tentative).

3.0.5-beta

• Amélioration du générateur de lignes de codes (tentative).
• Suppression du journal des modifications.

3.0.4

• Amélioration.

3.0.3

• la version 14.9.0 de nodeJS est requise.

3.0.2

• Mise à jour du fichier README.md.

3.0.1

• L'objet TSProperty peut être importé.

3.0.0

• Grosse Mise à jour (Fichiers renommés, Nouvelles fonctionnalités, Méthodes renommées, Objets supprimées, Corrections de bogues).
• Mise à jour des fichiers :
  • README.md
  • *.d.ts
• Nouvelles fonctionnalités :
  • Vous pouvez ajouter des documentations.
  • Vous pouvez ajouter des commentaires.
• Améliorations :
  • Correction de l'insertion d'indentations inutiles.
  • l'objet TSInterfaceMethod supprimé.
  • l'objet TSParameter supprimé.
  • l'objet TSImport supprimé.
  • l'objet TSProperty Créer.
  • TSConstant.addDoc (Ajoutée).
  • ClassBuilder.addDoc (Ajoutée).
  • EnumBuilder.addDoc (Ajoutée).
  • InterfaceBuilder.addDoc (Ajoutée).
  • InterfaceBuilder.addMethod (supprimée).
  • TSMethod.addDoc (Ajoutée).
  • TSConstant.get (supprimée) remplacée par TSConstant.add.
  • CodeBlock.newBlock (supprimée) remplacée par CodeBlock.new.
  • CodeBlock.addComment (ajoutée).
  • Le méthode addParameter des objets InterfaceBuilder et TSMethod ne prenent plus l'objet TSParameter en paramètre addParameter(path, nameClasses).
  • La méthode addProperty prend l'objet TSProperty en paramètre.

2.1.3

• Ajout d'un retour à la ligne pour des générations de fichiers.

2.1.2

• Ajout du modificateur READONLY
• Nouvelles fonctionnalités :
  • Déclaration de type
  • Déclaration de variable
• Mise à jour des fichiers *.d.ts.
• Mise à jour du fichier README.md.

2.0.2

• MISE À JOUR DE LA LICENCE (APACHE 2.0).
• Mise à jour des fichiers *.d.ts.
• Ajout d’un référentiel des mises à jour.
• Mise à jour du fichier package.json.
• Mise à jour du fichier README.md.

2.0 Production

• Mise à jour du fichier README.md.
• Mise à jour des fichiers *.d.ts.

0.0.44 Bêta

• Initialisation (version bêta).

0.0.1 Alpha

• Initialisation (version alpha).

TSPoet peut s’exécuter avec les fichiers .mjs

cli.mjs

import tspoet from "@msay2/tspoet";
const { TSType, TSMethod, Modifier, ObjectName } = tspoet;

Exemple

Voici un code simple

import { Manager } from "./build/generated/Manager.js";

export class Fragment extends Manager
{
	public onView():void{
		super.onView();
	}
}

Voici son équivalant généré avec TSPoet (dont le fichier TypeScript portera le même nom que son nom de classe).

let objectManager = ObjectName.get("./build/generated", "Manager")
let objectFragment = ObjectName.get(undefined, "Fragment");

let fragmentClassBuilder = TSType.classBuilder(objectFragment)
    .addModifiers(Modifier.EXPORT)
    .setSuperclass(objectManager);

let frgamentOnViewMethod = TSMethod.methodBuilder("onView")
    .addModifiers(Modifier.PUBLIC)
    .return(ObjectName.VOID)
    .addStatement("super.onView();");

fragmentClassBuilder.addMethod(frgamentOnViewMethod.build());

TSPoet.writeFile("app/", fragmentClassBuilder.build());

Pour déclarer notre classe Fragment ainsi que sa méthode Fragment.onView nous devons entamer la création d’un type d’élément TypeScript avec l’object TSType.
Nous configurons la classe Fragment en y ajoutant une importation, puis en ajoutant un modificateur qui configurera la portée de notre classe, ensuite nous ajoutons une classe à étendre de l’objet Manager.
Une fois la configuration de la classe Fragment nous devons ajouter une méthode d’implémentation à notre classe avec l’objet TSMethod que l’on nomme onView.
La méthode Fragment.onView sera configurée avec une portée public puis avec une valeur de retour typée void puis nous ajoutons une ligne de code.

Une fois les configurations terminées, nous pouvons « écrire » notre fichier en demandant à l’objet TSPoet de créer notre futur objet à partir des configurations du/des générateurs cités plus haut, avec la méthode TSPoet.writeFile.

• Classes --> TSType.classBuilder
• Interfaces --> TSType.interfaceBuilder
• Énumérations --> TSType.enumBuilder
• Implémentation anonyme --> TSType.anonymousImplBuilder

La configuration des méthodes, propriétées …etc n’étant pas modélisées, tous les paramètres appliqués pour la configuration de vos objets sont modélisés par TSPoet par de simples chaînes de caractères, ainsi que vos lignes de codes :

let doLoopBuilder = TSMethod.methodBuilder("doLoop")
    .return(ObjectName.VOID)
    .addStatement("let index:number = 0;" +
    "let value:boolean = true;" +
    "while (value)" +
    "{" +
    "console.log(`Index=[${value}]`);" +
    "index++;" +
    "if (index == 20)" +
    "{" +
    "value = false;" +
    "}" +
    "}")
    .build();

Ce qui générerait :

doLoop():void{
	let index:number = 0;let value:boolean = true;while (value){console.log(`Index=[${value}]`);index++;if (index == 20){value = false;}}
}

Pour remédier à ce genre de pratique fastidieuse, TSPoet comprend l’objet CodeBlock qui vous permet d’écrire vos ligne de code bloc par bloc :

let doLoopBuilder = TSMethod.methodBuilder("doLoop")
    .return(ObjectName.VOID)
    .addCodeBlock(CodeBlock.new()
        .addStatement("let index:number = 0, value:boolean = true")
        .beginBrace("while (value)")
        .addStatement("console.log(`Index=[${value}]`)")
        .addStatement("index++")
        .beginBrace("if (index == 20)")
        .addStatement("value = false")
        .endBrace()
        .endBrace()
        .build())
    .build();

Ce qui générerait :

doLoop():void{
    let index:number = 0, value:boolean = true;
    while (value){
        console.log(`Index=[${value}]`);
        index++;
        if (index == 20){
            value = false;
        }
    }
}

Concrètement, l’objet CodeBlock vous permet d’ajouter du code complexe, contrairement à la méthode par défaut TSMethod.addStatement qui vous permet d’ajouter vos lignes de codes SIMPLEMENT.
L'utilisation de l'objet CodeBlock est recommandé, celui-ci gère les indentations, les accolades et les points-virgule.

La méthode CodeBlock.addStatement insert vos lignes de codes et gère les indentation et les points-virgule.
La méthode CodeBlock.beginBrace insert une accolade ouvrante en fin d'instruction.
La méthode CodeBlock.endBrace insert une accolade fermante en fin d'instruction.
La méthode CodeBlock.nextBrace insert une accolade fermante puis ouvrante avant et fin d'instruction.

Créations

Classes

Créer une classe

let componentClassBuilder = TSType.classBuilder(ObjectName.get(undefined, "Component")).build();

Ce qui générerait

class Component
{
}

Un fichier TypeScript sera généré au nom de votre classe (soit Component.ts)

Interfaces

Créer une interface

let managerInterfaceBuilder = TSType.interfaceBuilder(ObjectName.get(undefined, "Manager")).build();

Ce qui générerait

interface Manager
{
}

Enumérations

Créer une énumération

let managerEventEnumBuilder = TSType.enumBuilder(ObjectName.get(undefined, "EventManager")).build();

Ce qui générerait

enum EventManager
{
}

Création du fichier TS et génération du type d'objet

Créer l'objet configuré

let classBuilder = ...;


TSPoet.writeFile("./app", classBuilder.build());

Ce qui générerait un ficher TypeScript au nom de votre objet classBuilder dans un dossier nommé app.

Bloc de code (bonnes pratiques)

L’objet CodeBlock possède une fonctionnalité vous permettant de ne plus écrire du code fastidieux (comprenant plusieurs caractères additionnelles pour la concaténation d’expressions littérales).

Pratiques

« Mauvaise » pratique

let enableChatBuilder = TSMethod.methodBuilder("enableChat")
    .addCodeBlock(CodeBlock.new()
        .addStatement("let count:number = 0")
        .beginBrace("for (let i:number = 0; i < 20; i++)")
        .addStatement("count += i")
        .endBrace()
        .buil())
    .build();

Pratique moins mauvaise

public static createMethod(from:number, to:number):void
{
    let counterBuilder = TSMethod.methodBuilder("counter")
        .addCodeBlock(CodeBlock.new()
            .addStatement("let count:number = 0")
            .beginBrace("for (let i:number = "+ from +"; i < "+ to +"; i++)")
            .addStatement("count += i")
            .endBrace()
            .buil())
        .build();
}

Pour éviter ces « mauvaises » pratiques, CodeBlock possède 4 expressions qui vous permet d’éviter toutes les concaténations « agaçantes ».

Bonne pratiques

let counterBuilder = TSMethod.methodBuilder("counter")
    .addCodeBlock(CodeBlock.new()
        .addStatement("let count:number = 0")
        .beginBrace("for (let i:number = $L; i < $L; i++)", 0, 20)
        .addStatement("count += i")
        .endBrace()
        .buil())
    .build();

L’objet CodeBlock vous donne la possibilité d’insérer vos lignes de code de manière similaire à la méthode string.replace.

Pour les expressions littérales

…
.beginBrace("for (let i:number = $L; i < $L; i++)", 0, 20)
…

Pour les chaînes de caractères

…
.beginBrace("let firstName:string = $S, lastName:string = $S", "Manon", "Carcer")
…

Pour les objets

…
.beginBrace("let myObject:$O = new $O()", ObjectName.get(undefined, "MyObject"), ObjectName.get(undefined, "MyObject"))
…

Pour les implémentations anonymes

…
.addStatement("let impl:any = $I", TSType.anonymousImplBuilder().build())
…

Importations

Les importations se font "automatiquement" avec l'objet ObjectName, pour ce faire vous devez simplement fournir le chemin d'accès valide de votre fichier par rapport à l'emplacement de votre futur type d'objet à générer.
L'objet ObjectName prend en paramètre 3 variables :

• (Annulable) Le nom d'accès du fichier.
• Le nom de l'objet.
• (Optionnel) Les noms des classes imbriquées.

ObjectName permet également le transtypage d'objets
Vous ne pouvez pas ajouter un objet à importer si il est utilisé nulle part

/!\ Avertissement /!\

ObjectName vous impose une convention strict sur sont utilisation, soit 1 Fichier = 1 Objet, si votre fichier contient plusieurs objets exportables, vos objets (sauf mentionné avec l'objet ObjectName) ne seront pas explicitement inscrit dans l'instruction import, cela signifie que, 1 Objet = 1 Exportable
Donc : 1 Fichier = 1 (ou plusieurs) Objet(s) = 1 Exportable.

Méthodes

Note : Si vous appliquez un modificateur abstrait à un générateur de méthode qui est pourvus d’une ligne de code (ou d’un bloc de code), ces dernières seront ignorées du fait que les méthodes abstraites ne doivent pas avoir de corp.

Créer une méthode

Note : Le générateur de méthode vérifiera toujours si votre méthode à générer possède une type de retour car il ne possède pas de valeur par défaut.

let checkValueBuilder = TSMethod.methodBuilder("checkValue")
    .addModifiers(Modifier.PUBLIC, Modifier.ABSTRACT);

// checkValueBuilder lèvera une exception car il ne contient aucun type de retour.

let checkerBuilder = TSMethod.methodBuilder("checker")
    .addModifiers(Modifier.PUBLIC)
    .return(ObjectName.VOID);

let checkClassBuilder = TSType.classBuilder(ObjectName.get(undefined, "Checker"))
    .addModifiers(Modifier.EXPORT, Modifier.ABSTRACT)
    .addMethod(checkValueBuilder.build())
    .addMethod(checkerBuilder.build())
    .build();

Ce qui générerait

export abstract class Checker
{
	public abstract checkValue():void;

	public checker():void{}
}

Paramètres

let objectContext = ObjectName.get(".", "Context").cast(ObjectName.STRING, ObjectName.BOOLEAN);

let overBuilder = TSMethod.methodBuilder("over")
    .addModifiers(Modifier.PRIVATE)
    .addParameter("value", ObjectName.BOOLEAN)
    .addParameter("name", ObjectName.STRING)
    .addParameter("previousContext", objectContext)
    .addParameter("newestContext", objectContext)
    .return(ObjectName.VOID)
    .build();

Ce qui générerait

import { Context } from "./Context.js"; // Uniquement si le chemin du fichier est spécifié dans l'objet ObjectName

private over(value:boolean, name:string, previousContext:Context<string, boolean>, newestContext:Context<string, boolean>):void{}

Constructeur

let constructorBuilder = TSMethod.constructorBuilder()
    .addModifiers(Modifier.PROTECTED)
    .build();

Ce qui générerait

protected constructor(){}

Variables

let myField = TSField.fieldBuilder("field")
    .addModifiers(Modifier.STATIC)
    .return(ObjectName.ANY)
    .setValue({
        from: 0,
        to: 255
    });

let countField = TSField.fieldBuilder("count")
    .addModifiers(Modifier.PUBLIC)
    .return(ObjectName.NUMBER)
    .setValue(48);

let myFields = TSField.fieldBuilder("fields")
    .addModifiers(Modifier.STATIC)
    .return(ObjectName.get(undefined, "Array").cast(ObjectName.STRING))
    .setValue([
        "Priscilla",
        "Samsung"
    ]);

let fieldsClassBuilder = TSType.classBuilder(ObjectName.get(undefined, "Fields"))
    .addField(myField.build())
    .addField(countField.build())
    .addField(myFields.build())
    .build();

Ce qui générerait

Note : Lève une exception si aucun type de retour est fournie au générateur de variables, soit TSField

class Fields
{
	static field:any = {
		from:0,
		to:255
	};
	public count:number = 48;
	static fields:Array<string> = [
		`Priscilla`,
		`Samsung`
	];
}

Interfaces

let objectArray = ObjectName.get(undefined, "Array").cast(ObjectName.STRING);

let testRobotPropertyBuilder = TSProperty.propertyBuilder("testRobot")
    .addParameter("hasProperties", ObjectName.BOOLEAN)
    .addParameter("list", objectArray)
    .return(objectArray);

let fetcherPropertyBuilder = TSProperty.propertyBuilder("fetcher")
    .return(ObjectName.STRING);

let robotInterface = TSType.interfaceBuilder(ObjectName.get(undefined, "Robot"))
    .addProperty(testRobotPropertyBuilder.build())
    .addProperty(fetcherPropertyBuilder.build());
    .build();

Ce qui générerait

interface Robot
{
	testRobot(hasProperties:boolean, list:Array<string>):Array<string>;
	fetcher():string;
}

Annotations

let object = {
    template: "La confiture c'est trop sucrée"
};
let array = [
    "Celin",
    "Casio"
];

let fooAnnotation = TSAnnotation.annotationBuilder(ObjectName.get(undefined, "Foo")).addValue(object);
let leeAnnotation = TSAnnotation.annotationBuilder(ObjectName.get(undefined, "Lee")).addValue(array);
let barAnnotation = TSAnnotation.annotationBuilder(ObjectName.get(undefined, "Bar")).addValue(TSAnnotation.EMPTY_VALUE);
let booAnnotation = TSAnnotation.annotationBuilder(ObjectName.get(undefined, "Boo"));

let helloBuilder = TSMethod.methodBuilder("hello")
    .addAnnotation(fooAnnotation.build())
    .addAnnotation(leeAnnotation.build())
    .addAnnotation(barAnnotation.build())
    .addAnnotation(booAnnotation.build())
    .return(ObjectName.VOID);

let robotInterface = TSType.classBuilder(ObjectName.get(undefined, "Robot"))
    .addMethod(helloBuilder.build())
    .build();

Ce qui générerait

@Foo({
	template:`La confiture c'est trop sucrée`
})
@Lee([
    `Celin`,
    `Casio`
])
@Bar()
@Boo
hello():void{}

Enumération

let constantUpTouch = TSConstant.constantBuilder("UP", 0);
let constantDownTouch = TSConstant.constantBuilder("DOWN", 1);

let onTouchEnum = TSType.enumBuilder(ObjectName.get(undefined, "OnTouch"))
    .addConstant(constantUpTouch.build())
    .addConstant(constantDownTouch.build())
    .build();

Ce qui générerait

enum OnTouch
{
	UP = 0,
	DOWN = 1
}

Commentaire

Pour ajouter des commentaires vous devez utiliser la méthode CodeBlock.addComment

let doLoopBuilder = TSMethod.methodBuilder("doLoop")
    .return(ObjectName.VOID)
    .addCodeBlock(CodeBlock.new()
        .addStatement("let index:number = 0, value:boolean = true")
        .beginBrace("while (value)")
        .addStatement("console.log(`Index=[${value}]`)")
        .addStatement("index++")
        .addComment("Check if index equals 20")
        .beginBrace("if (index == 20)")
        .addStatement("value = false")
        .endBrace()
        .endBrace()
        .build())
    .build();

Ce qui générerait

private doLoop():void{
    let index:number = 0, value:boolean = true;
    while (value){
        console.log(`Index=[${value}]`);
        index++;
        // Check if index equals 20
        if (index == 20){
            value = false;
        }
    }
}

Documentation

Pour ajouter une documentation vous devez utiliser la méthode addDoc des objets suivants :

• TSType.Builder
• TSConstant
• TSField
• TSMethod
• TSProperty

Insertion des documentations

let setNameMethod = TSMethod.methodBuilder("setName")
    .addModifiers(Modifier.PUBLIC)
    .return(ObjectName.VOID)
    .addDoc("Set the name of user.")
    .addDoc("@param name The name of user.")
    .addParameter("name", ObjectName.STRING)
    .addStatement("this.name = name;")
    .build();

Ce qui générerait

/**
 * Set the name of user.
 * @param name The name of user.
 */
public setName(name:string):void{
    this.name = name;
}

Génération

Pour générer des fichiers TypeScript, vous devez utiliser l’objet TSPoet.

Création + écriture (remplace l'ancien contenu)

let path:string = "app/draw";

let classBuilder = TSType.classBuilder(ObjectName.get(undefined, "MyClass"))
    ...;
let interfaceBuilder = TSType.interfaceBuilder(ObjectName.get(undefined, "MyInterface"))
    ...;
let enumBuilder = TSType.enumBuilder(ObjectName.get(undefined, "MyEnumeration"))
    ...;

TSPoet.writeFile(path, classBuilder.build());
TSPoet.writeFile(path, interfaceBuilder.build());
TSPoet.writeFile(path, enumBuilder.build());

TSPoet utilise les bibliothèques suivantes :

• fs

Référentiel d'objets

TSPoet

TSType

TSProperty

TSMethod

TSField

TSConstant

TSAnnotation

CodeBlock

ObjectName

Modifier

TSAnnotation

TSField

ObjectName

Modifier

License

Copyright (c) 2020-2021 MSay2 (Yoann Meclot) - @msay2/tspoet
 
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
 
    http://www.apache.org/licenses/LICENSE-2.0
 
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.