@substrate-system/util
    Preparing search index...

    @substrate-system/util

    util

    tests types module semantic versioning dependencies install size license

    Utility functions for the front end.

    npm i -S @substrate-system/util
    
    import util from '@substrate-system/util'

    // or individual functions
    import { attributesToString } from '@substrate-system/util'

    Prevents body scrolling, useful for things like "dialog" windows. Keeps track of which elements requested a lock so multiple levels of locking are possible without premature unlocking.

    Originally seen in the shoelace library.

    import { lockBodyScrolling, unlockBodyScrolling } from '@substrate-system/util'

    // stop scroll
    lockBodyScrolling(document.body)

    // ...sometime in the future...
    unlockBodyScrolling(document.body)

    Stop scrolling.

    function lockBodyScrolling (lockingEl:HTMLElement):void
    

    Resume scrolling.

    function unlockBodyScrolling (lockingEl:HTMLElement):void
    

    Various special characters.

    const EM_DASH = '\u2014'
    const EN_DASH = '\u2013'
    const NBSP = '\u00A0'
    const PETABYTE = (2 ** 50)
    const TERABYTE = (2 ** 40)
    const GIGABYTE = (2 ** 30)
    const MEGABYTE = (2 ** 20)
    const KILOBYTE = (2 ** 10)
    const ELLIPSIS = '\u2026'
    const BULLET = '\u2022'
    import { ELLIPSIS } from '@substrate-system/util/constants'

    element.textContent = `${ELLIPSIS} something dramatic ${ELLIPSIS}`

    Create a new class name string by concattenating the given input.

    import { classes } from '@substrate-system/util/classes'
    const className = classes('hello', '123', '100')
    // => 'hello 123 100'

    The self object for Node.

    import { self } from '@substrate-system/util/node'
    

    Take the number of bytes, return a string abbreviated to common sizes (megabyte, kilobyte, etc).

    import { humanFilesize } from '@substrate-system/util/filesize'

    const size = humanFilesize(10_000)
    console.log(size)
    // => 9.8 KiB
    function humanFilesize (
    bytes:number,
    si:boolean = false,
    dp:number = 1
    ):string
    • bytes the byte count
    • si -- use SI, instead of EIC units (default false)
    • dp is the number of decimal places to show.

    import { Queue } from '@substrate-system/util/queue'
    

    Create a queue of promises. Promises will execute 1 at a time, in sequential order.

    class Queue<T> {
    add (createP:()=>Promise<T>):Promise<T|void>
    }

    Take a function that returns a promise. Return a promise that will resolve when the created promise resolves.

    add (createP:()=>Promise<T>):Promise<T|void>
    
    Note


    This will resolve promises in the order they were added to the queue.

    import { test } from '@substrate-system/tapzero'
    import { Queue } from '@substrate-system/util'

    test('queue of 3 items', t => {
    const q = new Queue<string>()

    // [p1, p2, p3]
    const returned = [false, false, false]

    const p1 = q.add(() => {
    return new Promise<string>(resolve => {
    setTimeout(() => resolve('p1'), 300)
    })
    })

    const p2 = q.add(() => {
    return new Promise<string>(resolve => {
    setTimeout(() => resolve('p2'), 200)
    })
    })

    const p3 = q.add(() => {
    return new Promise<string>(resolve => {
    setTimeout(() => resolve('p3'), 100)
    })
    })

    // p1 takes the longest
    p1.then((value) => {
    t.equal(value, 'p1', '"p1" string is ok')
    returned[0] = true
    t.ok(!returned[2], 'p2 should not have returned yet')
    t.ok(!returned[1], 'p1 should not have returned yet')
    })

    p2.then(value => {
    t.equal(value, 'p2', 'should get string "p2"')
    returned[1] = true
    t.ok(returned[0], 'should have p1 b/c it was added first')
    t.ok(!returned[2], 'should not have 3 yet b/c it was addded last')
    })

    // p3 is the fastest
    p3.then(value => {
    t.equal(value, 'p3', 'should get string "p3"')
    returned[2] = true
    t.ok(returned[0], 'should have p1 because it was added first')
    t.ok(returned[1], 'should have p2 because it was added next')
    })

    // return 3 so the test knows when to end,
    // because they resolve in order,
    // even though the ms are backwards
    return p3
    })

    Import sleep from here to reduce duplication.

    function sleep (ms?:number):Promise<void>
    
    import { sleep } from '@substrate-system/util'

    await sleep(500) // 1/2 second

    Validate an email address.

    function isEmailValid (maybeEmail:string):boolean
    
    import { isEmailValid } from '@substrate-system/util/email'

    isEmailValid('aaa@bbb.com')
    // => true

    Parse a form and return a plain object. If a form control with the same name appears more than once, the property will be converted to an array.

    function parseForm (form:HTMLFormElement):Record<string, unknown>
    

    Take an array of attributes, and transform them into a string format. This can be useful for creating web components.

    function attributesToString (attrs:Attr[]):string {
    
    import { attributesToString } from '@substrate-system/util'

    const el = document.getElementById('example')
    const str = attributesToString(Array.from(el!.attributes))
    console.log(str)
    // => 'type="text" id="example" required'

    Set the given attributes from an object. Will handle boolean attributes like required.

    function setAttributes (el:HTMLElement, attrs:Record<string, string|boolean>)
    
    import { attributesToString, setAttributes } from '@substrate-system/util'

    const input = document.getElementById('test') as HTMLInputElement

    setAttributes(input, {
    id: 'test',
    required: true,
    name: 'fooo',
    class: 'testing'
    })

    console.log(attributesToString(Array.from(input.attributes)))
    // => 'id="test" class="testing" name="fooo" required',

    Return an object of { key: value } from an array of attributes. If an attribute is a boolean value, then it will be { name: true }.

    function attributesAsObject (attrs:Attr[]):Record<string, string|true>
    
    import { attributesAsObject } from '@substrate-system/util'

    const el = document.querySelector('input')
    const attrs = Array.from(el!.attributes)
    const obj = attributesAsObject(attrs)
    console.log(obj)
    // => {
    // "type": "text",
    // "required": true,
    // "name": "example",
    // "foo": "bar"
    // }

    Take an object, as from attributesAsObject, and stringify it for use in HTML.

    function objectToString (obj:Record<string, string|true>):string
    
    import { objectToString } from '@substrate-system/util'

    const obj = {
    type: "text",
    required: true,
    name: "example",
    foo: "bar"
    }
    const str = objectToString(obj)
    console.log(str)
    // => 'type="text" required name="example" foo="bar"'

    Expose unicode characters.

    import * as CONSTANTS from '@substrate-system/util/CONSTANTS'
    
    // CONSTANTS.ts
    export const EM_DASH = '\u2014'
    export const EN_DASH = '\u2013'
    export const NBSP = '\u00A0'