@kikiutils/wrappers

Table of contents

• @kikiutils/wrappers
  • Table of contents
  • Description
  • Prerequisites
  • Installation
  • Wrappers
    • tryAndGetBoolean
    • tryAndGetData
  • Notice
  • Versioning
  • Authors
  • License

Description

This package provides some useful function wrappers.

Prerequisites

This package requires Node v16 or above.

To check your installed version, run the following command.

$ node -v
v20.5.1

Installation

Before installing, please read the prerequisites.

To install and use this package, run:

$ npm i @kikiutils/wrappers     # Npm
$ pnpm add @kikiutils/wrappers  # Pnpm
$ yarn add @kikiutils/wrappers  # Yarn

Wrappers

All wrappers support passing in async or sync function.

tryAndGetBoolean

Run the function use try/catch.

Returns false if there was an error. Otherwise return true.

import { tryAndGetBoolean } from '@kikiutils/wrappers';

// Async usage
const wrappedFunc = tryAndGetBoolean(async (from: string, to: string) => {
	// ...some actions.
	return [from, to];
});

const asyncResult = await wrappedFunc('./from', './to');
// true - successfully executed
// false - an error occurred

// Sync usage
const wrappedFuncSync = tryAndGetBoolean((from: string, to: string) => {
	// ...some actions.
	return [from, to];
});

const syncResult = wrappedFuncSync('./from', './to');
// true - successfully executed
// false - an error occurred

tryAndGetData

Run the function use try/catch.

If an error occurs, returns undefined or the set value. Otherwise return the function result.

import { tryAndGetData } from '@kikiutils/wrappers';
import fs from 'fs';
import fsp from 'fs/promises';

// Async usage
const wrappedFunc = tryAndGetData(async (path: string) => {
	// ...some actions.
	return await fsp.readFile(path);
});

const asyncResult = await wrappedFunc('./package.json');
// Buffer - successfully read
// undefined - an error occurred

// Sync usage
const wrappedFuncSync = tryAndGetData((path: string) => {
	// ...some actions.
	return fs.readFileSync(path);
});

const syncResult = wrappedFuncSync('./package.json');
// Buffer - successfully read
// undefined - an error occurred

// With onErrorValue
const wrappedFunc = tryAndGetData(async (path: string) => {
	// ...some actions.
	return await fsp.readFile(path);
}, false);

const asyncResult = await wrappedFunc('./package.json');
// Buffer - successfully read
// false - an error occurred

Notice

If you're using typescript, wrapping a function with overloads will break the original type hints and checks for overloads.

But there is a compromise on the parameters and return types of the overload function, see this issue.

If you have a better solution or a solution for ReturnType, feel free to open an issue and raise it, thanks!

To solve this problem, you may need to wrap the function to be wrapped and specify the input type explicitly.

import { tryAndGetData } from '@kikiutils/wrappers';
import fsp from 'fs/promises';

// Original function
const oFile = await fsp.readFile('./package.json');
// oFile type is Buffer

// Wrapped function
const wrappedReadFile = tryAndGetData(fsp.readFile);
const wFile = await wrappedReadFile('./package.json');
// wFile type is string | Buffer | undefined

// Set params to get current type.
const cWrappedReadFile = tryAndGetData(async (path: string) => await fsp.readFile(path));
const cWFile = await cWrappedReadFile('./package.json');
// cWFile type is Buffer | undefined

Versioning

We adhere to Semantic Versioning for this project.

For the versions available, see the versions on npm.

Authors

• kiki-kanri - kiki-kanri

License

MIT License © kiki-kanri