Negating Past Mistakes

    @angeal185/domscript

    1.0.0 • Public • Published

    A lightning fast dom query and manipulation lib for when speed matters.

    cd-img dep-img sz-img

    NPM Version lic-img

    Documentation

    about

    Domscript is a lightning fast dom query/manipulation tool that you can easily customize to suit your needs.

    The goal of domscript is to enable developers to rapidly chain methods while achieving similar to vanilla js speed.

    if you can query and manipulate the dom with javascript, you can already use domscript.

    you should get the same results and errors as though you were writting vanilla js.

    • all prototype methods are optional
    • custom methods can be easily be built into the prototype chain
    • current maximum build size of 3.1kb minified
    • no regex/unsafe functions
    • about as close to using vanilla js speed as it gets.

    installation

    npm

    stable release

    $ npm install @angeal185/domscript --save

    dev release

    git

    $ git clone https://github.com/angeal185/domscript.git

    browser

    <html>
      <head>
        <meta charset="utf-8">
        <script src="/path/to/domscript.mjs" type="module"></script>
        <!-- or -->
        <script src="/path/to/domscript.js"></script>
      </head>
    </html>

    build

    $ npm run build will build domscript into the ./dist folder.

    • the config file is located at ./build/config.json.
    • the build source is located at ./lib/index.js.
    • config.includes allows you to enable/disable prototype methods from the final build.
    • You can also reorganize the order of the prototype chain based on your usage of the methods
    • reorganization should be done with your most used methods at the top.
    • you can also manually add custom methods to the prototype at ./lib/index.js.
    • the custom method names should be added and enabled to config.includes
    • config.export_as controls the variable name used to call domscript.
    • config.module_name controls the built output base name.
    • config.module_ext controls the built output file extension.
    • config.iuclude_utils controls adding the util function.
    • if none of your methods use domscripts util function config.iuclude_utils will exclude it from the build.
    • config.is_module controls the export method of domscript.
    • if you are not using domscript as a module, config.is_module should be false

    performance

    below is a very basic example of domscripts potential.

    // jquery
    console.time('jquery')
    for (let i = 0; i < 1000; i++) {
      $('#test-id').addClass('test1').text('test1');
    }
    console.timeEnd('jquery');
    
    // zepto
    console.time('zepto')
    for (let i = 0; i < 1000; i++) {
      $('#test-id').addClass('test2').text('test2');
    }
    console.timeEnd('zepto');
    
    // umbrella.js
    console.time('umbrella')
    for (let i = 0; i < 1000; i++) {
      u('#test-id').addClass('test3').text('test3');
    }
    console.timeEnd('umbrella');
    
    // vanilla javascript
    console.time('javascript')
    for (let i = 0; i < 1000; i++) {
      let item = document.getElementById('test-id');
      item.classList.add('test4');
      item.textContent = 'test4';
    }
    console.timeEnd('javascript');
    
    // domscript
    console.time('domscript')
    for (let i = 0; i < 1000; i++) {
      d.id('test-id').addClass('test5').txt('test5');
    }
    console.timeEnd('domscript');
    
    
    // jquery 157.0546875ms
    // zepto 145.590087890625ms
    // umbrella 143.53515625ms
    
    // javascript 14.052001953125ms
    // domscript 18.84423828125ms

    your end results should always have domscript running similar speed to native js. the lower the amount of methods included in the domscript prototype, the faster and closer it should be. if you don't use it, exclude it.

    id

    get elementById

    examples:

    // return element by id
    d.id('test-id').r;
    
    
    // get element by id, add class
    d.id('test-id').addClass('test-class');
    
    
    // get element by id, add class, add onclick event
    d.id('test-id').addClass('test-class').on('click', function(evt){
      console.log(evt.target.id)
    });

    class

    get elementsByClassName

    examples:

    // return HTMLCollection by class
    d.class('test-class').r;
    
    // return element by class and index
    d.class('test-class', 0).r;
    
    // get HTMLCollection by class, add id to each
    d.class('test-class').each(function(ele, idx){
      ele.id = 'id-'+ idx
    });
    
    // get first element by class, add id
    d.class('test-class', 0).id('test-id');
    

    tag

    get elementsByTagName

    examples:

    // return HTMLCollection by tag
    d.tag('div').r;
    
    // return element by tag and index
    d.tag('div', 0).r;
    
    // get HTMLCollection by tag, add id to each
    d.tag('div').each(function(ele, idx){
      ele.id = 'id-'+ idx
    });
    
    // get first element by tag, add id
    d.tag('tag', 0).id('test-id');
    

    qs

    document querySelector

    examples:

    // return element by selector
    d.qs('#test-id p').r;
    
    // remove element by selector
    d.qs('#test-id p').rm();
    
    // get element by selector and return textContent
    d.qs('#test-id p').txt();
    
    // get element by selector and edit textContent
    d.qs('#test-id p').txt('new text');
    
    // get element by selector and edit style
    d.qs('#test-id p').css('color', 'red');
    

    qsa

    document querySelectorAll

    examples:

    // return HTMLCollection by selector
    d.qsa('.test-class p');
    
    // get elements by selector and edit textContent of each
    d.qsa('.test-class p').each(function(ele,idx){
      ele.textContent = 'element '+ idx;
    })
    
    // get element by selector and remove all
    d.qsa('.test-class p').each(function(ele, idx){
      ele.remove()
    });
    

    name

    get elementsByName

    examples:

    // return HTMLCollection by name
    d.name('test-name').r;
    
    // return element by name and index
    d.name('test-name', 0).r;
    
    // get HTMLCollection by name, add id to each
    d.name('test-name').each(function(ele, idx){
      ele.id = 'id-'+ idx
    });
    
    // get first element by name, add id
    d.name('test-name', 0).id('test-id');
    

    addClass

    add class/classlist to element

    examples:

    // add a class
    d.id('test-id').addClass('class1');
    
    // add classes
    d.id('test-id').addClass('class1','class2','class3');
    

    rmClass

    remove class/classlist to element

    examples:

    // remove a class
    d.id('test-id').rmClass('class1');
    
    // remove classes
    d.id('test-id').rmClass('class1','class2','class3');
    

    tgClass

    toggle class of element

    examples:

    // remove/add class
    d.id('test-id').tgClass('class1');
    

    hasClass

    check if class exists

    examples:

    // check if class exists
    if(d.id('test-id').hasClass('class1')){
      console.log('class1 exists!')
    } else {
      console.log('class1 does not exist!')
    }

    attr

    set attribute/s

    examples:

    // add an attribute
    d.id('some-input').attr('type', 'text');
    
    // add multiple attributes
    d.id('some-input').attr({
      type: 'text',
      placeHolder: 'some placeholder'
    });

    rmAttr

    remove attribute/s

    examples:

    // remove an attribute
    d.id('some-input').rmAttr('type');
    
    // remove multiple attributes
    d.id('some-input').rmAttr('type', 'placeHolder');

    tgAttr

    toggle attribute/s

    examples:

    // add/remove an attribute
    d.id('some-input').tgAttr('readonly');
    
    // force add/remove an attribute
    d.id('some-input').tgAttr('readonly', true);

    getAttr

    get an element attribute/s

    examples:

    // get an attribute
    console.log(
      d.id('some-input').getAttr('placeHolder')
    )
    // 'some placeholder'
    
    // get multiple attributes
    console.log(
      d.id('some-input').getAttr(['type', 'placeHolder'])
    )
    //{type:"text",placeHolder:"some placeholder"}

    child

    get an element child/ren

    examples:

    // return HTMLCollection of children
    d.id('test-id').child().r
    
    // get children HTMLCollection and add id to each
    d.id('test-id').child().each(function(ele, idx){
      ele.id = 'id-'+ idx
    });
    
    // return child element by index
    d.id('test-id').child(0).r
    
    // return child element by index and return textContent
    d.id('test-id').child(0).txt()
    
    // return child element by index and edit textContent
    d.id('test-id').child(0).txt('new text')
    
    

    parent

    get an elements parent element

    examples:

    // return element parent
    d.id('test-id').parent().r
    
    // edit element parent textContent
    d.id('test-id').parent().txt('i am the parent')
    
    // return element parent's textContent
    d.id('test-id').parent().txt()
    
    // remove all children of parent
    d.id('test-id').parent().empty()
    
    // remove parent
    d.id('test-id').parent().rm()
    

    after

    insert after element

    examples:

    let item = d.create('div').r;
    
    // insert elements and text after querySelected element
    d.id('test-id')
    .after(item.cloneNode(),item.cloneNode(), 'after')
    .before(item.cloneNode(),item.cloneNode(), 'before')

    before

    insert before element

    examples:

    let item = d.create('div').r;
    
    // insert elements and text before querySelected element
    d.qs('#test-id')
    .before(item.cloneNode(),item.cloneNode(), 'before')
    .after(item.cloneNode(),item.cloneNode(), 'after')
    

    first

    get elements first child

    examples:

    // get firstChild of element
    d.id('test-id').first().r
    
    // remove firstChild of element
    d.id('test-id').first().rm()
    
    // empty firstChild of element
    d.id('test-id').first().empty()
    

    last

    get elements last child

    examples:

    // get lastChild of element
    d.id('test-id').last().r
    
    // remove lastChild of element
    d.id('test-id').last().rm()
    
    // empty lastChild of element
    d.id('test-id').last().empty()
    

    clone

    clone an element

    examples:

    // return a clone of selected element
    d.id('test-id').clone().r
    
    // return a deep clone of selected element
    d.id('test-id').clone(true).r
    

    append

    append to an element

    examples:

    let item = d.create('div').r;
    
    // append elements and text to querySelected element
    d.qs('#test-id')
    .append(item.cloneNode(),item.cloneNode(), 'appended')
    .prepend(item.cloneNode(),item.cloneNode(), 'prepended')

    prepend

    prepend to an element

    examples:

    let item = d.create('div').r;
    
    // prepend elements and text to querySelected element
    d.qs('#test-id')
    .prepend(item.cloneNode(),item.cloneNode(), 'prepended')
    .append(item.cloneNode(),item.cloneNode(), 'appended')

    next

    next sibling

    examples:

    // return the direct nextSibling
    d.id('test-id').next().r
    
    // return the nextElementSibling
    d.id('test-id').next(true).r
    // or d.id('test-id').next(1).r
    
    // change textContent of nextElementSibling
    d.id('test-id').next(true).txt('ok')
    
    // get textContent of nextElementSibling
    d.id('test-id').next(true).txt()
    
    // return a clone of the nextElementSibling
    d.id('test-id').next(true).clone().r

    prev

    previous sibling

    examples:

    // return the direct previousSibling
    d.id('test-id').prev().r
    
    // return the previousElementSibling
    d.id('test-id').prev(true).r
    // or d.id('test-id').prev(1).r
    
    // change textContent of previousElementSibling
    d.id('test-id').prev(true).txt('ok')
    
    // get textContent of previousElementSibling
    d.id('test-id').prev(true).txt()
    
    // return a clone of the previousElementSibling
    d.id('test-id').prev(true).clone().r

    rm

    remove element

    examples:

    // remove selected element
    d.id('test-id').rm();
    
    // remove selected elements firstchild
    d.id('test-id').first().rm();

    empty

    empty element

    examples:

    // remove all childnodes from selected element ~ loop
    d.id('test-id').empty();
    
    // remove all childnodes from selected element ~ innerHTML = ''
    d.id('test-id').empty(true);
    // or d.id('test-id').empty(1);
    
    // remove all childnodes from selected elements lastchild
    d.id('test-id').last().empty();

    replace

    replace element

    examples:

    let item = d.create('div').attr('id', 'replaced').r;
    
    
    // replace an element with another element
    d.id('test-id').replace(item)
    
    // replace an element with another element and edit new element
    d.id('test-id').replace(item).txt('replace success')

    html

    add or return innerHTML

    examples:

    // return innerHTML of element
    d.id('test-id').html()
    
    // replace or add innerHTML of element
    d.id('test-id').html('<p>new innerHTML</p>');

    txt

    add or return textContent

    examples:

    // return textContent of element
    d.id('test-id').txt()
    
    // replace or add textContent of element
    d.id('test-id').txt('new text');

    each

    loop over elements examples:

    // get HTMLCollection by class, add id to each
    d.class('test-class').each(function(ele, idx){
      ele.id = 'id-'+ idx
    });
    
    d.qsa('.test-class p').each(function(ele,idx){
      ele.textContent = 'element '+ idx;
    })
    
    // get element by selector and remove all
    d.qsa('.test-class p').each(function(ele, idx){
      ele.remove()
    });

    filter

    return filtered items

    examples:

    // filter HTMLCollection
    d.class('class1').filter(function(ele, idx){
      return ele.id !== 'id3';
    }).each(function(ele, idx){
      ele.textContent = 'ok';
    })
    
    d.class('class1').filter(function(ele, idx){
      return ele.id !== 'id3';
    }).r[0]
    

    on

    attach single on* event to element

    examples:

    // get element by id and add onclick event
    d.id('test-id').on('click', function(evt){
      console.log(evt.target)
    });
    
    // get element by id and add onkeyup event
    d.id('test-input').on('keyup', function(evt){
      console.log(evt.target)
    });
    
    // get element by id and add onload event
    d.id('test-img').on('load', function(evt){
      console.log(evt.target)
    });

    off

    remove single on* event from element

    examples:

    // get element by id and remove onclick event
    d.id('test-id').off('click');
    
    // get element by id and remove onkeyup event
    d.id('test-input').off('keyup');
    
    // get element by id and remove onload event
    d.id('test-img').off('load');

    addEvt

    attach event listener to element

    examples:

    function clickEvt(){
      console.log('clicked')
    }
    
    function keyEvt(){
      console.log('keyup')
    }
    
    function loadEvt(){
      console.log('loaded')
    }
    
    // get element by id and add click event listener
    d.id('test-id').addEvt('click', clickEvt);
    
    // get element by id and add onkeyup event
    d.id('test-input').addEvt('keyup', keyEvt);
    
    // get element by id and add onload event
    d.id('test-img').addEvt('load', loadEvt);

    rmEvt

    remove event listener from element

    examples:

    function clickEvt(){
      console.log('clicked')
    }
    
    function keyEvt(){
      console.log('keyup')
    }
    
    function loadEvt(){
      console.log('loaded')
    }
    
    // get element by id and remove click event listener
    d.id('test-id').rmEvt('click', clickEvt);
    
    // get element by id and remove onkeyup event
    d.id('test-input').rmEvt('keyup', keyEvt);
    
    // get element by id and remove onload event
    d.id('test-img').rmEvt('load', loadEvt);

    css

    add styles to element

    examples:

    // get element by selector and add single style
    d.id('test-id').css('color', 'red');
    
    // get element by selector and add multiple styles
    d.id('test-id').css({
      'color': 'red',
      'font-size': '96px'
    });

    eq

    select element by index

    examples:

    
    d.class('test-class', 0).txt('index 0')
    // or
    d.class('test-class').eq(1).txt('index 1')

    click

    click an element

    examples:

    // get element by selector and add single style
    d.id('some-button').click();

    submit

    submit a form

    examples:

    // get element by selector and add single style
    d.id('some-form').submit();

    focus

    focus an element

    examples:

    //focus an element
    d.id('some-input').focus();
    
    d.id('some-input').focus().attr('type','text');
    
    d.id('some-input').attr({
      placeHolder: 'test focus',
      type: 'text'
    }).focus()
    
    d.id('some-input').on('focus', function(evt){
      console.log('focus event')
    }).focus();

    blur

    blur an element

    examples:

    //blur a focused element
    d.id('some-input').focus();
    
    d.id('some-input').on('blur', function(evt){
      console.log('blur event')
    }).focus().blur();

    cb

    add callback to an item containing current proto state

    examples:

    // return element within callback function
    d.id('some-element').cb(function(ele){
      if(ele){
        d.set(ele).attr('readonly', true)
      }
    })

    set

    set the current proto state

    examples:

    // cached reference
    let cached_item = d.id('some-input').r,
    cached_item2 = d.id('other-input').r;
    
    d.set(cached_item).attr('readonly', true)
    d.set(cached_item2).attr('readonly', true)

    create

    domscript was designed for query/manipulation. It has a basic create function but domscript's sister lib clonecript is a much better alternative and designed to work alongside domscript.

    clonescript was made for creation and not query/manipulation clonescript

    examples:

    let item = d.create('div')
    // get element by selector and add created div
    
    d.id('test-id').append(item);
    
    // do not add a proto within the proto
    //d.id('test-id').append(d.create('div'));

    Install

    npm i @angeal185/domscript

    DownloadsWeekly Downloads

    0

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    33.5 kB

    Total Files

    8

    Last publish

    Collaborators

    • angeal185