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
| Formato | Archivo | Úsalo cuando… |
|---|---|---|
| ESM | dist/esm/index.js | Trabajas con un bundler moderno o con módulos ES nativos (recomendado). |
| CJS | dist/cjs/index.cjs | Tu entorno de Node.js usa require(). |
| IIFE / CDN | dist/cdn/neysla.min.js | Cargas la librería con una etiqueta <script>. |
| Tipos | dist/types/index.d.ts | Siempre: 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
fetches 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étodo | Verbo HTTP | Envía cuerpo |
|---|---|---|
Neysla.get(options) | GET | No |
Neysla.head(options) | HEAD | No |
Neysla.post(options) | POST | Sí |
Neysla.patch(options) | PATCH | Sí |
Neysla.put(options) | PUT | Sí |
Neysla.remove(options) | DELETE | Sí |
Opciones de la petición
| Opción | Tipo | Requerida | Por defecto | Descripción |
|---|---|---|---|---|
url | string | Sí | — | URL completa del endpoint. |
params | Record<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). |
headers | Record<string, string> | No | {} | Encabezados de la petición. |
body | Record<string, unknown> | FormData | No | — | 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. |
credentials | RequestCredentials | No | — | Igual que en fetch ("include" para enviar cookies a otro origen). |
progress | (event: ProgressEvent) => void | No | — | 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.stringifyyContent-Type: application/json."urlencoded"(por defecto):application/x-www-form-urlencoded."multipart": se construye unFormDatay el navegador define elContent-Typecon su boundary. También puedes pasar tu propioFormData.
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étodo | Tipo | Descripción |
|---|---|---|
status | number | Código de estado HTTP. |
statusText | string | Texto del estado. |
data | T | Cuerpo de la respuesta, leído según responseType. |
dataType | NeyslaResponseType | El responseType con el que se leyó. |
headers | Record<string, string> | Encabezados de la respuesta. Las claves siempre llegan en minúsculas. |
url | string | URL a la que se hizo la petición. |
getHeader(name) | string | null | Un 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 unTypeError. - 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 leerstatusydata:
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:
useryuser/:user_id. - Contactos de un usuario:
user/:user_id/contactyuser/:user_id/contact/:contact_id. - Teléfonos de un contacto:
user/:user_id/contact/:contact_id/phoney.../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:
| Atributo | Tipo | Requerido | Descripción |
|---|---|---|---|
name | string | Sí | Nombre del modelador; es la clave en el objeto que devuelve init. |
url | string | Sí | Base de las URLs de todos sus modelos. |
headers | Record<string, string> | No | Encabezados globales. |
params | NeyslaParams | No | Parámetros de query globales. |
body | Record<string, unknown> | No | Campos del cuerpo que se envían en cada post, patch, put y remove. |
requestType | "json" | "multipart" | "urlencoded" | No | Serialización del cuerpo por defecto (si no se indica, urlencoded). |
responseType | NeyslaResponseType | No | Lectura de la respuesta por defecto (si no se indica, json). |
credentials | RequestCredentials | No | Polí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 enurlal inicializar.userycontact: las partes estáticas, que van ensetModel.:user_idy:contact_id: las partes dinámicas, que van en cada petición comodelimiters.
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ón | Tipo | Descripción |
|---|---|---|
delimiters | string | number | Array<string | number> | Las partes dinámicas del recurso, en orden. |
params | NeyslaParams | Se combinan con los globales; los de la petición ganan. |
headers | Record<string, string> | Se combinan con los globales; los de la petición ganan. |
body | Record<string, unknown> | FormData | Se combina con el body global (solo en métodos con cuerpo). |
requestType | NeyslaRequestType | Sobrescribe el global para esta petición. |
responseType | NeyslaResponseType | Sobrescribe el global para esta petición. |
credentials | RequestCredentials | Sobrescribe el global para esta petición. |
progress | (event: ProgressEvent) => void | Progreso 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.