# @rainbow-n19/n1

> Value operators.

Latest version **0.1.1** (published 2024-11-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install @rainbow-n19/n1
pnpm add @rainbow-n19/n1
yarn add @rainbow-n19/n1
bun add @rainbow-n19/n1
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2024-11-27 |
| First published | 2024-11-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 248.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Rainbow Team |
| Maintainers | build_admin |

## Links

- npm: https://www.npmjs.com/package/@rainbow-n19/n1
- Repository: https://github.com/InsureMO/rainbow-n19
- Homepage: https://github.com/InsureMO/rainbow-n19#readme
- Issues: https://github.com/InsureMO/rainbow-n19/issues
- npm.io page: https://npm.io/package/@rainbow-n19/n1

## Dependencies (2)

- [dayjs](https://npm.io/package/dayjs.md) ^1.11.13
- [decimal.js](https://npm.io/package/decimal.js.md) ^10.4.3

## Recent versions

- 0.1.1 (latest) — 2024-11-27
- 0.1.2-alpha.1 (alpha) — 2025-03-19
- 0.1.0 — 2024-11-27

## README

![Static Badge](https://img.shields.io/badge/InsureMO-777AF2.svg)

# n19/n1

The `n19/n1` module provides a series of value operators that can be used via chainable calls. This module is primarily written in
TypeScript and managed using npm or yarn.

## Touch a Value

Begin the value touching via the following method:

- `ValueOperator.of`,
- `ValueOperator.from`,
- `ValueOperator.with`,

they are all equivalent.

## Value Actions

### Available Testers

The module includes various testers for different conditions. Below is a list of available testers:

#### Any Type Testers

- `isNull`: Checks if a value is null or undefined.
- `isNotNull`: Checks if a value is not null or undefined.
- `isEmpty`: Checks if a value is empty.
- `isNotEmpty`: Checks if a value is not empty.
- `isBlank`: Checks if a value is null, undefined, or a blank string.
- `isNotBlank`: Checks if a value is not null, undefined, or a blank string.
- `has`: Checks if a value has a specified property.
- `notHas`: Checks if a value does not have a specified property.

#### Dayjs Testers

- `toDate`: Converts a value to a Dayjs object if valid.
- `before`: Checks if a date is before the specified date.
- `notBefore`: Checks if a date is not before the specified date.
- `after`: Checks if a date is after the specified date.
- `notAfter`: Checks if a date is not after the specified date.
- `between`: Checks if a date is within the specified range.
- `notBetween`: Checks if a date is not within the specified range.

#### Decimal Testers

- `isDecimal`: Checks if a value is a valid Decimal.
- `isInteger`: Checks if a value is an integer Decimal.
- `isInRange`: Checks if a decimal value is within a specified range.
- `isNotInRange`: Checks if a decimal value is not within a specified range.
- `isPositive`: Checks if a decimal value is positive.
- `isNotPositive`: Checks if a decimal value is not positive.
- `isNegative`: Checks if a decimal value is negative.
- `isNotNegative`: Checks if a decimal value is not negative.
- `isZero`: Checks if a decimal value is zero.
- `isNotZero`: Checks if a decimal value is not zero.
- `isGreaterThan`: Checks if a decimal value is greater than a specified value.
- `isGreaterThanOrEqual`: Checks if a decimal value is greater than or equal to a specified value.
- `isLessThan`: Checks if a decimal value is less than a specified value.
- `isLessThanOrEqual`: Checks if a decimal value is less than or equal to a specified value.

#### String Testers

- `startsWith`: Checks if a string starts with the given prefix.
- `notStartsWith`: Checks if a string does not start with the given prefix.
- `endsWith`: Checks if a string ends with the given suffix.
- `notEndsWith`: Checks if a string does not end with the given suffix.
- `includes`: Checks if a string includes the given substring.
- `notIncludes`: Checks if a string does not include the given substring.
- `regexp`: Checks if a value matches the given regular expression.
- `isOneOf`: Checks if a value is one of the given values.
- `isNotAnyOf`: Checks if a value is not any of the given values.

### Available Transformers

The module includes various transformers for different data types. Below is a list of available transformers:

#### Any Type Transformers

- `formatDate`: Formats a date.
- `formatNumber`: Formats a number.
- `format`: General format function.
- `retrieve`: Retrieves a value.

#### Dayjs Transformers

- `travelTo`: Travels to a specified date. Specific dates or times are represented by a string:
	- `Y`/`y`, represents the year
	- `M`, represents the month
	- `D`/`d`, represents the day
	- `H`/`h`, represents the hour
	- `m`, represents the minute
	- `S`/`s`, represents the second
	- `+` represents moving forward in time
	- `-` represents going back in time
	- no symbol represents direct travel.
	- e.g. `+5Y2M-3d12H0m0s` represents traveling 5 years later, Feb., and minus 3 days, and time is 12:00:00, from given date and time.
- `year`: Travels to a specified year.
- `shiftYear`: Travels to previous or next years.
- `startOfYear`: Travels to the start of the year.
- `endOfYear`: Travels to the end of the year.
- `month`: Travels to a specified month.
- `shiftMonth`: Travels to previous or next months.
- `startOfMonth`: Travels to the start of the month.
- `endOfMonth`: Travels to the end of the month.
- `day`: Travels to a specified day of month.
- `shiftDay`: Travels to previous or next days.
- `startOfDay`: Travels to the start of the day.
- `endOfDay`: Travels to the end of the day.
- `hour`: Travels to a specified hour.
- `shiftHour`: Travels to previous or next hours.
- `startOfHour`: Travels to the start of the hour.
- `endOfHour`: Travels to the end of the hour.
- `minute`: Travels to a specified minute.
- `shiftMinute`: Travels to previous or next minutes.
- `startOfMinute`: Travels to the start of the minute.
- `endOfMinute`: Travels to the end of the minute.
- `second`: Travels to a specified second.
- `shiftSecond`: Travels to previous or next seconds.

#### String Transformers

- `stringify`: Converts a value to a string.
- `trim`: Trims whitespace from a string.
- `pad`: Pads a string.
- `padStart`: Pads a string at the start.
- `padLeft`: Alias for `padStart`.
- `lpad`: Alias for `padStart`.
- `padEnd`: Pads a string at the end.
- `padRight`: Alias for `padEnd`.
- `rpad`: Alias for `padEnd`.
- `lower`: Converts a string to lowercase.
- `upper`: Converts a string to uppercase.
- `capitalize`: Capitalizes a string.
- `capitalizeAll`: Capitalizes the first letter of each word in a string.
- `camel`: Transform a string to camel case.
- `pascal`: Transform a string to pascal case.
- `snake`: Transform a string to snake case.
- `kebab`: Transform a string to kebab case.
- `replace`: Replaces a substring in a string.
- `replaceAll`: Replaces all occurrences of a substring in a string.
- `prefix`: Adds a prefix to a string.
- `postfix`: Adds a postfix to a string.

#### Decimal Transformers

- `toDecimal`: Converts a value to a decimal.
- `toNumber`: Converts a value to a number.
- `toFixed0`: Formats a number to 0 decimal places.
- `toFixed1`: Formats a number to 1 decimal place.
- `toFixed2`: Formats a number to 2 decimal places.
- `toFixed3`: Formats a number to 3 decimal places.
- `toFixed4`: Formats a number to 4 decimal places.
- `toFixed5`: Formats a number to 5 decimal places.
- `toFixed6`: Formats a number to 6 decimal places.
- `toFixed`: General function to format a number to a specified number of decimal places.
- `round`: Rounds a number.
- `roundUp`: Rounds a number up.
- `roundDown`: Rounds a number down.
- `floor`: Floors a number.
- `ceil`: Ceils a number.
- `roundBy`: Rounds a number by a specified value.

### Satisfied with Given Actions

- `test`/`asyncTest`: Checks if a value satisfies a condition.
- `any`/`asyncAny`: Checks if a value satisfies at least one condition.
- `all`/`asyncAll`: Checks if a value satisfies all conditions.
- `prepend`/`asyncPrepend`: Prepends a value if it satisfies a condition.
	- `headWith`/`asyncHeadWith`: Never fail version, with a transformation function given.
- `exchange`/`asyncExchange`: Exchanges the value if it satisfies a condition.
	- `replaceWith`/`asyncReplaceWith`: Never fail version, with a transformation function given.
- `append`/`asyncAppend`: Appends a value if it satisfies a condition.
	- `tailWith`/`asyncTailWith`: Never fail version, with a transformation function given.
- `prependFirst`/`asyncPrependFirst`: Prepends the value from first satisfied condition.
	- `asyncHeadWithFirst`: Never fail version, with a transformation function given.
- `exchangeFirst`/`asyncExchangeFirst`: Exchanges the value from first satisfied condition.
	- `asyncReplaceWithFirst`: Never fail version, with a transformation function given.
- `appendFirst`/`grabFirst`/`withFirst`/`andFirst`/`asyncAppendFirst`/`asyncGrabFirst`/`asyncWithFirst`/`asyncAndFirst`: Appends the value
  from first satisfied condition.
	- `asyncTailWithFirst`: Never fail version, with a transformation function given.
- `prependAll`/`asyncPrependAll`: Prepends the values if they satisfy the conditions.
	- `headWithAll`/`asyncHeadWithAll`: Never fail version, with a transformation function given.
- `exchangeAll`/`asyncExchangeAll`: Exchanges the values from all satisfied conditions.
	- `replaceWithAll`/`asyncReplaceWithAll`: Never fail version, with a transformation function given.
- `appendAll`/`grabAll`/`withAll`/`andAll`/`asyncAppendAll`/`asyncGrabAll`/`asyncWithAll`/`asyncAndAll`: Appends the values from all
  satisfied conditions.
	- `tailWithAll`/`asyncTailWithAll`: Never fail version, with a transformation function given.

### Extendable

Extend the module by adding your own testers and transformers by `extend` function. The module is designed to be easily extensible.

## Default Value

When the value processing chain is not fully satisfied, a default value can be provided as the final return value. Could be configured by
using `orUseDefault`, `useDefault`, `withDefault`, `orElse`, or `else`, as they are all equivalent.

## Consuming the Value

- `value`: Returns the value.
- `promise`: Returns a promise that resolves to the value. Typically used for asynchronous value actions are placed in a chain, or simply
  using promisify can also be applicable.
- `success` and `failure`: Consumes the value by callbacks.
- `ok`: Consumes the boolean return value of the actions, will get `true` when all actions are satisfied, otherwise `false`.

## Examples

```typescript
import {ValueOperator} from '@rainbow-n19/n1';

const x = 'abc';
ValueOperator.of(x).isNotBlank.ok(); // true
ValueOperator.of(x).isNotBlank.success((v) => console.log(v)); // abc
const y = -1;
ValueOperator.from(y).isPositive().orUseDefault(0).value(); // 0
ValueOperator.from(y).isNegative.isInteger.replaceWith((n: number) => n * 10).toNumber.value(); // -10
```

---
_Source: https://npm.io/package/@rainbow-n19/n1 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._