La prueba de origen de la API de File System Observer

Thomas Steiner

La API de acceso al sistema de archivos y la API de sistema de archivos privados de origen permiten que los desarrolladores accedan a archivos y directorios en el dispositivo del usuario. El primero permite a los desarrolladores leer y escribir en el sistema de archivos normal que el usuario puede ver, y el segundo abre un sistema de archivos especial oculto para el usuario que es privado para el origen de cada sitio y que tiene ciertas ventajas de rendimiento. La forma en que los desarrolladores interactúan con los archivos y directorios en ambos casos es a través de objetos FileSystemHandle, más concretamente, FileSystemFileHandle para los archivos y FileSystemDirectoryHandle para los directorios. Hasta ahora, para recibir información sobre los cambios en un archivo o directorio en cualquiera de los sistemas de archivos, se requería algún tipo de sondeo y comparación de la marca de tiempo lastModified o incluso del contenido del archivo.

La API de File System Observer, en la prueba de origen de Chrome 129, cambia eso y permite que los desarrolladores reciban alertas automáticamente cuando se produzcan cambios. En esta guía, se explica cómo funciona y cómo probar la función.

Casos de uso

Usa la API de File System Observer en las apps que deban informarse sobre posibles cambios en el sistema de archivos en cuanto ocurran.

  • Entornos de desarrollo integrados (IDEs) basados en la Web que muestran una representación del árbol del sistema de archivos de un proyecto.
  • Apps que sincronizan los cambios del sistema de archivos con un servidor Por ejemplo, un archivo de base de datos SQLite.
  • Apps que necesitan notificar al subproceso principal los cambios del sistema de archivos desde un trabajador o desde otra pestaña.
  • Apps que observan un directorio de recursos, por ejemplo, para optimizar imágenes automáticamente.
  • Experiencias que se benefician de la recarga en caliente, como presentaciones de diapositivas basadas en HTML en las que se activa una recarga por un cambio de archivo

Cómo usar la API de File System Observer

Detección de atributos

Para ver si la API de File System Observer es compatible, ejecuta una prueba de funciones como en el siguiente ejemplo.

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

Cómo inicializar un observador de sistemas de archivos

Para inicializar un observador de sistemas de archivos, llama a new FileSystemObserver() y proporciónale una función callback como argumento.

const observer = new FileSystemObserver(callback);

Cómo comenzar a observar un archivo o directorio

Para comenzar a observar un archivo o directorio, llama al método observe() asíncrono de la instancia de FileSystemObserver. Proporciona a este método el FileSystemHandle del archivo o directorio seleccionado como argumento. Cuando observas un directorio, hay un argumento options opcional que te permite elegir si deseas recibir información sobre los cambios en el directorio de forma recursiva (es decir, para el directorio en sí y todos los subdirectorios y archivos contenidos). La opción predeterminada es observar solo el directorio en sí y los archivos que contiene directamente.

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

La función de devolución de llamada

Cuando se producen cambios en el sistema de archivos, se llama a una función de devolución de llamada con el cambio del sistema de archivos records y el observer como argumentos. Puedes usar el argumento observer para, por ejemplo, desconectar el observador (consulta Cómo dejar de observar el sistema de archivos) cuando se borren todos los archivos que te interesan.

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

El registro de cambios del sistema de archivos

Cada registro de cambios del sistema de archivos tiene la siguiente estructura. Todos los campos son de solo lectura.

  • root (un FileSystemHandle): Es el identificador que se pasa a la función FileSystemObserver.observe().
  • changedHandle (un FileSystemHandle): Es el identificador afectado por el cambio del sistema de archivos. Este campo será null para eventos de tipo "errored", "unknown" y "disappeared". Para ver qué archivo o directorio desapareció, usa relativePathComponents.
  • relativePathComponents (un Array): Es la ruta de acceso de changedHandle en relación con root.
  • type (un String): Es el tipo de cambio. Los siguientes tipos son posibles:
    • "appeared": El archivo o directorio se creó o se movió a root.
    • "disappeared": El archivo o directorio se borró o se movió fuera de root.
    • "modified": Se modificó el archivo o directorio.
    • "moved": El archivo o directorio se movió dentro de root.
    • "unknown": Esto indica que se omitieron cero o más eventos. Los desarrolladores deben sondear el directorio supervisado en respuesta a esto.
    • "errored": La observación ya no es válida. En este caso, te recomendamos que dejes de observar el sistema de archivos. Este valor también se enviará cuando se alcance el límite máximo de observaciones por origen. Este límite depende del sistema operativo y no se conoce de antemano. Si esto sucede, el sitio puede decidir volver a intentarlo, aunque no hay garantía de que el sistema operativo haya liberado suficientes recursos. Otro caso en el que se enviará este valor es cuando se borre o mueva el identificador observado (es decir, la raíz de la observación). En este caso, primero se envía el evento "disappeared", seguido de un evento "errored", que indica que la observación ya no es válida. Por último, este evento se envía cuando se quita el permiso al directorio o al identificador de archivo.
  • relativePathMovedFrom (un Array, opcional): Es la ubicación anterior de un control de desplazamiento. Solo está disponible cuando type es "moved".

Cómo dejar de observar un archivo o directorio

Para dejar de observar un FileSystemHandle, llama al método unobserve() y pásale el controlador como argumento.

observer.unobserve(fileHandle);

Cómo dejar de observar el sistema de archivos

Para dejar de observar el sistema de archivos, desconecta la instancia de FileSystemObserver de la siguiente manera.

observer.disconnect();

Prueba la API

Para probar la API de File System Observer de forma local, establece la marca #file-system-observer en about:flags. Para probar la API con usuarios reales, regístrate en la prueba de origen y sigue las instrucciones que se indican en la guía Pruebas de origen de Chrome. La prueba de origen se ejecutará desde Chrome 129 (11 de septiembre de 2024) hasta Chrome 134 (26 de febrero de 2025).

Demostración

Puedes ver la API de File System Observer en acción en la demo incorporada. Consulta el código fuente o haz un remix del código de demostración en Glitch. La demostración crea, borra o modifica archivos de forma aleatoria en un directorio observado y registra su actividad en la parte superior de la ventana de la app. Luego, registra los cambios a medida que ocurren en la parte inferior de la ventana de la app. Si lees esto en un navegador que no admite la API de File System Observer, consulta una captura de pantalla de la demostración.

Comentarios

Si tienes comentarios sobre la forma de la API de File System Observer, hazlos en el problema #123 del repositorio WHATWG/fs.

Agradecimientos

Daseul Lee, Nathan Memmott, Etienne Noël y Rachel Andrew revisaron este documento.