Elige qué cookies permites. Puedes cambiar tu elección en cualquier momento desde «Preferencias de cookies», al pie de cada página. Más información en el Aviso de Privacidad.

Librería open source · npm

Neysla

Producto de nuestra marca · 2018 – 2026

Sobre el proyecto

Neysla nació en 2018 de una molestia concreta: en cada proyecto volvía a escribir las mismas URLs anidadas de una API, con sus partes fijas y sus identificadores. La idea fue modelar cada recurso una sola vez y, en cada petición, indicar solo lo que cambia.

La versión 4 es una reescritura completa en TypeScript sobre la Fetch API nativa: sin dependencias en tiempo de ejecución, con tipos incluidos y distribuida como ESM, CommonJS y un bundle para CDN. Funciona igual en el navegador que en Node.js 18+.

No es un experimento aislado: Academia Luz de Luna, Onca Vega Sello Editorial, la invitación de boda y el regalo de cumpleaños de esta misma lista consumen sus APIs con Neysla.

Tecnologías

  • TypeScript
  • Fetch API
  • Rollup
  • Vitest

Lo más destacado

  • Dos modos: peticiones directas o recursos modelados una vez y reutilizados.
  • Cero dependencias en tiempo de ejecución; tipos de TypeScript incluidos.
  • ESM, CommonJS e IIFE para CDN.
  • Cuerpos JSON, multipart y urlencoded; progreso de subida en el navegador.
  • Pruebas con Vitest, cobertura en Codecov e integración continua en GitHub Actions.

Documentación

Todo lo necesario para usarlo, con ejemplos de código: navega entre las secciones desde el índice.

Instalación de Neysla

Instala Neysla con npm o desde un CDN, conoce sus formatos de distribución (ESM, CJS, IIFE) y empieza a consumir APIs RESTful en el navegador o en Node.js 18+.

Neysla es una librería isomórfica, escrita en TypeScript y basada en promesas, para consumir APIs HTTP RESTful desde el navegador o desde Node.js 18+. Se puede usar de dos maneras:

  • Uso directo: haces peticiones HTTP puntuales a una URL (Neysla.get, Neysla.post, etc.).
  • Uso como modelador: defines una sola vez los recursos de tu API (sus partes estáticas y dinámicas) y los reutilizas en toda la aplicación.

No tiene dependencias en tiempo de ejecución: usa la Fetch API nativa y, solo para reportar el progreso de subida en el navegador, XMLHttpRequest.

Instalación con npm

npm install neysla

Neysla expone named exports e incluye sus declaraciones de tipos, así que no necesitas instalar @types aparte:

import { Neysla } from "neysla";
import type { NeyslaResponse } from "neysla";

En CommonJS:

const { Neysla } = require("neysla");

Instalación desde un CDN

Para usarla directamente en el navegador, carga el bundle minificado. El script expone el objeto { Neysla, NeyslaModel } en window.Neysla:

<script src="https://cdn.jsdelivr.net/npm/neysla@4/dist/cdn/neysla.min.js"></script>
<script>
  const { Neysla } = window.Neysla;
</script>

Formatos de distribución

FormatoArchivoÚsalo cuando…
ESMdist/esm/index.jsTrabajas con un bundler moderno o con módulos ES nativos (recomendado).
CJSdist/cjs/index.cjsTu entorno de Node.js usa require().
IIFE / CDNdist/cdn/neysla.min.jsCargas la librería con una etiqueta <script>.
Tiposdist/types/index.d.tsSiempre: TypeScript los toma automáticamente.

Requisitos

  • Navegadores modernos con soporte para la Fetch API.
  • Node.js 18 o superior (la versión en la que fetch es global).

Licencia y versionado

Neysla se publica bajo la licencia MIT y sigue versionado semántico. El código está en GitHub y el paquete en npm.

Si vienes de la versión 3, revisa la sección de migración del README: los errores ahora se lanzan como TypeError (en lugar de devolver false) y los nombres de los headers de respuesta siempre llegan en minúsculas.

Uso directo de Neysla

Haz peticiones HTTP directas con Neysla (GET, HEAD, POST, PATCH, PUT y DELETE), envía cuerpos JSON, multipart o urlencoded y maneja la respuesta y los errores.

El uso directo sirve para peticiones puntuales: le indicas la URL completa y Neysla resuelve el envío, el formato del cuerpo y la lectura de la respuesta. Cada método es estático y devuelve una Promise.

MétodoVerbo HTTPEnvía cuerpo
Neysla.get(options)GETNo
Neysla.head(options)HEADNo
Neysla.post(options)POSTSí
Neysla.patch(options)PATCHSí
Neysla.put(options)PUTSí
Neysla.remove(options)DELETESí

Opciones de la petición

OpciónTipoRequeridaPor defectoDescripción
urlstringSí—URL completa del endpoint.
paramsRecord<string, string | number | boolean | Array<string | number>>No—Parámetros de la query string. Un arreglo se envía repitiendo la clave (?tag=a&tag=b).
headersRecord<string, string>No{}Encabezados de la petición.
bodyRecord<string, unknown> | FormDataNo—Cuerpo de la petición (solo en post, patch, put y remove).
requestType"json" | "multipart" | "urlencoded"No"urlencoded"Cómo se serializa el cuerpo y qué Content-Type se envía.
responseType"json" | "text" | "arraybuffer" | "blob" | "document" | "stream"No"json"Cómo se lee el cuerpo de la respuesta.
credentialsRequestCredentialsNo—Igual que en fetch ("include" para enviar cookies a otro origen).
progress(event: ProgressEvent) => voidNo—Progreso de la transferencia; solo en el navegador (ver abajo).

GET y HEAD

import { Neysla } from "neysla";

const response = await Neysla.get({
  url: "https://www.my-domain.com/api/users",
  params: { order: "age", tag: ["admin", "editor"] },
});
// GET https://www.my-domain.com/api/users?order=age&tag=admin&tag=editor
console.log(response.status, response.data);

const { headers } = await Neysla.head({
  url: "https://www.my-domain.com/api/users",
});

Para descargar un archivo, pide la respuesta como blob:

const { data: file } = await Neysla.get({
  url: "https://www.my-domain.com/api/reports/2026.pdf",
  responseType: "blob",
});

POST, PATCH, PUT y DELETE

El cuerpo se serializa según requestType:

  • "json": JSON.stringify y Content-Type: application/json.
  • "urlencoded" (por defecto): application/x-www-form-urlencoded.
  • "multipart": se construye un FormData y el navegador define el Content-Type con su boundary. También puedes pasar tu propio FormData.
await Neysla.post({
  url: "https://www.my-domain.com/api/users",
  headers: { Authorization: "Bearer <token>" },
  requestType: "json",
  body: {
    first_name: "Roberto",
    last_name: "Magallanes",
    active: false,
  },
});

await Neysla.patch({
  url: "https://www.my-domain.com/api/users/10",
  requestType: "json",
  body: { active: true },
});

await Neysla.put({
  url: "https://www.my-domain.com/api/users/10",
  requestType: "json",
  body: { first_name: "Roberto", last_name: "Magallanes", active: true },
});

await Neysla.remove({ url: "https://www.my-domain.com/api/users/10" });

La respuesta

Cada petición exitosa se resuelve con un objeto NeyslaResponse<T>:

Atributo o métodoTipoDescripción
statusnumberCódigo de estado HTTP.
statusTextstringTexto del estado.
dataTCuerpo de la respuesta, leído según responseType.
dataTypeNeyslaResponseTypeEl responseType con el que se leyó.
headersRecord<string, string>Encabezados de la respuesta. Las claves siempre llegan en minúsculas.
urlstringURL a la que se hizo la petición.
getHeader(name)string | nullUn encabezado específico; la búsqueda no distingue mayúsculas.

Con TypeScript puedes tipar data:

interface User {
  id: number;
  first_name: string;
}

const { data } = await Neysla.get<User[]>({
  url: "https://www.my-domain.com/api/users",
});

Errores

  • Si la configuración es inválida (por ejemplo, falta url), la promesa se rechaza con un TypeError.
  • Si el servidor responde con un estado >= 300 (o la red falla), la promesa se rechaza con el mismo objeto de respuesta, así que puedes leer status y data:
try {
  await Neysla.get({ url: "https://www.my-domain.com/api/users/999" });
} catch (error) {
  if (error instanceof TypeError) {
    // configuración inválida
  } else {
    console.log(error.status, error.data); // p. ej. 404 y el cuerpo del error
  }
}

Progreso de la transferencia

En el navegador, si defines progress, Neysla usa XMLHttpRequest en lugar de fetch para poder reportar el evento nativo. En Node.js la opción se ignora.

const file = document.querySelector<HTMLInputElement>("#avatar")!.files![0];

await Neysla.post({
  url: "https://www.my-domain.com/api/avatars",
  requestType: "multipart",
  body: { file, name: "Mi avatar" },
  progress(event) {
    if (event.lengthComputable) {
      console.log(`${Math.round((event.loaded / event.total) * 100)} %`);
    }
  },
});

Uso de Neysla como modelador

Modela una sola vez los recursos anidados de tu API RESTful con Neysla (init, setModel y delimiters) y reutilízalos con configuración global por modelador.

En una API RESTful bien diseñada, los recursos se anidan: en https://api.example.com/courses/2305/sections/2465, courses y sections son las partes estáticas del recurso y 2305 y 2465 son las partes dinámicas (los identificadores).

Neysla aprovecha esa estructura: defines una vez cada recurso por sus partes estáticas y, al hacer cada petición, solo indicas las dinámicas. Los modelos se reutilizan en toda la aplicación, en el navegador o en Node.js 18+.

Una API de ejemplo

A lo largo de esta página modelaremos una API publicada en https://www.my-domain.com/api/ con tres recursos anidados:

  • Usuarios: user y user/:user_id.
  • Contactos de un usuario: user/:user_id/contact y user/:user_id/contact/:contact_id.
  • Teléfonos de un contacto: user/:user_id/contact/:contact_id/phone y .../phone/:phone_id.

Inicializar Neysla

Crea una instancia y llama a init con la configuración de tu API. init es asíncrono y devuelve un objeto con un modelador por cada configuración, indexado por su name:

import { Neysla } from "neysla";

const neysla = new Neysla();

const modelers = await neysla.init({
  name: "myApi",
  url: "https://www.my-domain.com/api/",
  headers: { Authorization: "Bearer <token>" },
  params: { foo: "bar" },
  requestType: "json",
});

La configuración de init se aplica a todas las peticiones de ese modelador:

AtributoTipoRequeridoDescripción
namestringSíNombre del modelador; es la clave en el objeto que devuelve init.
urlstringSíBase de las URLs de todos sus modelos.
headersRecord<string, string>NoEncabezados globales.
paramsNeyslaParamsNoParámetros de query globales.
bodyRecord<string, unknown>NoCampos del cuerpo que se envían en cada post, patch, put y remove.
requestType"json" | "multipart" | "urlencoded"NoSerialización del cuerpo por defecto (si no se indica, urlencoded).
responseTypeNeyslaResponseTypeNoLectura de la respuesta por defecto (si no se indica, json).
credentialsRequestCredentialsNoPolítica de credenciales por defecto.

Si la configuración es inválida (falta name o url, o algún atributo tiene el tipo equivocado), init se rechaza con un TypeError que indica qué modelador falló.

Definir modelos

Cada modelador expone setModel, que recibe las partes estáticas de un recurso: un string para un recurso de primer nivel o un arreglo para uno anidado.

const api = modelers.myApi;

const user = api.setModel("user");
const userContact = api.setModel(["user", "contact"]);
const userContactPhone = api.setModel(["user", "contact", "phone"]);

Así, el recurso de contactos (user/:user_id/contact/:contact_id) se descompone en:

  • https://www.my-domain.com/api/: la base, definida en url al inicializar.
  • user y contact: las partes estáticas, que van en setModel.
  • :user_id y :contact_id: las partes dinámicas, que van en cada petición como delimiters.

La misma lógica sirve para recursos anidados a cualquier profundidad. Si setModel recibe algo que no es un string ni un arreglo, lanza un TypeError.

Hacer peticiones con los modelos

Cada modelo expone get, head, post, patch, put y remove (este último envía DELETE). Todos reciben un objeto opcional:

OpciónTipoDescripción
delimitersstring | number | Array<string | number>Las partes dinámicas del recurso, en orden.
paramsNeyslaParamsSe combinan con los globales; los de la petición ganan.
headersRecord<string, string>Se combinan con los globales; los de la petición ganan.
bodyRecord<string, unknown> | FormDataSe combina con el body global (solo en métodos con cuerpo).
requestTypeNeyslaRequestTypeSobrescribe el global para esta petición.
responseTypeNeyslaResponseTypeSobrescribe el global para esta petición.
credentialsRequestCredentialsSobrescribe el global para esta petición.
progress(event: ProgressEvent) => voidProgreso de la transferencia (solo en el navegador).
Delimiters

Un modelo con N partes estáticas acepta N o N − 1 delimiters:

  • Con N − 1 apuntas a la colección: ["user", "contact"] + [12] → user/12/contact.
  • Con N apuntas a un elemento: ["user", "contact"] + [12, 4] → user/12/contact/4.

Cualquier otra cantidad rechaza la petición con un error («Incorrect relation between name and delimiters»).

GET
await user.get();
// GET https://www.my-domain.com/api/user?foo=bar

await user.get({ delimiters: 10, responseType: "blob" });
// GET https://www.my-domain.com/api/user/10?foo=bar (respuesta como Blob)

await user.get({ params: { order: "age", foo: "notBar" } });
// GET https://www.my-domain.com/api/user?foo=notBar&order=age

await userContactPhone.get({
  delimiters: [1, 500],
  params: { page: 7, perPage: 35 },
});
// GET https://www.my-domain.com/api/user/1/contact/500/phone?foo=bar&page=7&perPage=35
POST, PATCH, PUT y DELETE con modelos
await userContact.post({
  delimiters: 12,
  params: { foo: "notBar" },
  body: { name: "Bart", phone_type: "mobile" },
});
// POST https://www.my-domain.com/api/user/12/contact?foo=notBar

await userContact.patch({
  delimiters: [12, 4],
  body: { name: "Bart" },
});
// PATCH https://www.my-domain.com/api/user/12/contact/4?foo=bar

await userContact.remove({ delimiters: [12, 4] });
// DELETE https://www.my-domain.com/api/user/12/contact/4?foo=bar

La respuesta y los errores funcionan igual que en el uso directo: una respuesta con estado >= 300 rechaza la promesa con el objeto de respuesta.

Varios modeladores

Si tu aplicación consume más de una API, pasa un arreglo a init. Cada configuración tiene su propia base, encabezados y valores por defecto:

const { usersApi, storageApi } = await neysla.init([
  {
    name: "usersApi",
    url: "https://users.my-domain.com/v1/",
    headers: { Authorization: "Bearer <token>" },
    requestType: "json",
  },
  {
    name: "storageApi",
    url: "https://storage.my-domain.com/",
    requestType: "multipart",
    responseType: "blob",
  },
]);

const profile = usersApi.setModel("profile");
const files = storageApi.setModel(["bucket", "file"]);

await profile.get({ delimiters: "me" });
await files.get({ delimiters: ["avatars", "marcos.webp"] });

En este ejemplo solo usersApi envía el encabezado de autorización; storageApi sube archivos como multipart y descarga como Blob sin repetirlo en cada llamada.

¿Necesitas algo parecido?

Cuéntame qué tienes en mente y lo platicamos.