https://github.com/norjs/utils
Common utils for ES6 and Node.js
https://github.com/norjs/utils
Last synced: 3 months ago
JSON representation
Common utils for ES6 and Node.js
- Host: GitHub
- URL: https://github.com/norjs/utils
- Owner: norjs
- License: mit
- Created: 2019-04-22T06:34:32.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T20:33:34.000Z (over 3 years ago)
- Last Synced: 2025-03-22T03:44:14.442Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 344 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# @norjs/utils
Common almost-non-dependable(*) utils for ES6 and Node.js, with MIT license.
(*) Only runtime dependency is to [Lodash](https://lodash.com/).
----------------------------------------------------------------------------------------------------
### Install stable from NPM
`npm install @norjs/utils`
### Install latest from Github
`npm install norjs/utils`
----------------------------------------------------------------------------------------------------
### TypeUtils
Runtime JSDoc style type asserting and testing.
```js
const TypeUtils = require('@norjs/utils/Type');
```
----------------------------------------------------------------------------------------------------
#### `TypeUtils.assert(value, type)`
This function throws a `TypeError` if value is not of the type definition.
```js
// Basic types
TypeUtils.assert( "123", "string");
TypeUtils.assert( 123, "number");
TypeUtils.assert( true, "boolean");
TypeUtils.assert( false, "boolean");
TypeUtils.assert( () => {}, "function");
TypeUtils.assert( undefined, "undefined");
TypeUtils.assert( null, "null");
// Objects
TypeUtils.assert( {}, "{}");
TypeUtils.assert( {}, "Object");
TypeUtils.assert( {foo: "bar"}, "Object.");
TypeUtils.assert( {foo:"bar"}, "{foo:string}");
// Arrays
TypeUtils.assert( [1, 2, 3], "Array");
TypeUtils.assert(["1", "2", "3"], "Array.");
TypeUtils.assert(["1", "2", "3"], "string[]");
// Multiple types
TypeUtils.assert("false", "boolean|string");
// Intersections
TypeUtils.assert( {"foo": 1, "bar": 2}, "{bar:number} & {foo:number}");
```
----------------------------------------------------------------------------------------------------
#### `TypeUtils.test(value, type)`
This function returns `false` if `value` is not of the type definition.
```js
if (TypeUtils.test("123", "string")) {
// ...
}
```
----------------------------------------------------------------------------------------------------
#### `TypeUtils.defineType(name, type)`
You can define your own JSDoc `typedef` definitions like this:
```js
/**
* @typedef {string} MyStringType
*/
TypeUtils.defineType("MyStringType", "string");
TypeUtils.assert("bar", "MyStringType");
/**
* @typedef {Object} MyFooType
* @property {string} foo - The foo property
*/
TypeUtils.defineType("MyFooType", {"foo": "string"});
TypeUtils.assert({foo:"bar"}, "MyFooType");
```
...and your classes like:
```js
class Foo {
// ...
}
TypeUtils.defineType("Foo", TypeUtils.classToTestType(Foo));
```
...and your interfaces like:
```js
/**
* @interface
*/
class FooInterface {
// ...
}
TypeUtils.defineType(
"FooInterface",
TypeUtils.classToObjectPropertyTypes(FooInterface),
{
acceptUndefinedProperties: true // Accept test subject to have properties not defined in FooInterface
}
);
```
----------------------------------------------------------------------------------------------------
#### `TypeUtils.toString(value)`
Returns a human readable string presentation of `value`.
----------------------------------------------------------------------------------------------------
#### `TypeUtils.isPromise(value)`
Returns `true` if `value` is a promise (eg. it is an object and has `then` method).
----------------------------------------------------------------------------------------------------
### LogicUtils
```js
const LogicUtils = require('@norjs/utils/Logic');
```
----------------------------------------------------------------------------------------------------
#### `LogicUtils.tryCatch(f, handleError)`
Will call function `f` inside a try-catch block.
If an exception is thrown, the `handleError(error)` function will be called with an error object.
The result from `f()` will be returned, except if an error occurs, then the result from `handleError(error)`.
*Note:* Some JS environments (eg. some versions of Google v8) will turn off performance optimizations
and fallback in to the slower interpreter mode when a try-catch block is detected for the whole
execution block. **However**, this function *may be slower than try-catch block* on modern environments.
----------------------------------------------------------------------------------------------------