@hypernym/utils 3.2.0 → 3.3.0

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,189 @@
 
 ## 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
+```
+
+### read
+
+Reads the entire contents of a file.
+
+```ts
+import { read } from '@hypernym/utils/fs'
+
+await read('dir/subdir/file.ts')
+```
+
+### 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,4 +1,4 @@
-import { access, constants, mkdir as mkdir$1, writeFile as writeFile$1, cp, rm } from 'node:fs/promises';
+import { access, constants, readFile, 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,11 @@ 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 write(path, data, options) {
   await mkdir$1(dirname(isURL(path) ? fileURLToPath(path) : path), {
     recursive: true
@@ -42,4 +47,4 @@ async function remove(path, options = {}) {
   }
 }
 
-export { copy, exists, mkdir, remove, write, writeFile };
+export { copy, exists, mkdir, read, 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,6 +13,42 @@ 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 WritePath = string | URL;
 /**
  * Writes data to a file recursively.
@@ -146,4 +182,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 RemoveOptions, type RemovePath, type WritePath, copy, exists, mkdir, read, remove, write, writeFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypernym/utils",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "author": "Hypernym Studio",
   "description": "A collection of reusable utilities.",
   "license": "MIT",
@@ -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",