Un standard ouvert pour les fonctions JavaScript

En tant que développeurs, nous cherchons toujours des moyens de mieux faire notre travail, que ce soit en suivant des modèles, en utilisant des bibliothèques et des cadres bien écrits, ou qu'avez-vous. Dans cet article, je vais partager avec vous une spécification JavaScript pour les fonctions facilement consommables. Cet article est destiné aux développeurs JavaScript et vous apprendrez à écrire des fonctions JavaScript avec une API universelle qui facilite la consommation de ces fonctions. Cela serait particulièrement utile pour la création de packages npm (comme nous le verrons à la fin de cet article).

Il n'y a pas de condition préalable particulière pour cet article. Si vous pouvez écrire une fonction JavaScript, vous pourrez suivre. Avec tout cela dit, plongeons-nous.

Que sont les machines?

Les machines sont des fonctions JavaScript prévisibles et auto-documentées qui suivent les spécifications de la machine écrites par Mike McNeil. Une machine se caractérise comme suit:

• Elle doit avoir un objectif clair, que ce soit d'envoyer un e-mail, d'émettre un jeton Web JSON de faire une demande de récupération, etc.
• Elle doit suivre la spécification, qui rend les machines prévisibles pour la consommation via des installations npm.

Par exemple, ici est une collection de machines qui fournit des API simples et cohérentes pour travailler avec Cloudinary. Cette collection expose des fonctions (machines) pour télécharger des images, supprimer des images, etc. C'est tout ce que les machines sont vraiment: elles exposent simplement une API simple et cohérente pour travailler avec les fonctions JavaScript et Node.js.

Caractéristiques des machines

• Les machines sont auto-documentées. Cela signifie que vous pouvez simplement regarder une machine et savoir ce qu'elle fait et ce qu'elle va exécuter (les paramètres). Cette fonctionnalité m'a vraiment vendu sur eux. Toutes les machines sont auto-documentées, ce qui les rend prévisibles.
• Les machines sont rapides à implémenter, comme nous le verrons. En utilisant l'outil machinepack pour l'interface de ligne de commande (CLI), nous pouvons rapidement échafauder une machine et la publier au npm.
• Les machines sont faciles à déboguer. Cela est également dû au fait que chaque machine possède une API standardisée. Nous pouvons facilement déboguer les machines car elles sont prévisibles.

Y a-t-il des machines là-bas?

Vous vous demandez peut-être: "Si les machines sont si bonnes, alors pourquoi n'en ai-je pas entendu parler jusqu'à présent?" En fait, ils sont déjà largement utilisés. Si vous avez utilisé le framework Node.js MVC Sails.js alors vous avez soit écrit une machine, soit interfacé avec un couple. L'auteur de Sails.js est également l'auteur de la spécification de la machine.

En plus du framework Sails.js, vous pouvez parcourir les machines disponibles sur npm en recherchant machinepack, ou vous rendre sur http: // node-machine.org/machinepacksqui est le démon de registre de machinepack; il se synchronise avec npm et se met à jour toutes les 10 minutes.

Les machines sont universelles. En tant que consommateur de forfaits, vous saurez à quoi vous attendre. Donc, n'essayez plus de deviner l'API d'un package particulier que vous avez installé. S'il s'agit d'une machine, vous pouvez vous attendre à ce qu'elle suive la même interface facile à utiliser.

Maintenant que nous avons une idée de ce que sont les machines, examinons les spécifications en analysant un exemple de machine.

Le Spécifications de la machine

     module.exports = {
  friendlyName: 'Faites quelque chose',
  description: 'Faites quelque chose avec les entrées fournies qui se traduit par l'un des scénarios de sortie.',
  extendedDescription: 'Cette description étendue facultative peut être utilisée pour communiquer des mises en garde, des notes techniques ou tout autre type d'informations supplémentaires qui pourraient être utiles aux utilisateurs de cette machine.',
  moreInfoUrl: «https://stripe.com/docs/api#list_cards»,
  sideEffects: 'cacheable',
  synchronisation: vrai,

  contributions: {
    marque: {
      friendlyName: 'Some input',
      description: 'La marque des vers gommeux.',
      extendedDescription: «La valeur fournie sera comparée à toutes les marques connues de vers gommeux. La correspondance est insensible à la casse et tolère les fautes de frappe dans la distance d'édition de Levenstein 

L'extrait ci-dessus est tiré de l'exemple interactif sur le site officiel. Décortiquons cette machine.

En regardant l'extrait ci-dessus, nous pouvons voir qu'une machine est un objet exporté contenant certaines propriétés standardisées et une seule fonction. Voyons d'abord quelles sont ces propriétés et pourquoi elles sont ainsi.

• friendlyName
  Ceci est un nom d'affichage pour la machine, et il suit ces règles:
  • est un cas de phrase (comme un normal phrase),
  • ne doit pas avoir de ponctuation de fin,
  • doit contenir moins de 50 caractères.
• description
  Ceci doit être une description claire d'une phrase dans l'impératif humeur (c'est-à-dire la voix faisant autorité) de ce que fait la machine. Un exemple serait «Émettre un jeton Web JSON», plutôt que «Émettre un jeton Web JSON». Sa seule contrainte est:
  • Il doit contenir moins de 80 caractères.
• extendedDescription (facultatif)
  Cette propriété fournit des informations supplémentaires facultatives, étendant ce qui a déjà été dit. dans la propriété description. Dans ce champ, vous pouvez utiliser des signes de ponctuation et des phrases complètes.
  • Il doit contenir moins de 2 000 caractères.
• moreInfoUrl (facultatif)
  Ce champ contient une URL dans lequel des informations supplémentaires sur le fonctionnement interne ou la fonctionnalité de la machine peuvent être trouvées. Cela est particulièrement utile pour les machines qui communiquent avec des API tierces telles que GitHub et Auth0.
• sideEffects (facultatif)
  Il s'agit d'un champ facultatif que vous pouvez soit omettre, soit définir comme cacheable ou idempotent . S'il est défini sur pouvant être mis en cache alors .cache () peut être utilisé avec cette machine. Notez que seules les machines qui n'ont pas sideEffects doivent être définies sur pouvant être mises en cache .
• sync (facultatif)
  Les machines sont asynchrones par défaut. La définition de l'option sync sur true désactive l'async pour cette machine, et vous pouvez ensuite l'utiliser comme une fonction régulière (sans async / attendre ou puis () ).

entrées

Il s'agit de la spécification ou de la déclaration des valeurs attendues par la fonction machine. Examinons les différents champs de saisie d'une machine.

• brand
  En utilisant l'extrait de machine ci-dessus comme guide, le champ de la marque est appelé la clé de saisie. Il est normalement en forme de chameau et doit être une chaîne alphanumérique commençant par une lettre minuscule.
  • Aucun caractère spécial n'est autorisé dans un identificateur ou un champ de clé d'entrée.
• friendlyName [19659025] Il s'agit d'un nom d'affichage lisible par l'homme pour l'entrée. Il doit:
  • être un cas de phrase,
  • ne pas avoir de ponctuation finale,
  • avoir moins de 50 caractères.
• description
Ceci est une courte description décrivant l'utilisation de l'entrée.
• extendedDescription
Tout comme le champ extendedDescription sur la machine elle-même, ce champ fournit des informations supplémentaires sur cette entrée particulière.
• moreInfoUrl
Il s'agit d'une URL facultative qui fournit plus d'informations sur l'entrée, si nécessaire.
• requis
Par défaut, chaque entrée est facultative. Cela signifie que si, à l'exécution, aucune valeur n'est fournie pour une entrée, le fn serait indéfini. Si vos entrées ne sont pas facultatives, il est préférable de définir ce champ sur true car cela entraînerait une erreur de la machine.
• exemple
Ce champ est utilisé pour déterminer le type de données attendu de l'entrée.
• whereToGet
Il s'agit d'un objet de documentation facultatif qui fournit des informations supplémentaires sur la façon de localiser les valeurs adéquates pour cette entrée. Ceci est particulièrement utile pour des choses comme les clés API, les jetons, etc.
• whereToGet.description
Ceci est une description claire d'une phrase, également dans l'état d'esprit impératif, qui décrit comment trouver le bon
• extendedDescription
Ceci fournit des informations supplémentaires sur où obtenir une valeur d'entrée appropriée pour cette machine.

exit

Ceci est la spécification pour tous les rappels de sortie possibles de cette machine. fn l'implémentation peut se déclencher. Cela implique que chaque sortie représente un résultat possible de l'exécution de la machine.

• succès
  Il s'agit de la clé de sortie standardisée dans les spécifications de la machine qui signifie que tout s'est bien passé et que la machine a fonctionné sans aucune erreur. Examinons les propriétés qu'il pourrait exposer:
  • outputFriendlyName
    Il s'agit simplement d'un nom d'affichage pour la sortie de sortie.
  • outputDescription
    Cette courte phrase nominale décrit la sortie d'une sortie

D'autres sorties signifient que quelque chose s'est mal passé et que la machine a rencontré une erreur. La convention de dénomination de ces sorties doit suivre la convention de dénomination de la clé d'entrée. Voyons les champs sous de telles sorties:

• description
Voici une brève description décrivant le moment où la sortie sera appelée.
• extendedDescription
Ceci fournit des informations supplémentaires sur le moment où cette sortie sera être appelé. C'est facultatif. Vous pouvez utiliser la syntaxe Markdown complète dans ce champ, et comme d'habitude, elle doit contenir moins de 2000 caractères.

You Made It!

C'était beaucoup à prendre en compte. Mais ne vous inquiétez pas: lorsque vous commencez à créer machines, ces conventions resteront en place, surtout après votre première machine, que nous écrirons ensemble sous peu. Mais d'abord…

Machinepacks

Lors de la création de machines, les machinepacks sont ce que vous publiez sur npm. Il s'agit simplement d'ensembles d'utilitaires associés pour effectuer des tâches de développement répétitives courantes avec Node.js . Supposons donc que vous ayez un pack machine qui fonctionne avec les tableaux; ce serait un ensemble de machines qui fonctionnent sur des tableaux, comme concat () map () etc. Voir le Pack de machines de tableaux dans le registre pour obtenir

Convention de dénomination des packs machine

Tous les packs machine doivent suivre la norme de «machinepack-» comme préfixe, suivi du nom de la machine. Par exemple, machinepack-array, machinepack-sessionauth.

Notre premier machinepack

Pour mieux comprendre les machines, nous allons écrire et publier un machinepack qui est un wrapper pour le contributeurs de fichiers paquet npm.

Mise en route

Nous avons besoin des éléments suivants pour créer notre machinepack:

1. Outil CLI Machinepack
   Vous pouvez l'obtenir en exécutant:

    npm install -g machinepack
    

2. Outil d'échafaudage Yeoman
   Installez-le globalement en exécutant:

    npm install -g yo
    

3. Machinepack Yeomen generator
   Installez-le comme ceci:

    npm install -g generator-machinepack
   

Remarque : Je suppose que Node.js et npm sont déjà installés sur votre machine.

Génération de votre premier pack machine

À l'aide des outils CLI que nous avons installés ci-dessus, générons un nouveau machinepack utilisant le générateur de machinepack. Pour ce faire, accédez d'abord au répertoire dans lequel vous souhaitez que le générateur génère les fichiers, puis exécutez ce qui suit:

 yo machinepack

La commande ci-dessus lancera un processus interactif de génération d'un pack machine barebones pour vous. Il vous posera quelques questions; assurez-vous de dire oui à la création d'un exemple de machine.

Remarque: J'ai remarqué que le générateur Yeoman a des problèmes lors de l'utilisation de Node.js 12 ou 13. Donc, je recommande d'utiliser nvm et installez Node.js 10.x, qui est l'environnement qui a fonctionné pour moi.

Si tout s'était déroulé comme prévu, nous aurions généré la couche de base de notre machinepack. Jetons un coup d'œil:

 DELETE_THIS_FILE.md
Machines/
package.json
package.lock.json
README.md
index.js
node_modules /

Les fichiers ci-dessus sont générés pour vous. Jouons avec notre exemple de machine, qui se trouve dans le répertoire machines . L'outil CLI de machinepack étant installé, nous pourrions exécuter les éléments suivants:

 machinepack ls

Ceci répertorierait les machines disponibles dans notre répertoire machines . Actuellement, il y en a une, la machine à dire bonjour. Voyons ce que say-hello fait en lançant ceci:

 machinepack exec say-hello

Cela vous demandera de saisir un nom et d'imprimer la sortie de la machine say-hello.

Comme vous le remarquerez, l'outil CLI tire parti de la normalisation des machines pour obtenir la description de la machine et Fonctionnalité.

Créons une machine

Ajoutons notre propre machine, qui encapsulera les contributeurs de fichiers et les paquetages d'extraction de nœuds (nous devrons également les installer avec npm). Donc, exécutez ceci:

 npm install file-contributors node-fetch --save

Ensuite, ajoutez une nouvelle machine en exécutant:

 machinepack add

Vous serez invité à saisir le nom convivial, la description (facultative) et la description étendue (également facultative) de la machine. Après cela, vous aurez réussi à générer votre machine.

Maintenant, développons les fonctionnalités de cette machine. Ouvrez la nouvelle machine que vous avez générée dans votre éditeur. Ensuite, exigez le package file-contributors, comme ceci:

 const fetch = require ('node-fetch');
const getFileContributors = require ('file-contributors'). default;

global.fetch = fetch; // solution de contournement puisque les contributeurs de fichiers utilisent windows.fetch () en interne

Remarque: Nous utilisons le package node-fetch et la solution de contournement global.fetch = fetch car le package file-contributors utilise windows.fetch () en interne, qui n'est pas disponible dans Node.js.

getFileContributors des contributeurs de fichiers nécessite trois paramètres pour fonctionner: propriétaire (propriétaire du référentiel), repo (le référentiel) et path (le chemin d'accès au fichier). Donc, si vous avez suivi, alors vous saurez que ceux-ci iraient dans notre clé d'entrées . Ajoutons-les maintenant:

 ...
 contributions: {
    propriétaire: {
      friendlyName: 'Owner',
      description: 'Le propriétaire du référentiel',
      requis: vrai,
      exemple: «DominusKelvin»
    },
    repo: {
      friendlyName: 'Repository',
      description: 'Le référentiel Github',
      requis: vrai,
      exemple: «machinepack-filecontributors»
    },
    chemin: {
      friendlyName: 'Path',
      description: 'Le chemin d'accès relatif au fichier',
      requis: vrai,
      exemple: 'README.md'
    }
  },
...

Maintenant, ajoutons les sorties. À l'origine, la CLI a ajouté une sortie réussie pour nous. Nous modifierions cela, puis ajouterions une autre sortie au cas où les choses ne se passeraient pas comme prévu.

 sorties: {

    Succès: {
      outputFriendlyName: 'File Contributors',
      outputDescription: 'Un tableau des contributeurs sur un fichier particulier',
      variableName: 'fileContributors',
      description: 'Terminé.',
    },

    Erreur: {
      description: «Une erreur s'est produite lors de la tentative d'obtention des contributeurs de fichiers»
    }

  },

Enfin, fabriquons la viande de la machine, qui est la fn :

 fn: fonction (entrées, sorties) {
    const contributors = getFileContributors (inputs.owner, inputs.repo, inputs.path)
    .then (contributeurs => {
      return exits.success (contributeurs)
    }). catch ((erreur) => {
      return exits.error (erreur)
    })
  },

Et voilà! Nous avons conçu notre première machine. Essayons-le à l'aide de l'interface CLI en exécutant ce qui suit:

 machinepack exec get-file-contributors

Une invite apparaîtrait demandant successivement propriétaire repo et chemin . Si tout s'est déroulé comme prévu, notre machine se terminera avec succès et nous verrons un tableau des contributeurs pour le fichier de référentiel que nous avons spécifié.

Utilisation dans le code

Je sais que nous n'utiliserons pas l'interface CLI pour consommer le pack machine dans notre base de code. Donc, ci-dessous est un extrait de la façon dont nous consommerions des machines à partir d'un pack machine:

 var FileContributors = require ('machinepack-filecontributors');

// Récupère les métadonnées d'un référentiel sur GitHub.
FileContributors.getFileContributors ({
  propriétaire: «DominusKelvin»,
  repo: 'vue-cli-plugin-chakra-ui',
   chemin: 'README.md'
}). exec ({
  // Une erreur inattendue est apparue.
  erreur: function () {
  },
  // D'ACCORD.
  succès: fonction (contributeurs) {
    console.log ('Got:  n', contributeurs);
  },
});

Conclusion

Félicitations! Vous venez de vous familiariser avec les spécifications de la machine, de créer votre propre machine et de voir comment consommer des machines. Je serai ravi de voir les machines que vous créez.

Ressources

Consultez le référentiel pour cet article. Le paquet npm que nous avons créé est également disponible sur npm .

(ra, il, al)