shelving/util/dictionary.js

Toolkit for using data in JavaScript.

import { RequiredError } from "../error/RequiredError.js";
import { ValueError } from "../error/ValueError.js";
import { isIterable } from "./iterate.js";
import { deleteProps, isPlainObject, omitProps, pickProps, setProp, setProps, withProp, withProps } from "./object.js";
/** Is an unknown value a dictionary object? */
export function isDictionary(value) {
    return isPlainObject(value);
}
/** Assert that an unknown value is a dictionary object */
export function assertDictionary(value, caller = assertDictionary) {
    if (!isDictionary(value))
        throw new ValueError("Must be dictionary object", { received: value, caller });
}
/** Convert a possible dictionary into a dictionary. */
export function getDictionary(dict) {
    return isDictionary(dict) ? dict : Object.fromEntries(dict);
}
export function getDictionaryItems(input) {
    return isIterable(input) ? input : Object.entries(input);
}
/** Is an unknown value the key for an own prop of a dictionary. */
export function isDictionaryItem(dict, key) {
    return typeof key === "string" && Object.hasOwn(dict, key);
}
/** Assert that an unknown value is the key for an own prop of a dictionary. */
export function assertDictionaryItem(dict, key, caller = assertDictionaryItem) {
    if (!isDictionaryItem(dict, key))
        throw new RequiredError("Key must exist in dictionary object", { key, dict, caller });
}
/** Get an item in a map or throw `RequiredError` if it doesn't exist. */
export function requireDictionaryItem(dict, key, caller = requireDictionaryItem) {
    assertDictionaryItem(dict, key, caller);
    return dict[key];
}
/** Get an item in a map or `undefined` if it doesn't exist. */
export function getDictionaryItem(dict, key) {
    return dict[key];
}
/** Set a prop on a dictionary object (immutably) and return a new object including that prop. */
export const withDictionaryItem = withProp;
/** Set several props on a dictionary object (immutably) and return a new object including those props. */
export const withDictionaryItems = withProps;
/** Remove several key/value entries from a dictionary object (immutably) and return a new object without those props. */
export const omitDictionaryItems = omitProps;
/** Remove a key/value entry from a dictionary object (immutably) and return a new object without that prop. */
export const omitDictionaryItem = omitProps;
/** Pick several props from a dictionary object and return a new object with only thos props. */
export const pickDictionaryItems = pickProps;
/** Set a single named prop on a dictionary object (by reference) and return its value. */
export const setDictionaryItem = setProp;
/** Set several named props on a dictionary object (by reference). */
export const setDictionaryItems = setProps;
/** Remove several key/value entries from a dictionary object (by reference). */
export const deleteDictionaryItems = deleteProps;
/** Remove a key/value entry from a dictionary object (by reference). */
export const deleteDictionaryItem = deleteProps;
/** An empty dictionary object. */
export const EMPTY_DICTIONARY = { __proto__: null };