basekits

    1.3.1 • Public • Published

    basekits

    Tree-shakable javascript utility package for browser and node.

    NPM npm version npm bundle size npm

    Install

    npm install basekits

    Import

    There are different types of distributions depending on your use case. Essentially, the package can be imported via require:

    const kit = require('basekits')

    or via script tag:

    <script src="https://unpkg.com/basekits@1/dist/basekits.iife.js" crossorigin type="text/javascript"></script>

    but there are lots of other options. See distribution report below.

    Use

    Import the kit you would like to use:

    import {typekit} from 'basekits' // or const {typekit} = require('basekits')
    
    typekit.isObject({sample: ''}) // true

    A list of kits you can import:

    import {
      typekit, errorkit, hashkit,
      stringkit, objectkit,
      arraykit,
      functionkit,
      validationkit,
      domkit
    } from 'basekits'

    Either you use es module imports or commonjs imports, only the kit you specified will be in your bundle. Tree-shaking tested in rollup.js but it will work in other bundlers.

    Some kits contain other ones to function correctly. Here is a map:

    import {
      // has no other kit
      typekit, errorkit, hashkit,
    
      // has typekit
      stringkit, objectkit,
    
      // has typekit, objectkit
      arraykit,
    
      // has typekit, errorkit
      functionkit,
    
      // has typekit, errorkit, arraykit
      validationkit,
    
      // has typekit, objectkit, functionkit
      domkit
    } from 'basekits'

    You are not going to need to import typekit if you import stringkit, for example.

    import {stringkit} from 'basekits'
    
    stringkit.isObject({'itis': 'object'}) // true
    stringkit.template('Hello {{name}}', {name: 'Murat'}) // Hello Murat

    Time to show you the full api. 👇

    API

    basekits.typekit

    // Checks if the value is a string. Returns boolean.
    typekit.isString(v)
    
    // Checks if the value is a boolean. Returns boolean.
    typekit.isBoolean(v)
    
    // Checks if the value is null. Returns boolean.
    typekit.isNull(v)
    
    // Checks if the value is positive or negative finite number. Returns boolean.
    typekit.isNumber(v)
    
    // Checks if the value is positive or negative integer. Returns boolean.
    typekit.isInteger(v)
    
    // Checks if the value is NaN. Returns boolean.
    typekit.isNan(v)
    
    // Checks if the value is an object. Returns boolean.
    typekit.isObject(v)
    
    // Checks if the value is an array. Returns boolean.
    typekit.isArray(v)
    
    // Checks if the value is a promise. Returns boolean.
    typekit.isPromise(v)
    
    // Checks if the value is a native error object. Returns boolean.
    typekit.isError(v)
    
    // Checks if the value is a native date object. Returns boolean.
    typekit.isDate(v)
    
    // Checks if the value is a function. Returns boolean.
    typekit.isFunction(v)
    
    // Checks if the value is a regular expression. Returns boolean.
    typekit.isRegExp(v)
    
    // Checks if the value is a BigInt. Returns boolean.
    typekit.isBigInt(v)
    
    // Checks if the value is a Symbol. Returns boolean.
    typekit.isSymbol(v)
    
    // Checks if the value is a DOM element. Returns boolean.
    typekit.isDOMElement(v)
    /*
    * Finds the type of the value.
    * Returns one of "object", "array", "promise", "error", "date", "null",
    * "undefined", "function", "number", "nan", "regexp", "string", "boolean",
    * "bigint", "symbol", "domelement" or "none"
    */
    typekit.getType(v)

    basekits.errorkit

    // Converts native error object to an object.
    errorkit.objectifyError(new Error('some error message'))
    
    // Converts native error to a string
    errorkit.stringifyError(new Error('some error message'))

    basekits.hashkit

    /*
    * Java's hashcode implementation in javascript.
    * Returns positive or negative number.
    */
    hashkit.hashcode(str)
    
    // Examples:
    hashkit.hashcode('hello') // returns 99162322
    hashkit.hashcode('lorem ipsum') // returns -2126368101

    basekits.stringkit

    // Replaces %s expressions in the str string with given args in order.
    stringkit.sprintf(str, args:String|Array)
    
    // Examples:
    stringkit.sprintf('Hey %s', 'Murat')
    // Returns "Hey Murat"
    
    stringkit.sprintf('Hey %s, you have %s items in your cart.', ['Murat', 4])
    // Returns "Hey Murat, you have 4 items in your cart."
    // Replaces {{...}} expressions in a string with given props.
    stringkit.template(str, props:Object)
    
    // Examples:
    stringkit.template('Hey {{name}}!', {name: 'Murat'})
    // Returns "Hey Murat"
    /*
    * Case convertion methods.
    * They use native functions: toLocaleUpperCase and toLocaleLowerCase
    * Specify locale (en-US, tr-TR etc.) for locale aware convertion.
    */
    
    // Capitalize the whole str.
    stringkit.uppercase(str, locale = 'en-US')
    
    // Lowercase the whole str.
    stringkit.lowercase(str, locale = 'en-US')
    
    // Capitalizes only the first letter of the first word in given str.
    // nouns are the list of words that will be excluded while converting. Useful for brand names.
    stringkit.sentencecase(str, locale = 'en-US', nouns = [])
    
    // Capitalizes the first letter of each word in given str.
    // nouns are the list of words that will be excluded while converting. Useful for brand names.
    stringkit.titlecase(str, locale = 'en-US', nouns = [])

    basekits.objectkit

    /*
    * Flattens the nested object as key-value pairs
    * - $sep is put between each nested parts of a key.
    * - $roots keeps previous parent properties as they will be added as a prefix to each key
    */
    objectkit.flatten(obj, sep = '.', roots = [])
    
    // Example:
    const obj1 = {
      a: null,
      b: 'b',
      d: {dd: null},
      e: {f: {g: 'g'}}
    }
    const flatten = objectkit.flatten(obj1)
    {
      'a': null,
      'b': 'b',
      'd.dd': null,
      'e.f.g': 'g'
    }
    
    // or:
    const obj5 = {
      name: 'Sample 1',
      fields: [
        {age: 7, country: 'TR'},
        {age: 9, country: 'AZ'}
      ]
    }
    const flatten5 = objectkit.flatten(obj5)
    {
      name: 'Sample 1',
      'fields[0].age': 7,
      'fields[0].country': 'TR',
      'fields[1].age': 9,
      'fields[1].country': 'AZ',
    }
    /*
    * Reverse of the flatten. Unflattens, expands the key-value paired object.
    */
    
    objectkit.unflatten(obj)
    
    // Examples:
    const obj3f = {
      'name': 'Sample 2',
      'family.since': '2020',
      'family.children[0].name': 'Child 1',
      'family.children[0].age': 7,
      'family.children[0].address.city': 'City 1',
      'family.children[1].name': 'Child 2',
      'family.children[1].age': 3,
      'family.children[1].address.city': 'City 2',
      'abc.def': 1
    }
    objectkit.unflatten(obj3f)
    // Returns:
    {
      "name": "Sample 2",
      "family": {
        "since": "2020",
        "children": [
          {
            "name": "Child 1",
            "age": 7,
            "address": {
              "city": "City 1"
            }
          },
          {
            "name": "Child 2",
            "age": 3,
            "address": {
              "city": "City 2"
            }
          }
        ]
      },
      "abc": {
        "def": 1
      }
    }
    /*
    * Merges objects and properties of objects, recursively.
    * - $objects is the list of the objects you want to merge.
    * - $opts is an options object:
        $opts = {
          concatArrays: false,
          discardNonObjectReplacements: false,
          ignoreKeys: []
        }
    */
    objectkit.assignDeep(objects=[], opts={})
    
    // Example:
    const obj3 = {a: {b: {c: {d: '1', e: '2'}, f: '3'}}, g: ['4', '5']}
    const obj3a = {h: '6', a: {b: {i: '7'}}, g: ['8']}
    const obj3a2 = {h: '6', a: 'non-object', g: ['8']}
    objectkit.assignDeep([obj3, obj3a, obj3a2])
    // Returns:
    {a: 'non-object', g: ['8'], h: '6'}
    
    objectkit.assignDeep([obj3, obj3a, obj3a2], {discardNonObjectReplacements: true})
    // Returns:
    {a: {b: {c: {d: '1', e: '2'}, f: '3', i: '7'}}, g: ['8'], h: '6'}
    // Finds the value of the property specified in path inside an obj.
    objectkit.getProp(obj, path, defaultValue = undefined)
    
    // Examples:
    const obj = {
      name: 'Murat',
      address: {
        country: 'TR'
      }
    }
    objectkit.getProp(obj, 'name') // returns 'Murat'
    objectkit.getProp(obj, ['address', 'country']) // returns 'TR'
    objectkit.getProp(obj, 'nonExistingProp', 'none') // returns 'none'
    /*
    * Returns:
    * - a new object by removing its prop.
    * - input object if it doesn't have a prop.
    * - undefined if obj is not an object.
    */
    objectkit.removeProp(obj, prop)

    basekits.arraykit

    // Sorts array of objects according to a property specified in path.
    arraykit.sortItemsBy(arr, paths, order = 'asc')
    
    // Examples:
    const arr = [
      {n: 'a', num: 2, props: {num: 3}},
      {n: 'b', num: 3, props: {num: 1}},
      {n: 'c', num: 1, props: {num: 2}},
    ]
    
    arraykit.sortItemsBy(arr, 'num', 'asc')
    arraykit.sortItemsBy(arr, ['props', 'num'], 'desc')
    // Removes duplicate items in the arr.
    arraykit.removeDuplicates(arr, deep = false)

    About deep argument: The function performs strict equality check by default. Set deep to true if you want to perform deep equality check which is useful if arr contains objects or other complex structured types. But in order of this option to work correctly, validationkit must be imported.


    basekits.functionkit

    // Stringifies the input. Input can be one of basekits types.
    // It will give you the innerText property in the case of a domElement.
    // Returns an empty string in the case of unrecognized types.
    functionkit.stringify(value)
    
    // Destringifies the input according to basekitType.
    // Returns value as it is if basekitType left empty. basekitType is one of basekits type.
    functionkit.destringify(value, basekitType = null)
    // Stringifies the url object created by the native js function new URL('...')
    const obj = {
      protocol: 'http:',
      hostname: 'monodrom.org',
      port: 81,
      pathname: 'path'
    }
    functionkit.stringifyURLObject(obj)
    // Returns http://monodrom.org:81/path
    
    // Destringifies the input according to basekitType.
    // Returns value as it is if basekitType left empty. basekitType is one of basekits type.
    functionkit.destringify(value, basekitType = null)
    /*
    * Runs condition function every interval miliseconds and runs callback if
    * condition function returns true. The callback will also be run if condition
    * doesn't return true after timeout miliseconds.
    */
    functionkit.waitForIt(condition, callback, interval = 300, timeout = 10000)
    
    // Examples:
    // wait for library to be available
    function checkLib() {
      return 'someLibrary' in window
    }
    
    function useLibrary() {
      window.someLibrary.someMethod.call()
    }
    
    functionkit.waitForIt(checkLib, useLibrary)
    // interval is 0.3 and timeout is 10 seconds by default

    An article that explains what debounce and throttle does. Implementation of debounce and throttle taken from lodash.

    functionkit.debounce(func, wait, options)
    functionkit.throttle(func, wait, options)

    basekits.validationkit

    // Returns true if value is {}, [], '', 0, null or false. Returns false otherwise.
    validationkit.isEmpty(v)
    
    // Returns the opposite of what would isEmpty() returned.
    validationkit.isNotEmpty(v)
    
    // Returns true if the value is an email.
    validationkit.isEmail(v)
    // Performs a deep and strict equality check. Returns a boolean.
    validationkit.isEqual(value, otherValue)
    
    // Examples:
    validationkit.isEqual('hey', 'hey') // returns true
    validationkit.isEqual(
      {a: {b: {c: 'hey', d: 'dey'}}, b: 'bey'},
      {a: {b: {c: 'hey', d: 'dey'}}, b: 'bey'}
    ) // returns true
    validationkit.isEqual(
      {a: {b: {c: 'hey', d: 'dey'}}, b: 'bey'},
      {a: {b: {c: 'cey', d: 'dey'}}, b: 'bey'}
    ) // returns false
    // Returns true if the value is an RFC compliant UUID.
    validationkit.isUUID(v)
    
    // Examples:
    validationkit.isUUID('109156be-c4fb-41ea-b1b4-efe1671c5836') // returns true
    validationkit.isUUID('109156be-c4fb-41ea-b1b4-efe1671a') // returns false
    // Returns true if the value is a URL.
    validationkit.isURL(value, opts)
    
    // Examples:
    const defaultOpts = {
      allowLocal: false,
      allowDataUrl: false,
      schemes: ['http', 'https']
    }
    validationkit.isURL('http://github.com') // returns true
    validationkit.isURL('ftp://github.com') // returns false
    validationkit.isURL('ftp://github.com', {schemes: ['ftp', 'https']}) // returns true

    basekits.domkit

    domkit.onOutsideClick(elements = [], fn, opts = {once: true})
    
    // Example:
    function closeDropdown() {
      // hide dropdown menu
    }
    domkit.onOutsideClick( document.getElementById('sample'), closeDropdown, {once: true} )

    Executes a function when click event happens outside of one of the elements. elements can be:

    1. Array of selector strings.
    2. Array of DOM elements.
    3. A selector string.
    4. A DOM element.
    // Sets the caret position in the text and textarea inputs or
    // selects some text in the input if start and end are different.
    domkit.setCaretPos(element, start, end)
    
    // Example:
    const el = document.querySelector('input[type="text"]')
    // move the caret to the 4th index
    domkit.setCaretPos( el, 4, 4 )
    // or shorter:
    domkit.setCaretPos( el, 4 )
    // Returns the width and height of the current visible area in the browser.
    domkit.getViewportDimensions() // returns {width: 800, height: 600}
    
    // Returns element's absolute distance from top of the page in pixels.
    domkit.getAbsoluteDistanceFromTop(element) // returns 3392 for example
    
    // Returns element's relative distance from top of the viewport in pixels.
    domkit.getViewportRelativeDistanceFromTop(element) // returns 9 for example
    
    // Returns element's relative distance from bottom of the viewport in pixels.
    domkit.getViewportRelativeDistanceFromBottom(element) // returns 584 for example
    
    // Override window or document globals.
    domkit.setDOMGlobal(name, value)
    domkit.setDOMGlobal('window', window)
    domkit.setDOMGlobal('document', document)

    Distributions Report

    This is an auto-generated report that shows the type, name and size of the bundles available to use individually.

    [
      "basekits.amd.js (18.61 KB)",
      "basekits.amd.polyfilled.js (49.91 KB)",
      "basekits.cjs.js (18.64 KB)",
      "basekits.cjs.polyfilled.js (50.00 KB)",
      "basekits.es.js (18.54 KB)",
      "basekits.es.polyfilled.js (49.90 KB)",
      "basekits.iife.js (18.62 KB)",
      "basekits.iife.polyfilled.js (49.91 KB)",
      "basekits.umd.js (18.81 KB)",
      "basekits.umd.polyfilled.js (50.10 KB)"
    ]

    Babel Polyfills Report

    This is an auto-generated report that shows the pollyfils added by core-js to the pollyfilled distributions based on the targets configuration described below.

    // polyfills:
    []
    // based on the targets:
    {
      "android": "4.4.3",
      "chrome": "49",
      "edge": "90",
      "firefox": "78",
      "ie": "9",
      "ios": "9.3",
      "opera": "76",
      "safari": "13.1",
      "samsung": "4"
    }

    Thanks for watching 🐬

    ko-fi

    Install

    npm i basekits

    DownloadsWeekly Downloads

    342

    Version

    1.3.1

    License

    MIT

    Unpacked Size

    412 kB

    Total Files

    37

    Last publish

    Collaborators

    • muratgozel