npm promotes metadefinitions

    bpd-dom

    1.0.1 • Public • Published

    bpd-dom

    Simple library, fast dom inspired, handling HTML DOM mutations

    When to use

    Key feature of library is to make HTML DOM mutations easier. Each time you change anything in HTML element via javascript (styles, content, classes, attributes, etc) browser needs to re-render document or at least part of it. Multiple changes (or done in loop) may cause page and it's animations to stutter if requestAnimationFrame is not used.

    bpd-dom bring handy set of features that allow you to perform multiple DOM mutations in a single frame. It provides queueing mechanism which makes your requests executed in a correct order. Moreover you can use Promises to await for mutation result or just wait until mutation is done.

    Initialization

    Library comes with a dom instance already initalized. To access use import:

    import dom from 'bpd-dom';
    

    If you import an UMD module use:

    const dom = bpdDom.dom.default;
    

    Usage

    For each available option you can choose to call an async which will return a Promise that will resolve when all action are performed. The other option is method exec that also performs action without returning any value. It allows, however, to pass onResolve and onError callbacks.

    Mutation

    To get a mutation task call dom.mutate(...actions), pass list of action to be executed. Dom instance will create new task builder which exposes following methods:

    Method Arguments Return Description
    push ...DomActions this Adds more actions to list
    initWith T this sets initial value - it will be passed to first mutation
    exec onResolve, onError void executes task by pushing it to buffer
    async - Promise Promisified exec

    Fetch

    To get a fetch task call dom.fetch(fetchActions), pass a fetch callback that results with input for mutation actions. Dom instance will create new task builder which exposes following methods:

    • thenMutate - (...actions) - add actions to mutation actions list
    • initWith - (initialValue) - set initial value - it will be passed to fetch callback
    • exec - (onResolve, onReject) - executes task by pushing it to buffer
    • async - Promisified exec
    Method Arguments Return Description
    thenMutate ...DomActions this add actions to mutation actions list
    initWith T this sets initial value - it will be passed to fetch callback
    exec onResolve, onError void executes task by pushing it to buffer
    async - Promise Promisified exec

    Loop

    To execute callback in a loop (animation like) call dom.loop(mutationAction), pass a mutation callback. On each iteration builder first mutates action then checks condition (passed via method until), if it passes - it breaks an execution.

    NOTE

    Take into account the fact that check function is executed for the first time right before starting a loop. If it passed than loop doesn't even start - execution is resolved with initial value

    Dom instance will create new task builder which exposes following methods:

    Method Arguments Return Description
    until (timestamp: number, t: T) => boolen this sets callback that verifies whether loop shall continue
    initWith T this set initial value - it will be passed first to check condition (the one executed on start), then to first mutation callback
    exec onResolve, onError void executes task by pushing it to buffer
    async - Promise Promisified exec

    Example

    Mutation

    const task = dom.mutate<T>((ti: number, value: T) => {
        // Do mutation
        return value
    }).initWith(value: T)
    
    const result = await task.async();
    
    // Alternatively
    
    task.exec((t: T) => {
        // Handle result
    }, (e) => {
        // Handle error
    })

    Fetch

    const task = dom.fetch<T>((ti: number, value: T) => {
        // Do fetch...
        return // value to be passed to first mutation action
    })
    .initWith(value: T)
    .thenMutate((ti: number, value: T) => {
        // Do mutation
        return
    })
    const result = await task.async();
    
    // Alternatively
    
    task.exec((t: T) => {
        // Handle result
    }, (e) => {
        // Handle error
    })

    Loop

    const task = dom.loop<T>((ti: number, value: T) => {
        // Do fetch...
        return // value to be passed to first mutation action
    })
    .initWith(value: T)
    .until((ti: number, value: T) => {
        if(value) {
            // Stop
            return true;
        }
    
        // Continue
        return false;
    })
    const result = await task.async();
    
    // Alternatively
    
    task.exec((t: T) => {
        // Handle result
    }, (e) => {
        // Handle error
    })

    Install

    npm i bpd-dom

    DownloadsWeekly Downloads

    7

    Version

    1.0.1

    License

    GPL-3.0-or-later

    Unpacked Size

    130 kB

    Total Files

    31

    Last publish

    Collaborators

    • bpd_dev