slow_file_system 1.0.0

Simulate slow file systems by wrapping package:file with delayed I/O operations and delayed returned file objects.

slow_file_system

slow_file_system wraps any package:file FileSystem and adds a fixed artificial delay to operations that touch the file system.

It is useful for tests and demos where code should behave correctly when storage is slow, without changing the real file system implementation underneath.

Features

• Adds a configurable delay to file system I/O: create, delete, rename, read, write, stat, type checks, directory listing, links, metadata changes, RandomAccessFile operations, and IOSink writes from openWrite().
• Keeps non-I/O operations fast: file(), directory(), link(), path helpers, basename, dirname, parent, absolute, uri, and isWatchSupported do not sleep.
• Wraps returned objects so later calls are still slow: SlowDirectory, SlowFile, SlowLink, SlowRandomAccessFile, and SlowIOSink.
• Works with MemoryFileSystem, LocalFileSystem, and other package:file implementations.
• Targets Dart and Flutter I/O platforms. It is not intended for web builds because package:file exposes dart:io file types.

Installation

dependencies:
  slow_file_system: ^1.0.0

Usage

import 'dart:io' as io;

import 'package:file/memory.dart';
import 'package:slow_file_system/slow_file_system.dart';

Future<void> main() async {
  final memoryFs = MemoryFileSystem();
  final fs = SlowFileSystem(memoryFs, const Duration(milliseconds: 500));

  final directory = await fs.directory('/tmp').create();
  final file = directory.childFile('note.txt');

  final stopwatch = Stopwatch()..start();
  await file.writeAsString('hello');
  print('write took ${stopwatch.elapsedMilliseconds} ms');

  stopwatch
    ..reset()
    ..start();
  print(file.basename);
  print('basename took ${stopwatch.elapsedMicroseconds} us');

  final sink = file.openWrite(mode: io.FileMode.append);
  sink.writeln('more data');
  await sink.close();
}

Delay Contract

The delay is added once per public I/O call before the wrapped delegate performs the operation. Calls that fail still wait first, because the package is simulating latency in reaching the file system, not successful work only.

Stream-producing methods are lazy:

• File.openRead(), Directory.list(), and FileSystemEntity.watch() return quickly.
• The delay happens when the returned stream is listened to.
• Stream events are not throttled per chunk or per entry.

Returned handles keep the delay:

• File.open() and File.openSync() return SlowRandomAccessFile.
• File.openWrite() returns SlowIOSink.
• Directory, file, and link operations that return entities return SlowDirectory, SlowFile, or SlowLink.

Synchronous delayed methods use dart:io's sleep, so they block the current isolate just like other synchronous file APIs. Asynchronous delayed methods wait with a timer and then call the delegate.

The package does not simulate bandwidth, throughput, caching, random latency, or file system errors. It preserves the behavior of the wrapped FileSystem, including symlink behavior such as Directory.list(followLinks: true).

Testing This Package

dart test
dart analyze