Comprender las máquinas: un estándar abierto para funciones de JavaScript

 

 

 

  • Patrones de diseño de interfaces inteligentes, vídeo de 10h + formación UX
  • Implemente rápidamente. Implementar inteligentemente

  • Índice
    1. ¿Qué son las máquinas?
    2. Características de las máquinas
    3. ¿Hay máquinas por ahí?
    4. La especificación de la máquina
      1. entradas
      2. salidas
    5. ¡Lo hiciste!
    6. Paquetes de máquinas
    7. Convención de nomenclatura de Machinepacks
    8. Nuestro primer paquete de máquinas
    9. Empezando
    10. Generando su primer Machinepack
    11. Hagamos una máquina
      1. Uso en código
      2. Conclusión
      3. Recursos

    En este artículo, Kelvin Omereshone le presenta las máquinas, un estándar abierto para funciones de JavaScript. Al final de este artículo, debería estar familiarizado con qué son las máquinas y cómo implementarlas.

     

    Como desarrolladores, siempre buscamos formas de hacer mejor nuestro trabajo, ya sea siguiendo patrones, utilizando bibliotecas y marcos bien escritos, o lo que sea. En este artículo, compartiré contigo una especificación de JavaScript para funciones fácilmente utilizables. Este artículo está dirigido a desarrolladores de JavaScript y aprenderá a escribir funciones de JavaScript con una API universal que facilita el consumo de esas funciones. Esto sería particularmente útil para crear paquetes npm (como veremos al final de este artículo).

    No existe ningún requisito previo especial para este artículo. Si puedes escribir una función de JavaScript, podrás seguirla. Dicho todo esto, profundicemos.

    ¿Qué son las máquinas?

    Las máquinas son funciones de JavaScript predecibles y autodocumentadas que siguen las especificaciones de la máquina , escritas por Mike McNeil. Una máquina se caracteriza por lo siguiente:

     

    • Debe tener un propósito claro, ya sea enviar un correo electrónico, emitir un token web JSON , realizar una solicitud de recuperación, etc.
    • Debe seguir la especificación, lo que hace que el consumo de las máquinas sea predecible a través de instalaciones npm.

    Como ejemplo, aquí hay una colección de máquinas que proporcionan API simples y consistentes para trabajar con Cloudinary. Esta colección expone funciones (máquinas) para cargar imágenes, eliminar imágenes y más. Eso es todo lo que son las máquinas en realidad: simplemente exponen una API simple y consistente para trabajar con funciones de JavaScript y Node.js.

    Características de las máquinas

    • Las máquinas se autodocumentan. Esto significa que puede simplemente mirar una máquina y saber qué está haciendo y qué ejecutará (los parámetros). Esta característica realmente me convenció. Todas las máquinas se autodocumentan, lo que las hace predecibles.
    • Las máquinas se implementan rápidamente, como veremos. Usando la herramienta machinepack para la interfaz de línea de comandos (CLI), podemos desarrollar rápidamente una máquina y publicarla en npm.
    • Las máquinas son fáciles de depurar. Esto también se debe a que cada máquina tiene una API estandarizada. Podemos depurar máquinas fácilmente porque son predecibles.

    ¿Hay máquinas por ahí?

    Quizás estés pensando: "Si las máquinas son tan buenas, ¿por qué no he oído hablar de ellas hasta ahora?". De hecho, ya se utilizan mucho. Si ha utilizado el marco MVC de Node.js Sails.js , entonces ha escrito una máquina o ha interactuado con un par. El autor de Sails.js es también el autor de la especificación de la máquina.

    Además del marco Sails.js, puede explorar las máquinas disponibles en npm buscando machinepack o dirigirse a https://node-machine.org/machinepacks , que es el demonio de registro de machinepack; se sincroniza con npm y se actualiza cada 10 minutos.

    Las máquinas son universales. Como consumidor de paquetes, sabrá qué esperar. Por lo tanto, ya no tendrá que intentar adivinar la API de un paquete en particular que haya instalado. Si es una máquina, entonces puedes esperar que siga la misma interfaz fácil de usar.

    Ahora que sabemos qué son las máquinas, analicemos las especificaciones analizando una máquina de muestra.

    La especificación de la máquina

     module.exports = { friendlyName: 'Do something', description: 'Do something with the provided inputs that results in one of the exit scenarios.', extendedDescription: 'This optional extended description can be used to communicate caveats, technical notes, or any other sort of additional information which might be helpful for users of this machine.', moreInfoUrl: 'https://stripe.com/docs/api#list_cards', sideEffects: 'cacheable', sync: true, inputs: { brand: { friendlyName: 'Some input', description: 'The brand of gummy worms.', extendedDescription: 'The provided value will be matched against all known gummy worm brands. The match is case-insensitive, and tolerant of typos within Levenstein edit distance = 2 (if ambiguous, prefers whichever brand comes first alphabetically).', moreInfoUrl: 'https://gummy-worms.org/common-brands?countries=all', required: true, example: 'haribo', whereToGet: { url: 'https://gummy-worms.org/how-to-check-your-brand', description: 'Look at the giant branding on the front of the package. Copy and paste with your brain.', extendedDescription: 'If you don't have a package of gummy worms handy, this probably isn't the machine for you. Check out the `order()` machine in this pack.' } } }, exits: { success: { outputFriendlyName: 'Protein (g)', outputDescription: 'The grams of gelatin-based protein in a 1kg serving.', }, unrecognizedFlavors: { description: 'Could not recognize one or more of the provided `flavorStrings`.', extendedDescription: 'Some **markdown**.', moreInfoUrl: 'https://gummyworms.com/flavors', } }, fn: function(inputs, exits) { // ... // your code here var result = 'foo'; // ... // ...and when you're done: return exits.success(result); };}

    El fragmento anterior está tomado del ejemplo interactivo del sitio web oficial. Analicemos esta máquina.

     

    Al observar el fragmento anterior, podemos ver que una máquina es un objeto exportado que contiene ciertas propiedades estandarizadas y una única función. Veamos primero cuáles son esas propiedades y por qué son así.

    • friendlyName
      Este es un nombre para mostrar para la máquina y sigue estas reglas:
      • es oración-caso (como una oración normal),
      • no debe tener puntuación final,
      • debe tener menos de 50 caracteres.
    • description
      Debe ser una descripción clara de una frase en modo imperativo (es decir, la voz autoritaria) de lo que hace la máquina. Un ejemplo sería "Emitir un token web JSON", en lugar de "Emitir un token web JSON". Su única restricción es:
      • Debe tener menos de 80 caracteres.
    • extendedDescription(opcional)
      Esta propiedad proporciona información complementaria opcional, ampliando lo que ya se dijo en la propiedad de descripción. En este campo, puede utilizar puntuación y oraciones completas.
      • Debe tener menos de 2000 caracteres.
    • moreInfoUrl(opcional)
      Este campo contiene una URL en la que se puede encontrar información adicional sobre el funcionamiento interno o la funcionalidad de la máquina. Esto es particularmente útil para máquinas que se comunican con API de terceros como GitHub y Auth0.
      • Asegúrese de utilizar una URL completa, como https://xyz.abc/qwerty
    • sideEffects(opcional)
      Este es un campo opcional que puede omitir o establecer como cacheableo idempotent. Si se establece en cacheable, se .cache()puede utilizar con esta máquina. Tenga en cuenta que sólo las máquinas que no lo tengan sideEffectsdeben configurarse en cacheable.
    • sync(opcional)
      Las máquinas son asíncronas de forma predeterminada. Configurar la syncopción para truedesactivar la sincronización para esa máquina, y luego puede usarla como una función normal (sin async/ awaito then()).

    entradas

    Esta es la especificación o declaración de los valores que espera la función de la máquina. Veamos los diferentes campos de entrada de una máquina.

     

    • brand
      Usando el fragmento de máquina anterior como guía, el campo de marca se denomina clave de entrada. Normalmente está en mayúsculas y debe ser una cadena alfanumérica que comienza con una letra minúscula.
      • No se permiten caracteres especiales en un campo o identificador de clave de entrada.
    • friendlyName
      Este es un nombre para mostrar legible por humanos para la entrada. Debería:
      • ser caso-oración,
      • no tener puntuación final,
      • tener menos de 50 caracteres.
    • description
      Esta es una breve descripción que describe el uso de la entrada.
    • extendedDescription
      Al igual que el extendedDescriptioncampo de la propia máquina, este campo proporciona información complementaria sobre esta entrada en particular.
    • moreInfoUrl
      Esta es una URL opcional que proporciona más información sobre la entrada, si es necesario.
    • required
      De forma predeterminada, cada entrada es opcional. Lo que eso significa es que si, en tiempo de ejecución, no se proporciona ningún valor para una entrada, entonces no fnestaría definido. Si sus entradas no son opcionales, entonces es mejor configurar este campo como verdadero porque esto haría que la máquina arrojara un error.
    • example
      Este campo se utiliza para determinar el tipo de datos esperado de la entrada.
    • whereToGet
      Este es un objeto de documentación opcional que proporciona información adicional sobre cómo localizar valores adecuados para esta entrada. Esto es particularmente útil para cosas como claves API, tokens, etc.
    • whereToGet.description
      Esta es una descripción clara de una oración, también en modo imperativo, que describe cómo encontrar el valor correcto para esta entrada.
    • extendedDescription
      Esto proporciona información adicional sobre dónde obtener un valor de entrada adecuado para esta máquina.

    salidas

    Esta es la especificación para todas las posibles devoluciones de llamada de salida que la fnimplementación de esta máquina puede desencadenar. Esto implica que cada salida representa un posible resultado de la ejecución de la máquina. Diets, plans and health

    • success
      Esta es la clave de salida estandarizada en las especificaciones de la máquina que significa que todo salió bien y que la máquina funcionó sin errores. Veamos las propiedades que podría exponer:
      • outputFriendlyName
        Este es simplemente un nombre para mostrar para la salida de salida.
      • outputDescription
        Esta breve frase nominal describe el resultado de una salida.

    Otras salidas significan que algo salió mal y que la máquina encontró un error. La convención de nomenclatura para dichas salidas debe seguir la convención de nomenclatura de la clave de entrada. Veamos los campos debajo de dichas salidas:

     

    • description
      Esta es una breve descripción que describe cuándo se llamaría a la salida.
    • extendedDescription
      Esto proporciona información adicional sobre cuándo se llamaría esta salida. Es opcional. Puede utilizar la sintaxis completa de Markdown en este campo y, como siempre, debe tener menos de 2000 caracteres.

    ¡Lo hiciste!

    Eso fue mucho para asimilar. Pero no se preocupe: cuando comience a crear máquinas, estas convenciones se mantendrán, especialmente después de su primera máquina, que escribiremos juntos en breve. Pero primero…

    Paquetes de máquinas

    Al crear máquinas, los paquetes de máquinas son lo que publica en npm. Son simplemente conjuntos de utilidades relacionadas para realizar tareas de desarrollo comunes y repetitivas con Node.js. Entonces digamos que tienes un paquete de máquina que funciona con matrices; sería un conjunto de máquinas que funcionan en matrices, como concat(), map()etc. Consulte el paquete de máquinas Arrays en el registro para obtener una vista completa.

    Convención de nomenclatura de Machinepacks

    Todos los paquetes de máquinas deben seguir el estándar de tener "machinepack-" como prefijo, seguido del nombre de la máquina. Por ejemplo, machinepack-array, machinepack-sessionauth.

    Nuestro primer paquete de máquinas

    Para comprender mejor las máquinas, escribiremos y publicaremos un paquete de máquina que es un contenedor para el paquete npm de contribuyentes de archivos .

    Empezando

    Requerimos lo siguiente para elaborar nuestro paquete de máquinas:

    1. Herramienta CLI de Machinepack
      Puede obtenerla ejecutando:
      npm install -g machinepack
    2. Herramienta de andamios Yeoman
      Instálelo globalmente ejecutando:
       npm install -g yo
    3. Generador Machinepack Yeomen
      Instálelo así:
      npm install -g generator-machinepack

    Nota : Supongo que Node.js y npm ya están instalados en su máquina.

    Generando su primer Machinepack

    Usando las herramientas CLI que instalamos anteriormente, generemos un nuevo paquete de máquina usando el generador de paquetes de máquina. Haga esto ingresando primero al directorio en el que desea que el generador genere los archivos y luego ejecute lo siguiente:

    yo machinepack

    El comando anterior iniciará un proceso interactivo para generar un paquete de máquina básico para usted. Le hará un par de preguntas; asegúrese de decirle que sí creando una máquina de ejemplo.

    Nota: Noté que el generador Yeoman tiene algunos problemas al usar Node.js 12 o 13. Por lo tanto, recomiendo usar nvm e instalar Node.js 10.x, que es el entorno que funcionó para mí.

     

    Si todo ha salido según lo planeado, entonces habremos generado la capa base de nuestro paquete de máquinas. Echemos un vistazo:

    DELETE_THIS_FILE.mdmachines/package.jsonpackage.lock.jsonREADME.mdindex.jsnode_modules/

    Los anteriores son los archivos generados para usted. Juguemos con nuestra máquina de ejemplo, que se encuentra dentro del machinesdirectorio. Como tenemos instalada la herramienta CLI machinepack, podríamos ejecutar lo siguiente:

    machinepack ls

    Esto enumeraría las máquinas disponibles en nuestro machinesdirectorio. Actualmente existe una, la máquina de saludar. Averigüemos qué hace decir hola ejecutando esto:

    machinepack exec say-hello

    Esto le pedirá que ingrese un nombre e imprimirá el resultado de la máquina de saludo.

    Como notará, la herramienta CLI aprovecha la estandarización de las máquinas para obtener la descripción y la funcionalidad de la máquina. ¡Con buena pinta!

    Hagamos una máquina

    Agreguemos nuestra propia máquina, que empaquetará los paquetes de contribuyentes de archivos y de recuperación de nodos (también necesitaremos instalarlos con npm). Entonces, ejecuta esto:

    npm install file-contributors node-fetch --save

    Luego, agregue una nueva máquina ejecutando:

    machinepack add

    Se le pedirá que complete el nombre descriptivo, la descripción (opcional) y la descripción ampliada (también opcional) de la máquina. Después de eso, habrá generado exitosamente su máquina.

    Ahora, desarrollemos la funcionalidad de esta máquina. Abra la nueva máquina que generó en su editor. Luego, requiere el paquete file-contributors, así:

    const fetch = require('node-fetch');const getFileContributors = require('file-contributors').default;global.fetch = fetch; // workaround since file-contributors uses windows.fetch() internally

    Nota: Estamos usando el paquete node-fetch y la global.fetch = fetchsolución alternativa porque el paquete file-contributors lo usa windows.fetch()internamente, que no está disponible en Node.js.

    Los contribuyentes de archivos getFileContributorsrequieren tres parámetros para funcionar: owner(el propietario del repositorio), repo(el repositorio) y path(la ruta al archivo). Entonces, si nos han seguido, sabrán que estos irán en nuestra inputsclave. Agreguemos estos ahora:

    ... inputs: { owner: { friendlyName: 'Owner', description: 'The owner of the repository', required: true, example: 'DominusKelvin' }, repo: { friendlyName: 'Repository', description: 'The Github repository', required: true, example: 'machinepack-filecontributors' }, path: { friendlyName: 'Path', description: 'The relative path to the file', required: true, example: 'README.md' } },...

    Ahora, agreguemos las salidas. Originalmente, la CLI agregó una successsalida para nosotros. Modificaríamos esto y luego agregaríamos otra salida en caso de que las cosas no salgan según lo planeado.

    exits: { success: { outputFriendlyName: 'File Contributors', outputDescription: 'An array of the contributors on a particular file', variableName: 'fileContributors', description: 'Done.', }, error: { description: 'An error occurred trying to get file contributors' } },

    Finalmente, creemos la carne de la máquina, que es fn:

     fn: function(inputs, exits) { const contributors = getFileContributors(inputs.owner, inputs.repo, inputs.path) .then(contributors = { return exits.success(contributors) }).catch((error) = { return exits.error(error) }) },

    ¡Y voilá! Hemos fabricado nuestra primera máquina. Probémoslo usando la CLI ejecutando lo siguiente:

    machinepack exec get-file-contributors

    Aparecería un mensaje pidiendo owner, repoy path, sucesivamente. Si todo ha salido según lo planeado, nuestra máquina saldrá exitosamente y veremos una serie de contribuyentes para el archivo del repositorio que hemos especificado.

    Uso en código

    Sé que no usaremos la CLI para consumir el paquete de máquina en nuestro código base. Entonces, a continuación se muestra un fragmento de cómo consumiríamos máquinas desde un paquete de máquinas:

     var FileContributors = require('machinepack-filecontributors');// Fetch metadata about a repository on GitHub.FileContributors.getFileContributors({ owner: 'DominusKelvin', repo: 'vue-cli-plugin-chakra-ui', path: 'README.md' }).exec({ // An unexpected error occurred. error: function (){ }, // OK. success: function (contributors){ console.log('Got:n', contributors); },});

    Conclusión

    ¡Felicidades! Acaba de familiarizarse con las especificaciones de la máquina, creó su propia máquina y vio cómo consumir máquinas. Me alegrará ver las máquinas que creas.

    Recursos

    • “ Getting Started ”, máquina de nodo
    • contribuyentes de archivos , npm

    Consulte el repositorio de este artículo. El paquete npm que creamos también está disponible en npm .

    (ra, il, al)Explora más en

    • javascript
    • Marcos





    Tal vez te puede interesar:

    1. ¿Deberían abrirse los enlaces en ventanas nuevas?
    2. 24 excelentes tutoriales de AJAX
    3. 70 técnicas nuevas y útiles de AJAX y JavaScript
    4. Más de 45 excelentes recursos y repositorios de fragmentos de código

    Comprender las máquinas: un estándar abierto para funciones de JavaScript

    Comprender las máquinas: un estándar abierto para funciones de JavaScript

    Patrones de diseño de interfaces inteligentes, vídeo de 10h + formación UX Implemente rápidamente. Implementar inteligentemente Índice

    programar

    es

    https://aprendeprogramando.es/static/images/programar-comprender-las-maquinas-un-estandar-abierto-para-funciones-de-javascript-1028-0.jpg

    2024-05-21

     

    Comprender las máquinas: un estándar abierto para funciones de JavaScript
    Comprender las máquinas: un estándar abierto para funciones de JavaScript

    Si crees que alguno de los contenidos (texto, imagenes o multimedia) en esta página infringe tus derechos relativos a propiedad intelectual, marcas registradas o cualquier otro de tus derechos, por favor ponte en contacto con nosotros en el mail [email protected] y retiraremos este contenido inmediatamente

     

     

    Top 20