feat(fs/unstable): add readDirSync

[jbronder]

This PR adds the readDirSync API to @std/fs, which is intended to mirror the Deno.readDirSync function. The PR also adds additional @param and @returns documentation to the readDir API.

Towards #6255 .

[codecov]

Codecov Report

Attention: Patch coverage is 28.57143% with 10 lines in your changes missing coverage. Please review.

Project coverage is 95.75%. Comparing base (3b75ee7) to head (49c01ca).

Files with missing lines	Patch %	Lines
fs/unstable_read_dir.ts	28.57%	10 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6381      +/-   ##
==========================================
- Coverage   96.23%   95.75%   -0.48%     
==========================================
  Files         556      554       -2     
  Lines       42065    37209    -4856     
  Branches     6371     6358      -13     
==========================================
- Hits        40481    35630    -4851     
+ Misses       1544     1533      -11     
- Partials       40       46       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[kt3k]

CI is failing with Deno v1.x because IteratorObject type is not available in Deno 1.x (which uses TypeScript 5.5. IteratorObject was added in TypeScript 5.6).

One workaround is to use Iterable instead, but that prevents us using iterator helper method on it.

Does anyone have an idea to best handle this situation?

[jbronder]

I've only tried testing it on Deno v1.46.0, the function signatures are indeed different for readDirSync:

// In the 1.x Deno namespace:
function readDirSync(path: string | URL): Iterable<DirEntry>

// In the 2.x Deno namespace:
function readDirSync(path: string | URL): IteratorObject<DirEntry>

I suppose there's no real benefit to having readDirSync use a return type of Iterable<DirEntry> for the @std/fs package for both 1.x and 2.x other than to satisfy the CI, unless that is indeed the goal.

After modifying the return type to Iterable<DirType>, the iterable returned by Deno 1.x readDirSync does allow access to Iterator Helper methods after testing it out in a small script in the project root:

import { readDirSync } from "./fs/unstable_read_dir.ts";

const dir = readDirSync("fs/testdata");
const partialList = dir.take(5).toArray();
console.log("partialList:", partialList);

It probably doesn't help from a TypeScript perspective since the function signature does not semantically convey what the function does because of the return type differences.

I can leave this on the back burner for now and make progress on other APIs and return to it.

[petamoriken]

How about defining the type of IteratorObject here?

Suggested change

	interface IteratorObject<T> extends Iterable<T> {}

In Deno 1 (TypeScript 5.3 or lower), it should be treated as just a new type definition, and in Deno 2 (TypeScript 5.4 or higher), where IteratorObject type exists, it should be treated as a merge of interface types and nothing should happen.