OS.File.DirectoryIterator for workers

This document presents the mechanisms for walking the contents of a directory from a worker thread. For other uses of OS.File and OS.File.DirectoryIterator, please see the main document on OS.File.

Using OS.File.DirectoryIterator

Example: Finding the subdirectories of a directory using an iterator

The following snippet walks through the content of a directory, selecting subdirectories:

let iterator = new OS.File.DirectoryIterator(somePath);
try {
  for (let entry in iterator) {
    if (entry.isDir) {
      // entry is a directory
} finally {

Or a variant using array comprehension:

let iterator = new OS.File.DirectoryIterator(somePath);
try {
  return [entry for (entry in iterator) if (entry.isDir) ];
} finally {

Example: Sorting files by last modification date

The following takes advantage of feature detection to minimize file I/O:

let iterator = new OS.File.DirectoryIterator(somePath);
try {
  let entries;
  if ("winCreationDate" in OS.File.DirectoryIterator.Entry.prototype) {
    // Under Windows, additional information allow us to sort files immediately
    // without having to perform additional I/O.
    entries = [{entry: entry, creationDate: entry.winCreationDate} for (entry in iterator)];
  } else {
    // Under other OSes, we need to call OS.File.stat
    entries = [{entry: entry, creationDate: OS.File.stat(entry.path).creationDate} for (entry in iterator)];
  // Finally, sort the array
  return entries.sort(function compare(a, b) {
      return a.creationDate - b.creationDate;

Instances of OS.File.DirectoryIterator

General remark

All instances of worker thread OS.File.DirectoryIterator can be iterated using array comprehension. This is generally the best way to walk through a directory.

Instances of OS.File.DirectoryIterator uses valuable system resources ā€“ typically the same resources as files. There is a limit to the total number of files and directory iterators that can be open at any given time. Therefore, you should make sure that these resources are released as early as possible. To do this, you should use method close().


  in string path,
  [optional] in object options
) throws OS.File.Error
The full path to a directory.
An object that may contain the following fields:
(ignored on non-Windows platforms) This option accepts a pattern such as "*.exe" or "*.txt". The iterator will only display items whose name matches this pattern.

Method overview

void close()
void forEach(in function callback)
Array nextBatch([optional] in number length)
Entry next()



Close the iterator, releasing the system resources it uses.

void close() throws OS.File.Error

You should always call this method once you are done with an iterator. Calling this method several times is harmless. Calling this method while iterating through the directory is harmless but will stop the iteration.


Walk through the iterator.

void forEach(
  in function callback
) throws OS.File.Error
A function. It will be applied to each entry in the directory successively, with the following arguments:
An instance of OS.File.DirectoryIterator.Entry.
The index of the entry in the enumeration.
The iterator itself. You may stop the iteration by calling iterator.close().


Return several entries at once.

array nextBatch(
  [optional] in number entries
) throws OS.File.Error
The number of entries to return at once. If unspecified, all entries.

An array containing entries entries, or less if there are not enough entries left in the directory. Once iteration is complete, calls to nextBatch return the empty array.


Return the next entry in the directory.

Entry next() throws OS.File.Error, StopIteration

The next entry in the directory.

In case of file error
If the method is called after the last entry has been returned