@hypernym/utils 3.0.1 → 3.2.0

package/README.md

@@ -1,12 +1,22 @@
-# @hypernym/utils
+<h1 align="center">Hyperutils</h1>
 
-A collection of reusable utilities.
+<p align="center">A collection of reusable utilities.</p>
 
-<sub><a href="https://github.com/hypernym-studio/utils">Repository</a> | <a href="https://www.npmjs.com/package/@hypernym/utils">Package</a> | <a href="https://github.com/hypernym-studio/utils/releases">Releases</a> | <a href="https://github.com/hypernym-studio/utils/discussions">Discussions</a></sub>
+<p align="center">
+  <a href="https://github.com/hypernym-studio/utils">Repository</a>
+  <span>+</span>
+  <a href="https://www.npmjs.com/package/@hypernym/utils">Package</a>
+  <span>+</span>
+  <a href="https://github.com/hypernym-studio/utils/releases">Releases</a>
+  <span>+</span>
+  <a href="https://github.com/hypernym-studio/utils/discussions">Discussions</a>
+</p>
 
-```sh
-pnpm add @hypernym/utils
-```
+<pre align="center">pnpm add @hypernym/utils</pre>
+
+<h4 align="center">Hypernym Studio</h4>
+
+<br>
 
 ## Features
 

package/dist/fs/index.mjs

@@ -1,13 +1,45 @@
-import { access, constants, mkdir, writeFile as writeFile$1 } from 'node:fs/promises';
+import { access, constants, 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';
 
 async function exists(path) {
   return await access(path, constants.F_OK).then(() => true).catch(() => false);
 }
 
-async function writeFile(path, data, options) {
-  await mkdir(dirname(path), { recursive: true });
-  return await writeFile$1(path, data, options);
+async function write(path, data, options) {
+  await mkdir$1(dirname(isURL(path) ? fileURLToPath(path) : path), {
+    recursive: true
+  });
+  await writeFile$1(path, data, options);
 }
+const writeFile = write;
 
-export { exists, writeFile };
+async function copy(source, destination, options = {}) {
+  const { recursive = true, filter } = options;
+  const sources = isString(source) || isURL(source) ? [source] : source;
+  for (const src of sources) {
+    await cp(src, destination, {
+      recursive,
+      filter
+    });
+  }
+}
+
+async function mkdir(path, options = {}) {
+  const { recursive = true, mode } = options;
+  const paths = isString(path) || isURL(path) ? [path] : path;
+  for (const p of paths) {
+    await mkdir$1(p, { recursive, mode });
+  }
+}
+
+async function remove(path, options = {}) {
+  const { recursive = true, force = true } = options;
+  const paths = isString(path) || isURL(path) ? [path] : path;
+  for (const p of paths) {
+    await rm(p, { recursive, force, ...options });
+  }
+}
+
+export { copy, exists, mkdir, remove, write, writeFile };

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

@@ -8,22 +8,142 @@ import { writeFile as writeFile$1 } from 'node:fs/promises';
  * ```ts
  * import { exists } from '@hypernym/utils/fs'
  *
- * exists('dir/file.ts') // => true
+ * await exists('dir/file.ts') // => true
  * ```
  */
 declare function exists(path: string): Promise<boolean>;
 
+type WritePath = string | URL;
 /**
  * Writes data to a file recursively.
  *
  * @example
  *
  * ```ts
- * import { writeFile } from '@hypernym/utils/fs'
+ * import { write } from '@hypernym/utils/fs'
  *
- * writeFile('dir/subdir/file.ts', `console.log('Hello World!')`)
+ * await write('dir/subdir/file.ts', `console.log('Hello World!')`)
  * ```
  */
-declare function writeFile(path: string, data: Parameters<typeof writeFile$1>[1], options?: Parameters<typeof writeFile$1>[2]): Promise<void>;
+declare function write(path: WritePath, data: Parameters<typeof writeFile$1>[1], options?: Parameters<typeof writeFile$1>[2]): Promise<void>;
+/**
+ * @deprecated Use `write` instead.
+ */
+declare const writeFile: typeof write;
+
+type CopySource = string | URL;
+type CopyDestination = string | URL;
+interface CopyOptions {
+    /**
+     * Copies files or directories recursively.
+     *
+     * @default true
+     */
+    recursive?: boolean;
+    /**
+     * Filters copied `files` or `directories`.
+     *
+     * Returns `true` to copy the item, `false` to ignore it.
+     *
+     * @default undefined
+     */
+    filter?(source: string, destination: string): boolean | Promise<boolean>;
+}
+/**
+ * Copies `files` or `directories` recursively.
+ *
+ * Accepts a single source or a range of sources.
+ *
+ * @example
+ *
+ * ```ts
+ * import { copy } from '@hypernym/utils/fs'
+ *
+ * await copy('src/subdir/file.ts', './dist/subdir')
+ * ```
+ */
+declare function copy(source: CopySource | CopySource[], destination: CopyDestination, options?: CopyOptions): Promise<void>;
+
+type MakeDirPath = string | URL;
+interface MakeDirOptions {
+    /**
+     * Indicates whether parent folders should be created.
+     *
+     * If a folder was created, the path to the first created folder will be returned.
+     *
+     * @default true
+     */
+    recursive?: boolean;
+    /**
+     * A file mode. If a string is passed, it is parsed as an octal integer.
+     *
+     * @default 0o777
+     */
+    mode?: string | number;
+}
+/**
+ * Creates a `directory` recursively.
+ *
+ * Accepts a single path or a range of paths.
+ *
+ * @example
+ *
+ * ```ts
+ * import { mkdir } from '@hypernym/utils/fs'
+ *
+ * await mkdir('src/subdir')
+ * ```
+ */
+declare function mkdir(path: MakeDirPath | MakeDirPath[], options?: MakeDirOptions): Promise<void>;
+
+type RemovePath = string | URL;
+interface RemoveOptions {
+    /**
+     * If `true`, perform a recursive directory removal.
+     *
+     * In recursive mode, operations are retried on failure.
+     *
+     * @default true
+     */
+    recursive?: boolean;
+    /**
+     * When `true`, exceptions will be ignored if `path` does not exist.
+     *
+     * @default true
+     */
+    force?: boolean;
+    /**
+     * If an `EBUSY`, `EMFILE`, `ENFILE`, `ENOTEMPTY`, or
+     * `EPERM` error is encountered, Node.js will retry the operation with a linear
+     * backoff wait of `retryDelay` ms longer on each try. This option represents the
+     * number of retries. This option is ignored if the `recursive` option is not
+     * `true`.
+     *
+     * @default 0
+     */
+    maxRetries?: number;
+    /**
+     * The amount of time in milliseconds to wait between retries.
+     *
+     * This option is ignored if the `recursive` option is not `true`.
+     *
+     * @default 100
+     */
+    retryDelay?: number;
+}
+/**
+ * Removes `files` and `directories` recursively.
+ *
+ * Accepts a single path or a range of paths.
+ *
+ * @example
+ *
+ * ```ts
+ * import { remove } from '@hypernym/utils/fs'
+ *
+ * await remove('src/subdir/file.ts')
+ * ```
+ */
+declare function remove(path: RemovePath | RemovePath[], options?: RemoveOptions): Promise<void>;
 
-export { exists, writeFile };
+export { type CopyDestination, type CopyOptions, type CopySource, type MakeDirOptions, type MakeDirPath, type RemoveOptions, type RemovePath, type WritePath, copy, exists, mkdir, remove, write, writeFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypernym/utils",
-  "version": "3.0.1",
+  "version": "3.2.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.9.0",
+  "packageManager": "pnpm@9.10.0",
   "engines": {
     "node": ">=20.0.0",
     "pnpm": ">=9.0.0"
@@ -63,14 +63,14 @@
     }
   },
   "devDependencies": {
-    "@hypernym/bundler": "^0.10.0",
+    "@hypernym/bundler": "^0.11.0",
     "@hypernym/eslint-config": "^3.5.0",
     "@hypernym/prettier-config": "^3.2.0",
     "@hypernym/tsconfig": "^2.3.0",
-    "@types/node": "^20.16.5",
+    "@types/node": "^22.5.5",
     "eslint": "^9.10.0",
     "prettier": "^3.3.3",
     "typescript": "^5.5.4",
-    "vitest": "^2.0.5"
+    "vitest": "^2.1.1"
   }
 }