JavaScript
Distingue el lenguaje JavaScript de las APIs que aporta el navegador y explica cómo el runtime conecta eventos, red, almacenamiento y renderizado.
JavaScript es el lenguaje. Las Web APIs son capacidades que el navegador proporciona para trabajar con documentos, red, almacenamiento, permisos, sensores y otros recursos.
ECMAScript
├─ valores
├─ funciones
├─ objetos
├─ promesas
└─ módulos
Navegador
├─ window y document
├─ eventos
├─ fetch
├─ almacenamiento
├─ timers
├─ workers
└─ permisos y dispositivosEstas características pertenecen al lenguaje:
Array;
Map;
Promise;
JSON;Estas pertenecen al navegador:
document;
fetch;
localStorage;
navigator;
setTimeout;Otros runtimes pueden ofrecer APIs diferentes.
globalThis === window;En una ventana principal normalmente es true. globalThis permite referirse al global de forma portable, aunque las propiedades disponibles dependen del contexto.
En un worker no existe window ni document, pero sí otro global.
El DOM representa documentos HTML y XML como nodos manipulables.
const button = document.querySelector("button");
button.textContent = "Save";No pertenece al núcleo de JavaScript; es una API del navegador.
button.addEventListener("click", handleClick);El navegador crea y despacha eventos. JavaScript ejecuta las callbacks cuando el Event Loop lo permite.
const response = await fetch("/api/products");Fetch trabaja con Request, Response, Headers, streams y políticas del navegador como CORS.
localStorage;
sessionStorage;
indexedDB;
caches;No son equivalentes:
new URL("/products", location.origin);
history.pushState({}, "", "/products");location, history y URL permiten leer o cambiar navegación bajo reglas del navegador.
await navigator.permissions.query({
name: "geolocation",
});No todas las APIs utilizan exactamente el mismo flujo de permisos. Algunas requieren:
if ("IntersectionObserver" in globalThis) {
// Usar la mejora.
}Detecta capacidades cuando existe una alternativa razonable. La presencia de una propiedad no siempre garantiza que el usuario conceda permiso o que todas las opciones estén soportadas.
APIs sensibles suelen requerir HTTPS. localhost puede recibir excepciones para desarrollo.
HTTPS no vuelve segura toda la aplicación; protege el transporte y habilita garantías necesarias para ciertas capacidades.
Callbacks:
navigator.geolocation.getCurrentPosition(
onSuccess,
onError,
);Eventos:
document.addEventListener(
"visibilitychange",
handleVisibility,
);Promesas:
await navigator.clipboard.writeText(text);Cada API define su contrato. No todas pueden consumirse de la misma manera.
Un listener, observer, timer o worker puede conservar referencias y seguir trabajando.
const observer = new IntersectionObserver(callback);
observer.observe(element);
function dispose() {
observer.disconnect();
}Quien inicia una capacidad también debería definir cómo detenerla.
Una API puede fallar porque:
No conviertas todos esos casos en un mensaje genérico sin conservar la causa.
Hay tres preguntas distintas:
¿La sintaxis se puede parsear?
¿La API existe?
¿La función está permitida en este contexto?Un transpiler puede resolver sintaxis, pero no inventar acceso a geolocalización o clipboard donde el host no lo ofrece.
Estas entradas siguen siendo externas:
Valida antes de llevarlas al núcleo de la aplicación.
async function copyText(text) {
if (navigator.clipboard?.writeText) {
await navigator.clipboard.writeText(text);
return;
}
throw new Error(
"Clipboard API is not available",
);
}La función expresa la ausencia de capacidad en lugar de fingir éxito.
¿Por qué Promise puede existir en un worker, pero document no?
Promise pertenece a ECMAScript. document pertenece al DOM de una ventana y un worker no controla directamente un documento.
DOM explica cómo el navegador representa, consulta y modifica un documento.