La prueba de origen de la API de File System Observer

Thomas Steiner

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

La API de File System Observer, en prueba de origen de Chrome 129, cambia esta situación y permite que los desarrolladores reciban alertas automáticas cuando se producen cambios. En esta guía, se explica cómo funciona y cómo probarla.

Casos de uso

Usa la API de File System Observer en apps que necesiten ser informadas de posibles cambios en el sistema de archivos en cuanto se produzcan.

  • Son entornos de desarrollo integrados (IDE) basados en la Web que muestran una representación del árbol del sistema de archivos de un proyecto.
  • Las apps que sincronizan cambios del sistema de archivos con un servidor Por ejemplo, un archivo de base de datos SQLite.
  • Apps que deben notificar al subproceso principal sobre los cambios en el 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

Cómo usar la API de File System Observer

Detección de funciones

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.
}

Inicializa un observador del sistema de archivos

Inicializa un observador del sistema de archivos llamando a new FileSystemObserver() y proporciónale una función callback como argumento.

const observer = new FileSystemObserver(callback);

Comienza a observar un archivo o directorio

Para comenzar a observar un archivo o directorio, llama al método asíncrono observe() de la instancia FileSystemObserver. Proporciona 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 manera recurrente (es decir, para el directorio en sí y para todos los subdirectorios y archivos contenidos). La opción predeterminada es solo observar el directorio en sí y los archivos contenidos 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 observer como sus argumentos. Puedes usar el argumento observer para, por ejemplo, desconectar al observador (consulta Deja 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 cambio del sistema de archivos tiene la siguiente estructura. Todos los campos son de solo lectura.

  • root (un FileSystemHandle): Es el controlador que se pasa a la función FileSystemObserver.observe().
  • changedHandle (un FileSystemHandle): Es el controlador afectado por el cambio del sistema de archivos.
  • relativePathComponents (un Array): Es la ruta de acceso de changedHandle en relación con el 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": Indica que se perdieron cero o más eventos. Los desarrolladores deben sondear el directorio observado en respuesta a esto.
    • "errored": La observación ya no es válida. En este caso, es posible que quieras dejar de observar el sistema de archivos.
  • relativePathMovedFrom (un Array, opcional): Es la ubicación anterior de un controlador que se movió. 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);

Dejar de observar el sistema de archivos

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

observer.disconnect();

Prueba la API

Para probar la API de File System Observer de forma local, configura 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 realizará desde Chrome 129 (11 de septiembre de 2024) a Chrome 134 (26 de febrero de 2025).

Demostración

Puedes ver la API de File System Observer en acción en la demostración incorporada. Consulta el código fuente o remezcla el 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 leíste esto en un navegador que no es compatible con 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, comenta el problema n.o 123 en el repositorio WHATWG/fs.

Agradecimientos

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