# @opi_pib/ts-utility

> Typescript utility

Latest version **2.3.2** (published 2025-11-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @opi_pib/ts-utility
pnpm add @opi_pib/ts-utility
yarn add @opi_pib/ts-utility
bun add @opi_pib/ts-utility
```

## Health

**Score 65/100 (B)** — status: stable.

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.3.2 |
| Published | 2025-11-04 |
| First published | 2022-09-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 2 |
| Unpacked size | 26.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Author | Dawid Lubowiecki |
| Maintainers | national-information-processing-institute-opi-pib, dlubowiecki, mpaduszynski |
| Keywords | utility, helpers, ddd, value object, entity, type maybe |

## Links

- npm: https://www.npmjs.com/package/@opi_pib/ts-utility
- Repository: https://github.com/OPI-PIB/ts-utility
- Homepage: https://github.com/OPI-PIB/ts-utility#readme
- Issues: https://github.com/OPI-PIB/ts-utility/issues
- npm.io page: https://npm.io/package/@opi_pib/ts-utility

## Dependencies (2)

- [ramda](https://npm.io/package/ramda.md) ^0.31.0
- [typescript](https://npm.io/package/typescript.md) ^5.0.0

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 2.3.2 (latest) — 2025-11-04
- 2.3.1 — 2025-11-03
- 2.3.0 — 2025-11-03
- 2.2.0 — 2025-06-24
- 2.1.0 — 2024-11-29
- 2.0.1 — 2024-09-25
- 2.0.0 — 2024-09-25
- 1.2.2 — 2024-08-23
- 1.2.1 — 2024-06-25
- 1.2.0 — 2024-06-24
- 1.1.16 — 2024-05-06
- 1.1.15 — 2024-05-06
- 1.1.14 — 2024-02-26
- 1.1.13 — 2023-11-14
- 1.1.12 — 2023-10-20
- … 16 more at https://npm.io/package/@opi_pib/ts-utility/versions

## README

# @opi_pib/ts-utility

- [Install](#install)
- [Assert](#assert)
  - [Usage](#usage)
    - [TypeScript](#typescript)
- [Logic](#logic)
  - [Is](#is)
- [Models](#models)
  - [Entity](#entity)
  - [Value object](#value-object)
- [Types](#types)
  - [Maybe<T>](#maybet)
- [Utils](#utils)
  - [stripHtml](#striphtml)

## Install

```
npm install @opi_pib/ts-utility
```

## Assert

### Usage

```typescript
function add(x, y) {
	always(typeof x === 'number', "Argument 'x' has to be a number.");
	always(typeof y === 'number', "Argument 'y' has to be a number.");
	return x + y;
}
```

always() function throw an Error if the condition is false:

```typescript
always(1 > 0); // ok
always(1 < 0); // throws Error
```

never() does the same but in reverse:

```typescript
never(1 > 0); // throws Error
never(1 < 0); // ok
```

#### TypeScript

function always() are typed to assert that the condition you pass them are true, which gives you certainty that your variable is of a given type at runtime.

```typescript
export declare function always(condition: boolean, code: string): asserts condition;
```

```typescript
const x: unknown = someUntypedFunction();
always(typeof x === 'string');
const y = x.toUpperCase(); // TypeScript knows that x must be a string, your IDE can suggest toUpperCase() method
```

## Logic

### Is

Static methods of this class will check type of provided value

### Is.defined

```typescript
Is.defined('123'); // true
Is.defined(null); // false
Is.defined(undefined); // false
```

### Is.function

Checks if value is function

```typescript
Is.function(() => {}); // true
Is.function(''); // false
Is.function(new Promise(() => '')); // false
```

### Is.instanceOf

Checks if value is instance of value

```typescript
class TestClass {}
Is.InstanceOf(TestClass, new TestClass()); // true
Is.InstanceOf(TestClass, 1); // false
```

### Is.object

Checks if value is object

```typescript
Is.object({}); // true
Is.object([]); // false
Is.object(() => {}); // false
Is.object(new Promise(() => '')); // false
```

### Is.promise

Checks if value is promise

```typescript
Is.promise({}); // false
Is.promise(new Promise(() => '')); // true
```

### Is.url

Checks if value is valid url

```typescript
Is.url('www.google.com'); // false
Is.url('https://google.com'); // true
```

### Other types

Checks if provided value is of provided type

```typescript
Is.date(new Date()); // true
Is.boolean(true); // true
Is.string(''); // true
Is.null(null); // true
Is.regexp(/someRegularExpression/i); // true
Is.regexp(new RegExp('someRegularExpression', 'i')); // true
Is.array([]); // true
Is.number(0); // true
Is.number(NaN); // true
Is.number(Infinity); // true
```

## Models

### Entity

Entities are objects that we determine their equality through their identifier.

Example:

```typescript
interface IdProps {
	id: string;
}

class Id extends ValueObject<IdProps> {
	private constructor(protected readonly props: IdProps) {
		super(props);
	}

	static create(id: string): Id {
		return new Id({ id });
	}
}

interface TestedEntityDto {
	id: Id;
	value: string;
}

interface TestedEntityProps {
	id: Id;
	value: string;
}

class TestedEntity extends Entity<TestedEntityProps> {
	private constructor(protected readonly props: TestedEntityProps) {
		super(props);
	}

	static create(testedEntityDto: TestedEntityDto): TestedEntity {
		return new TestedEntity(testedEntityDto);
	}
}

it('should equals by id', () => {
	const id1 = Id.create('123');
	const id2 = Id.create('123');
	const a = TestedEntity.create({ id: id1, value: 'example1' });
	const b = TestedEntity.create({ id: id2, value: 'example2' });

	expect(a.equals(b)).toBe(true);
});

it('should not equal if id1 not equals id2', () => {
	const id1 = Id.create('123');
	const id2 = Id.create('1234');
	const a = TestedEntity.create({ id: id1, value: 'example' });
	const b = TestedEntity.create({ id: id2, value: 'example' });

	expect(a.equals(b)).toBe(false);
});
```

### Value object

ValueObjects are objects that we determine their equality through their structrual property.

Example:

```typescript
interface TestedValueObjectProps {
	name: string;
	city: {
		name: string;
	};
}

class TestedValueObject extends ValueObject<TestedValueObjectProps> {
	private constructor(protected readonly props: TestedValueObjectProps) {
		super(props);
	}

	static create(name: string, cityName: string): TestedValueObject {
		return new TestedValueObject({ name, city: { name: cityName } });
	}
}

it('should equals by structure', () => {
	const a = TestedValueObject.create('name', 'cityName');
	const b = TestedValueObject.create('name', 'cityName');

	expect(a.equals(b)).toBe(true);
});

it('should not equals if structure is different', () => {
	const a = TestedValueObject.create('name', 'cityName1');
	const b = TestedValueObject.create('name', 'cityName2');

	expect(a.equals(b)).toBe(false);
});
```

## Types

### Maybe<T>

Marks value as nullable, it can be T, undefined, null.
It forces null check on every usage of value.

```typescript
interface Example {
	a: string;
	b?: Maybe<string>;
}

const obj: Example = {
	a: 'string',
	b: 'maybeString'
};

const { a, b } = obj;

a.length; // Ok
b.length; // Error, b can be undefined

if (b != null) {
	b.length; // Ok
}
```

## Utils

### stripHtml

Removes HTML tags from string

```typescript
stripHtml('<h1>Title</h1> <p>content</p><img src="">'); // 'Title content'
```

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