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:
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:
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:
- Fork this repository.
- Create a feature branch in git using a name that describes the feature/bug/addition you are updating/fixing/adding.
- 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 undersrc/functions/scroll.ts
. - If possible, please add some light documentation of the class/function's parameters and variable types using the JSDoc specification. (see an example here)
- 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:
- Run
npm i
oryarn
to install dependencies - Run
[npm|yarn] start
to start the Rollup (JS bundler) in development mode; note, it is recommended to also run thetest:watch
script alongside the development process, to catch preliminary bugs in the test suite(s) (see #5). - All modules are written in Typescript, and are located in
src
; functions are included in modules by category, and classes are their own modules - Tests should be written against each added function/class; all tests are located in the
__tests__
directory. - Run
[npm|yarn] test
to run a one-off test run; running[npm|yarn] run test:watch
will start a watch process for tests - Once additions have been properly tested, run
[npm|yarn] run build
to build the module bundles intodist
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:
-
yarn run test
: runs through each test suite, and outputs a report based on how many tests and suites passed or failed. -
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 intomaster
branch.