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 41.17647% with 10 lines in your changes missing coverage. Please review.

Project coverage is 95.28%. Comparing base (61f9fd3) to head (9ede890).
Report is 3 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6381      +/-   ##
==========================================
- Coverage   95.29%   95.28%   -0.02%     
==========================================
  Files         576      576              
  Lines       43315    43331      +16     
  Branches     6477     6478       +1     
==========================================
+ Hits        41279    41286       +7     
- Misses       1995     2004       +9     
  Partials       41       41              

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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

[sigmaSd]

Is there on update on this ?

[kt3k]

Maybe we can make progress by making the return type to Iterable<DirEntry>. (It would be a little inconvenient because it doesn't have access to iterator helpers, but we can improve it later when we dropped that support of Deno 1.46)

BTW I tried @petamoriken's suggestion, but it didn't seem working unfortunately

[jbronder]

I'll take another look at this soon. While not related to the readDirSync, but still related to the File System, I'm currently working on a forthcoming PR for open, openSync, and FsFile` at the moment.

[jbronder]

I appreciate your patience, @kt3k. This PR is ready for review at your convenience.

[kt3k]

LGTM. Thanks!