undio

⇔ Conventionally and Safely convert between various JavaScript data types

TypesUtils
unjs/undioundio

README

⇔ undio


⇔ Conventionally and safely convert between various JavaScript data types.

✅ Features


- Type-safe usage
- Runtime-type safety assertion
- Auto type detection and conversion
- Tree-shakable and compact build
- Leverage runtime native performance (+Bun stream utils)

Usage


Install package:


  1. ```sh
  2. # ✨ Auto-detect
  3. npx nypm install undio

  5. # npm
  6. npm install undio

  8. # yarn
  9. yarn add undio

  11. # pnpm
  12. pnpm install undio

  14. # bun
  15. bun install undio
  16. ```


Import:


ESM (Node.js, Bun)

  1. ```js
  2. import {} from "undio";
  3. ```

CommonJS (Legacy Node.js)

  1. ```js
  2. const {} = require("undio");
  3. ```

CDN (Deno, Bun and Browsers)

  1. ```js
  2. import {} from "https://esm.sh/undio";
  3. ```


Auto Convert


Undio automatically detects the input type and uses the proper method to convert it to the expected type.

Example:

  1. ```ts
  2. import { detectType, toText, toReadableStream } from "undio";

  4. // Convert any supported type (auto-detected)
  5. const string = await toText(value);
  6. const stream = await toReadableStream(value);

  8. // "ArrayBuffer" | "Blob"| "DataView" | "NumberArray" | "ReadableStream" | "String" | "Uint8Array";
  9. const type = detectType(value);
  10. ```

[!NOTE]

Because of stream support, the return type can be a promise. Always make sure to use an await before them.


[!NOTE]

Alternatively you can use low-level `To(value)` utils to explicitly convert from one type to another. See all utils section.


Runtime type checking


You can use `is(input) and assert(input)` utils to validate input type.

[!NOTE]

All conversion utilities use assertions for runtime type safety by default, so you don't need to manually do this.


Example:

  1. ```ts
  2. import { isReadableStream, assertArrayBuffer } from "undio";

  4. if (isReadableStream(value)) {
  5.   /* do something */
  6. }

  8. assertArrayBuffer(value); // Throws an error if value is not ArrayBuffer
  9. // do something
  10. ```