Dollarsign NPM

Dollarsign - Native jQuery

A small library for native DOM selection and event binding. Wraps basic browser functionality into a more consistent API. Supports most of jQuery's basic API for event binding, DOM selection, and CSS/attribute manipulation.

Installation

Install Dollarsign with NPM:

$ npm install dollarsign --save

Or Yarn:

$ yarn add dollarsign

You can then import the $ factory function:

import $ from "dollarsign";

Usage

Use Dollarsign to select DOM elements and bind events:

import $ from "dollarsign";

$("#change-color").on("click", function (event) {
  event.preventDefault();
  $("h1").css({ color: "#ff000" });
});

<body>
  <h1>I'm different!</h1>

  <nav>
    <a href="#" id="change-color">Change Color</a>
  </nav>
</body>

Much of the jQuery API is provided, with some notable exceptions (like $.ajax).

Programmatic Usage

You can also use the Dollarsign class on its own and build your own factory function:

import { Dollarsign } from "dollarsign";

function $(selector) {
  return new Dollarsign(document, selector);
}

Plugins

Plugins are similar to the jQuery implementation:

$.fn.plugin = function () {
  this.each((element) => {
    $(element).addClass("plugined");
  });
};

$("#element").plugin();
$("#element").hasClass("plugined"); // => true

Testing Plugins

You can test your plugins in isolation by using a stripped-down build. Here's an example written in Jest:

import { foo } from "./foo";
import { $ } from "dollarsign/factory";

$.fn.foo = foo;

test("foo", () => {
  expect($(document).foo()).toEqual("bar");
});

Roll Your Own

The plugin system is not only used for 3rd-party plugins, it's also how Dollarsign implements most of its functionality. This means you can leverage the relatively small size of Dollarsign's core functionality and "roll your own" build of the library, using tree-shaking and compile-time optimizations to get the smallest possible bundle size with the least amount of work.

To roll your own build of Dollarsign, import $ from the factory module rather than the default:

import { $ } from "dollarsign/factory";

This gives you a "blank slate" Dollarsign object. You can still query for elements, but there's not much you can do with them. You'll need to import some functionality and apply them as plugins. For example, if you only wanted the event binding functionality, you might do:

import { $ } from "dollarsign/factory";
import { on, off, fire } from "dollarsign/events";

$.fn.on = on;
$.fn.off = off;
$.fn.fire = fire;

export default $;

Note that some parts of the standard set of plugins are dependent on one another. For example, to use load(), you will need to also include the following plugins (or at least reasonable facsimiles of them):

import { $ } from "dollarsign";
import { load } from "dollarsign/ajax";
import { html } from "dollarsign/dom";

$.fn.html = html;
$.fn.load = load;

API Documentation

For more information about what API methods are implemented, visit the documentation at https://tubbo.github.io/dollarsign

Development

To contribute to Dollarsign, download the Git repository:

$ git clone https://github.com/tubbo/dollarsign.git
$ cd dollarsign

Then, install dependencies:

$ yarn install

Make your changes to the .js files and run tests to make sure everything still works (and write tests for new functionality!):

$ yarn test

We use Jest for our test runner, and Babel to compile our JavaScript to a format that Jest will understand. Since Jest does not yet support ESModules syntax out of the box, we need to use babel-jest here to transpile our syntax.