DOCSEARCHbyAlgolia
Submit Docs

undio

repository·main·Indexed 42 days ago

https://github.com/unjs/undio

A utility library for conventionally and safely converting between JavaScript data types, including ArrayBuffer, Blob, Base64, Uint8Array, and Streams. Version 0.2.0 provides high-level utilities for auto-detection, type validation via is* and assert* functions, and polymorphic conversion helpers like convertTo(), toText(), and toUint8Array().

Tokens
12.1K
Snippets
55
Records
64
Agent score
50%

What's inside undio

  1. How auto-detection and conversion work

    main

    Undio provides high-level utilities that automatically detect the input type and convert it to the requested target type. This simplifies code when dealing with polymorphic data (e.g., a value that could be a Blob, ArrayBuffer, or Uint8Array).

    Important: Because some conversions involve streams, the returned value may be a Promise. Always use await when calling these utilities.

    Supported types for auto-detection include:

    • ArrayBuffer
    • Base64
    • Blob
    • DataView
    • Number Array
    • ReadableStream
    • NodeStream
    • Response
    • Text
    • Uint8Array
    import { detectType, toText, toReadableStream } from "undio";

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

// Returns: "ArrayBuffer" | "Blob"| "DataView" | "NumberArray" | "ReadableStream" | "String" | "Uint8Array"
const type = detectType(value);

  2. Validate types with is* and assert* utilities

    main

    Undio provides two ways to perform runtime type checking:

    1. is* utilities: Return a boolean (true or false) indicating if the input matches the type.
    2. assert* utilities: Throw a TypeError if the input does not match the type.

    Note: All conversion utilities (like toText) use assertions for runtime type safety by default, so manual validation is often unnecessary before conversion.

    import { isReadableStream, assertArrayBuffer } from "undio";

if (isReadableStream(value)) {
  /* do something safe */
}

assertArrayBuffer(value); // Throws a TypeError if value is not ArrayBuffer
// do something safe

  3. Import undio

    main

    Depending on your environment, use the appropriate import syntax:

    • ESM (Node.js, Bun, Deno)
    • CommonJS (Legacy Node.js)
    • CDN (Deno, Bun, and Browsers)
    // ESM
import {} from "undio";

// CommonJS
const {} = require("undio");

// CDN
import {} from "https://esm.sh/undio";

  4. Install undio

    main

    You can install undio using your preferred package manager. It supports npm, yarn, pnpm, bun, and deno.

    # ✨ Auto-detect
npx nypm install undio

# npm
npm install undio

# yarn
yarn add undio

# pnpm
pnpm install undio

# bun
bun install undio

# deno
deno install undio

  5. Validate Response objects

    main

    Undio provides utilities to check or enforce that a value is a valid Response instance:

    • isResponse(input): Returns true if the input is a Response, otherwise false.
    • assertResponse(input): Returns nothing if the input is a Response, otherwise throws a TypeError.

  6. Validate Strings

    main

    Undio provides utilities to check or enforce that a value is a valid String:

    • isText(input): Returns true if the input is a String, otherwise false.
    • assertText(input): Returns nothing if the input is a String, otherwise throws a TypeError.

  7. Convert Uint8Array to other types

    main

    Use the uint8ArrayTo* family of functions to transform a Uint8Array into various data formats. Supported conversions include:

    • uint8ArrayToArrayBuffer(uint8Array)
    • uint8ArrayToBase64(uint8Array, base64Options?)
    • uint8ArrayToBlob(uint8Array, options?)
    • uint8ArrayToDataView(uint8Array)
    • uint8ArrayToNumberArray(uint8Array)
    • uint8ArrayToReadableStream(uint8Array)
    • uint8ArrayToResponse(uint8Array, init?)
    • uint8ArrayToText(uint8Array)

  8. Convert specific types to Response

    main

    You can create Response objects from several different input types:

    • numberArrayToResponse(numberArray, init?): From a Number Array.
    • readableStreamToResponse(readableStream, init?): From a ReadableStream.
    • textToResponse(string, init?): From a String.
    • uint8ArrayToResponse(uint8Array, init?): From a Uint8Array.

  9. Convert Strings to other types

    main

    Use the textTo* family of functions to transform a String into various data formats. Supported conversions include:

    • textToArrayBuffer(string)
    • textToBase64(string, opts?)
    • textToBlob(string, options?)
    • textToDataView(string)
    • textToNumberArray(string)
    • textToReadableStream(string)
    • textToUint8Array(string)

  10. Validate Uint8Array

    main

    Undio provides utilities to check or enforce that a value is a valid Uint8Array:

    • isUint8Array(input): Returns true if the input is a Uint8Array, otherwise false.
    • assertUint8Array(input): Returns nothing if the input is a Uint8Array, otherwise throws a TypeError.

  11. Convert any value to any supported type

    main

    Undio provides high-level conversion and detection utilities that work across different types:

    • convertTo(toType, input, fromType?): Convert from any value to any supported data type.
    • detectType(input): Detect the type of the provided input.
    • toText(input): Convert any value to a String.
    • toUint8Array(input): Convert any value to a Uint8Array.

  12. Convert Response objects to other types

    main

    Use the responseTo* family of functions to transform a Response instance into various data formats. Supported conversions include:

    • responseToArrayBuffer(response)
    • responseToBase64(response, base64Options?)
    • responseToBlob(response)
    • responseToDataView(response)
    • responseToNumberArray(response)
    • responseToReadableStream(response)
    • responseToText(response)
    • responseToUint8Array(response)