@hypernym/utils 3.1.0 → 3.2.1

package/README.md

@@ -14,7 +14,9 @@
 
 <pre align="center">pnpm add @hypernym/utils</pre>
 
-<h4 align="center">Hypernym Studio</h4>
+<p align="center">
+  <strong>Hypernym Studio</strong>
+</p>
 
 <br>
 
@@ -26,14 +28,179 @@
 
 ## Usage
 
+After installation, import `Hyperutils` into your project:
+
 ```ts
 // ESM & TS
 import { isNull, isString, ... } from '@hypernym/utils'
 
+// ESM & TS
+import { exists, copy, ... } from '@hypernym/utils/fs'
+
 // Types
 import type { IsAny, RequiredDeep, ... } from '@hypernym/utils'
 ```
 
+## CDN
+
+Here are some examples of how to integrate **Hyperutils** from a CDN via a script tag.
+
+Also, it is possible to download files manually and serve them accordingly.
+
+#### minified esm
+
+```html
+<script type="module">
+  import { isNull, isString, ... } from 'https://unpkg.com/@hypernym/utils/dist/index.min.mjs'
+</script>
+```
+
+#### minified iief
+
+```html
+<script src="https://unpkg.com/@hypernym/utils/dist/index.iief.mjs"></script>
+<script>
+  const { isNull, isString, ... } = Hyperutils
+</script>
+```
+
+#### minified umd
+
+```html
+<script src="https://unpkg.com/@hypernym/utils/dist/index.umd.mjs"></script>
+<script>
+  const { isNull, isString, ... } = Hyperutils
+</script>
+```
+
+## is
+
+### isBrowser
+
+Checks if the code is running in the browser.
+
+```ts
+import { isBrowser } from '@hypernym/utils'
+
+isBrowser // true
+```
+
+### isNull
+
+Returns a boolean if the given value is a `null`.
+
+```ts
+import { isNull } from '@hypernym/utils'
+
+isNull(null) // => true
+```
+
+### isUndefined
+
+Returns a boolean if the given value is a `undefined`.
+
+```ts
+import { isUndefined } from '@hypernym/utils'
+
+isUndefined(undefined) // => true
+```
+
+### isString
+
+Returns a boolean if the given value is a `string`.
+
+```ts
+import { isString } from '@hypernym/utils'
+
+isString('@hypernym/utils') // => true
+```
+
+## fs
+
+### exists
+
+Checks if the file or directory exists.
+
+```ts
+import { exists } from '@hypernym/utils/fs'
+
+await exists('dir/file.ts') // => true
+```
+
+### write
+
+Writes data to a file recursively.
+
+```ts
+import { write } from '@hypernym/utils/fs'
+
+await write('dir/subdir/file.ts', `console.log('Hello World!')`)
+```
+
+### copy
+
+Copies `files` or `directories` recursively.
+
+Accepts a single source or a range of sources.
+
+```ts
+import { copy } from '@hypernym/utils/fs'
+
+await copy('src/subdir/file.ts', './dist/subdir')
+```
+
+### mkdir
+
+Creates a `directory` recursively.
+
+Accepts a single path or a range of paths.
+
+```ts
+import { mkdir } from '@hypernym/utils/fs'
+
+await mkdir('src/subdir')
+```
+
+### remove
+
+Removes `files` and `directories` recursively.
+
+Accepts a single path or a range of paths.
+
+```ts
+import { remove } from '@hypernym/utils/fs'
+
+await remove('src/subdir/file.ts')
+```
+
+## Types
+
+### PartialDeep
+
+Constructs a type by recursively setting all properties as optional.
+
+Use `Partial<T>` for one level.
+
+```ts
+type PartialObject = PartialDeep<Object>
+
+// Disables recursive mode for arrays and tuples.
+type PartialObject = PartialDeep<Object, { arrays: false }>
+```
+
+### RequiredDeep
+
+Constructs a type by recursively setting all properties as required.
+
+Use `Required<T>` for one level.
+
+```ts
+type RequiredObject = RequiredDeep<Object>
+
+// Disables recursive mode for arrays and tuples.
+type RequiredObject = RequiredDeep<Object, { arrays: false }>
+```
+
 ## Community
 
 Feel free to ask questions or share new ideas.

package/dist/fs/index.mjs

@@ -1,17 +1,21 @@
-import { access, constants, mkdir, writeFile as writeFile$1, cp } 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 { isString, isURL } from '../index.mjs';
+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;
 
-async function copy(source, destination, options) {
+async function copy(source, destination, options = {}) {
   const { recursive = true, filter } = options;
   const sources = isString(source) || isURL(source) ? [source] : source;
   for (const src of sources) {
@@ -22,4 +26,20 @@ async function copy(source, destination, options) {
   }
 }
 
-export { copy, exists, writeFile };
+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/index.iife.js

@@ -0,0 +1 @@
+var Hyperutils=function(t){"use strict";const u=()=>{},e=i=>Object.prototype.toString.call(i).slice(8,-1),N=typeof window<"u",s=i=>i===null,l=i=>typeof i>"u",n=i=>typeof i=="string",S=i=>n(i)&&i.trim().length===0,a=i=>typeof i=="boolean",b=i=>i===!0,r=i=>i===!1,c=i=>typeof i=="number"&&!isNaN(i),m=i=>Array.isArray(i),d=i=>m(i)&&i.length===0,y=i=>e(i)==="Object",L=i=>y(i)&&Object.keys(i).length===0,H=i=>i instanceof Function,M=i=>typeof i=="number"&&isNaN(i),O=i=>i instanceof RegExp,j=i=>i instanceof Map,k=i=>i instanceof WeakMap,v=i=>i instanceof Set,A=i=>i instanceof WeakSet,o=i=>e(i)==="Symbol",B=i=>i instanceof Date&&!isNaN(i.valueOf()),f=i=>typeof i=="bigint",R=i=>i===1/0||i===-1/0,W=i=>i instanceof URL,h=i=>i instanceof Error,C=i=>n(i)||c(i)||f(i)||a(i)||o(i)||s(i)||l(i),F=i=>i instanceof Element,U=i=>i instanceof HTMLElement,w=i=>i instanceof SVGElement,E=i=>i instanceof NodeList,I=i=>E(i)&&i.length===0,g=i=>i instanceof HTMLCollection,T=i=>g(i)&&i.length===0;return t.isArray=m,t.isArrayEmpty=d,t.isBigInt=f,t.isBoolean=a,t.isBrowser=N,t.isDate=B,t.isElement=F,t.isError=h,t.isFalse=r,t.isFunction=H,t.isHtmlCollection=g,t.isHtmlCollectionEmpty=T,t.isHtmlElement=U,t.isInfinity=R,t.isMap=j,t.isNaNValue=M,t.isNodeList=E,t.isNodeListEmpty=I,t.isNull=s,t.isNumber=c,t.isObject=y,t.isObjectEmpty=L,t.isPrimitive=C,t.isRegExp=O,t.isSet=v,t.isString=n,t.isStringEmpty=S,t.isSvgElement=w,t.isSymbol=o,t.isTrue=b,t.isURL=W,t.isUndefined=l,t.isWeakMap=k,t.isWeakSet=A,t.noop=u,t.toString=e,t}({});

package/dist/index.min.mjs

@@ -0,0 +1 @@
+const y=()=>{},i=e=>Object.prototype.toString.call(e).slice(8,-1),g=typeof window<"u",s=e=>e===null,n=e=>typeof e>"u",t=e=>typeof e=="string",E=e=>t(e)&&e.trim().length===0,o=e=>typeof e=="boolean",N=e=>e===!0,b=e=>e===!1,a=e=>typeof e=="number"&&!isNaN(e),l=e=>Array.isArray(e),u=e=>l(e)&&e.length===0,r=e=>i(e)==="Object",S=e=>r(e)&&Object.keys(e).length===0,L=e=>e instanceof Function,d=e=>typeof e=="number"&&isNaN(e),M=e=>e instanceof RegExp,O=e=>e instanceof Map,h=e=>e instanceof WeakMap,j=e=>e instanceof Set,k=e=>e instanceof WeakSet,c=e=>i(e)==="Symbol",H=e=>e instanceof Date&&!isNaN(e.valueOf()),f=e=>typeof e=="bigint",A=e=>e===1/0||e===-1/0,R=e=>e instanceof URL,W=e=>e instanceof Error,v=e=>t(e)||a(e)||f(e)||o(e)||c(e)||s(e)||n(e),w=e=>e instanceof Element,x=e=>e instanceof HTMLElement,B=e=>e instanceof SVGElement,p=e=>e instanceof NodeList,C=e=>p(e)&&e.length===0,m=e=>e instanceof HTMLCollection,F=e=>m(e)&&e.length===0;export{l as isArray,u as isArrayEmpty,f as isBigInt,o as isBoolean,g as isBrowser,H as isDate,w as isElement,W as isError,b as isFalse,L as isFunction,m as isHtmlCollection,F as isHtmlCollectionEmpty,x as isHtmlElement,A as isInfinity,O as isMap,d as isNaNValue,p as isNodeList,C as isNodeListEmpty,s as isNull,a as isNumber,r as isObject,S as isObjectEmpty,v as isPrimitive,M as isRegExp,j as isSet,t as isString,E as isStringEmpty,B as isSvgElement,c as isSymbol,N as isTrue,R as isURL,n as isUndefined,h as isWeakMap,k as isWeakSet,y as noop,i as toString};

package/dist/index.umd.js

@@ -0,0 +1 @@
+(function(e,n){typeof exports=="object"&&typeof module<"u"?n(exports):typeof define=="function"&&define.amd?define(["exports"],n):(e=typeof globalThis<"u"?globalThis:e||self,n(e.Hyperutils={}))})(this,function(e){"use strict";const n=()=>{},t=i=>Object.prototype.toString.call(i).slice(8,-1),d=typeof window<"u",l=i=>i===null,a=i=>typeof i>"u",s=i=>typeof i=="string",N=i=>s(i)&&i.trim().length===0,o=i=>typeof i=="boolean",S=i=>i===!0,b=i=>i===!1,f=i=>typeof i=="number"&&!isNaN(i),m=i=>Array.isArray(i),r=i=>m(i)&&i.length===0,c=i=>t(i)==="Object",L=i=>c(i)&&Object.keys(i).length===0,H=i=>i instanceof Function,h=i=>typeof i=="number"&&isNaN(i),j=i=>i instanceof RegExp,M=i=>i instanceof Map,O=i=>i instanceof WeakMap,k=i=>i instanceof Set,A=i=>i instanceof WeakSet,y=i=>t(i)==="Symbol",B=i=>i instanceof Date&&!isNaN(i.valueOf()),u=i=>typeof i=="bigint",R=i=>i===1/0||i===-1/0,T=i=>i instanceof URL,W=i=>i instanceof Error,v=i=>s(i)||f(i)||u(i)||o(i)||y(i)||l(i)||a(i),C=i=>i instanceof Element,F=i=>i instanceof HTMLElement,U=i=>i instanceof SVGElement,E=i=>i instanceof NodeList,w=i=>E(i)&&i.length===0,g=i=>i instanceof HTMLCollection,I=i=>g(i)&&i.length===0;e.isArray=m,e.isArrayEmpty=r,e.isBigInt=u,e.isBoolean=o,e.isBrowser=d,e.isDate=B,e.isElement=C,e.isError=W,e.isFalse=b,e.isFunction=H,e.isHtmlCollection=g,e.isHtmlCollectionEmpty=I,e.isHtmlElement=F,e.isInfinity=R,e.isMap=M,e.isNaNValue=h,e.isNodeList=E,e.isNodeListEmpty=w,e.isNull=l,e.isNumber=f,e.isObject=c,e.isObjectEmpty=L,e.isPrimitive=v,e.isRegExp=j,e.isSet=k,e.isString=s,e.isStringEmpty=N,e.isSvgElement=U,e.isSymbol=y,e.isTrue=S,e.isURL=T,e.isUndefined=a,e.isWeakMap=O,e.isWeakSet=A,e.noop=n,e.toString=t});

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

@@ -13,19 +13,26 @@ import { writeFile as writeFile$1 } from 'node:fs/promises';
  */
 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'
  *
- * await 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.
@@ -55,6 +62,88 @@ interface CopyOptions {
  * await copy('src/subdir/file.ts', './dist/subdir')
  * ```
  */
-declare function copy(source: string | URL | (string | URL)[], destination: string | URL, options: CopyOptions): Promise<void>;
+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 { type CopyOptions, copy, 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.1.0",
+  "version": "3.2.1",
   "author": "Hypernym Studio",
   "description": "A collection of reusable utilities.",
   "license": "MIT",