Class ObjectParser

The ObjectParser is a specialized parser designed to safely access and validate values within a plain JavaScript object. It provides type-safe methods for retrieving values of various types (strings, numbers, arrays, etc.), ensuring that required fields are present and correctly typed.

This parser is useful in scenarios where you need to interact with complex objects and ensure the presence and type correctness of specific keys, such as when dealing with parsed JSON or other data structures.

Usage

ObjectParser wraps a generic object and provides methods to:

  • Check if a key exists (has).
  • Retrieve values of specific types (string, number, array, etc.).
  • Handle complex nested objects by returning new ObjectParser instances.
  • Validate the type or instance of an object field.

It also throws custom errors (MissingKeyError, InvalidTypeError, InvalidInstanceOfError) to handle validation issues, making debugging easier.

How It Works

  • Methods like string, number, and array enforce the type correctness of the retrieved values.
  • For nested objects, the object method returns a new ObjectParser instance, allowing safe and structured access to deeply nested data.
  • The instanceOf method ensures that an object is an instance of the specified constructor, which is useful for retrieving specific types like Date.

Example

let data = {
  username: "John",
  age: 30,
  active: true,
  metadata: { role: "admin" }
};
let parser = new ObjectParser(data);

parser.string("username"); // "John"
parser.number("age"); // 30
parser.getBoolean("active"); // true
parser.object("metadata").string("role"); // "admin"

Hierarchy (View Summary)

Constructors

constructor

Properties

value

Methods

array bigint boolean date function get has instanceOf isNull isUndefined number object set string symbol typeOf valueOf

Constructors

constructor

Properties

Protectedvalue

value: object

Methods

array

  • array(key: Key): any[]

    Retrieves the value associated with the key as an array.

    Parameters

    • key: Key

      The key to retrieve the array for.

    Returns any[]

    The array value.

    Throws

    If the value is not an array.

bigint

  • bigint(key: Key): bigint

    Retrieves the value associated with the key as a bigint.

    Parameters

    • key: Key

      The key to retrieve the bigint value for.

    Returns bigint

    The bigint value.

    Throws

    If the value is not a bigint.

boolean

  • boolean(key: Key): boolean

    Retrieves the value associated with the key as a boolean.

    Parameters

    • key: Key

      The key to retrieve the boolean value for.

    Returns boolean

    The boolean value.

    Throws

    If the value is not a boolean.

date

  • date(key: Key): Date

    Retrieves the value associated with the key as a Date object.

    Parameters

    • key: Key

      The key to retrieve the Date for.

    Returns Date

    The Date value.

    Throws

    If the value is not a Date instance.

function

  • function(key: Key): Function

    Retrieves the value associated with the key as a function.

    Parameters

    • key: Key

      The key to retrieve the function for.

    Returns Function

    The function value.

    Throws

    If the value is not a function.

get

  • get<O = unknown>(key: Key): O

    Retrieves the value associated with the specified key.

    Type Parameters

    • O = unknown

    Parameters

    • key: Key

      The key to retrieve the value for.

    Returns O

    The value associated with the key.

    Throws

    If the key is missing.

has

  • has(key: Key): boolean

    Checks if the given key exists in the object.

    Parameters

    • key: Key

      The key to check.

    Returns boolean

    true if the key exists, otherwise false.

instanceOf

  • instanceOf<I>(key: Key, ctor: new (...args: any[]) => I): I

    Access a value from the object as an instance of the provided constructor.

    Type Parameters

    • I

    Parameters

    • key: Key

      The key to retrieve the instance for.

    • ctor: new (...args: any[]) => I

      The constructor function to check the instance against.

    Returns I

    The value as an instance of the provided constructor.

    Throws

    If the value is not an instance of the provided constructor.

isNull

  • isNull(key: Key): boolean

    Checks if the value associated with the key is null.

    Parameters

    • key: Key

      The key to check.

    Returns boolean

    true if the value is null, otherwise false.

isUndefined

  • isUndefined(key: Key): boolean

    Checks if the value associated with the key is undefined.

    Parameters

    • key: Key

      The key to check.

    Returns boolean

    true if the value is undefined, otherwise false.

number

  • number(key: Key): number

    Retrieves the value associated with the key as a number.

    Parameters

    • key: Key

      The key to retrieve the number value for.

    Returns number

    The number value.

    Throws

    If the value is not a number.

object

  • object(key: Key): ObjectParser

    Retrieves the value associated with the key as an ObjectParser for nested object access.

    Parameters

    • key: Key

      The key to retrieve the object value for.

    Returns ObjectParser

    A new ObjectParser instance for the nested object.

    Throws

    If the value is not an object.

set

  • set<O = unknown>(key: Key, value: O): void

    Sets the value associated with the specified key.

    If the key does not exist, it will be created.

    Type Parameters

    • O = unknown

    Parameters

    • key: Key

      The key to set the value for.

    • value: O

      The value to set.

    Returns void

    Example

    parser.set("username", "johndoe");

string

  • string(key: Key): string

    Retrieves the value associated with the key as a string.

    Parameters

    • key: Key

      The key to retrieve the string value for.

    Returns string

    The string value.

    Throws

    If the value is not a string.

symbol

  • symbol(key: Key): symbol

    Retrieves the value associated with the key as a symbol.

    Parameters

    • key: Key

      The key to retrieve the symbol for.

    Returns symbol

    The symbol value.

    Throws

    If the value is not a symbol.

typeOf

  • typeOf(
        key: Key,
    ):
        | "string"
        | "number"
        | "bigint"
        | "boolean"
        | "symbol"
        | "undefined"
        | "object"
        | "function"

    Retrieves the type of the value associated with the specified key.

    Parameters

    • key: Key

      The key to check the type for.

    Returns
        | "string"
        | "number"
        | "bigint"
        | "boolean"
        | "symbol"
        | "undefined"
        | "object"
        | "function"

    The type of the value as a string (e.g., "string", "number").

valueOf

Settings

Member Visibility

On This Page

UsageHow It Works
Constructors
Properties
Methods