# @fgv/ts-utils

> Assorted Typescript Utilities

Latest version **5.0.2** (published 2025-12-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install @fgv/ts-utils
pnpm add @fgv/ts-utils
yarn add @fgv/ts-utils
bun add @fgv/ts-utils
```

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.0.2 |
| Published | 2025-12-17 |
| First published | 2020-07-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 996.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Author | Erik Fortune |
| Maintainers | efortune |
| Keywords | typescript, json |

## Links

- npm: https://www.npmjs.com/package/@fgv/ts-utils
- Repository: https://github.com/ErikFortune/fgv
- Homepage: https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#readme
- Issues: https://github.com/ErikFortune/fgv/issues
- npm.io page: https://npm.io/package/@fgv/ts-utils

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 5.0.2 (latest) — 2025-12-17
- 5.1.0-55 (alpha) — 2026-08-24
- 5.1.0-54 — 2026-08-23
- 5.1.0-53 — 2026-08-22
- 5.1.0-52 — 2026-08-22
- 5.1.0-51 — 2026-08-18
- 5.1.0-50 — 2026-08-16
- 5.1.0-49 — 2026-08-14
- 5.1.0-48 — 2026-08-13
- 5.1.0-47 — 2026-08-07
- 5.1.0-46 — 2026-08-01
- 5.1.0-45 — 2026-07-28
- 5.1.0-44 — 2026-07-27
- 5.1.0-43 — 2026-07-20
- 5.1.0-42 — 2026-07-16
- … 185 more at https://npm.io/package/@fgv/ts-utils/versions

## README

<div align="center">
  <h1>ts-utils</h1>
  Assorted Typescript Utilities
</div>

<hr/>

## Summary

Assorted typescript utilities that I'm tired of copying from project to project. Most notable and closest to production-ready are:
* Result\<T\> - Easily combine inline and exception-based error handling
* Converter\<T\> - Conversion framework especially useful for type-safe processing of JSON

---

- [Summary](#summary)
- [Installation](#installation)
- [API Documentation](#api-documentation)
- [Overview](#overview)
  - [The Result Pattern](#the-result-pattern)
  - [Converters](#converters)
- [API](#api)
  - [Result\<T\>](#resultt)
  - [Converter\<T\>](#convertert)

## Installation

With npm:
```sh
npm install @fgv/ts-utils
```

## API Documentation
Extracted API documentation is [here](./docs/ts-utils.md).

## Overview
### The Result Pattern

A Result\<T\> represents the success or failure of executing some operation.  A successful result contains a return *value* of type *T*, while a failure result contains an error message of type *string*.  Taken by itself, the use of Result\<T\> allows for simple inline error handling.

```ts
const result = functionReturningResult();
if (result.isSuccess()) {
    functionAcceptingT(result.value);
}
else {
    console.log(result.error);
}
```

Use *succeed\<T>()* and *fail\<T\>()* to return success or failure:

```ts
function thisFunctionSucceeds(): string {
    return succeed('I succeeded!');
}

function thisFunctionFails(): number {
    return fail('Oops!  I failed');
}
```

Use *orDefault* when a failure can be safely ignored:
```ts
// returns undefined on failure
const value1: string|undefined = functionReturningResult('whatever').orDefault();

// returns 'oops' on failure
const value2: string = functionReturningResult('whatever').orDefault('oops');
```

The *orThrow* method converts a failure result to an exception, for use in contexts (such as constructors) in which an exception is the most appropriate way to handle errors.

```ts
constructor(param: string) {
    this._param = validateReturnsResult(param).orThrow();
}
```

The *captureResult* function converts an exception to a failure for simplified inline processing.

```ts
class Thing {
    static create(param: string): Result<Thing> {
        return captureResult(new Thing(param));
    }
}
```

Other methods and helpers allow for chaining and conversion of results, working with mulitple results and more.  See the [API documentation](#resultt) for details.

### Converters

The basic *Converter\<T\>* implements a *convert* method which converts *unknown* to *T*, using the result pattern to report success or failure.

```ts
class Converter<T> {
    public convert(from: unknown): Result<T>;
}
```

But built-in converters, including converters which can extract a field for an object or which apply converters according to the shape of some object can be composed to provide compact and legible type-safe conversion from anything to a strongly typed Typescript object:

```ts
interface Thing {
    title: string;
    count: number;
    isGood: boolean;
    hints: string[];
}

const thingConverter = Converters.object<Thing>({
    title: Converters.string,
    count: Converters.number,
    isGood: Converters.boolean,
    hints: Converters.array(Converters.string),
});

// gets a Thing or throws an error
const thing: Things = thingConverter.convert(json).orThrow();
```

Everything is strongly-typed, so Intellisense will autocomplete properties and highlight errors in the object supplied to *Converters.object*.

Other helpers and methods enable optional values or fields, chaining of results and a variety of other conversions and transformations.

## API

### Result\<T\>

### Converter\<T\>

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