annex

by Sebastian Schlapkohl

Unit-tested and semantically packaged standard solutions for everyday frontend tasks and syntax streamlining for those ugly darks corners of JS.

A Word of Caution

This package has reached beta status. Everything included is tested with unit tests and/or browser examples. And the contents include everything I aimed for in the first version. Although everything is finished from a technical perspective, this package is not yet battle-proven.

The beta should be fine to use (cautiously), but I will delay the bump to version 1.0.0 stable until after I've used this in a real-world project.

What is This?

After more than 15 years of web development I have gotten quite opinionated about JavaScript, its way of doing things, the dark places of this language, what it is lacking and how I like to do things instead.

This package is a collection of helpers, solutions and best practices that have amassed over the years, providing quality of life solutions, best practices (in my opinion) and additions, that I can't and don't want to live without (especially some Python stuff).

Everything included here is strictly frontend-oriented and not meant for node or window-less or dom-less environments. Think of it as lodash's little frontend brother.

Every single solution/helper/function is importable by itself using ES6 imports (and maybe a bundler), documented with jsdoc, tested with Ava (unit tests can be found in test), used in a live browser example (in case unit tests are not helpful; examples can be found in examples) and semantically structured into modules concerning topics and aspects of development (such as logging or strings).

So, the TL;DR is: annex is a battle-proven, tested pool of frontend js tools to solve reappearing tasks quickly and make JavaScript more bearable by streamlining syntactical nonsense and providing functions other languages provide naturally.

Some of the Batteries Included

• event helpers including a complete event system
• variable normalization and type evaluation
• DOM handling with element creation and manipulation
• streamlined standard requests (basic requests & special versions for html/css/js/json)
• url and navigation helpers
• better logging
• better randomization for numbers and ids
• string generation and conversion tools like formatting and slugification
• array tools like actually usable removal functionality based on values and flexible indices
• dates, that actually make sense and offer helpful functions
• browser capability checks and context evaluation
• viewport information and functionality
• interaction solutions like obfuscated mailto and tel links
• better (& more precise) timers
• polling
• cookie handling
• image and webfont availability callbacks
• form helpers for data

Is This Documented Somewhere?

Yes, that as well.

Visit the documentation on GitHub or open /docs/documentation/index.html locally after checking out the repo.

Is This Tested in Any Way?

Yes, it actually is!

The algorithmic core is tested via Ava and all tests are to be found in test.

Many features are not really well suited for unit testing but require a real browser as a context. For all those cases I built example pages (to be found under examples, just opening index.hml from the file system should work, at least for the es5 version). In these example pages you can browse all topics not covered by unit tests and play around with the functionality.

How Can I Run the Examples?

Either view the examples on GitHub or open /docs/examples/index.html locally after checking out the repo.

How Do I Install This?

Besides just downloading the zip file and dropping the package in your project (which I would not recommend doing), you may easily use NPM or Yarn.

Currently, I'm publishing to Github packages and not the central NPM registry. If you want to directly install the package, not using the repository URL, , you'll have to tell NPM/Yarn, that @oktarintentakel can be found at GitHub packages and not at the central NPM registry and add an access token to use for installing. To do this, add or edit a .npmrc file (either globally in your home folder or next to the package.json to your project) and add @oktarintentakel:registry=https://npm.pkg.github.com to the file (following GitHub's documentation). After this, the defined namespace is installed from there automatically. Additionally, we also need a personal access token by adding the line //npm.pkg.github.com/:_authToken=TOKEN (following GitHub's documentation).

Hint: I am aware, that this is rather cumbersome currently, and therefore I currently suggest using the repository URL, but I implemented the workflow anyway, awaiting an easier workflow in the future.

NPM

npm install @oktarintentakel/annex

or with a version

npm install @oktarintentakel/annex@X.X.X

or via GitHub repository

npm install oktarintentakel/annex

or via GitHub repository using a tag

npm install oktarintentakel/annex#vX.X.X

Yarn

yarn add @oktarintentakel/annex

or with a version

yarn add @oktarintentakel/annex@X.X.X

or via GitHub repository

yarn add oktarintentakel/annex

or via GitHub repository using a tag

yarn add oktarintentakel/annex#vX.X.X

Using an Alias Location

In many cases (especially when installing directly from Github repository) it makes sense to define an install alias, to manually define a folder inside node_modules to install to.

Using NPM

npm install my-alias-location@:npm@oktarintentakel/annex@X.X.X

or using NPM with GitHub repository

npm install my-alias-location@oktarintentakel/annex#vX.X.X

or using Yarn

yarn add my-alias-location@:npm@oktarintentakel/annex@X.X.X

or using Yarn with GitHub repository

yarn add my-alias-location@oktarintentakel/annex#vX.X.X

or in package.json

{
  "dependencies": {
      "my-alias-location" : "npm:@oktarintentakel/annex@X.X.X"
  }
}

or with Github repository

{
  "dependencies": {
      "my-alias-location" : "oktarintentakel/annex#vX.X.X"
  }
}

@client Package Separation

It may be a good idea, to generally split node and client packages up. Why? Client packages are delivered directly to the client and are executed and interpreted on the user's machine. So, these packages have a different set of rules applying to them. For example: it is not really clever to give client packages an approximate version, like a normal node dependency using ^ oder ~, because every minor change in a client package may affect all receiving clients after a reevaluation of npm versions. This is a nightmare, because this means, that, at undetermined points in time, all cross-browser testing you did may be invalid and since you are not seeing everything while developing all the time, your app may fall apart on certain devices, without you knowing.

Another problem is sharing of packages between dev/build/hosting and frontend/client. Let's say both use lodash or q promises: both have to agree on the exact same version, that should not be changed frequently because of the aforementioned problems. That is very unpractical for both usages and each should be able to use the version fitting its purpose, since they are used for different things on very different machines, even if it is the same package under the hood.

So I generally propose separating all npm packages, that are delivered to the client directly in any way into a specific @client package in node_modules using fixed versioning for these (I originally got the idea when I transitioned) from bower to npm, reading the bower team's ideas about this.

So, I propose to generally use an alias location for client packages, such as this (see previous point, for all/other options):

{
  "dependencies": {
      "@client/annex" : "oktarintentakel/annex#vX.X.X"
  }
}

How Do I Include and Use This?

After installation, just include single functions/symbols from the semantic packages like this:

import {log} from 'annex/source/logging';

It might be a good idea, to set a path alias in your bundler, to skip the source path.

In Webpack a path alias would look like this (see documentation):

{
  resolve: {
    alias: {
      annex : path.resolve(__dirname, 'node_modules/@client/annex/source/')
    }
  }
}

Which would allow you an import like this: import {log} from 'annex/logging';

If you want to serve packages without bundling, as they are, you can do so, by serving them as type module scripts. For this purpose I included a dist dir, containing minified, ES6 scripts. Use these, you would do:

<script type="module" src="annex/dist/logging.js"></script>

In this case, make sure all dist file are publicly available and are in the same dir, so imports can work.

Of course, you can also import dist files via a bundler, but in that case you would lose the capability to jump to readable source in your IDE and you would also lose all JSDOC strings.

Be aware, that all module source code is written in fairly up-to-date ES6, disregarding legacy concerns. So, whether you are bundling the modules or using them verbatim, keep the browser support in mind and make sure to set up transpilation during bundling, matching your browser matrix, if necessary. All features I'm using are transpilable with Babel and polyfillable with core-js (have a look at the gulpfile for a working webpack setup). Anything additionally necessary, I've included as a polyfill function in the "polyfills" module (stuff like CustomEvents, which are not included in core-js).

If you need to use ES5, I also included a monolithic ES5 version in dist as a UMD. So you can easily load the script with

<script src="public/annex/dist/es5-monolith.js"></script>

After which there should be window.annex, which has each package as a key, so for example

window.annex.logging.log('test')

should write something to the console.

ES5 is compiled with a target >= IE11.

Versioning

I'm using semver, so majors are definitely breaking, minors may be breaking and bugfixes should never break anything.

Is This Any Good, Why Should I Use This?

Well, since this package is not monolithic: Why not?

If anything catches your eye, just use this one thing and maybe you find other helpful things as well. Since ES6 we have the luxurious situation of being able to pick and choose, without immediately bloating the bundle. And since annex has no peer dependencies, you are not even bloating your node_modules.

On the other hand, you are also completely free to just scan the source and copy whatever you need, if you do not want to add the dependency. You are completely free to just use the repo as reference as well!