@hypernym/utils 0.3.1 → 1.1.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) Hypernym Studio
+Copyright (c) 2023 Hypernym Studio, Ivo Dolenc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,4 +1,4 @@
-# Utils
+# @hypernym/utils
 
 A collection of reusable utilities.
 
@@ -6,40 +6,30 @@ A collection of reusable utilities.
 
 ## Features
 
+- Supports CJS & ESM
 - TypeScript friendly
-- Zero dependencies
+- Fully tree-shakeable
+- No dependencies
 
 ## Installation
 
 ```sh
-npm i @hypernym/utils
+npm i -D @hypernym/utils
 ```
 
-## Imports
+## Usage
 
 ```ts
+// CJS
+const { isNull, isString, ... } = require('@hypernym/utils')
+
 // ESM & TS
-import { util } from '@hypernym/utils'
+import { isNull, isString, ... } from '@hypernym/utils'
 
 // Types
-import type { Util } from '@hypernym/utils'
+import type { IsAny, RequiredDeep, ... } from '@hypernym/utils'
 ```
 
-## API
-
-- [`generic`](./src/generic.ts) - Useful common utilities.
-- [`is`](./src/is.ts) - Simple conditional utilities.
-
-### Types
-
-- [`Primitive`](./src/types/primitive.ts) - Matches any primitive value.
-- [`BuiltIn`](./src/types/built-in.ts) - Matches any `Primitive`, `Date` or `RegExp` value.
-- [`PartialDeep`](./src/types/partial-deep.ts) - Constructs a type by recursively setting all properties as optional.
-- [`RequiredDeep`](./src/types/required-deep.ts) - Constructs a type by recursively setting all properties as required.
-- [`IsNull`](./src/types/is.ts) - Returns a boolean if the given type is a `null`.
-- [`IsAny`](./src/types/is.ts) - Returns a boolean if the given type is a `any`.
-- [`IsNever`](./src/types/is.ts) - Returns a boolean if the given type is a `never`.
-
 ## Community
 
 Feel free to use the official [discussions](https://github.com/hypernym-studio/utils/discussions) for any additional questions.

package/dist/node.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+var promises = require('node:fs/promises');
+var node_path = require('node:path');
+var formatBytes = require('../mix/format-bytes');
+
+async function exists(path) {
+  return await promises.access(path, promises.constants.F_OK).then(() => true).catch(() => false);
+}
+
+async function getDirStats(dirPath, options) {
+  const dirFiles = await promises.readdir(dirPath);
+  const dirBase = node_path.basename(dirPath);
+  let dirStats = [];
+  const subdirList = [];
+  const fileList = [];
+  let dirSize = 0;
+  let dirIndex = 0;
+  let fileIndex = -1;
+  let subdirIndex = -1;
+  for (const file of dirFiles) {
+    const filePath = node_path.resolve(dirPath, file);
+    const fileStat = await promises.stat(filePath);
+    if (fileStat.isDirectory()) {
+      subdirIndex++;
+      subdirList.push({
+        index: subdirIndex,
+        path: filePath,
+        base: file
+      });
+      if (options?.recursive) {
+        dirBase === dirPath ? dirBase : node_path.basename(filePath);
+        const stats = await getDirStats(filePath);
+        const updateDirStats = { ...stats[0], ...{ index: dirIndex++ } };
+        dirStats = [...dirStats, updateDirStats];
+      }
+    } else {
+      const { base, name, ext } = node_path.parse(file);
+      const path = filePath;
+      const size = formatBytes.formatBytes(fileStat.size);
+      fileIndex++;
+      dirSize += fileStat.size;
+      fileList.push({
+        index: fileIndex,
+        path,
+        base,
+        name,
+        ext,
+        size
+      });
+    }
+  }
+  dirStats.push({
+    index: dirIndex,
+    path: dirPath,
+    base: dirBase,
+    size: formatBytes.formatBytes(dirSize),
+    subdirs: subdirList,
+    files: fileList
+  });
+  return dirStats;
+}
+
+exports.exists = exists;
+exports.getDirStats = getDirStats;

package/dist/node.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Checks if the file exists.
+ */
+declare function exists(path: string): Promise<boolean>;
+
+/**
+ * Scans the specified directory and gets details for each subdirectory and file.
+ *
+ * By default, recursive mode is disabled so only one level is scanned.
+ */
+declare function getDirStats(dirPath: string, options?: DirStatsOptions): Promise<DirStats[]>;
+
+interface SubdirDetails {
+    index: number;
+    path: string;
+    base: string;
+}
+interface FileDetails {
+    index: number;
+    path: string;
+    base: string;
+    name: string;
+    ext: string;
+    size: string;
+}
+interface DirStats {
+    index: number;
+    path: string;
+    base: string;
+    size: string;
+    subdirs: SubdirDetails[];
+    files: FileDetails[];
+}
+interface DirStatsOptions {
+    recursive?: boolean;
+}
+
+export { DirStats, DirStatsOptions, exists, getDirStats };

package/dist/node.mjs

@@ -0,0 +1,62 @@
+import { access, constants, readdir, stat } from 'node:fs/promises';
+import { basename, resolve, parse } from 'node:path';
+import { formatBytes } from '../mix/format-bytes';
+
+async function exists(path) {
+  return await access(path, constants.F_OK).then(() => true).catch(() => false);
+}
+
+async function getDirStats(dirPath, options) {
+  const dirFiles = await readdir(dirPath);
+  const dirBase = basename(dirPath);
+  let dirStats = [];
+  const subdirList = [];
+  const fileList = [];
+  let dirSize = 0;
+  let dirIndex = 0;
+  let fileIndex = -1;
+  let subdirIndex = -1;
+  for (const file of dirFiles) {
+    const filePath = resolve(dirPath, file);
+    const fileStat = await stat(filePath);
+    if (fileStat.isDirectory()) {
+      subdirIndex++;
+      subdirList.push({
+        index: subdirIndex,
+        path: filePath,
+        base: file
+      });
+      if (options?.recursive) {
+        dirBase === dirPath ? dirBase : basename(filePath);
+        const stats = await getDirStats(filePath);
+        const updateDirStats = { ...stats[0], ...{ index: dirIndex++ } };
+        dirStats = [...dirStats, updateDirStats];
+      }
+    } else {
+      const { base, name, ext } = parse(file);
+      const path = filePath;
+      const size = formatBytes(fileStat.size);
+      fileIndex++;
+      dirSize += fileStat.size;
+      fileList.push({
+        index: fileIndex,
+        path,
+        base,
+        name,
+        ext,
+        size
+      });
+    }
+  }
+  dirStats.push({
+    index: dirIndex,
+    path: dirPath,
+    base: dirBase,
+    size: formatBytes(dirSize),
+    subdirs: subdirList,
+    files: fileList
+  });
+  return dirStats;
+}
+
+export { exists, getDirStats };

package/dist/utils.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+const noop = () => {
+};
+const toString = (v) => Object.prototype.toString.call(v).slice(8, -1);
+
+const isBrowser = typeof window !== "undefined";
+const isNull = (v) => v === null;
+const isUndefined = (v) => typeof v === "undefined";
+const isString = (v) => typeof v === "string";
+const isStringEmpty = (v) => isString(v) && v.trim().length === 0;
+const isBoolean = (v) => typeof v === "boolean";
+const isNumber = (v) => typeof v === "number" && !isNaN(v);
+const isArray = (v) => Array.isArray(v);
+const isArrayEmpty = (v) => isArray(v) && v.length === 0;
+const isObject = (v) => toString(v) === "Object";
+const isObjectEmpty = (v) => isObject(v) && Object.keys(v).length === 0;
+const isFunction = (v) => v instanceof Function;
+const isNaNValue = (v) => typeof v === "number" && isNaN(v);
+const isRegExp = (v) => v instanceof RegExp;
+const isMap = (v) => v instanceof Map;
+const isSet = (v) => v instanceof Set;
+const isSymbol = (v) => toString(v) === "Symbol";
+const isDate = (v) => v instanceof Date && !isNaN(v.valueOf());
+const isBigint = (v) => typeof v === "bigint";
+const isInfinity = (v) => v === Infinity || v === -Infinity;
+const isURL = (v) => v instanceof URL;
+const isError = (v) => v instanceof Error;
+const isPrimitive = (v) => isString(v) || isNumber(v) || isBigint(v) || isBoolean(v) || isSymbol(v) || isNull(v) || isUndefined(v);
+const isElement = (v) => v instanceof Element;
+const isNodeList = (v) => v instanceof NodeList;
+const isNodeListEmpty = (v) => isNodeList(v) && v.length === 0;
+const isHtmlCollection = (v) => v instanceof HTMLCollection;
+const isHtmlCollectionEmpty = (v) => isHtmlCollection(v) && v.length === 0;
+
+function formatBytes(bytes, options) {
+  const decimals = options?.decimals || 2;
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  if (bytes === 0)
+    return `0 B`;
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(dm))} ${units[i]}`;
+}
+
+exports.formatBytes = formatBytes;
+exports.isArray = isArray;
+exports.isArrayEmpty = isArrayEmpty;
+exports.isBigint = isBigint;
+exports.isBoolean = isBoolean;
+exports.isBrowser = isBrowser;
+exports.isDate = isDate;
+exports.isElement = isElement;
+exports.isError = isError;
+exports.isFunction = isFunction;
+exports.isHtmlCollection = isHtmlCollection;
+exports.isHtmlCollectionEmpty = isHtmlCollectionEmpty;
+exports.isInfinity = isInfinity;
+exports.isMap = isMap;
+exports.isNaNValue = isNaNValue;
+exports.isNodeList = isNodeList;
+exports.isNodeListEmpty = isNodeListEmpty;
+exports.isNull = isNull;
+exports.isNumber = isNumber;
+exports.isObject = isObject;
+exports.isObjectEmpty = isObjectEmpty;
+exports.isPrimitive = isPrimitive;
+exports.isRegExp = isRegExp;
+exports.isSet = isSet;
+exports.isString = isString;
+exports.isStringEmpty = isStringEmpty;
+exports.isSymbol = isSymbol;
+exports.isURL = isURL;
+exports.isUndefined = isUndefined;
+exports.noop = noop;
+exports.toString = toString;

package/dist/utils.d.ts

@@ -1,8 +1,16 @@
+/**
+ * An empty arrow function that performs no operation.
+ */
+declare const noop: () => void;
+/**
+ * Returns a string representing the object.
+ */
+declare const toString: (v: any) => string;
+
 /**
  * Matches any primitive value.
  */
 type Primitive = null | undefined | string | number | boolean | symbol | bigint;
-
 /**
  * Matches any `Primitive`, `Date` or `RegExp` value.
  */
@@ -11,7 +19,7 @@ type BuiltIn = Primitive | Date | RegExp;
 /**
  * Checks if the code is running in the browser.
  */
-declare const isClient: boolean;
+declare const isBrowser: boolean;
 /**
  * Returns a boolean if the given value is a `null`.
  */
@@ -134,6 +142,15 @@ type IsAny<T> = 0 extends 1 & T ? true : false;
  */
 type IsNever<T> = [T] extends [never] ? true : false;
 
+/**
+ * Converts bytes to a _human-readable_ size and appends a units suffix.
+ */
+declare function formatBytes(bytes: number, options?: FormatBytesOptions): string;
+
+interface FormatBytesOptions {
+    decimals?: number;
+}
+
 type OptionsDeep = {
     /**
      * Enables recursive mode for arrays and tuples.
@@ -171,9 +188,4 @@ type RequiredObjectDeep<T extends object, Options extends OptionsDeep = {
     [K in keyof T]-?: RequiredDeep<T[K], Options>;
 };
 
-/**
- * An empty arrow function that performs no operation.
- */
-declare const noop: () => void;
-
-export { BuiltIn, IsAny, IsNever, IsNull, PartialDeep, Primitive, RequiredDeep, isArray, isArrayEmpty, isBigint, isBoolean, isClient, isDate, isElement, isError, isFunction, isHtmlCollection, isHtmlCollectionEmpty, isInfinity, isMap, isNaNValue, isNodeList, isNodeListEmpty, isNull, isNumber, isObject, isObjectEmpty, isPrimitive, isRegExp, isSet, isString, isStringEmpty, isSymbol, isURL, isUndefined, noop };
+export { BuiltIn, FormatBytesOptions, IsAny, IsNever, IsNull, OptionsDeep, PartialDeep, Primitive, RequiredDeep, formatBytes, isArray, isArrayEmpty, isBigint, isBoolean, isBrowser, isDate, isElement, isError, isFunction, isHtmlCollection, isHtmlCollectionEmpty, isInfinity, isMap, isNaNValue, isNodeList, isNodeListEmpty, isNull, isNumber, isObject, isObjectEmpty, isPrimitive, isRegExp, isSet, isString, isStringEmpty, isSymbol, isURL, isUndefined, noop, toString };

package/dist/utils.mjs

@@ -1,8 +1,8 @@
 const noop = () => {
 };
+const toString = (v) => Object.prototype.toString.call(v).slice(8, -1);
 
-const getType = (v) => Object.prototype.toString.call(v).slice(8, -1);
-const isClient = typeof window !== "undefined";
+const isBrowser = typeof window !== "undefined";
 const isNull = (v) => v === null;
 const isUndefined = (v) => typeof v === "undefined";
 const isString = (v) => typeof v === "string";
@@ -11,14 +11,14 @@ const isBoolean = (v) => typeof v === "boolean";
 const isNumber = (v) => typeof v === "number" && !isNaN(v);
 const isArray = (v) => Array.isArray(v);
 const isArrayEmpty = (v) => isArray(v) && v.length === 0;
-const isObject = (v) => getType(v) === "Object";
+const isObject = (v) => toString(v) === "Object";
 const isObjectEmpty = (v) => isObject(v) && Object.keys(v).length === 0;
 const isFunction = (v) => v instanceof Function;
 const isNaNValue = (v) => typeof v === "number" && isNaN(v);
 const isRegExp = (v) => v instanceof RegExp;
 const isMap = (v) => v instanceof Map;
 const isSet = (v) => v instanceof Set;
-const isSymbol = (v) => getType(v) === "Symbol";
+const isSymbol = (v) => toString(v) === "Symbol";
 const isDate = (v) => v instanceof Date && !isNaN(v.valueOf());
 const isBigint = (v) => typeof v === "bigint";
 const isInfinity = (v) => v === Infinity || v === -Infinity;
@@ -31,4 +31,15 @@ const isNodeListEmpty = (v) => isNodeList(v) && v.length === 0;
 const isHtmlCollection = (v) => v instanceof HTMLCollection;
 const isHtmlCollectionEmpty = (v) => isHtmlCollection(v) && v.length === 0;
 
-export { isArray, isArrayEmpty, isBigint, isBoolean, isClient, isDate, isElement, isError, isFunction, isHtmlCollection, isHtmlCollectionEmpty, isInfinity, isMap, isNaNValue, isNodeList, isNodeListEmpty, isNull, isNumber, isObject, isObjectEmpty, isPrimitive, isRegExp, isSet, isString, isStringEmpty, isSymbol, isURL, isUndefined, noop };
+function formatBytes(bytes, options) {
+  const decimals = options?.decimals || 2;
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  if (bytes === 0)
+    return `0 B`;
+  const k = 1024;
+  const dm = decimals < 0 ? 0 : decimals;
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(dm))} ${units[i]}`;
+}
+
+export { formatBytes, isArray, isArrayEmpty, isBigint, isBoolean, isBrowser, isDate, isElement, isError, isFunction, isHtmlCollection, isHtmlCollectionEmpty, isInfinity, isMap, isNaNValue, isNodeList, isNodeListEmpty, isNull, isNumber, isObject, isObjectEmpty, isPrimitive, isRegExp, isSet, isString, isStringEmpty, isSymbol, isURL, isUndefined, noop, toString };

package/node.d.ts

@@ -0,0 +1 @@
+export * from './dist/node'

package/package.json

@@ -1,22 +1,34 @@
 {
   "name": "@hypernym/utils",
-  "version": "0.3.1",
+  "version": "1.1.0",
   "author": "Hypernym Studio",
+  "maintainers": [
+    "Ivo Dolenc (https://github.com/ivodolenc)"
+  ],
   "description": "A collection of reusable utilities.",
   "license": "MIT",
+  "funding": "https://github.com/sponsors/ivodolenc",
   "repository": "hypernym-studio/utils",
   "homepage": "https://github.com/hypernym-studio/utils",
   "type": "module",
+  "main": "./dist/utils.cjs",
   "module": "./dist/utils.mjs",
   "types": "./dist/utils.d.ts",
   "exports": {
     ".": {
       "types": "./dist/utils.d.ts",
-      "import": "./dist/utils.mjs"
+      "import": "./dist/utils.mjs",
+      "require": "./dist/utils.cjs"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.mjs",
+      "require": "./dist/node.cjs"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "*.d.ts"
   ],
   "keywords": [
     "typescript",
@@ -30,27 +42,26 @@
   "scripts": {
     "dev": "vite playgrounds/client",
     "dev:node": "vite-node -w playgrounds/node/main.ts",
-    "build": "rollup -c",
-    "test:types": "vitest typecheck",
+    "build": "rollup -c ./.config/rollup.config.js",
+    "test:types": "vitest -c ./.config/vitest.config.ts typecheck",
     "prepublishOnly": "npm run build",
     "format": "prettier --write .",
     "lint": "eslint .",
     "fix": "eslint --fix ."
   },
   "devDependencies": {
-    "@types/node": "^20.2.5",
-    "@typescript-eslint/eslint-plugin": "^5.59.9",
-    "@typescript-eslint/parser": "^5.59.9",
-    "eslint": "^8.42.0",
-    "eslint-config-prettier": "^8.8.0",
+    "@hypernym/eslint-config": "^1.0.1",
+    "@hypernym/prettier-config": "^1.0.1",
+    "@types/node": "^20.4.1",
+    "eslint": "^8.44.0",
     "prettier": "^2.8.8",
-    "rollup": "^3.24.0",
+    "rollup": "^3.26.2",
     "rollup-plugin-dts": "^5.3.0",
     "rollup-plugin-esbuild": "^5.0.0",
     "typescript": "^5.0.4",
-    "vite": "^4.3.9",
-    "vite-node": "^0.32.0",
-    "vitest": "^0.32.0"
+    "vite": "^4.4.2",
+    "vite-node": "^0.33.0",
+    "vitest": "^0.33.0"
   },
   "publishConfig": {
     "access": "public"
@@ -58,5 +69,5 @@
   "eslintConfig": {
     "extends": "./.config/eslint.config.cjs"
   },
-  "prettier": "./.config/prettier.config.cjs"
+  "prettier": "@hypernym/prettier-config"
 }