@archermalmo/am.js v1.0.1

am.js

This project is an internal Javascript library of useful utility classes and functions that can be shared and maintained across Archer Malmo's Digital department.

Links:

• Docs
• Coverage

Installation

You can install using yarn:

$ yarn add -D @archermalmo/am.js

or npm:

$ npm i --save-dev @archermalmo/am.js

You can use am.js without installing via npm/yarn as well; include a script tag in the head of your document that points to the Unpkg distribution:

<script src="https://unpkg.com/@archermalmo/am.js"></script>

This will pull in the production version of the IIFE build.

Lastly, you can grab a ZIP or TAR download of the latest release on Github.

Usage

Many utilities in am.js are able to be used cross-environment. To support browsers, module systems, and node.js, this library is built into three different distributions:

• IIFE
• CommonJS module
• ES2015 module

All build targets also have development builds for ease-of-use during initial development.

IIFE

Add the following script tag to your HTML:

<script src="/path/to/am.js"></script>

Now, am.js utilities are available to be used under the global object AM.

const siteNavElement = AM.select("nav#site");
// -> <nav id="site">…</nav>

const titleCaseMessage = AM.capitalize("hello world");
// -> 'Hello World'

const dataRequest = new AM.Request({ endpoint: "https://example.com/" });
dataRequest.send().then(res => res.json()).then(console.log);
// -> { some: 'data' }

CommonJS Modules

Use the require() function to target the CommonJS build in a file intended to be used in a node.js program or CommonJS module system.

const { trim, capitalize } = require("am.cjs");

capitalize(trim("  hello world     "));
// -> "Hello World"

ES2015 Modules

Use the import ... from "..." syntax to target the ECMAScript Module build in a file intended to be used in an ES6+ environment or module system (e.g. a Webpack bundle).

import { selectById, slugify, Request } from "am.esm"

const titleText = selectById("title").innerText;
// -> "Hello World"

const sluggedTitle = slugify(titleText);
// -> "hello-world"

const postTitle = new Request({ endpoint: "https://api.example.com/", options: { method: "POST" }, body: JSON.stringify(sluggedTitle) });

const postResponse = postTitle.send();

postResponse.then(console.log);
// -> { status: 200, ok: true, …}

Environment-Specific Builds

All environment targets have development builds, denoted by a .dev before the Javascript file extension:

• IIFE: am.dev.js
• CommonJS: am.cjs.dev.js
• ES2015: am.esm.dev.js

These builds are non-uglified, with sourcemaps and documenting comments in place; they should only be used in development environments/stages, and switched to non-development builds before deploying to production.

Non-development builds are uglified and minified to provide the most performant bundle possible.

In order to get the most out of the library and include the least amount of code, it is recommended to use a build tool such as Webpack alongside the .esm or .cjs module distributions.

Contributing

Adding functions or classes by PR

If you have a class or function that you think should be added, complete the following steps:

1. Fork this repository.
2. Create a feature branch in git using a name that describes the feature/bug/addition you are updating/fixing/adding.
3. Add your class or function to the related module under the respective directory in src; for example, a function that logs the how much of a page has been scrolled would go under src/functions/scroll.ts.
4. If possible, please add some light documentation of the class/function's parameters and variable types using the JSDoc specification. (see an example here)
5. Open a pull request on this package to your feature branch.

Running the project

To get started developing this library, follow these steps to get started:

1. Run npm i or yarn to install dependencies
2. Run [npm|yarn] start to start the Rollup (JS bundler) in development mode; note, it is recommended to also run the test:watch script alongside the development process, to catch preliminary bugs in the test suite(s) (see #5).
3. All modules are written in Typescript, and are located in src; functions are included in modules by category, and classes are their own modules
4. Tests should be written against each added function/class; all tests are located in the __tests__ directory.
5. Run [npm|yarn] test to run a one-off test run; running [npm|yarn] run test:watch will start a watch process for tests
6. Once additions have been properly tested, run [npm|yarn] run build to build the module bundles into dist

Testing

Testing for am.js is taken care of in two different ways: unit tests and continuous integration.

Unit Tests

The library unit tests, located in __tests__ are written in Jest, an open-source Javascript unit testing framework from Facebook. It is quite versatile, allowing tests to be run against simple value comparisons, or more complex tests involving mocking DOM nodes.

As noted above, you can run these test suites two different ways:

1. yarn run test: runs through each test suite, and outputs a report based on how many tests and suites passed or failed.
2. yarn run test:watch: starts a watch process that runs through tests as they or their dependencies are changed. Following the command line interface's prompts, you can configure the process to only watch certain tests, e.g. ones that follow a regex pattern, only tests that have changed since the last run, etc.

Continuous Integration

This library is also tested after a push event is triggered on the Github repo, including any branch push or pull request openings. These tests are handled in a continuous integration, or CI, environment; this repo's code is tested using TravisCI.

While local unit tests ensure during development that code is properly tested and error-free, they are ran at the discresion of a developer; CI tests are automatically ran against the same tests when code changes occur or new branch code is available.

Notes

Below is a list of repo-related notes/gotchas that are useful to know when working on this project or interacting with this repo:

• TravisCI build is disabled for the docs branch; no library changes should be made on this branch. Still, adding [skip ci] at the beginning of the commit message is useful for preventing these commits from triggering a build when merged into master branch.