Gustavo Leon

Creando un router basado en archivos con Preact, preact-router y Parcel

2023-07-01T00:30:00+00:00

Para este ejercicio estoy utilizando Parcel, una build tool simple de usar y configurable a partir de plugins.

Un router basado en archivos permite que una aplicación client-side pueda armar sus rutas utilizando archivos como base. Esta convención es utilizada por frameworks como Next.js o Remix, por nombrar algunos.

Gracias a esta convención, organizar archivos se vuelve una tarea mucho más sencilla, ya que existe una relación un poco más directa entre las rutas que ven los usuarios en su navegador con la estructura de archivos que ven los programadores al desarrollar una aplicación web frontend.

Como un ejercicio para aprender cómo funciona el plugin de resolver de Parcel, vamos a ver cómo crear un router basado en archivos utilizando Preact y preact-router.

Este acercamiento a tener un router basado en archivos es experimental y más un ejercicio inicial que una implementación lista para producción.

El resultado final será que lograremos tener una aplicación con rutas completamente funcional con una estructura de archivos como esta:

./app/organizations/[subdomain]/layout.js
./app/organizations/[subdomain]/page.js
./app/organizations/[subdomain]/courses/layout.js
./app/organizations/[subdomain]/courses/page.js
./app/organizations/[subdomain]/courses/[identifier]/layout.js
./app/organizations/[subdomain]/courses/[identifier]/page.js
./app/organizations/[subdomain]/courses/[identifier]/cohorts/page.js
./app/organizations/[subdomain]/courses/[identifier]/edit/page.js
./app/organizations/[subdomain]/users/page.js
./app/organizations/new/page.js
./app/organizations/(course_editor)/[subdomain]/courses/[identifier]/[section]/[lesson]/layout.js
./app/organizations/(course_editor)/[subdomain]/courses/[identifier]/[section]/[lesson]/page.js

Y un archivo index.js como este:

import { render } from "preact";
import Router from "@hpneo/router";

render(<Router />, document.body);

Creando un resolver de Parcel

Un resolver en Parcel toma un specifier (lo que comúnmente es la ruta de un archivo o el nombre de un módulo de NPM) y devuelve un resultado que luego es usado por otros resolvers o por transformers.

El resolver que escribiremos interceptará los import a @hpneo/router y devolverá el código que le indiquemos, también llamado virtual module, porque el módulo definido por el specifier no existe “físicamente” como un archivo en la carpeta del proyecto.

Lo primero que haremos será escribir la estructura básica de un resolver:

// ./parcel-resolver-router/index.mjs
import { Resolver } from "@parcel/plugin";
import path from "path";

export default new Resolver({
  async resolve({ specifier, options }) {
    if (specifier === "@hpneo/router") {
      const code = ``;

      return {
        filePath: path.join(options.projectRoot, "router.js"),
        code: code
      };
    }
  }
});

Este resolver actualmente solo devuelve un virtual module vacío. Sin embargo, contiene 2 detalles importantes a tener en cuenta: specifier es el nombre del módulo que estamos interceptando, y options contiene una propiedad llamada projectRoot, que devuelve la ruta desde donde Parcel está ejecutándose.

El siguiente paso es obtener todos los archivos que nos servirán para armar nuestras rutas. En este caso usaremos la convención de Next.js y su nuevo App Router, y usaremos fast-glob para obtener todos los archivos llamados page.js.

El siguiente bloque de código va dentro del método resolve de nuestro plugin:

import glob from "fast-glob";

const files = await glob("./app/**/page.js", {
  ignore: ["node_modules"],
  cwd: options.projectRoot,
});

// [
//   './app/organizations/[subdomain]/page.js',
//   './app/organizations/new/page.js',
//   './app/organizations/[subdomain]/courses/page.js',
//   './app/organizations/[subdomain]/users/page.js',
//   './app/organizations/[subdomain]/courses/[identifier]/page.js',
//   './app/organizations/[subdomain]/courses/[identifier]/cohorts/page.js',
//   './app/organizations/[subdomain]/courses/[identifier]/edit/page.js',
//   './app/organizations/[subdomain]/courses/[identifier]/[section]/[lesson]/page.js'
// ]

Una vez que tenemos las rutas de todos los archivos, vamos a iterar por cada uno de ellos para obtener la ruta de la aplicación a partir de la ruta del archivo:

// ./parcel-resolver-router/index.mjs
const DYNAMIC_ROUTE_SEGMENT_PATTERN = /\[([a-zA-Z]*)\]/;
const CATCH_ALL_SEGMENT_PATTERN = /\[(\.\.\.([a-zA-Z]*))\]/;
const ROUTE_GROUP_PATTERN = /\(([a-zA-Z_-]*)\)/;

function buildRouteFromFilePath(filePath) {
  const pageRoute = filePath
    .replace(/^\.\/app/, "")
    .replace(/\/page\.js$/, "")
    .split("/")
    .map((segment) =>
      segment
        .replace(CATCH_ALL_SEGMENT_PATTERN, ":$2*")
        .replace(DYNAMIC_ROUTE_SEGMENT_PATTERN, ":$1")
        .replace(ROUTE_GROUP_PATTERN, "")
    )
    .filter(Boolean)
    .join("/");

  // Las rutas de aplicación deben empezar con '/'
  return pageRoute.startsWith("/") ? pageRoute : `/${pageRoute}`;
}

Como lo que estamos retornando en el resolver es un virtual module, vamos a actualizar el código dentro del método resolve de nuestro plugin:

const files = await glob("./app/**/page.js", {
  ignore: ["node_modules"],
  cwd: options.projectRoot,
});

const code = `const pages = [
  ${files
    .map((pagePath) => {
      const pageRoute = buildRouteFromFilePath(pagePath);

      return `{
        route: "${pageRoute}",
        component: require("${pagePath}")
      }`;
    })
    .join(",\n")}
];`;

Con estos cambios, la variable pages de nuestro virtual module contiene un array de objetos con 2 propiedades: route y component, que es como vamos a importar cada página.

Soporte para layouts

Una vez que tenemos las rutas con sus respectivos módulos importados, vamos a obtener los layouts, si existieran. Un layout es un componente que envuelve al componente de una página y a todos los componentes hijo que compartan la misma ruta.

En nuestro caso, si tenemos un layout en ./app/organizations/[subdomain]/layout.js, el componente que se exporta desde ese archivo va a estar presente al renderizar las siguientes rutas:

/organizations/:subdomain
/organizations/:subdomain/courses
/organizations/:subdomain/courses/:identifier
/organizations/:subdomain/courses/:identifier/cohorts
/organizations/:subdomain/courses/:identifier/edit
/organizations/:subdomain/courses/:identifier/:section/:lesson
/organizations/:subdomain/users

Sin embargo, el layout no se renderizará en la siguiente ruta:

/organizations/new

Para obtener los layouts para cada página, haremos lo siguiente:

import fsSync from "fs";

const code = `const pages = [
  ${files
    .map((pagePath) => {
      const pageRoute = buildRouteFromFilePath(pagePath);
      const layoutPath = pagePath.replace(/page\.js$/, "layout.js");
      const hasLayout = fsSync.existsSync(layoutPath);
      const layout = hasLayout ? `require("${layoutPath}")` : "null";

      return `{
        route: "${pageRoute}",
        component: require("${pagePath}"),
        layout: ${layout}
      }`;
    })
    .join(",\n")}
];`;

Soporte para route groups

Los route groups permiten agrupar rutas de manera lógica sin afectar la URL final en la aplicación, y sirven para poder tener múltiples root layouts.

Dado que los route groups se definen con carpetas con nombre siguiente el formato (nombre), solo tenemos que verificar si cumple esa condición con una expresión regular:

const ROUTE_GROUP_PATTERN = /\(([a-zA-Z_-]*)\)/;

const code = `const pages = [
  ${files
    .map((pagePath) => {
      const pageRoute = buildRouteFromFilePath(pagePath);
      const layoutPath = pagePath.replace(/page\.js$/, "layout.js");
      const hasLayout = fsSync.existsSync(layoutPath);
      const layout = hasLayout ? `require("${layoutPath}")` : "null";
      const isPartOfRouteGroup = !!pagePath.match(ROUTE_GROUP_PATTERN);

      return `{
        route: "${pageRoute}",
        component: require("${pagePath}"),
        layout: ${layout},
        isPartOfRouteGroup: ${isPartOfRouteGroup}
      }`;
    })
    .join(",\n")}
];`;

Renderizando rutas con `preact-router`

Ahora que ya tenemos una colección de rutas, vamos a usar preact-router para renderizarlas en una aplicación de Preact.

Pero antes de hacer eso debemos entender que hay rutas que pueden estar anidadas, por lo que debemos convertir nuestro array en un árbol. Para eso, agregamos la siguiente función al código del virtual module:

// Este bloque de código va dentro de la variable `code`, como parte del código del virtual module:
import sortBy from "lodash/sortBy";
import partition from "lodash/partition";

function createRoutesFromPages(pages) {
  const routes = [];

  // Dado que las rutas son anidadas, es mejor si ordenamos nuestra colección de rutas de menor a mayor cantidad de caracteres.
  // Esto nos sirve para poder trabajar primero las rutas padre y luego las rutas hijas.
  let sortedPagesByRouteLength = sortBy(pages, (page) => page.route.length);

  while (sortedPagesByRouteLength.length > 0) {
    const page = sortedPagesByRouteLength.shift();

    // Usamos la función de Lodash llamada `partition` para dividir las rutas restantes entre
    // las que sí son hijas de la ruta actual y las que no
    const [childrenPages, otherPages] = partition(
      sortedPagesByRouteLength,
      (childPage) => {
        // Si una ruta es parte de un route group, la ponemos al mismo nivel que la ruta actual
        if (childPage.isPartOfRouteGroup) {
          return false;
        }

        return childPage.route.startsWith(page.route);
      }
    );

    sortedPagesByRouteLength = otherPages;

    routes.push({
      ...page,
      children: createRoutesFromPages(childrenPages),
    });
  }

  return routes;
}

Dado que las rutas van a estar anidadas, necesitamos un componente especial que pueda ser usando del router de preact-router. Este componente se llama Route y va a manejar todos los posibles escenarios de nuestra aplicación:

// Este bloque de código va dentro de la variable `code`, como parte del código del virtual module:
import { h, Fragment } from "preact";
import Router from "preact-router";

// El componente `<Router />` de `preact-router` espera que sus componentes hijo tengan un prop `path`, así que lo pasamos acá
function Route({ path, component, layout, childRoutes = [], ...routeProps }) {
  childRoutes = Array.isArray(childRoutes) ? childRoutes : [childRoutes];

  // Creamos un elemento de Preact usando `h` de `preact`.
  // Como veremos luego, `component` es el componente que exporta cada archivo page.js
  const element = h(component, { path });
  // `layout` también es un componente, pero si no existe usamos `<Fragment />` de `preact`
  const LayoutOrFragment = layout ?? Fragment;

  // Si esta ruta no tiene rutas hija, simplemente renderizamos el componente con su layout
  if (childRoutes.length === 0) {
    return <LayoutOrFragment {...routeProps}>{element}</LayoutOrFragment>;
  }

  // Pero si la ruta tiene rutas hija, creamos un nested router, y le pasamos las rutas hija como un array de `<Route />`
  return (
    <LayoutOrFragment {...routeProps}>
      <Router>
        {element}
        {childRoutes.map((page) => (
          <Route
            key={page.route}
            // Si una de las rutas hija tiene más rutas hija, debemos hacer que el path soporte routers anidados
            path={page.children.length === 0 ? page.route : `${page.route}/:rest*`}
            component={page.component.default}
            layout={page.layout?.default}
            childRoutes={page.children}
          />
        ))}
      </Router>
    </LayoutOrFragment>
  );
}

Finalmente, creamos nuestro componente <ApplicationRouter />, el cual tendrá todas las rutas creadas con <Route /> en base al resultado de createRoutesFromPages:

// Este bloque de código va dentro de la variable `code`, como parte del código del virtual module:
function ApplicationRouter() {
  const routes = createRoutesFromPages(pages);

  if (routes.length === 0) {
    return null;
  }

  return (
    <Router>
      {routes.map((page) => (
        <Route
          key={page.route}
          // Si una de las rutas hija tiene más rutas hija, debemos hacer que el path soporte routers anidados
          path={page.children.length === 0 ? page.route : `${page.route}/:rest*`}
          component={page.component.default}
          layout={page.layout?.default}
          childRoutes={page.children}
        />
      ))}
    </Router>
  );
}

export default ApplicationRouter;

Y si bien con esto ya tenemos nuestro propio router basado en archivos, hay un último punto que debemos tener en cuenta: Si levantamos el proyecto con Parcel y agregamos luego nuevos archivos page.js o layout.js, nuestro router no reflejará las nuevas rutas. Esto es debido a que los plugins de Parcel usan una caché, por lo que debemos invalidar la caché de Parcel bajo ciertos escenarios.

Invalidar caché de Parcel

Para invalidar la caché de nuestro resolver, debemos agregar ciertas propiedades al objeto que retorna la función resolve:

import { Resolver } from "@parcel/plugin";
import path from "path";

export default new Resolver({
  async resolve({ specifier, options }) {
    if (specifier === "@hpneo/router") {
      const glob_pattern = "./app/**/page.js";
      const glob_layout_pattern = "./app/**/layout.js";

      const files = await glob(glob_pattern, fs, {
        ignore: ["node_modules"],
        cwd: options.projectRoot,
      });
      const layouts = await glob(glob_layout_pattern, fs, {
        ignore: ["node_modules"],
        cwd: options.projectRoot,
      });

      const code = `...`;

      return {
        filePath: path.join(options.projectRoot, "router.js"),
        code: code,
        // Le decimos a Parcel que invalide cualquier archivo que cumpla con los patrones glob para `page.js` o `layout.js`
        invalidateOnFileCreate: [
          { glob: glob_pattern },
          { glob: glob_layout_pattern },
        ],
        // Le decimos a Parcel que invalide cualquier cambio en los archivos `page.js` o `layout.js` dentro de "./app":
        invalidateOnFileChange: [
          ...files.map((filePath) => path.join(options.projectRoot, filePath)),
          ...layouts.map((filePath) => path.join(options.projectRoot, filePath)),
        ],
      };
    }
  }
});

Si quisieramos soportar otras convenciones de nombres de archivos, como error.js o template.js, también debemos incluirlos aquí en invalidateOnFileCreate y invalidateOnFileChange.

El código completo del plugin de Parcel lo puedes encontrar en este Gist: https://gist.github.com/hpneo/c9e9e61e9d530d6c412163f20d8a7df4

Creando un clon de Storybook desde 0 con Parcel

2023-06-28T01:10:00+00:00

Storybook permite mostrar en un solo lugar los componentes que utilizas en tu aplicación. Esto es útil si tienes componentes reutilizables y quieres documentar cómo se ven y cómo se usan sin necesidad de ir al código.

Como un ejercicio para aprender cómo funcionan el plugin de transformer de Parcel, vamos a crear un clon de Storybook.

Component Story Format (o CSF)

El primer paso es entender que Storybook funciona leyendo archivos llamados stories (o historias), los cuales son archivos de JavaScript cuyo nombre termina en .stories.js. Esto es una convención y puede cambiarse en la configuración de Storybook; pero lo importante es que, al fin y al cabo, estos archivos siguen un formato llamado Component Story Format, o CSF.

Un ejemplo básico es CSF es este archivo que llamaremos button.stories.js:

// Importamos el componente que usaremos en nuestras stories
import { Button } from "../src/ui";

// Definimos un objeto llamado meta (el nombre no importa), que luego exportaremos como default.
const meta = {
  title: "Components/Button",
  component: Button,
};

// Definimos una variable Basic que también exportaremos.
export const Basic = {
  args: {
    variant: "primary",
    children: "Click Me!",
    loading: false,
  },
  render(args) {
    return <Button {...args} />;
  },
};

// Finalmente exportamos meta como default.
export default meta;

La story más simple posible, siguiendo el Component Story Format, tiene 2 exports: un default export y un named export. El default export contiene meta datos sobre la story, como el componente del que se está escribiendo, o el título de la story.

Por otro lado, el named export es un objeto que tiene 2 propiedades: args y render. A su vez, args es un objeto que contiene los props del componente que el usuario puede configurar mediante un panel de control, y render es una función que retorna el componente del que estamos escribiendo, y que también recibe una copia de args como argumento. Cada vez que los valores de args cambian, Storybook vuelve a llamar a render y el componente se re-renderiza.

Ahora que ya sabemos como funciona una story, vamos a crear nuestro propio Storybook.

Obteniendo todos los archivos `.stories.js`

Para este ejercicio estoy utilizando Parcel, una build tool simple de usar y configurable a partir de plugins.

Para poder listar todas las stories que existen en nuestro proyecto, necesitamos primero importar todos los archivos JavaScript que terminen en .stories.js. Para lograr esta primera tarea usaremos un paquete llamado @parcel/resolver-glob.

Los resolvers se encargan de resolver un import, ya sea convirtiendo el specifier de un import (lo que comunmente es el nombre del módulo) en la ruta absoluta de un archivo o retornando código. Esto último se conoce como virtual module, porque el módulo definido por el specifier no existe “físicamente” como un archivo.

Lo que hace @parcel/resolver-glob es utilizar el specifier como si fuera un patrón llamado glob, y retorna un objeto con todos los módulos que cumplen con el patrón.

import * as stories from "../stories/**/*.stories.js";

console.log(stories);
// {
//   button: {
//     default: { title: "Components/Button", component: ... },
//     Basic: { args: { variant: "primary", children: "Click Me!", loading: false }, render: ... }
//   }
// }

Para poder utilizar un resolver dentro de nuestra aplicación, debemos agregarlo en la configuración de Parcel (.parcelrc):

{
  "extends": "@parcel/config-default",
  "resolvers": ["@parcel/resolver-glob", "..."]
}

Una vez que ya tenemos los módulos importados en nuestro archivo, debemos obtener más información sobre los componentes que vamos a probar en las stories.

Obteniendo información de los componentes con `react-docgen`

Si bien ya importamos los módulos de nuestras stories, es muy poco lo que podemos hacer con ellas, excepto quizá renderizar los named exports.

Si quisieramos crear una interfaz gráfica que nos permita cambiar los valores de las propiedades definidas en args, necesitamos saber de qué tipo de dato es cada atributo de ese objeto. Dado que args en realidad representa los valores que tienen los props de un componente, usamos react-docgen para obtener la información de los props directamente del componente. ¿Cómo podemos hacer eso?

En la sección anterior vimos los resolvers de Parcel, pero Parcel tiene otro tipo de plugin que es igual o más útil: los transformers. Un transformer toma un asset (por ejemplo: un módulo de JavaScript) y lo transforma, pudiendo retornar código que es cualquier otra cosa excepto el código original del asset. En este caso, vamos a usar un transformer para obtener información del componente, mediante react-docgen.

Lo que hace este transformer es obtener el código fuente del asset con asset.getCode(), para luego pasárselo a ReactDocGen. Luego, ReactDocGen analiza el código y retorna información de los props del componente, utilizando la propiedad propTypes del componente.

Si deseas hacer lo mismo pero tus componentes están escritos en TypeScript, puedes usar react-docgen-typescript.

Una vez que obtenemos la información de los props de un componente, usamos una expresión regular para cambiar el código original e incluir lo devuelto por ReactDocGen como una propiedad más del component. Otra forma de lograr el mismo resultado es manipulando el AST con alguna biblioteca que permita eso, como @babel/core.

Finalmente, reemplazamos el código original del asset por el editado, con asset.setCode(output). No debemos olvidar asegurarnos que el asset sea de tipo js, para que Parcel siga procesando el archivo en caso hayan otros transformers en su pipeline.

import { Transformer } from "@parcel/plugin";
import ReactDocGen from "react-docgen";

export default new Transformer({
  async transform({ asset }) {
    try {
      const source = await asset.getCode();
      const code = ReactDocGen.parse(source);

      const output = source.replace(
        /export default ([a-zA-Z]*)/,
        (substring, group) => {
          return `${group}.__docgenInfo = ${JSON.stringify(
            code
          )};\n\n${substring}`;
        }
      );

      asset.type = "js";
      asset.setCode(output);
    } catch (error) {}

    return [asset];
  },
});

A diferencia de los resolvers, los transformers pueden ser definidos como parte de un pipeline específico, los cuales son diferenciados utilizando globs. En este caso, quiero que mi transformer solo sea utilizado en los archivos .js dentro de la carpeta src/ui.

{
  "extends": "@parcel/config-default",
  "resolvers": ["@parcel/resolver-glob", "..."],
  "transformers": {
    "src/ui/*.js": ["./parcel-transformer-react-docgen/index.mjs", "..."]
  }
}

Los "..." al final del pipeline le dicen a Parcel que debe seguir procesando esos archivos con el pipeline por defecto para archivos .js.

Con este pequeño ejercicio hemos aprendido a utilizar los plugins resolvers de Parcel, y cómo escribir nuestro propio transformer. Con estos 2 plugins, cubrimos la funcionalidad básica de Storybook, pero se puede extender utilizando otras bibliotecas, como @storybook/csf-tools.

Persistiendo estados de React con Web Storage

2021-02-25T13:30:00+00:00

La API de Web Storage permite guardar datos dentro del navegador en forma llave/valor. Con Web Storage podamos persistir datos en el navegador y volver a leerlos incluso después de haber recargado una página, lo cual es útil si queremos guardar datos sobre configuración de usuario, o incluso usarlo como caché.

Existen dos tipos de Web Storage, localStorage y sessionStorage, y ambos comparten las mismas propiedades, métodos y eventos. Así mismo, ambos comparten las siguientes características:

Crean un espacio por cada origen (un origen está formado por el protocolo y el host).
Cada espacio no comparte información con otros espacios de otros orígenes.
Los datos persisten las recargas de página.
Cada espacio está limitado a guardar 5MB como máximo.

La principal diferencia entre ambos tipos es que sessionStorage borra los datos al momento que el tab o la ventana del navegador se cierra, mientras que localStorage mantiene los datos guardados hasta que son manualmente eliminados.

Como ambos tienen una interfaz similar, vamos a usar localStorage en este post, pero el mismo código se puede aplicar para sessionStorage (teniendo en cuenta sus limitaciones).

Accediendo a elementos del Storage

Si revisamos localStorage vamos a ver que parece ser solo un objeto con algunas entradas:

Mi localStorage desde https://developer.mozilla.org/

Esto significa que podemos acceder a las entradas de localStorage como si accediéramos a cualquier objeto en JavaScript:

localStorage['banner.developer_needs.embargoed_until'];
// "1604634596534"

Sin embargo, localStorage también tiene un método llamado getItem que cumple la misma función:

localStorage.getItem('banner.developer_needs.embargoed_until');
// "1604634596534"

Escribiendo en el Storage

Como ya vimos, localStorage se comporta como un objeto en JavaScript, lo que significa que también podemos guardar valores de la misma forma que guardamos valores en un objeto:

localStorage['banner.developer_needs.embargoed_until'] = Date.now();
// 1614099381524

Y de igual forma, localStorage tiene un método setItem que hace exactamente lo mismo:

localStorage.setItem('banner.developer_needs.embargoed_until', Date.now());
// undefined

Hasta aquí no hay nada fuera de lo común con Web Storage, excepto por un tema bastante particular: Los valores son guardados como cadenas. Volviendo al ejemplo anterior:

localStorage['banner.developer_needs.embargoed_until'];
// "1614099592460"

localStorage.getItem('banner.developer_needs.embargoed_until');
// "1614099592460"

Sabemos que Date.now() devuelve un número, pero al acceder a la propiedad banner.developer_needs.embargoed_until de localStorage, lo que obtenemos es una cadena. ¿Qué pasa si queremos guardar un objeto dentro de localStorage?

const userConfiguration = {
  receiveNotifications: false,
  displaySubscriptionBanner: true,
  enableGeolocation: false,
};

localStorage.setItem('userConfiguration', userConfiguration);

// Ahora tratamos de leer el objeto guardado en localStorage.
// La línea después de `localStorage.getItem...` es el resultado:
localStorage.getItem('userConfiguration');
// "[object Object]"

Como vemos, en vez de obtener el objeto userConfiguration tenemos una cadena "[object Object]". Esto es por el type coercion de JavaScript, que convierte el objeto en una cadena. Felizmente, tenemos una forma fácil de convertir objetos en cadenas: JSON.stringify.

JSON.stringify convierte cualquier valor de JavaScript a una cadena usando su representación en JSON, que es justamente lo que necesitamos ahora.

const userConfiguration = {
  receiveNotifications: false,
  displaySubscriptionBanner: true,
  enableGeolocation: false,
};

localStorage.setItem('userConfiguration', JSON.stringify(userConfiguration));

localStorage.getItem('userConfiguration');
// "{"receiveNotifications":false,"displaySubscriptionBanner":true,"enableGeolocation":false}"

Luego de esta extensa introducción, podemos ver el tema que da título a este post: ¿Cómo podemos usar localStorage para persistir algunos estados de React?

Creando nuestro propio hook en React

Los hooks son una funcionalidad de las tantas ofrecidas por React para poder trabajar dentro de los componentes creados a través de funciones. En particular nos interesa usar el hook useState, con el cual podemos leer y escribir estados dentro de un componente.

Supongamos que queremos guardar la configuración del usuario en nuestra aplicación, y para eso tenemos el siguiente componente:

import React, { useState } from 'react';
import UserConfigurationForm from './UserConfigurationForm';

function UserConfigurationDashboard() {
  const [userConfiguration, setUserConfiguration] = useState({});

  return (
    <UserConfigurationForm onSubmit={(data) => setUserConfiguration(data)} />
  );
}

El componente <UserConfigurationDashboard /> está usando useState para crear un estado que almacenará la configuración del usuario. Este estado luego es actualizado cuando el componente <UserConfigurationForm /> lanza un evento onSubmit.

Este componente funciona sin problemas pero, si refrescamos la página, el estado de <UserConfigurationDashboard /> vuelve a su valor inicial ({}). Para evitar esto usaremos localStorage.

El primer paso será hacer que el valor inicial de el estado venga de localStorage:

import React, { useState } from 'react';
import UserConfigurationForm from './UserConfigurationForm';

function UserConfigurationDashboard() {
  const initialUserConfiguration = localStorage.getItem('userConfiguration');
  const [userConfiguration, setUserConfiguration] = useState(initialUserConfiguration);

  return (
    <UserConfigurationForm onSubmit={(data) => setUserConfiguration(data)} />
  );
}

Como ya sabemos, los valores de localStorage son guardados como cadenas, por lo que debemos convertirlos a objetos usando la contraparte de JSON.stringy: la función JSON.parse:

import React, { useState } from 'react';
import UserConfigurationForm from './UserConfigurationForm';

function UserConfigurationDashboard() {
  const initialUserConfiguration = JSON.parse(localStorage.getItem('userConfiguration'));
  const [userConfiguration, setUserConfiguration] = useState(initialUserConfiguration);

  return (
    <UserConfigurationForm onSubmit={(data) => setUserConfiguration(data)} />
  );
}

Ahora nuestro estado userConfiguration siempre va iniciar con el valor que venga del localStorage, pero ahora notamos algo: Realmente no estamos persistiendo cualquier nuevo valor ingresado por el usuario. Esto es porque en ninguna parte hemos usado setItem.

Para sincronizar nuestro estado con localStorage vamos a usar un nuevo hook llamado useEffect. Este hook tiene dos partes: una función (también llamada callback) y un arreglo de dependencias; y ejecuta el callback cuando cualquier elemento del arreglo de dependencias es actualizado.

En este caso, cada vez que el estado userConfiguration se actualice, lo grabaremos en el localStorage:

import React, { useState, useEffect } from 'react';
import UserConfigurationForm from './UserConfigurationForm';

function UserConfigurationDashboard() {
  const initialUserConfiguration = JSON.parse(localStorage.getItem('userConfiguration'));
  const [userConfiguration, setUserConfiguration] = useState(initialUserConfiguration);

  useEffect(() => {
    // Recuerda usar `JSON.stringify` para convertir un objeto en cadena con formato JSON.
    localStorage.setItem('userConfiguration', JSON.stringify(userConfiguration));
  }, [userConfiguration]);

  return (
    <UserConfigurationForm onSubmit={(data) => setUserConfiguration(data)} />
  );
}

Ahora que ya tenemos la lógica lista podemos trabajar en crear nuestro propio hook, y para hacer eso vamos a mover esta lógica a una nueva función:

import React, { useState, useEffect } from 'react';
import UserConfigurationForm from './UserConfigurationForm';

// La convención es que todos los hooks deben empezar con `use`.
// Le pasamos un `defaultValue` como valor por defecto, en caso la entrada no exista en `localStorage`.
function useUserConfiguration(defaultValue) {
  const initialUserConfiguration = JSON.parse(localStorage.getItem('userConfiguration')) || defaultValue;
  const [userConfiguration, setUserConfiguration] = useState(initialUserConfiguration);

  useEffect(() => {
    // Recuerda usar `JSON.stringify` para convertir un objeto en cadena con formato JSON.
    localStorage.setItem('userConfiguration', JSON.stringify(userConfiguration));
  }, [userConfiguration]);

  return [userConfiguration, setUserConfiguration];
}

function UserConfigurationDashboard() {
  const [userConfiguration, setUserConfiguration] = useUserConfiguration({});

  return (
    <UserConfigurationForm onSubmit={(data) => setUserConfiguration(data)} />
  );
}

De esta forma hemos encapsulado parte de la lógica del componente dentro de un hook e incluso aprovechamos en agregar soporte para valores por defecto. Pero como eso no es suficiente, vamos a hacerlo un poco más genérico y reutilizable:

import React, { useState, useEffect } from 'react';
import UserConfigurationForm from './UserConfigurationForm';

function useLocalStorageState(localStorageKey, defaultValue) {
  const initialValue = JSON.parse(localStorage.getItem(localStorageKey)) || defaultValue;
  const [value, setValue] = useState(initialValue);

  useEffect(() => {
    localStorage.setItem(localStorageKey, JSON.stringify(value));
  }, [value]);

  return [value, setValue];
}

function UserConfigurationDashboard() {
  const [userConfiguration, setUserConfiguration] = useLocalStorageState('userConfiguration', {});

  return (
    <UserConfigurationForm onSubmit={(data) => setUserConfiguration(data)} />
  );
}

Con este hook propio hemos aprendido a trabajar con la API de Web Storage dentro de React. Si bien el ejemplo usa localStorage, el mismo código puede usarse con sessionStorage; e incluso se puede extender useLocalStorageState para poder elegir entre una y otra opción para persistir nuestros estados.

Pasando datos síncronamente desde Rails hacia React

2021-02-23T00:30:00+00:00

Una de las cosas que más me gustan de Webpacker es lo fácil es que es integrar React en una aplicación Rails. Si bien hay otras formas de tener una aplicación de React, como CRA, manejar el frontend y el backend en una sola aplicación sigue siendo el enfoque con el que más me siento cómodo.

Una de las ventajas de tener React integrado con Rails es que podemos enviar datos en la carga inicial de la página sin necesidad de hacer peticiones asíncronas. De esta forma podemos, por ejemplo, enviar datos sobre el usuario actual, una lista de categorías, configuración inicial, etc.

Para lograr esto, vamos a necesitar trabajar tanto por el lado de Rails como por el lado de React; y para eso usaremos el DOM y JSON.

Renderizando datos para React desde Rails

Al estar en el lado del cliente, podemos usar JavaScript para leer el HTML que devuelve Rails, que luego podemos incluir en cualquier componente. Y para seguir aprovechando las ventajas del lenguaje, usaremos JSON para pasar datos de un ambiente (backend con Rails) a otro (frontend con React).

Para conseguir esto, vamos a crear una etiqueta <script> dentro de una vista de Rails:

<script type="application/json" id="root-initial-state-data">
</script>

<!-- Nuestro nodo raíz, donde React montará la aplicación que hemos construido. -->
<main id="root"></main>

Este <script> es diferente al que escribimos usualmente, por dos motivos:

Su atributo type es application/json, en vez de text/javascript (o simplemente no lleva).
Tiene un atributo id.

Esta forma de utilizar <script> nos permite incluir código JSON dentro de una página HTML de tal forma que: a) no es visible para el usuario final, y b) puede ser leído por nuestro código en el frontend, o por otras máquinas.

Una vez que tenemos esta etiqueta <script> dentro de una vista, podemos incluir código JSON usando algunos métodos de Ruby y Rails:

<script type="application/json" id="root-initial-state-data">
{
  "currentUser": <%= @current_user.to_json.html_safe %>
}
</script>

En este caso, tenemos una propiedad currentUser, cuyo valor es una variable @current_user que viene de un controller de Rails. Para poder convertir esta variable en JSON, usamos el método to_json, y html_safe para asegurarnos que el valor JSON devuelto pueda ser insertado dentro de HTML sin problemas.

Nota: Si quieres aprender sobre otros usos de esta técnica, puedes leer sobre JSON+LD.

Ahora que ya tenemos los datos disponibles para ser leídos por React, vamos a ver cómo leerlos desde un componente.

Leyendo datos del DOM con React

Como mencioné líneas arriba, React tiene acceso al DOM, por lo que leer el HTMl renderizado por Rails es relativamente sencillo.

Lo primero que debemos hacer es obtener acceso al elemento que queremos leer, para eso usaremos getElementById:

const initialDataElement = document.getElementById('root-initial-state-data');

Para poder leer el contenido de initialDataElement usamos la propiedad textContent, lo que nos devuelve una cadena con el contenido de la etiqueta:

const initialDataElement = document.getElementById('root-initial-state-data');
initialDataElement.textContent;
// '{ "currentUser": {...} }'

Llegado a este punto, solo tenemos una cadena con el contenido, y para poder trabajar con ese contenido como un objeto en JavaScript necesitamos convertirlo usando JSON.parse:

const initialDataElement = document.getElementById('root-initial-state-data');
const initialData = JSON.parse(initialDataElement.textContent);

initialData.currentUser
// { id: 1, username: ... }

Podemos agrupar esta lógica en una función, y quedaría así:

function getDOMState(elementID) {
  const initialDataElement = document.getElementById(elementID);
  const initialData = JSON.parse(initialDataElement.textContent);

  return initialData;
}

Hasta aquí, solo hemos usado JavaScript para obtener los datos que han sido renderizados por Rails, pero nos falta usarlos en React. Para lograr eso podemos llamar a la función getDOMState dentro del componente, como una variable más:

function getDOMState(elementID) {
  const initialDataElement = document.getElementById(elementID);
  const initialData = JSON.parse(initialDataElement.textContent);

  return initialData;
}

const initialData = getDOMState('root-initial-state-data');

function Home() {
  const { currentUser } = initialData;

  if (currentUser) {
    return <Dashboard />;
  }

  return <SignIn />;
}

Si queremos ir un paso más allá, podemos hacer algunas mejoras a getDOMState, para asegurarnos que JSON.parse no falle si el elemento del DOM no existe o está vacío. Para eso, haremos los siguientes cambios:

function getDOMState(elementID) {
  const initialDataElement = document.getElementById(elementID);

  if (initialDataElement && initialDataElement.textContent) {
    const initialData = JSON.parse(initialDataElement.textContent);

    return initialData;
  }

  return null;
}

Con esta condición aprovechamos el type coercion de JavaScript donde un objeto del DOM (initialDataElement) y una cadena que no está vacía (initialDataElement.textContent) son considerados como true.

Esta técnica nos permite aprovechar las funcionalidades que nos ofrece un stack donde el backend y el frontend coexisten en una sola aplicación. Expandiendo un poco más esta idea podemos tratar al DOM como un state de React, que no solo pueda ser leído si no re-escrito.

Creando bookmarks de CodeMirror con Preact

2020-07-25T21:30:00+00:00

CodeMirror es una de mis bibliotecas favoritas y la que más utilizo cuando se trata de implementar un editor de texto plano. Una de las funcionalidades que estoy explorando ahora es la de los llamados bookmarks.

Un bookmark es una marca dentro del editor que está asociado a una posición específica (línea y columna) y puede contener un nodo del DOM. Los bookmarks son útiles para extender la funcionalidad del editor y proveer acciones dentro de un contexto específico (por ejemplo codemirror-colorpicker agrega un color picker en un bookmark cuando encuentra un color dentro del texto).

Lo interesante es que, al contener un nodo del DOM, el bookmark puede recibir eventos, con lo que podemos usar JavaScript para agregarle eventos. O, podríamos usar una biblioteca que nos permita simplificar ese trabajo, e incluso reutilizar otras partes de nuestro código.

Aquí es donde entra Preact. Con solo [email protected]">4kB de tamaño es ideal para crear componentes como React, pero más ligeros.

Digamos que para el caso que nos ocupa, vamos a hacer un editor de texto que, cuando encuentre un texto date:, agregue un botón al costado derecho que permita incrustar la fecha y hora local.

Creando el editor con CodeMirror (y Preact)

Primero debemos crear un editor de texto con CodeMirror. En mi caso, voy a utilizar Preact para crear el bookmark y el editor.

Para esto creo un <div /> con un <textarea />. El <textarea /> debe tener un ref, que luego voy a usar dentro de un hook para crear la instancia de CodeMirror.

import { useRef, useEffect } from "preact/hooks";
import CodeMirror from "codemirror/lib/codemirror";
import "codemirror/lib/codemirror.css";

const options = {
  lineNumbers: true
};

export default function Editor() {
  const ref = useRef(null);

  useEffect(() => {
    CodeMirror.fromTextArea(ref.current, options);
  }, []);

  return (
    <div class="editor">
      <textarea ref={ref} />
    </div>
  );
}

Este primer paso es bastante directo, y si no utilizas Preact (o React), también puedes usarlo con cualquier otra biblioteca, o incluso con JavaScript puro.

Creando el component del bookmark con Preact

El siguiente paso es crear el componente que irá dentro del bookmark. En este caso, el componente es un simple botón que, al hacer click, llamará al prop onClick, pasándole la fecha y hora actual como una cadena.

export default function NowButton({ onClick }) {
  function handleOnClick() {
    onClick(new Date().toString());
  }

  return <button onClick={handleOnClick}>Now</button>;
}

Creando el bookmark

Este paso es el más complejo, porque requiere conocer un poco del API de CodeMirror.

Lo primero que tenemos que hacer es crear la función createBoomarks. Esta función va a usar el API de CodeMirror para crear los bookmarks en base a nuestra condición inicial (que haya una línea que empiece con date:).

Para poder hacer esto debemos permitir que createBoomarks reciba como argumento, la instancia de CodeMirror que corresponde al editor.

function createBoomarks(cm) {
}

Luego, para poder aplicar los bookmarks sin bloquear el editor, lo que evitaría que el usuario pueda escribir, usaremos el método operation de CodeMirror.

Este método permite pasarle un callback que puede contener varios cambios y operaciones en el editor, pero que se aplicará como un solo cambio dentro de CodeMirror, mejorando la performance de nuestras operaciones.

function createBoomarks(cm) {
  cm.operation(() => {});
}

El siguiente paso es iterar por cada línea del editor para agregar nuestro bookmark, si cumple con la condición:

function createBoomarks(cm) {
  cm.operation(() => {
    cm.eachLine(lineHandle => {
      // Si no cumple la condición, ignoramos el resto del callback.
      if (!lineHandle.text.startsWith("date:")) {
        return;
      }

      // Obtenemos el número de línea y caracter para saber dónde posicionar el bookmark.
      const line = lineHandle.lineNo();
      const ch = lineHandle.text.indexOf(":");

      // Creamos el "widget", que será el contenedor de nuestro componente.
      const widget = document.createElement("div");
      widget.style.display = "inline";
      widget.style.verticalAlign = "middle";
      widget.style.height = "14px";

      // Creamos el bookmark con cm.doc.setBookmark, pasándole la línea y caracter, y el widget.
      cm.state.bookmarks[line] = cm.doc.setBookmark(
        { line, ch: ch + 1 },
        { widget, handleMouseEvents: true }
      );
    });
  });
}

Aquí hay algo importante a considerar. Dado que el texto de nuestro editor puede cambiar varias veces (porque el usuario edita el texto), es necesario guardar una referencia de nuestros bookmarks en caso necesitemos eliminarlos antes del siguiente cambio.

Es por eso que CodeMirror nos da un objeto cm.state, donde podemos definir estados para el editor. En nuestro caso, usaremos state para crear un objeto bookmarks donde las llaves serán los números de línea, y los valores serán los bookmarks.

Nota: En nuestro caso, las llaves del objeto cm.state.bookmarks son los números de línea porque se asume que nuestros bookmarks solo aparecen una vez por línea. Pero en otros casos podría ser una combinación de línea y caracter u otro.

Hasta aquí hemos creado una función que crea un bookmark con un elemento <div /> que no hace nada. Ahora toca agregarle el componente:

function createBoomarks(cm) {
  cm.operation(() => {
    cm.eachLine(lineHandle => {
      // if (!lineHandle.text.startsWith("date:")) {
      //   return;
      // }

      // const line = lineHandle.lineNo();
      // const ch = lineHandle.text.indexOf(":");

      // const widget = document.createElement("div");
      // widget.style.display = "inline";
      // widget.style.verticalAlign = "middle";
      // widget.style.height = "14px";

      // Aquí definimos el valor del prop `onClick`. Recordemos que esta función recibe la fecha y hora local como una cadena.
      function setDate(date) {
        // `cm.doc.replaceRange` va a reemplazar cualquier texto que exista luego de "date:" con el valor que reciba la función `setDate`.
        cm.doc.replaceRange(
          date,
          { line, ch: ch + 1 },
          {
            line,
            ch: ch + date.length
          }
        );
      }

      // Aquí es donde creamos el componente que definimos algunos párrafos arriba.
      const button = <NowButton onClick={setDate} />;

      // cm.state.bookmarks[line] = cm.doc.setBookmark(
      //   { line, ch: ch + 1 },
      //   { widget, handleMouseEvents: true }
      // );

      // Por último, montamos y renderizamos nuestro componente usando la función `render` de Preact.
      render(button, widget);
    });
  });
}

Por último, debemos definir un init hook. Un init hook en CodeMirror es una función que se va a llamar al crear un editor. Esto es útil si sabemos que el editor tendrá un valor inicial y queremos crear nuestros bookmarks inmediatamente después de crear el editor. Pero no solo eso, también es aquí donde guardaremos un estado con los bookmarks.

También vamos a requerir asociarnos a un evento change, que permitirá ejecutar nuestra función createBoomarks (la que va a crear los bookmarks) cada vez que haya un cambio en el editor.

CodeMirror.defineInitHook(cm => {
  cm.state.bookmarks = {};
  createBoomarks(cm);
  cm.on("change", () => createBoomarks(cm));
});

Líneas arriba había mencionado que podemos requerir borrar todos los bookmarks antes del siguiente cambio. Esto es posible agregando el siguiente código dentro del callback de cm.operation:

function createBoomarks(cm) {
  cm.operation(() => {
    Object.keys(cm.state.bookmarks).forEach(lineNumber => {
      // Desmontamos el componente al llamar a la función `render` de preact con un `null`.
      const widget = cm.state.bookmarks[lineNumber].replacedWith;
      render(null, widget);

      // Llamamos al método `clear` de los bookmarks y eliminamos `cm.state.bookmarks[lineNumber]` de la memoria.
      cm.state.bookmarks[lineNumber].clear();
      delete cm.state.bookmarks[lineNumber];
    });

    // cm.eachLine(lineHandle => {
    // ...
  });
}

¿Por qué es importante desmontar los componentes antes de llamar a clear()? Por dos motivos:

Si solo llamamos a clear(), CodeMirror eliminará el nodo del DOM (el famoso widget), pero Preact seguirá manteniendo una instancia del componente para ese nodo y no liberará memoria (los ya conocidos memory leaks).
Al desmontar los componentes con render(null, widget) también logramos que los componentes se desuscriban de sus propios side effects. Si no desmontamos el componente, un (hipotético) setInterval seguirá llamándose incluso luego de haber eliminado el bookmark, o un fetch podría seguir en ejecución tratando de finalizar un request aunque el editor esté completamente vacío.

El código completo quedaría así:

import { render } from "preact";
import CodeMirror from "codemirror/lib/codemirror";
import NowButton from "./nowButton";

function createBoomarks(cm) {
  cm.operation(() => {
    Object.keys(cm.state.bookmarks).forEach(lineNumber => {
      const widget = cm.state.bookmarks[lineNumber].replacedWith;
      render(null, widget);
      cm.state.bookmarks[lineNumber].clear();
      delete cm.state.bookmarks[lineNumber];
    });

    cm.eachLine(lineHandle => {
      if (!lineHandle.text.startsWith("date:")) {
        return;
      }

      const line = lineHandle.lineNo();
      const ch = lineHandle.text.indexOf(":");

      const widget = document.createElement("div");
      widget.style.display = "inline";
      widget.style.verticalAlign = "middle";
      widget.style.height = "14px";

      function setDate(date) {
        cm.doc.replaceRange(
          date,
          { line, ch: ch + 1 },
          {
            line,
            ch: ch + date.length
          }
        );
      }

      const button = <NowButton onClick={setDate} />;

      cm.state.bookmarks[line] = cm.doc.setBookmark(
        { line, ch: ch + 1 },
        { widget, handleMouseEvents: true }
      );

      render(button, widget);
    });
  });
}

CodeMirror.defineInitHook(cm => {
  cm.state.bookmarks = {};
  createBoomarks(cm);
  cm.on("change", () => createBoomarks(cm));
});

Y aquí un ejemplo en vivo:

Esto es solo una exploración de lo que podría hacerse con los bookmarks de CodeMirror y una biblioteca de componentes como Preact. Algo que creo que vale la pena seguir revisando es ver cómo lograr mantener un estado entre unmounts del mismo componente, o en su defecto hacer un diff inteligente para borrar solo algunos bookmarks y no todos en cada operación.

Estructuras de datos para React

2020-07-15T01:30:00+00:00

React recomienda evitar mutar los datos de una aplicación. Es por eso que técnicas como usar el spread operator son bastante utilizadas para manejar datos en React, pero conforme pasamos del código de ejemplo, nos podemos dar cuenta de lo complicado que puede llegar a ser manipular la data en cada vista.

Por ejemplo, tenemos el clásico to-do list:

import React, { useState } from "react";

function TodoList() {
  const [items, setItems] = useState([]);

  return (
    <ul>
      {items.map(item => <li key={item}>{item}</li>)}
    </ul>
  );
}

En este ejemplo, los elementos de esta lista están guardados en un array, o arreglo, y para poder agregar un elemento a items, podemos hacer:

const [items, setItems] = useState([]);

function addItem(newItem) {
  const updatedItems = [...items, newItem];

  return setItems(updatedItems);
}

Y si queremos eliminar un elemento nos topamos con un problema. ¿Cómo se hace?

Eliminar un elemento de una colección:

Para eliminar un elemento de una colección tenemos 2 opciones:

Usando `splice`

[].splice permite eliminar elementos de un array en base a su índice.

El primer parámetro de splice es el índice o posición donde se empieza a contar los elementos a eliminar, mientras que el segundo parámetro es el número de elementos a eliminar:

function removeItem(indexToRemove) {
  const updatedItems = [...items];
  updatedItems.splice(indexToRemove, 1);

  return setItems(updatedItems);
}

Usando `filter`

[].filter permite filtrar los elementos de un array en base a una condición.

En este caso, la condición es “todos los elementos excepto el que tenga el índice a eliminar”:

function removeItem(indexToRemove) {
  const updatedItems = items.filter((_item, index) => index !== indexToRemove);

  return setItems(updatedItems);
}

Reemplazar un elemento de la colección

Para reemplazar un elemento dentro de una colección también tenemos 2 opciones, muy similar a la forma como eliminamos elementos.

Usando `splice`

splice tiene un tercer parámetro que puede ser uno o más elementos que se van a insertar en la posición definida por el primer parámetro (en nuestro ejemplo, indexToReplace).

En este caso, lo que le decimos a splice es: “elimina 1 elemento en la posición indexToReplace, y además agrega newItem en la posición indexToReplace“:

function replaceItem(indexToReplace, newItem) {
  const updatedItems = [...items];
  updatedItems.splice(indexToReplace, 1, newItem);

  return setItems(updatedItems);
}

Usando `map`

[].map toma un array, itera por todos sus elementos, aplicando una función sobre cada uno de los elementos, y guarda el resultado en un nuevo array.

En este caso, lo que le decimos a map es: “Devuelve los mismos elementos, a menos que el índice de la iteración actual sea el índice a reemplazar”:

function replaceItem(indexToReplace, newItem) {
  const updatedItems = items.map((item, index) => {
    if (index === indexToReplace) {
      return newItem;
    }

    return item;
  });

  return setItems(updatedItems);
}

Reemplazar la propiedad de un objeto

Ahora supongamos que los elementos del to-do list son objetos que no solo guardan el texto de cada tarea, si no otras propiedades, como fecha de creación, si está marcado como completado o no, etc.

Para poder cambiar las propiedades de un elemento de esa lista, vamos a tener que manipular un nuevo tipo de estructura de datos, que en este caso es un objeto.

Asumiendo que cada elemento de la lista tiene esta estructura:

{
  text: "Aprendiendo sobre estructuras de datos",
  isCompleted: false,
  createdAt: "2020-07-15T00:42:03.338Z"
}

Podemos modificar una propiedad de un objeto usando el spread operator, que nos permite crear una copia del objeto que queremos modificar, sin cambiar el objeto anterior:

function markAsCompleted(item, isCompleted) {
  const newItem = { ...item };
  newItem.isCompleted = isCompleted;

  return newItem;
}

Relacionar dos colecciones

Vayamos un paso más allá. Ahora la data viene de una API y tienes 2 recursos: todoLists y todoItems.

Los todoLists tienen la siguiente estructura:

const todoLists = [
  {
    id: 1,
    name: "Aprendiendo React"
  },
  {
    id: 2,
    name: "Aprendiendo Ruby"
  }
]

Y los todoItems tienen la siguiente estructura:

const todoItems = [
  {
    id: 1,
    todoListId: 1,
    text: "Aprendiendo sobre estructuras de datos",
    isCompleted: false,
    createdAt: "2020-07-15T00:42:03.338Z"
  },
  {
    id: 2,
    todoListId: 1,
    text: "React hooks",
    isCompleted: false,
    createdAt: "2020-07-15T00:45:03.338Z"
  },
  {
    id: 3,
    todoListId: 1,
    text: "React Context",
    isCompleted: false,
    createdAt: "2020-07-15T00:46:03.338Z"
  },
  {
    id: 4,
    todoListId: 2,
    text: "Metaprogramación en Ruby",
    isCompleted: false,
    createdAt: "2020-07-15T00:48:03.338Z"
  }
]

En este caso, tenemos tres elementos para la lista con ID 1, y un elemento para el ID 2. ¿Cómo podríamos hacer para poder mostrar ambos recursos en una vista?

Supongamos que queremos mostrar algo así:

* Aprendiendo React
  - [ ] Aprendiendo sobre estructuras de datos
  - [ ] React hooks
  - [ ] React Context
* Aprendiendo Ruby
  - [ ] Metaprogramación en Ruby

Para lograr esto podemos usar [].filter:

const todoListsWithItems = todoLists.map((todoList) => {
  const listWithItems = { ...todoList };

  listWithItems.todoItems = todoItems.filter((todoItem) =>
    todoItem.todoListId === todoList.id
  );

  return listWithItems;
});

De esta forma, podemos tener una estructura de datos mucho más fácil de usar dentro de un componente de React, como por ejemplo:

function TodoListsSummary() {
  // const todoLists =  [...];
  // const todoItems =  [...];
  // const todoListsWithItems = todoLists.map((todoList) => {...;

  return todoListsWithItems.map((listWithItems) => (
    <article key={listWithItems.id}>
      <h3>{listWithItems.name}</h3>
      <ul>
        {listWithItems.todoItems.map((todoItem) => (
          <li key={todoItem.id}>{todoItem.text}</li>
        ))}
      </ul>
    </article>
  ));
}

Hay varias bibliotecas que permiten manejar estructuras de datos de manera inmutable, como Immutable o Immer, pero es interesante conocer cómo podemos manejar este tipo de estructuras de manera relativamente sencilla sin depender de bibliotecas de terceros.

Web scraping y análisis de datos con Ruby

2020-07-12T18:30:00+00:00

Nota: Lo utilizado en este post es estrictamente de uso personal.

Buscar un lugar para vivir siempre es complicado, porque hay tantas variables a considerar antes de tomar una decisión. No solo es importante el precio, y la zona, si no también el número de habitaciones o incluso la cantidad de baños y el área construida.

Me he mudado varias veces en los últimos años, y algo que trato de hacer antes de elegir un lugar es analizar todas las ofertas disponibles.

Para esto, lo que hacía era buscar anuncios de lugares para vivir y volcar la información a mano en una hoja de cálculo, luego ir descartando los lugares más alejados, o con peor relación de m2/precio. Pero este es un proceso manual y tedioso que puede automatizarse. Y para automatizarlo me apoyo en 2 bibliotecas que construí en Ruby: ScrapKit y ActiveWorksheet.

ScrapKit permite hacer web scraping y mapear selectores del DOM a propiedades de un objeto plano, mientras que ActiveWorksheet lee un archivo CSV o XLS/XLSX y lo convierte a objetos de Ruby, donde cada fila es un registro y las columnas se vuelven propiedades de estos registros.

Usando ScrapKit

Esta es la parte más delicada del proceso, ya que implica hacer web scraping, que no es más que automatizar la extracción de información de una página web. Algunos sitios web no permiten usar esta técnica, pero ya que es para uso personal, espero que no haya problemas.

En mi caso, estoy usando Nexo Inmobiliario para obtener la información de las ofertas inmobiliarias que hay actualmente.

ScrapKit en su forma más básica me permite mapear selectores del DOM a atributos. Por ejemplo, puedo mapear el selector .Project-header h1 al atributo title.

ScrapKit tiene una característica más poderosa, que permite mapear estructuras complejas usando el atributo especial selector, el cual es una colección de selectores que se va internando en el DOM hasta que cumpla una condición establecida.

Por ejemplo, en [".Project-available-model", { ".name_tipology": "Departamento tipo A" }], ScrapKit busca dentro de .Project-available-model algún elemento que cumpla con el selector .name_tipology y que tenga el valor Departamento tipo A.

Sabiendo todo esto, podemos crear una “receta” de ScrapKit de la siguiente forma:

url = "https://nexoinmobiliario.pe/proyecto/venta-de-departamento-123-en-lima"
type = "Departamento tipo A"

# Defino el mapeo de selectores a atributos a través de una "receta".
recipe = ScrapKit::Recipe.load(
  url: url,
  attributes: {
    title: ".Project-header h1",
    id: "#project_id",
    stage: ".bx-data-project.box-st > table > tbody > tr:nth-child(4) > td:nth-child(2)",
    due_date: ".bx-data-project.box-st > table > tbody > tr:nth-child(5) > td:nth-child(2)",
    latitude: "#latitude",
    longitude: "#longitude",
    info: {
      selector: [".Project-available-model", { ".name_tipology": type }],
      children_attributes: {
        tipology: "span.name_tipology",
        bedrooms: "span.bedroom",
        area: "span.area",
        price: "span.price"
      }
    }
  }
)

# Obtengo el resultado ejecutando la receta.
output = recipe.run

Dado que es un proceso que toma tiempo, es recomendable hacerlo una vez y guardar estos datos en algún lado para procesarla después. Y aquí es donde entra ActiveWorksheet.

Usando ActiveWorksheet

ActiveWorksheet permite definir una clase en Ruby que se comporta de manera similar a un objeto de ActiveResource o ActiveRecord, con la diferencia que, mientras ActiveResource lee los datos desde un endpoint y ActiveRecord hace lo mismo desde una base de datos, ActiveWorksheet lo hace desde un archivo CSV, XLS o XLSX.

Los datos obtenidos por ScrapKit fueron guardados en un archivo en la ruta ~/departamentos.csv, que tiene este formato:

Date,ID,Project,Model,Bedrooms,Area,Price,Due Date,Stage,Latitude,Longitude
2020-07-12,1823,SARAY 2,TIPO K,3,70.24 m2,"S/ 347,568","15 de Diciembre, 2021",En construcción,-12.087613139816469,-77.07117197819613

Con ActiveWorksheet creo una clase llamada Project que herede de ActiveWorksheet::Base, donde cada columna del CSV es automáticamente mapeado a un atributo:

require "active_worksheet"

class Project < ActiveWorksheet::Base
  self.source = "~/departamentos.csv"

  # Estos métodos son usados para obtener y calcular valores en base a lo que viene del archivo CSV.
  def currency
    self.price.split(" ").first
  end

  def price_as_number
    self.price.split(" ").last.gsub(",", "").to_f
  end

  def area_as_number
    self.area.gsub(" m2", "").to_f
  end

  def price_per_m2
    (self.price_as_number / self.area_as_number).round(2)
  end
end

Con el método de clase all, ActiveWorksheet devuelve una colección de instancias de Project, una por cada fila del archivo CSV. Así, puedo filtrar por los registros que no cumplen los requisitos mínimos que busco:

projects = Project.all
  .select { |project| project.date == Date.today }
  .select { |project| project.bedrooms > 1 }
  .select { |project| project.price_as_number <= 380_000 }
  .select { |project| project.area_as_number >= 60 }
  .select { |project| project.stage != "En planos" }

sorted_projects = projects.sort_by(&:price_as_number)

Los siguientes pasos serían: empezar a recopilar los datos de manera semanal, si se quiere hacer un análisis de los precios en el tiempo, y presentar los datos en un formato más legible para poder decidir mejor. Para ello desarrollé una herramienta de línea de comandos que está alojada en este repositorio de GitHub.

Usando OpenStruct

2020-02-16T16:30:00+00:00

Ruby tiene varias formas de simplificar algunas partes del desarrollo, como por ejemplo el manejo de atributos en un objeto.

Nos podemos encontrar en la situación donde queremos dejar de usar hashes y manejar la data como si fueran objetos de Ruby. De esta forma podemos hacer el código un poco más simple o legible.

Por ejemplo, teniendo este array:

pages = [
  {
    title: "Aprendiendo a usar arrays en JavaScript",
    slug: "/2020-02-15-javascript-arrays.html"
  },
  {
    title: "APIs de Internacionalización en JavaScript",
    slug: "/2019-05-13-apis-internacionalizacion.html"
  },
  {
    title: "Ejecutando comandos desde Ruby",
    slug: "/2019-03-25-ejecutar-comandos-ruby.html"
  },
  {
    title: "Usando Higher-Order Components",
    slug: "/2019-03-19-usando-hocs.html"
  }
]

Podríamos hacer:

pages.map { |page| page[:slug] }

O, si convertimos pages a un array de OpenStruct, podríamos hacer:

pages.map(&:slug)

OpenStruct permite crear objetos que leen y guardan atributos de manera dinámica, utilizando metaprogramación.

Para usar OpenStruct, creamos una instancia de OpenStruct:

require "ostruct"

page = OpenStruct.new(title: "", slug: "")
#=> #<OpenStruct title="", slug="">

Con la estructura anterior, podemos hacer:

require "ostruct"

pages = [
  {
    title: "Aprendiendo a usar arrays en JavaScript",
    slug: "/2020-02-15-javascript-arrays.html"
  },
  {
    title: "APIs de Internacionalización en JavaScript",
    slug: "/2019-05-13-apis-internacionalizacion.html"
  },
  {
    title: "Ejecutando comandos desde Ruby",
    slug: "/2019-03-25-ejecutar-comandos-ruby.html"
  },
  {
    title: "Usando Higher-Order Components",
    slug: "/2019-03-19-usando-hocs.html"
  }
]

pages = pages.map do |page|
  OpenStruct.new(page)
end

pages.map(&:slug)
#=> ["/2020-02-15-javascript-arrays.html", "/2019-05-13-apis-internacionalizacion.html", "/2019-03-25-ejecutar-comandos-ruby.html", "/2019-03-19-usando-hocs.html"]

Si queremos ir más allá, podemos crear una clase que herede de OpenStruct:

require "ostruct"
require "date"

class Page < OpenStruct
  def created_at
    date_as_string = self.slug.slice(1, 10)
    date_parts = date_as_string.split("-").map(&:to_i)

    Date.new(date_parts[0], date_parts[1], date_parts[2])
  end
end

pages = [
  #...
]

pages = pages.map do |page|
  Page.new(page)
end

pages_created_in_2019 = pages.filter { |page| page.created_at.year == 2019 }
#=> [#<Page title="APIs de Internacionalizacion en JavaScript", slug="/2019-05-13-apis-internacionalizacion.html">, #<Page title="Ejecutando comandos desde Ruby", slug="/2019-03-25-ejecutar-comandos-ruby.html">, #<Page title="Usando Higher-Order Components", slug="/2019-03-19-usando-hocs.html">]

De esta forma, podemos hacer más escribiendo un poco menos, ahorrándonos varios attr_accessor y tener que definir un método initialize para Page.

Aprendiendo a usar arrays en JavaScript

2020-02-15T23:15:00+00:00

Los arrays (o arreglos) son un tipo especial de objetos y representan colecciones que pueden guardar cualquier tipo de dato en JavaScript.

Los arrays tienen una propiedad llamada length, que guarda el tamaño, o número de elementos que contiene dicho array, y utilizan los corchetes ([]) para acceder a un elemento del arreglo a través de su índice. En JavaScript, el índice de los arrays empieza en 0.

Trabajando con arrays

Al ser objetos, los arrays tienen una serie de métodos que sirven para manipularlos:

join
pop
push
indexOf
reverse
concat
find
forEach
map
filter
reduce

`join`

Une todos los elementos de un array en una cadena, utilizando un separador.

const dateParts = [2020, 2, 15];

dateParts.length;
// 3

dateParts.join('-');
// "2020-2-15"

`pop`

Quita el último elemento del array y retorna su valor.

const dateParts = [2020, 2, 15];

dateParts.pop();
// 15

dateParts;
// [2020, 2]

Nota:: pop es uno de los tantos métodos que modifican el array original.

`push`

Agrega un elemento al final del array original y retorna el nuevo tamaño.

const dateParts = [2020, 2, 15];

dateParts.pop();
// 15

dateParts.push(14);
// 3

dateParts;
// [2020, 2, 14]

`indexOf`

Devuelve el índice (o posición) en el array del primer elemento que sea igual al argumento que recibe.

const dateParts = [2020, 2, 15];

dateParts.indexOf(2);
// 1

dateParts.indexOf(15);
// 2

`reverse`

Modifica el array invirtiendo sus elementos y retorna el array invertido.

const dateParts = [2020, 2, 15];

dateParts.reverse();
// [15, 2, 2020]

dateParts;
// [15, 2, 2020]

`concat`

Agrega elementos a una copia del array original y devuelve la copia con los nuevos elementos agregados.

const dateParts = [2020, 2, 15];

dateParts.concat(18, 15, 0);
// [2020, 2, 15, 18, 15, 0]

dateParts;
// [2020, 2, 15]

`find`

Devuelve el primer elemento que cumpla con una condición pasada como función.

const dateParts = [2020, 2, 15];

dateParts.find(part => part > 1900);
// 2020

`forEach`

Recorre cada elemento del array a través de una función.

const dateParts = [2020, 2, 15];

dateParts.forEach(part => console.log(part));
// 2020
// 2
// 15

`map`

Devuelve un nuevo array, donde cada elemento es el resultado de aplicar una función sobre cada elemento del array original.

const dateParts = [2020, 2, 15];

dateParts.map(part => part + 2);
// [2022, 4, 17]

`filter`

Devuelve un nuevo array, cuyos elementos son aquellos elementos del array original que cumplen con una condición pasada como función.

const dateParts = [2020, 2, 15];

dateParts.filter(part => part < 1990);
// [2, 15]

`reduce`

reduce permite trabajar sobre todos los elementos de un array y devolver un resultado, que puede ser cualquier cosa.

Como en los métodos anteriores, recibe una función como argumento, solo que en esta ocasión el parámetro es llamado acumulador. El acumulador empieza con un valor inicial y acumula el valor retornado por cada iteración. Al final, reduce retorna el valor del acumulador.

Un ejemplo bastante común es sumar un array de números:

const numbers = [1, 2, 3, 4, 5, 6];

numbers.reduce((accumulator, number) => accumulator + number);
// 21

El valor inicial de un acumulador es pasado como segundo parámetro, luego de la función. Si no se pasa ningún valor inicial, el valor inicial es el primer elemento del array.

Para nuestro ejemplo, ya que dateParts es un array que contiene año, mes y día, podemos generar un objeto que tenga la misma información pero estructurada de otra forma. Para eso creamos dateKeys, un array que contiene los nombres de las propiedades asociados al año, mes y día:

const dateParts = [2020, 2, 15];
const dateKeys = ["year", "month", "day"];

dateParts.reduce((accumulator, part, index) => {
  const key = dateKeys[index];

  accumulator[key] = part;

  return accumulator;
}, {});
// {year: 2020, month: 2, day: 15}

Nota:: find, forEach, map y filter tienen una función como primer parámetro, que a su vez puede recibir hasta 3 argumentos, en el siguiente orden: item, index y array. reduce tiene un argumento adicional (el acumulador) que va antes de item.

APIs de Internacionalización en JavaScript

2019-05-13T14:15:57+00:00

Cuando hablamos de internacionalización en front-end nos encontramos con algunos retos. Dejando de lado la traducción de etiquetas, botones y textos en general, nos podemos topar con escenarios donde necesitemos mostrar fechas o monedas para diferentes idiomas o países.

Felizmente existe un conjunto de APIs que nos facilitan este trabajo, y si antes necesitábamos bibliotecas de terceros para manejar estas tareas, con Intl podemos hacerlo nativamente, sin necesidad de agregar más dependencias a nuestra aplicación.

`Intl.DateTimeFormat`

Intl.DateTimeFormat nos permite formatear una fecha según el idioma que elijamos. Por ejemplo, las fechas en Estados Unidos tienen el formato mes/día/año, mientras que en Gran Bretaña y países de Hispanoamérica, el formato es día/mes/año.

const date = new Date();

const formatterUnitedStates = new Intl.DateTimeFormat('en-US');
const formatterGreatBritan = new Intl.DateTimeFormat('en-GB');
const formatterPeru = new Intl.DateTimeFormat('es-PE');
const formatterSpain = new Intl.DateTimeFormat('es-ES');

console.log(formatterUnitedStates.format(date));
// 5/13/2019
console.log(formatterGreatBritan.format(date));
// 13/05/2019
console.log(formatterPeru.format(date));
// 13/5/2019
console.log(formatterSpain.format(date));
// 13/5/2019

`Intl.RelativeTimeFormat`

Intl.RelativeTimeFormat es una API interesante que nos permite formatear cantidades de tiempo relativas. Por ejemplo, si queremos mostrar “2 días antes” o “1 día después” de manera más humana podemos hacerlo con esta API.

const formatterEN = new Intl.RelativeTimeFormat('en');
const formatterENAuto = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
const formatterES = new Intl.RelativeTimeFormat('es');
const formatterESAuto = new Intl.RelativeTimeFormat('es', { numeric: 'auto' });

console.log(formatterEN.format(1, 'day'));
// in 1 day
console.log(formatterENAuto.format(1, 'day'));
// tomorrow
console.log(formatterEN.format(1, 'week'));
// in 1 week
console.log(formatterENAuto.format(1, 'week'));
// next week

console.log(formatterES.format(1, 'day'));
// dentro de 1 día
console.log(formatterESAuto.format(1, 'day'));
// mañana
console.log(formatterES.format(1, 'week'));
// dentro de 1 semana
console.log(formatterESAuto.format(1, 'week'));
// la próxima semana

`Intl.NumberFormat`

Intl.NumberFormat es un API que nos ayuda a formatear números, monedas y porcentajes. El caso de uso más común es cuando tenemos una aplicación que realiza cálculos de montos y la moneda varía según el cliente. Por ejemplo, si queremos mostrar un monto en dólares, en pesos mexicanos o en soles peruanos.

Nota:: Esta API no realiza conversión entre monedas, solo se encarga de formatear el monto que se le pase.

const total = 145.50;

const formatterDollars = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
const formatterSoles = new Intl.NumberFormat('es-PE', { style: 'currency', currency: 'PEN' });

console.log(formatterDollars.format(total));
// $145.50
console.log(formatterSoles.format(total));
// S/ 145.50

Nota:: El resultado de format depende no solo de currency, si no también del idioma que le pases, por ejemplo:

const total = 145.50;

const formatterDollars = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' });
const formatterSoles = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'PEN' });
const formatterPesos = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'MXN' });

console.log(formatterDollars.format(total));
// $145.50
console.log(formatterSoles.format(total));
// PEN 145.50
console.log(formatterPesos.format(total));
// MX$145.50

`Intl.ListFormat`

Intl.ListFormat nos ayuda a mostrar una lista de elementos de manera humana. Por ejemplo, si queremos convertir ['manzana', 'uva', 'sandía'] a “manzana, uva y sandía” o “manzana, uva o sandía”, esta API nos facilita esta tarea.

const items = ['Iron Man', 'Captain America', 'Thor'];

const formatterENAnd = new Intl.ListFormat('en', { type: 'conjunction' });
const formatterENOr = new Intl.ListFormat('en', { type: 'disjunction' });
const formatterESAnd = new Intl.ListFormat('es', { type: 'conjunction' });
const formatterESOr = new Intl.ListFormat('es', { type: 'disjunction' });

console.log(formatterENAnd.format(items));
// Iron Man, Captain America, and Thor
console.log(formatterENOr.format(items));
// Iron Man, Captain America, or Thor
console.log(formatterESAnd.format(items));
// Iron Man, Captain America y Thor
console.log(formatterESOr.format(items));
// Iron Man, Captain America o Thor

Nota:: Existe un bug en español para “y” u “o” cuando la última palabra empieza con “i”/“hi” u “o”/“ho”, respectivamente.

Usualmente, para formatear fechas o monedas teníamos que recurrir a algunas bibliotecas, o escribir código más complejo. Con las APIs de Internacionalización nos ahorramos agregar más dependencias a nuestra aplicación.

De todas formas, es importante revisar el soporte de estas APIs en los navegadores antes de decidir usarlas en producción.

Gustavo Leon

Creando un router basado en archivos con Preact, preact-router y Parcel

Creando un resolver de Parcel

Soporte para layouts

Soporte para route groups

Renderizando rutas con preact-router

Invalidar caché de Parcel

Creando un clon de Storybook desde 0 con Parcel

Component Story Format (o CSF)

Obteniendo todos los archivos .stories.js

Obteniendo información de los componentes con react-docgen

Persistiendo estados de React con Web Storage

Accediendo a elementos del Storage

Escribiendo en el Storage

Creando nuestro propio hook en React

Pasando datos síncronamente desde Rails hacia React

Renderizando datos para React desde Rails

Leyendo datos del DOM con React

Creando bookmarks de CodeMirror con Preact

Creando el editor con CodeMirror (y Preact)

Creando el component del bookmark con Preact

Creando el bookmark

Estructuras de datos para React

Eliminar un elemento de una colección:

Usando splice

Usando filter

Reemplazar un elemento de la colección

Usando splice

Usando map

Reemplazar la propiedad de un objeto

Relacionar dos colecciones

Web scraping y análisis de datos con Ruby

Usando ScrapKit

Usando ActiveWorksheet

Usando OpenStruct

Aprendiendo a usar arrays en JavaScript

Trabajando con arrays

join

pop

push

indexOf

reverse

concat

find

forEach

map

filter

reduce

APIs de Internacionalización en JavaScript

Intl​.Date​Time​Format

Intl​.Relative​Time​Format

Intl​.Number​Format

Intl​.List​Format

Renderizando rutas con `preact-router`

Obteniendo todos los archivos `.stories.js`

Obteniendo información de los componentes con `react-docgen`

Usando `splice`

Usando `filter`

Usando `splice`

Usando `map`

`join`

`pop`

`push`

`indexOf`

`reverse`

`concat`

`find`

`forEach`

`map`

`filter`

`reduce`

`Intl.DateTimeFormat`

`Intl.RelativeTimeFormat`

`Intl.NumberFormat`

`Intl.ListFormat`