Whoj Utils

https://github.com/who-jonson/utils
Admin
A collection of utility functions for JavaScript and TypeScript projects, offering helpful tools for...
Tokens:6,475
Snippets:36
Trust Score:8.6
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install @whoj/utils

Source: https://github.com/who-jonson/utils/blob/master/packages/all/README.md

Installs the @whoj/utils package using either npm or pnpm. This is the primary method to include the utility library in your project.

```bash
npm i @whoj/utils # OR pnpm add @whoj/utils
```

--------------------------------

### Install @whoj/utils-core

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Provides installation commands for @whoj/utils-core using various package managers including npm, yarn, pnpm, bun, and deno. It also includes an auto-detection command using npx.

```sh
# ✨ Auto-detect
npx nypm install @whoj/utils-core

# npm
npm install @whoj/utils-core

# yarn
yarn add @whoj/utils-core

# pnpm
pnpm install @whoj/utils-core

# bun
bun install @whoj/utils-core

# deno
deno install @whoj/utils-core
```

--------------------------------

### Install @whoj/utils-php

Source: https://github.com/who-jonson/utils/blob/master/packages/php/README.md

Instructions for installing the @whoj/utils-php package using different package managers like npm, yarn, pnpm, bun, and deno. It also shows an auto-detect option using npx.

```Shell
# ✨ Auto-detect
npx nypm install @whoj/utils-php

# npm
npm install @whoj/utils-php

# yarn
yarn add @whoj/utils-php

# pnpm
pnpm install @whoj/utils-php

# bun
bun install @whoj/utils-php

# deno
denp install @whoj/utils-php
```

--------------------------------

### Install @whoj/utils-vue

Source: https://github.com/who-jonson/utils/blob/master/packages/vue/README.md

Provides commands for installing the @whoj/utils-vue package using various package managers like npx, npm, yarn, pnpm, bun, and deno.

```sh
# ✨ Auto-detect
npx nypm install @whoj/utils-vue

# npm
npm install @whoj/utils-vue

# yarn
yarn add @whoj/utils-vue

# pnpm
pnpm install @whoj/utils-vue

# bun
bun install @whoj/utils-vue

# deno
denp install @whoj/utils-vue
```

--------------------------------

### Install @whoj/utils-types

Source: https://github.com/who-jonson/utils/blob/master/packages/types/README.md

Provides commands to install the @whoj/utils-types package using various package managers like npm, yarn, pnpm, bun, and deno. It also includes an auto-detection command.

```sh
# ✨ Auto-detect
npx nypm install @whoj/utils-types

# npm
npm install @whoj/utils-types

# yarn
yarn add @whoj/utils-types

# pnpm
pnpm install @whoj/utils-types

# bun
bun install @whoj/utils-types

# deno
denp install @whoj/utils-types
```

--------------------------------

### Vue Fuse.js Search Example

Source: https://github.com/who-jonson/utils/blob/master/packages/vue/README.md

Demonstrates how to use the `useVueFuse` hook from `@whoj/utils-vue/fusejs` within a Vue 3 component. It sets up a search input, displays results, and handles cases with no matching results.

```vue
<template>
  <div>
    <input type="text" v-model="search">
    <p v-if="noResults">Sorry, no results for {{search}}</p>
    <div v-for="(r, i) in results" :key="i">
      {{ r }}
    </div>
  </div>
</template>

<script lang="ts">
import { defineComponent } from 'vue';
import { useVueFuse } from '@whoj/utils-vue/fusejs';

export default defineComponent({
  setup () {
    const myList = ['aaaa', 'bbbb', 'cccc', 'abc', 'xyz']
    const { search, results, noResults } = useVueFuse(myList)

    return {
      search,
      results,
      noResults,
    }
  }
})
</script>
```

--------------------------------

### serial: Execute promises serially

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Executes an array of asynchronous tasks sequentially. It takes an array of tasks and a function to process each task, ensuring each task completes before the next one starts.

```JavaScript
async function serial(tasks, fn) {
  let result;
  for (const task of tasks) {
    result = await fn(task, result);
  }
  return result;
}
```

--------------------------------

### Array Utilities in @whoj/utils-core

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

This section details various utility functions for array manipulation, including clamping array ranges, flattening arrays (deeply and by key), getting the last element, merging arrays, moving elements, partitioning, generating ranges, removing elements, sampling, shuffling, converting to arrays, and finding unique elements.

```javascript
function createUser(name: string): User {
  return tap(new User, user => {
    user.name = name
  })
}
```

```javascript
const payload = [ { child: [{name: 'John Doe'}] }, { child: [ {age: 23} ] } ]; flattenDeepArray(payload, 'child'); Result: [{name: 'John Doe'}, {age: 23}]
```

```javascript
array.filter(isTruthy)
```

```javascript
array.filter(noNull)
```

```javascript
array.filter(notNullish)
```

```javascript
array.filter(notUndefined)
```

--------------------------------

### template: Simple string templating

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

A basic string templating function similar to Python's `.format()`. It replaces placeholders in a string with provided arguments.

```JavaScript
function template(str, ...args) {
  return str.replace(/\{(\d+)\}/g, (match, index) => {
    return args[index] !== undefined ? args[index] : match;
  });
}
```

--------------------------------

### Global Utilities in @whoj/utils-core

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Utilities for accessing global objects like `document` and `window` based on the execution environment (client or server). Functions include `getDocument`, `getGlobal`, `getWindow`, `isClient`, and `isServer`.

```javascript
function createUser(name: string): User {
  return tap(new User, user => {
    user.name = name
  })
}
```

--------------------------------

### Function Utilities in @whoj/utils-core

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

This section covers utility functions for managing and invoking functions. It includes `batchInvoke` to call multiple functions, `invoke` to call a single function, and `tap` to pass a value through a callback while returning the original value, often used for side effects.

```javascript
function createUser(name: string): User {
  return tap(new User, user => {
    user.name = name
  })
}
```

--------------------------------

### Math Utilities in @whoj/utils-core

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Provides mathematical utility functions such as `clamp` to constrain a number within a specified range and `sum` to calculate the sum of multiple numbers.

```javascript
function createUser(name: string): User {
  return tap(new User, user => {
    user.name = name
  })
}
```

--------------------------------

### parallelSafe: Execute promises in parallel safely

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Executes an array of asynchronous tasks concurrently, but handles rejections gracefully. It returns a promise that resolves with an array of results or rejection reasons.

```JavaScript
async function parallelSafe(tasks, fn) {
  return Promise.allSettled(tasks.map(fn));
}
```

--------------------------------

### createSingletonPromise: Create a singleton promise function

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Creates a function that, when called multiple times, will only execute the underlying asynchronous operation once. Subsequent calls will return the same promise as the first call.

```JavaScript
function createSingletonPromise(fn) {
  let promise;
  return (...args) => {
    if (!promise) {
      promise = fn(...args);
    }
    return promise;
  };
}
```

--------------------------------

### TypeScript Interfaces for Encrypter and Serializer

Source: https://github.com/who-jonson/utils/blob/master/packages/php/README.md

Defines TypeScript interfaces for encryption and serialization operations. Includes methods for encrypting/decrypting values and strings, managing encryption keys, and serializing/unserializing data.

```TypeScript
export interface Encrypter {
  /**
   * Encrypt the given value.
   *
   * @param {any} value
   * @param {boolean|undefined} serialize
   *
   * @return string
   *
   * @throws {EncryptException}
   */
  encrypt(value: any, serialize?: boolean): string;

  /**
   * Decrypt the given value.
   *
   * @param {any} value
   * @param {<S>} unserialize
   *
   * @returns {string | <T>}
   *
   * @throws {DecryptException}
   */
  decrypt<T = any, S extends boolean = true>(value: any, unserialize?: S): S extends true ? T : string;

  /**
   * Get the encryption key that the encrypter is currently using.
   *
   * @returns {Buffer}
   */
  get getKey(): Buffer;

  /**
   * Get the current encryption key and all previous encryption keys.
   *
   * @returns {Array<Buffer>}
   */
  get getAllKeys(): Array<Buffer>;

  /**
   * Get the previous encryption keys.
   *
   * @returns {Array<Buffer>}
   */
  get getPreviousKeys(): Array<Buffer>;
}

export interface StringEncrypter {
  /**
   * Encrypt the given string.
   *
   * @param {any} value
   *
   * @return string
   *
   * @throws {EncryptException}
   */
  encryptString(value: string): string;

  /**
   * Decrypt the given string.
   *
   * @param {any} value
   *
   * @returns {string}
   *
   * @throws {DecryptException}
   */
  decryptString(value: string): string;
}

export interface Serializer {
  serialize(data: any): string;

  unserialize<T = any>(data: string): T;
}

export {};

```

--------------------------------

### Object Utilities in @whoj/utils-core

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Utility functions for object manipulation, including clearing undefined fields, deep merging objects, creating objects from key-value pairs, type guards for object keys, and strict typed versions of `Object.entries` and `Object.keys`.

```javascript
function createUser(name: string): User {
  return tap(new User, user => {
    user.name = name
  })
}
```

--------------------------------

### createPromiseLock: Create a promise lock

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Creates a promise-based lock mechanism to control concurrent access to a resource or function. It ensures that only one operation runs at a time, queuing subsequent requests.

```JavaScript
function createPromiseLock() {
  let current = Promise.resolve();
  const run = async (fn) => {
    const result = await (current = current.then(fn));
    return result;
  };
  const wait = () => current;
  return { run, wait };
}
```

--------------------------------

### objectPick: Create a subset object

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Creates a new object containing only the specified keys from the original object. Optionally, it can omit properties with undefined values.

```JavaScript
function objectPick(obj, keys, omitUndefined) {
  const result = {};
  for (const key of keys) {
    if (key in obj) {
      const value = obj[key];
      if (!omitUndefined || value !== undefined) {
        result[key] = value;
      }
    }
  }
  return result;
}
```

--------------------------------

### parallel: Execute promises in parallel

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Executes an array of asynchronous tasks concurrently. It takes an array of tasks and a function to process each task, returning a promise that resolves with an array of results.

```JavaScript
async function parallel(tasks, fn) {
  return Promise.all(tasks.map(fn));
}
```

--------------------------------

### noop: No operation function

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

A function that does nothing. It's often used as a default callback or placeholder.

```JavaScript
function noop() {}

```

--------------------------------

### isWindow: Check if window is defined

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Determines if the global `window` object is defined, typically indicating a browser environment.

```JavaScript
function isWindow(val) {
  return val && val.window === val;
}
```

--------------------------------

### createControlledPromise: Create a promise with resolve/reject

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Returns a Promise object along with its `resolve` and `reject` functions, allowing external control over the promise's state. This is useful for deferring promise resolution or rejection.

```JavaScript
function createControlledPromise() {
  let resolve;
  let reject;
  const promise = new Promise((res, rej) => {
    resolve = res;
    reject = rej;
  });
  return Object.assign(promise, { resolve, reject });
}
```

--------------------------------

### sleep: Promised setTimeout

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Provides a Promise-based version of `setTimeout`. It delays execution for a specified number of milliseconds, optionally executing a callback.

```JavaScript
function sleep(ms, callback) {
  return new Promise((resolve) => {
    setTimeout(() => {
      if (callback) {
        callback();
      }
      resolve();
    }, ms);
  });
}
```

--------------------------------

### assert: Assert a condition

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Checks if a given condition is true. If the condition is false, it throws an error with the specified message.

```JavaScript
function assert(condition, message) {
  if (!condition) {
    throw new Error(message || 'Assertion failed');
  }
}
```

--------------------------------

### objectMap: Map object key/value pairs

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Maps key/value pairs of an object using a provided function and constructs a new object with the transformed pairs. The function can modify keys, values, or filter entries by returning undefined.

```JavaScript
function objectMap(obj, fn) {
  const result = {};
  for (const k in obj) {
    if (Object.prototype.hasOwnProperty.call(obj, k)) {
      const v = obj[k];
      const pair = fn(k, v);
      if (pair !== undefined) {
        result[pair[0]] = pair[1];
      }
    }
  }
  return result;
}
```

--------------------------------

### isString: Check if value is a String

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Determines whether the provided value is a string.

```JavaScript
function isString(val) {
  return typeof val === 'string';
}
```

--------------------------------

### Guard Utilities in @whoj/utils-core

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Type guard functions to filter values based on their truthiness or nullishness. Includes `isTruthy`, `noNull`, `notNullish`, and `notUndefined`, useful for filtering arrays.

```typescript
array.filter(isTruthy)
```

```typescript
array.filter(noNull)
```

```typescript
array.filter(notNullish)
```

```typescript
array.filter(notUndefined)
```

--------------------------------

### toPairs: Convert object to key/value pairs

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Converts an object into an array of key/value pairs. This is useful for iterating over object properties or when a function expects an array of pairs.

```JavaScript
function toPairs(obj) {
  const result = [];
  for (const k in obj) {
    if (Object.prototype.hasOwnProperty.call(obj, k)) {
      result.push([k, obj[k]]);
    }
  }
  return result;
}
```

--------------------------------

### isObject: Check if value is an Object

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Determines whether the provided value is an object (and not null or an array).

```JavaScript
function isObject(val) {
  return typeof val === 'object' && val !== null && !Array.isArray(val);
}
```

--------------------------------

### isFunction: Check if value is a Function

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Determines whether the provided value is a function.

```JavaScript
function isFunction(val) {
  return typeof val === 'function';
}
```

--------------------------------

### isDef: Check if value is defined

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Determines whether the provided value is defined (not `undefined` or `null`).

```JavaScript
function isDef(val) {
  return val !== undefined && val !== null;
}
```

--------------------------------

### isArray: Check if value is an Array

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Determines whether the provided value is an array.

```JavaScript
function isArray(val) {
  return Array.isArray(val);
}
```

--------------------------------

### isGlobPattern: Check for glob pattern

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Checks if a string appears to be a glob pattern. This is a basic check and may not cover all edge cases.

```JavaScript
function isGlobPattern(pattern, options) {
  // Basic check for common glob characters
  return typeof pattern === 'string' && /[\*\?\{\}\[\]]/.test(pattern);
}
```

--------------------------------

### isNumber: Check if value is a Number

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Determines whether the provided value is a number.

```JavaScript
function isNumber(val) {
  return typeof val === 'number';
}
```

--------------------------------

### isBoolean: Check if value is boolean

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Determines whether the provided value is a boolean.

```JavaScript
function isBoolean(val) {
  return typeof val === 'boolean';
}
```

--------------------------------

### isNumberish: Check if value is Numberish

Source: https://github.com/who-jonson/utils/blob/master/packages/core/README.md

Determines whether the provided value is a number or a string that can be coerced into a number.

```JavaScript
function isNumberish(val) {
  return typeof val === 'number' || (typeof val === 'string' && !isNaN(parseFloat(val)) && isFinite(val));
}
```
Tokens:
Raw