DOCSEARCHbyAlgolia
Submit Docs

destr

repository·main·Indexed 23 days ago

https://github.com/unjs/destr

A faster, secure, and convenient alternative to JSON.parse. destr handles untrusted input by preventing prototype pollution and providing graceful fallbacks instead of throwing errors. It includes a standard destr function for resilient parsing and a safeDestr function for strict parsing that throws errors on invalid JSON.

Tokens
959
Snippets
3
Records
9
Agent score
76%

What's inside destr

  2. Import destr

    main

    Import destr and safeDestr using ESM or CommonJS depending on your project setup. For Deno, import directly from the Deno land URL.

    // Node.js ESM
import { destr, safeDestr } from "destr";

// Node.js CommonJS
const { destr, safeDestr } = require("destr");

// Deno
import { destr, safeDestr } from "https://deno.land/x/destr/src/index.ts";

  3. Use destr() for safe JSON parsing

    main

    The destr function is a safer and more convenient alternative to JSON.parse. It provides several key benefits:

    • Type Safety: By default, it returns unknown. You can provide a generic type to ensure the output is well-typed.
    • Resilience: It does not throw errors on invalid JSON. Instead, it falls back to the original input (e.g., if you pass a non-string or a plain string that isn't JSON, it returns that value).
    • Built-in Value Lookup: It can quickly resolve known string values like "TRUE" to true.
    • Prototype Pollution Protection: It automatically sanitizes input to prevent prototype pollution attacks.

  4. Use safeDestr() for strict JSON parsing

    main
    If you require strict parsing where invalid JSON must result in an error, use safeDestr. Unlike destr, safeDestr will throw an error if the input is not a valid JSON string or if parsing fails (though non-string values and built-ins are still returned as-is).

  5. Use destr() to parse JSON safely

    main

    The destr() function is used to parse a value (typically a string) into its corresponding JavaScript type. It is designed to be fast and secure against prototype pollution.

    Key behaviors:

    • If the input is not a string, it returns the input as-is.
    • If the input is a quoted string without escapes, it returns the unquoted content.
    • It performs fast lookups for common values like true, false, null, undefined, NaN, and infinity.
    • If parsing fails and options.strict is not enabled, it falls back to returning the original input value.
    • It automatically drops __proto__ and constructor keys to prevent prototype pollution, issuing a warning to the console.

  6. Use safeDestr() for strict parsing

    main

    The safeDestr() function is a wrapper around destr() that enforces strict: true.

    Unlike the standard destr(), which falls back to the original input if parsing fails, safeDestr() will throw an error if the input is not valid JSON or if potential prototype pollution is detected. Use this when you require guaranteed valid JSON output and want to handle parsing errors explicitly.

  7. Import destr in CommonJS

    main
    When using destr in a CommonJS environment, you can require the module directly. The module exports the destr function as the default export, but it also attaches destr and safeDestr as named properties to that function to allow for mixed default and named imports.

  8. Configure destr() with Options

    main

    The destr() and safeDestr() functions accept an optional options object of type Options to control strictness.

    OptionTypeDefaultDescription
    strictbooleanfalseWhen true, destr() will throw a SyntaxError for invalid JSON or an Error for suspected prototype pollution instead of falling back to the original value.
    export type Options = {
  strict?: boolean;
};

  9. Use destr and safeDestr functions

    main

    The library provides two primary functions for safe JSON parsing:

    • destr: Parses a string into a JavaScript object. If parsing fails, it returns the original input.
    • safeDestr: Similar to destr, but specifically designed for safe parsing operations.