1.0.0 • Published 2 years ago

@angeal185/domscript v1.0.0

Weekly downloads
-
License
MIT
Repository
github
Last release
2 years ago

npm.io

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'));