feat: add new fs readdir util (#21)

Author: ivodolenc

README.md

@@ -119,7 +119,7 @@ isString('@hypernym/utils') // => true
 
 ### exists
 
-Checks if the file or directory exists.
+Checks if the `file` or `directory` exists.
 
 ```ts
 import { exists } from '@hypernym/utils/fs'
@@ -129,17 +129,27 @@ await exists('dir/file.ts') // => true
 
 ### read
 
-Reads the entire contents of a file.
+Reads the entire contents of a `file`.
 
 ```ts
 import { read } from '@hypernym/utils/fs'
 
 await read('dir/subdir/file.ts')
 ```
 
+### readdir
+
+Reads the contents of a `directory` recursively.
+
+```ts
+import { readdir } from '@hypernym/utils/fs'
+
+await readdir('dir/subdir')
+```
+
 ### write
 
-Writes data to a file recursively.
+Writes data to a `file` recursively.
 
 ```ts
 import { write } from '@hypernym/utils/fs'

src/fs/exists.ts

@@ -1,7 +1,7 @@
 import { access, constants } from 'node:fs/promises'
 
 /**
- * Checks if the file or directory exists.
+ * Checks if the `file` or `directory` exists.
  *
  * @example
  *

src/fs/index.ts

@@ -1,5 +1,6 @@
 export * from './exists'
 export * from './read'
+export * from './readdir'
 export * from './write'
 export * from './copy'
 export * from './mkdir'

src/fs/read.ts

@@ -30,7 +30,7 @@ export interface ReadOptions<T extends ReadEncodingType> {
 }
 
 /**
- * Reads the entire contents of a file.
+ * Reads the entire contents of a `file`.
  *
  * @example
  *

src/fs/readdir.ts

@@ -0,0 +1,65 @@
+import { readdir as readDir } from 'node:fs/promises'
+import type { Dirent } from 'node:fs'
+
+export type ReaddirPath = string | URL
+export type ReaddirEncodingType = BufferEncoding | null | 'buffer' | undefined
+export type ReaddirWithFileType = true | undefined
+
+export type ReaddirType<E, F> = F extends true
+  ? Dirent
+  : E extends BufferEncoding | undefined
+    ? string
+    : E extends null | 'buffer'
+      ? Buffer
+      : never
+
+export interface ReaddirOptions<
+  E extends ReaddirEncodingType,
+  F extends ReaddirWithFileType,
+> {
+  /**
+   * If the encoding is set to `'buffer'` or `null`, the filenames returned will be passed as `Buffer` objects.
+   *
+   * @default 'utf-8'
+   */
+  encoding?: E
+  /**
+   * If `withFileTypes` is set to `true`, the returned array will contain `fs.Dirent` objects.
+   *
+   * @default undefined
+   */
+  withFileTypes?: F
+  /**
+   * Reads the directory recursively.
+   *
+   * @default true
+   */
+  recursive?: boolean
+}
+
+/**
+ * Reads the contents of a `directory` recursively.
+ *
+ * @example
+ *
+ * ```ts
+ * import { readdir } from '@hypernym/utils/fs'
+ *
+ * await readdir('dir/subdir')
+ * ```
+ */
+export async function readdir<
+  E extends ReaddirEncodingType = BufferEncoding,
+  F extends ReaddirWithFileType = undefined,
+>(
+  path: ReaddirPath,
+  options: ReaddirOptions<E, F> = {},
+): Promise<ReaddirType<E, F>[]> {
+  const { encoding = 'utf-8', recursive = true } = options
+
+  return (await readDir(path, {
+    encoding,
+    recursive,
+    ...options,
+  } as any)) as ReaddirType<E, F>[]
+}

src/fs/write.ts

@@ -6,7 +6,7 @@ import { isURL } from '@'
 export type WritePath = string | URL
 
 /**
- * Writes data to a file recursively.
+ * Writes data to a `file` recursively.
  *
  * @example
  *