hofkit v0.1.2

hofkit

hofkit (Higher Order Function toolKIT) is a modular functional utility library for JavaScript & TypeScript. This library collects frequently rewritten experimental functional wrappers for commonly used utility functions (either custom or from popular libraries such as lodash). These wrappers emphasised functional concepts (e.g., higher order functions, state purity, etc.) to provide functional benefits (e.g., less state, composition) whilst preserving compatibility with existing imperative approaches.

Through this flexiblity, the toolkit aims to be reusable across projects for a wide variety of uses ranging from array & object manipulation (e.g., filtering object entries) to concurrency-controlled Promises.

Additional benefits include builtin type support, environment-specific modules (i.e., featureGroups that group functions to separate dependencies), live-reloadable per-function test suites, and auto-generated live-reloadable documentation.

Features

Usage

Install:

npm install hofkit

Using core functions in TypeScript:

import * as H from 'hofkit'; // Import all `core` functions.
// JavaScript: const H = require('hofkit');

import { titleCase } from H; // Named import.
// JavaScript: const { titleCase } = H;

titleCase('foo bar'); //=> 'Foo Bar'

// Typed return value: `toTitle: any => string`.
const toTitle = H.compose(
    titleCase,
    H.trim,
);
toTitle(' Foo-barBaz '); //=> 'Foo Bar Baz'

Using modular environment-specific functions (currently only node is supported), e.g., node functions:

import * as H from 'hofkit';
import * as HN from 'hofkit/dist/node'; // Import all `node` functions (requires Node environment).
import { readFile } from HN; // Named import.

// Using `async` IFFE for clarity but can be replaced by `H.promiseTryOr` to handle errors.
(async () => {
    // Writing to a file.
    await HN.writeFile('path/to/file')('foo');

    // Find existing paths.
    const filePaths = ['path1', 'path2', 'path3']; // Several file paths.
    const existingFilePaths = await H.promiseFilter(HN.pathExists);

    // Reading data for all existing files.
    let contents: string[] = [];
    const poolSize = 10;
    const onPoolComplete = (poolData: string) => [...contents, ...poolData]; // Flattens data from pools.
    const toFileContents = H.compose(
        H.promiseAll(poolSize, onPoolComplete), // Controlled concurrency.
        H.map(readFile)
    );
    toFileContents(existingFilePaths); //=> [['content1', ...], ...]

    // Overwriting all files.
    const writeFoo = (filePath: string) => HN.writeFile(filePath)('foo');
    const overwriteExistingFiles = H.compose(
        H.promiseAll(), // Uncontrolled concurrency;
        H.map(HN.writeFoo)
    );
    overwriteExistingFiles(filePaths);
})();

Documentation

Function documentation is available via the documentation website.

Screenshot of core documentation website:

<div align="center"><img src="https://user-images.githubusercontent.com/11654341/116275988-fea56400-a77b-11eb-9133-5ee54d8905ed.png" width="100%"/></div>

Scripts

Future Plans

• Complete remaining [spec](./spec.md) functions
• Test async composition
• Support web environments (e.g., browser, react, etc.)
• Changelog