@funboxteam/diamonds

@funboxteam/diamonds

This is a set of helpers that we use in the current projects and will probably use in the future ones.

All helpers are independent of each other, which means that your project's bundle won't be bloated by useless code.

По-русски

Contents

• Rationale
• Installation
• List of helpers
  • base64ToUint8Array
  • disableBodyScroll, enableBodyScroll
  • camelToKebab
  • colorize
  • datauriToBlob
  • debounce
  • deepClone
  • equals
  • findLast
  • formatBytes
  • formatNumberString
  • formatPhoneNumberString
  • getBrowserScrollbarWidth
  • getDisplayName
  • getImageOrientation
  • getObjectPath
  • getPlural
  • getRandomNum
  • getUniqueId
  • hexToRgb
  • isElementInViewport
  • isEmailValid
  • isInputTypeSupported
  • isMobile
  • kebabToCamel
  • objectToQueryString
  • omit
  • pick
  • queryStringToObject
  • rgbToHex
  • shuffle
  • sleep
  • storage
  • throttle
• Credits

Rationale

When developers create projects they use a lot of small functions that are not connected to the project itself. Usually such functions are stored in folders like utils or helpers.

To prevent copy-pasting between a huge amount of projects we've created this package.

These functions are not aimed to be absolutely safe to unexpected usage. They do exactly what they say they do, and nothing else.

Installation

Add the package to deps:

npm install --save @funboxteam/diamonds 

Import functions:

import { getUniqueId } from '@funboxteam/diamonds';

List of helpers

It's easier to check every helper's source code rather than reading docs. But if you want some, here they are.

base64ToUint8Array

Converts Base64 string to a Uint8Array.

disableBodyScroll, enableBodyScroll

The first function disables scroll on the current page with the possibility to save the current scrolled position, the second one enables the scroll and restores its position if it was saved.

It's useful when you want to disable scroll e.g. while opening sidebar and enable it while closing.

camelToKebab

Converts camelCase string into kebab-case.

capitalize

Change the passed strings's first letter case to upper.

colorize

Returns passed params as string with color tags inside.

It's useful when you want to colorize logs in terminal.

cookieStringToObject

Converts cookie string (usually, the one you get from document.cookie) into an object.

datauriToBlob

Converts DataURI string into Blob instance.

It's useful when you need to send an image from online editor to the server.

debounce

Returns a debounced function that delays invoking callback until passed seconds have elapsed since the last time the debounced function was invoked.

It's useful when you have to handle flow of events but want to fire callback after the flow finishes.

deepClone

Returns deep clone of the passed object. Does not work with circular links.

It's useful when you need to deeply clone an object. Object.assign does not work in this case, because it creates a shadow copy.

equals

Deeply compares passed params.

findLast

Returns the value of the last element in the provided array that satisfies the provided testing function. Otherwise undefined.

formatBytes

Converts size in bytes to KB, MB, GB, etc.

formatNumberString

Formats a number (or a string with a number inside) using the passed format.

It's useful when you need to format, let's say, the cost of something.

formatPhoneNumberString

Formats a number (or a string with a number inside) by the mask of Russian MSISDNs.

getBrowserScrollbarWidth

Returns browser scrollbar width.

getDisplayName

Returns displayName for React HOC.

getImageOrientation

Extracts orientation from the passed images EXIF.

Example:

getImageOrientation.call(this, image, orientation => {
  let rotate;

  switch (orientation) {
    case 8:
      rotate = 270;
      break;
    case 6:
      rotate = 90;
      break;
    case 3:
      rotate = 180;
      break;
    default:
      rotate = 0;
  }

  this.setState({ rotate });
});

getObjectPath

Gets the value at path of object.

It's useful when you have to work with highly nested objects and don't want to write long conditionals. getObjectPath(obj, 'key1.key2.key3') and the work is done.

getPlural

Picks and returns a correct unit name for the passed number (according to Russian lang rules).

It's useful when it's important to pick correct unit name. E.g. “1 day”, “2 days”, etc.

getRandomNum

Returns pseudorandom number from the passed range.

getUniqueId

Returns a string generated by the pattern prefix-number where prefix is the passed param, but number is unique.

It's useful when you need a unique string that can be namespaced. E.g. for generating unique IDs for DOM elements.

hexToRgb

Converts HEX color string to RGB object.

isElementInViewport

Returns true when the passed DOM node is visible in the viewport (fully or partially depending on the params).

isEmailValid

Returns true when the passed string is a valid email.

isInputTypeSupported

Checks browser support of the passed type attribute value for input tag.

It's useful when you deal with old browsers.

isMobile

Returns true when UA is similar to mobile.

It is useful when you don't need a precise check (the checks that are used inside the script are quite simple).

kebabToCamel

Converts kebab-case string into camelCase.

objectToQueryString

Converts the passed object which contains primitive values or arrays of primitive values into the query string.

omit

Returns shallow copy of the passed object but without the passed keys.

E.g. in React: omit(this.props, 'mods', 'mix').

pick

Returns shallow copy of the passed object but with the passed keys only.

queryStringToObject

Converts query-string into object.

rgbToHex

Transforms RBG color object into HEX string.

shuffle

Shuffles the passed array and returns it.

sleep

Returns Promise which waits for the passed amount of ms before resolving.

storage

Makes it possible to use localStorage safely.

throttle

Transforms the passed callback into the function that delays callback firing.

It's useful when you want to react on some events but no than once an N ms.

Credits

Cute picture for the project was made by Igor Garybaldi.

Changelog

8.9.0 (31.05.2023)

Ensured Node.js 18 support.

deepClone typings have become more strict due to the goal to remove any. Thus, this helper does not expect any anymore. Instead it expects boolean | number | bigint | string | undefined | null | Date, or array of them, or an object with values of these types. The array and theh object may be nested.

We believe that this is not a breaking change, because this change makes types more correct and more close to the implementation. It means that if your code does not satisfy the types of deepClone, you're probably not using it right.

Nevertheless, we've deprecated deepClone due to existence of structuredClone.