wootils

v5.0.1

Published

2 years ago

A set of Javascript utilities for building Node and browser apps.

Downloads

0High
0Medium
0Low

homer0

Wootils

A set of Javascript utilities for building Node and browser apps.

Motivation/Introduction

The idea was to take all those small thing I'm always rewriting on every project and move them to a single package so I can, not only stop copying & pasting them all over the place, but also maintain them all together.

There are two rules I followed when I had to decide what to put and what to keep somewhere else:

The utility needs to fit on a single file.
It shouldn't include any specific business logic from any other project.

Usage

The package is divided on 3 folders:

node: Utilities that are only compatible with Node.
shared: Utilities that can work on both browser and Node.
browser: Utilities that can only be used while on a browser.

Node utilities

Two notes about the Node utilities:

I'm a big fan of Jimple, so all the files not only export the utility but also a service provider or a "servicer provider generator" to register the utility on a Jimple app.
Some of them may depend on the others.

AppConfiguration

This is a service to manage applications configurations. It takes care of loading, activating, switching and merging configuration files.

EnvironmentUtils

A really small service to centralize the place where you read environment variables and check if you are running on development or production.

ErrorHandler

Listens for uncaught exceptions and unhandled promises rejections, and logs them out with full detail.

Logger

The name leaves nothing to the imagination. As you may have guessed, this is service for logging messages into the console.

packageInfo

A tiny function that reads the contents of the app package.json. This is really useful on an Jimple application where you can register it, because the returned value gets cached and it's available as a service.

PathUtils

An easy way to manage locations and build paths relative to those locations on a Node app.

rootRequire

Is basically require but the path is relative to the project root directory.

Shared utilities

APIClient

A really basic client to work with an API endpoints requests.

DeepAssign

Deep merge (and copy) of objects({}) and Arrays using native spread syntax.

deferred

Create a deferred promise using the native Promise object.

EventsHub

A small implementation of a pubsub service for handling events on an app.

extendPromise

A way to extend promise chains by injecting custom properties.

Jimple Functions

A set of utility functions to generate resources that can be used on Jimple or abstractions created from it (like Jimpex).

ObjectUtils

A small collection of utility methods to work with objects.

Browser utilities

SimpleStorage

An abstract class allows you to build services that relay on browser storage (session/local) and simplifies the way you work it.

ES Modules

All files are written using commonjs, as I targeted the oldest Node LTS and it doesn't support modules (without a flag) yet, but you can use it with ESM.

When the package gets published, an ESM version is generated on the path /esm. If you are using the latest version of Node, or a module bundler (like projext :D), instead of requiring from the package's root path, you should do it from the /esm sub path:

// commonjs
const ObjectUtils = require('wootils/shared/objectUtils');

// ESM
import ObjectUtils from 'wootils/esm/shared/objectUtils';

Since the next LTS to become "the oldest" is 12, which still uses the flag, I still have no plans on going with ESM by default.

Development

NPM/Yarn Tasks

| Task | Description | |------------|--------------------------------------| | docs | Generates the project documentation. | | lint | Lints the staged files. | | lint:all | Lints the entire project code. | | test | Runs the project unit tests. | | todo | Lists all the pending to-do's. |

Repository hooks

I use husky to automatically install the repository hooks so...

The code will be formatted and linted before any commit.
The dependencies will be updated after every merge.
The tests will run before pushing.

Commits convention

I use conventional commits with commitlint in order to support semantic releases. The one that sets it up is actually husky, that installs a script that runs commitlint on the git commit command.

The configuration is on the commitlint property of the package.json.

Releases

I use semantic-release and a GitHub action to automatically release on NPM everything that gets merged to main.

The configuration for semantic-release is on ./releaserc and the workflow for the release is on ./.github/workflow/release.yml.

Testing

I use Jest to test the project.

The configuration file is on ./.jestrc.js, the tests are on ./tests and the script that runs it is on ./utils/scripts/test.

Code linting and formatting

For linting, I use ESlint with my own custom configuration; there are two configuration files, ./.eslintrc for the source and the tooling, and ./tests/.eslintrc, and there's also a ./.eslintignore to exclude some files.

And for formatting, I use Prettier with my JSDoc plugin and my own custom configuration. The configuration file is ./.prettierrc.

The script that runs them is ./utils/scripts/lint; the script lint-all only runs ESLint, and runs it for the entire project.

Documentation

I use JSDoc to generate an HTML documentation site for the project.

The configuration file is on ./.jsdoc.js and the script that runs it is on ./utils/scripts/docs.

To-Dos

I use @todo comments to write all the pending improvements and fixes, and Leasot to generate a report. The script that runs it is on ./utils/scripts/todo.

Windows

This project uses bash scripts for development, so if you want to develop on Windows, you need to do it with WSL.