@hypernym/utils 3.2.1 → 3.4.0

package/README.md

@@ -77,7 +77,7 @@ Also, it is possible to download files manually and serve them accordingly.
 
 ### isBrowser
 
-Checks if the code is running in the browser.
+Checks if the code is running in the `browser`.
 
 ```ts
 import { isBrowser } from '@hypernym/utils'
@@ -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'
@@ -127,9 +127,29 @@ import { exists } from '@hypernym/utils/fs'
 await exists('dir/file.ts') // => true
 ```
 
+### read
+
+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'

package/dist/fs/index.mjs

@@ -1,4 +1,4 @@
-import { access, constants, mkdir as mkdir$1, writeFile as writeFile$1, cp, rm } from 'node:fs/promises';
+import { access, constants, readFile, readdir as readdir$1, mkdir as mkdir$1, writeFile as writeFile$1, cp, rm } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isURL, isString } from '../index.mjs';
@@ -7,6 +7,20 @@ async function exists(path) {
   return await access(path, constants.F_OK).then(() => true).catch(() => false);
 }
 
+async function read(path, options = {}) {
+  const { encoding = "utf-8" } = options;
+  return await readFile(path, { encoding, ...options });
+}
+
+async function readdir(path, options = {}) {
+  const { encoding = "utf-8", recursive = true } = options;
+  return await readdir$1(path, {
+    encoding,
+    recursive,
+    ...options
+  });
+}
+
 async function write(path, data, options) {
   await mkdir$1(dirname(isURL(path) ? fileURLToPath(path) : path), {
     recursive: true
@@ -42,4 +56,4 @@ async function remove(path, options = {}) {
   }
 }
 
-export { copy, exists, mkdir, remove, write, writeFile };
+export { copy, exists, mkdir, read, readdir, remove, write, writeFile };

package/dist/types/fs/index.d.ts

@@ -1,7 +1,8 @@
+import { Dirent } from 'node:fs';
 import { writeFile as writeFile$1 } from 'node:fs/promises';
 
 /**
- * Checks if the file or directory exists.
+ * Checks if the `file` or `directory` exists.
  *
  * @example
  *
@@ -13,9 +14,82 @@ import { writeFile as writeFile$1 } from 'node:fs/promises';
  */
 declare function exists(path: string): Promise<boolean>;
 
+type ReadPath = string | URL;
+type ReadEncodingType = BufferEncoding | null | undefined;
+type ReadType<T> = T extends BufferEncoding | undefined ? string : T extends null ? Buffer : never;
+interface ReadOptions<T extends ReadEncodingType> {
+    /**
+     * If no encoding is specified, the data is returned as a `Buffer` object. Otherwise, the data will be a string.
+     *
+     * @default 'utf-8'
+     */
+    encoding?: T;
+    /**
+     * When provided the corresponding `AbortController` can be used to cancel an asynchronous action.
+     *
+     * @default undefined
+     */
+    signal?: AbortSignal;
+    /**
+     * If a flag is not provided, it defaults to `'r'`.
+     *
+     * @default 'r'
+     */
+    flag?: number | string;
+}
+/**
+ * Reads the entire contents of a `file`.
+ *
+ * @example
+ *
+ * ```ts
+ * import { read } from '@hypernym/utils/fs'
+ *
+ * await read('dir/subdir/file.ts')
+ * ```
+ */
+declare function read<T extends ReadEncodingType = BufferEncoding>(path: ReadPath, options?: ReadOptions<T>): Promise<ReadType<T>>;
+
+type ReaddirPath = string | URL;
+type ReaddirEncodingType = BufferEncoding | null | 'buffer' | undefined;
+type ReaddirWithFileType = true | undefined;
+type ReaddirType<E, F> = F extends true ? Dirent : E extends BufferEncoding | undefined ? string : E extends null | 'buffer' ? Buffer : never;
+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')
+ * ```
+ */
+declare function readdir<E extends ReaddirEncodingType = BufferEncoding, F extends ReaddirWithFileType = undefined>(path: ReaddirPath, options?: ReaddirOptions<E, F>): Promise<ReaddirType<E, F>[]>;
+
 type WritePath = string | URL;
 /**
- * Writes data to a file recursively.
+ * Writes data to a `file` recursively.
  *
  * @example
  *
@@ -146,4 +220,4 @@ interface RemoveOptions {
  */
 declare function remove(path: RemovePath | RemovePath[], options?: RemoveOptions): Promise<void>;
 
-export { type CopyDestination, type CopyOptions, type CopySource, type MakeDirOptions, type MakeDirPath, type RemoveOptions, type RemovePath, type WritePath, copy, exists, mkdir, remove, write, writeFile };
+export { type CopyDestination, type CopyOptions, type CopySource, type MakeDirOptions, type MakeDirPath, type ReadEncodingType, type ReadOptions, type ReadPath, type ReadType, type ReaddirEncodingType, type ReaddirOptions, type ReaddirPath, type ReaddirType, type ReaddirWithFileType, type RemoveOptions, type RemovePath, type WritePath, copy, exists, mkdir, read, readdir, remove, write, writeFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypernym/utils",
-  "version": "3.2.1",
+  "version": "3.4.0",
   "author": "Hypernym Studio",
   "description": "A collection of reusable utilities.",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "prepublishOnly": "npm run build"
   },
   "sideEffects": false,
-  "packageManager": "pnpm@9.10.0",
+  "packageManager": "pnpm@9.11.0",
   "engines": {
     "node": ">=20.0.0",
     "pnpm": ">=9.0.0"
@@ -66,7 +66,7 @@
     "@hypernym/bundler": "^0.11.0",
     "@hypernym/eslint-config": "^3.5.0",
     "@hypernym/prettier-config": "^3.2.0",
-    "@hypernym/tsconfig": "^2.3.0",
+    "@hypernym/tsconfig": "^2.4.0",
     "@types/node": "^22.5.5",
     "eslint": "^9.10.0",
     "prettier": "^3.3.3",