Rethinking the $
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cjs
coverage
esm
test
.gitignore
.npmignore
.travis.yml
LICENSE
README.md
_config.yml
base.html
index.js
min.js
package.json
rollup.config.js

README.md

QueryResult, rethinking the $()

Build Status Coverage Status

In a nutshell

This model is a modern, minimal, 60LOC (esm) based version of a jQuery(ish) utility.

Features:

  • $(readyFunction) to run code when document is ready
  • $(CSS, optionalParent) to return a collection of elements
  • $(document || window) to use methods with these globals
  • $(anyArrayLike) to transform a collection into a QueryResult instance
  • any instanceof $ to know if an object implements all QueryResult methods
  • $.extend(name, function () { ... }) to pollute the QueryResult prototype
  • $(...).on(type, handler, options) to add listeners to all entries
  • $(...).off(type, handler, options) to remove listeners from all entries
  • $(...).dispatch(type, initDictionary) to dispatch a CustomEvent to all entries

Everything else can be added via $.extend(methodName, function () {}), remembering that arrow functions aren't a good idea if you need a context too.

// ready equivalent $(ready)
$(event => {
  $('input[required]')
    // regular Array methods available
    .filter(el => !el.value.trim())
    // add a specific class to the filtered list
    .map(el => {
      el.classList.add('please-fill-me');
      return el;
    })
    // still on an instance of QueryResult
    // so we could add a listener to each element
    .on('focus', el => el.classList.remove('please-fill-me'))
    // with chainability included
    .on('blur', el => {
      if (!el.value.trim())
        el.classList.add('please-fill-me');
    });
});

:first

If a string contains the pseudo selector :first at its end, the result will stop at the very first encountered match.

This is the only non-standard pseudo-selector implemented.

// will return only first matched p
// and the first matched span
$('p:first, span:first')

This is especially handy in term of performance since the browser will actually stop searching instead of analyzing the entire document (using querySelector instead of querySelectorAll).

Examples

// add a listener
$('a:first').on('click', function(e) {
  e.preventDefault();
  alert(e.detail);
});

// dispatch an event
$('a:first').dispatch(
  'click',
  // optional CustomEvent dictionary
  {detail: 'Hello there!'}
);

// using Array methods
var newCollection = $('.new-nodes')
      .concat(previousCollection)
      .filter(because)
      .on('custom:event', react);


// extending via method
$.extend('html', function (html) {
  var el = (this[0] || {});
  if (html) el.innerHTML = html;
  else return el.innerHTML;
});


// extending via descriptor
$.extend('html', {
  get () {
    return this[0] && this[0].innerHTML;
  },
  set (html) {
    if (this.length) {
      this[0].innerHTML = html;
    }
  }
});

Compatibility

You can verify by yourself through this page but it should work down to very old browsers.

How to include

  • import $ from 'query-result' for ESM (query-result/esm/index.js explicitly)
  • const $ = require('query-result/cjs') for CJS
  • <script src="min.js"></script> for browsers as global $