No! Primate Mutation!

    @jgarber/cashcash

    3.0.0 • Public • Published

    CashCash

    A very small DOM library inspired by jQuery that smooths over some of the rough edges in JavaScript's native DOM querying methods.

    npm Downloads Build Maintainability Vulnerabilities

    Key Features

    • Uses JavaScript's native querySelectorAll method
    • Dependency-free
    • ES2015/AMD/Node module support

    Getting CashCash

    You've got a couple options for adding CashCash to your project:

    • Download a tagged version from GitHub and do it yourself (old school).
    • Install using npm: npm install @jgarber/cashcash --save
    • Install using Yarn: yarn add @jgarber/cashcash

    Usage

    CashCash takes a similar approach to DOM selection as the aforementioned (and insanely popular) jQuery.

    CashCash('p');          // select all `<p>`s on a page
    CashCash('#main');      // select the element with the ID of `main`
    CashCash('p', '#main'); // select all `<p>`s within an element with the ID of `main`

    CashCash accepts two arguments: a selector (a string) and an optional context (a string or an HTMLElement). For basic DOM selection, you should be fine passing in any supported CSS selector. For more advanced usage, the second context argument might prove useful:

    const divs = CashCash('div');              // select all `<div>`s on a page
    const paragraphs = CashCash('p', divs[0]); // select all `<p>`s within the first `<div>`

    Under the covers, CashCash uses the browser's native querySelectorAll method and therefore supports the same CSS selectors.

    When selecting DOM nodes based on the provided selector string, CashCash will store references to those selected DOM elements on itself in an array-like fashion for easy access to individual DOM nodes.

    Given the following markup:

    <p>Paragraph 1</p>
    <p>Paragraph 2</p>
    <p>Paragraph 3</p>
    <p>Paragraph 4</p>
    <p>Paragraph 5</p>

    You can do the following:

    const paragraphs = CashCash('p');
    
    paragraphs.forEach(paragraph => console.log(paragraph)); // logs `<p>Paragraph 1</p>`, `<p>Paragraph 2</p>`, etc.

    Collection Properties

    length

    For all queries (valid or otherwise), CashCash will return the length (defaulting to 0) of the queried elements.

    const thisManyBodyElements = CashCash('body').length; // returns `1`

    selector

    As best as possible, CashCash keeps track of the selector used in a given query, making it available to you by calling:

    console.log(CashCash('p').selector);                // logs the string `p`
    console.log(CashCash('p', '#container').selector);  // logs the string `#container p`
    console.log(CashCash('p', document.body).selector); // logs the string `p`

    context

    CashCash makes available a reference to the context for a given query (if one is provided and that context is an HTMLElement). If no context is given (or if the given context is a string), CashCash will default to HTMLDocument.

    console.log(CashCash('p').context);                // logs a reference to `HTMLDocument`
    console.log(CashCash('p', '#container').context);  // logs a reference to `HTMLDocument`
    console.log(CashCash('p', document.body).context); // logs a reference to `<body>`
    
    const container = CashCash('#container');
    
    console.log(CashCash('p', container[0]).context); // logs a reference to `<div id="container">`

    Example

    For a full-featured CashCash demonstration, check out the included example file.

    Tips and Tricks

    Mimicking jQuery

    If you want to cut down on some typing (and potentially confuse your teammates), you can reassign CashCash to $ to mimic jQuery:

    <script src="./dist/cashcash.js"></script>
    <script>
      (function($) {
        const paragraphs = $('p');
    
        // …
      })(CashCash);
    </script>

    …or:

    <script type="module">
      import $ from './dist/cashcash.mjs';
    
      const paragraphs = $('p');
    
      // …
    </script>

    Browser Support

    CashCash works in modern browsers. The library makes use of several new(ish) JavaScript features, including:

    • Arrow function expressions (MDN)
    • Classes (MDN)
    • Template literals (MDN)
    • Document.querySelectorAll() (MDN)
    • NodeList.prototype.forEach (MDN)

    CashCash, in an effort to remain as lightweight and dependency-free as possible, leaves it up to you to choose whether or not to polyfill features for older browsers.

    Acknowledgments

    CashCash is inspired by jQuery and the many micro DOM libraries it inspired (like Ken Wheeler's cash, for instance).

    CashCash is written and maintained by Jason Garber and is another in a growing line of small, curiously-named JavaScript utilities:

    License

    CashCash is freely available under the MIT License. Use it, learn from it, fork it, improve it, change it, tailor it to your needs.

    Install

    npm i @jgarber/cashcash

    DownloadsWeekly Downloads

    6

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    12.3 kB

    Total Files

    6

    Last publish

    Collaborators

    • jgarber