fs: expose glob and globSync

PR-URL: nodejs#51912
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
Reviewed-By: Nitzan Uziely <linkgoron@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

doc/api/fs.md

@@ -1069,6 +1069,38 @@ including subdirectories and files.
 When copying a directory to another directory, globs are not supported and
 behavior is similar to `cp dir1/ dir2/`.
 
+### `fsPromises.glob(pattern[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `pattern` {string|string\[]}
+* `options` {Object}
+  * `cwd` {string} current working directory. **Default:** `process.cwd()`
+  * `exclude` {Function} Function to filter out files/directories. Return
+    `true` to exclude the item, `false` to include it. **Default:** `undefined`.
+* Returns: {AsyncIterator} An AsyncIterator that yields the paths of files
+  that match the pattern.
+
+```mjs
+import { glob } from 'node:fs/promises';
+
+for await (const entry of glob('**/*.js'))
+  console.log(entry);
+```
+
+```cjs
+const { glob } = require('node:fs/promises');
+
+(async () => {
+  for await (const entry of glob('**/*.js'))
+    console.log(entry);
+})();
+```
+
 ### `fsPromises.lchmod(path, mode)`
 
 <!-- YAML
@@ -3073,6 +3105,44 @@ changes:
 Change the file system timestamps of the object referenced by the supplied file
 descriptor. See [`fs.utimes()`][].
 
+### `fs.glob(pattern[, options], callback)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `pattern` {string|string\[]}
+
+* `options` {Object}
+  * `cwd` {string} current working directory. **Default:** `process.cwd()`
+  * `exclude` {Function} Function to filter out files/directories. Return
+    `true` to exclude the item, `false` to include it. **Default:** `undefined`.
+
+* `callback` {Function}
+  * `err` {Error}
+
+* Retrieves the files matching the specified pattern.
+
+```mjs
+import { glob } from 'node:fs';
+
+glob('**/*.js', (err, matches) => {
+  if (err) throw err;
+  console.log(matches);
+});
+```
+
+```cjs
+const { glob } = require('node:fs');
+
+glob('**/*.js', (err, matches) => {
+  if (err) throw err;
+  console.log(matches);
+});
+```
+
 ### `fs.lchmod(path, mode, callback)`
 
 <!-- YAML
@@ -5529,6 +5599,33 @@ changes:
 
 Synchronous version of [`fs.futimes()`][]. Returns `undefined`.
 
+### `fs.globSync(pattern[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `pattern` {string|string\[]}
+* `options` {Object}
+  * `cwd` {string} current working directory. **Default:** `process.cwd()`
+  * `exclude` {Function} Function to filter out files/directories. Return
+    `true` to exclude the item, `false` to include it. **Default:** `undefined`.
+* Returns: {string\[]} paths of files that match the pattern.
+
+```mjs
+import { globSync } from 'node:fs';
+
+console.log(globSync('**/*.js'));
+```
+
+```cjs
+const { globSync } = require('node:fs');
+
+console.log(globSync('**/*.js'));
+```
+
 ### `fs.lchmodSync(path, mode)`
 
 <!-- YAML

lib/fs.js

@@ -86,6 +86,8 @@ const {
 const { toPathIfFileURL } = require('internal/url');
 const {
   customPromisifyArgs: kCustomPromisifyArgsSymbol,
+  emitExperimentalWarning,
+  getLazy,
   kEmptyObject,
   promisify: {
     custom: kCustomPromisifiedSymbol,
@@ -3102,6 +3104,38 @@ function createWriteStream(path, options) {
   return new WriteStream(path, options);
 }
 
+const lazyGlob = getLazy(() => require('internal/fs/glob').Glob);
+
+function glob(pattern, options, callback) {
+  emitExperimentalWarning('glob');
+  if (typeof options === 'function') {
+    callback = options;
+    options = undefined;
+  }
+  callback = makeCallback(callback);
+
+  const Glob = lazyGlob();
+  // TODO: Use iterator helpers when available
+  (async () => {
+    try {
+      const res = [];
+      for await (const entry of new Glob(pattern, options).glob()) {
+        ArrayPrototypePush(res, entry);
+      }
+      callback(null, res);
+    } catch (err) {
+      callback(err);
+    }
+  })();
+}
+
+function globSync(pattern, options) {
+  emitExperimentalWarning('globSync');
+  const Glob = lazyGlob();
+  return new Glob(pattern, options).globSync();
+}
+
+
 module.exports = fs = {
   appendFile,
   appendFileSync,
@@ -3135,6 +3169,8 @@ module.exports = fs = {
   ftruncateSync,
   futimes,
   futimesSync,
+  glob,
+  globSync,
   lchown,
   lchownSync,
   lchmod: constants.O_SYMLINK !== undefined ? lchmod : undefined,