Documentation Index
Fetch the complete documentation index at: https://mintlify.com/tinrab/temelj/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The value utilities module provides functions for working with primitive values, deep equality comparison, and value transformations.
Type definitions
Primitive
A JavaScript value that is not an object and has no methods or properties.
type Primitive =
| string
| boolean
| number
| bigint
| symbol
| null
| undefined;
PrimitiveObject
A plain JavaScript object with primitive values.
type PrimitiveObject = { [key: string]: PrimitiveValue };
PrimitiveValue
A primitive value, primitive object, or array of primitive values.
type PrimitiveValue =
| Primitive
| PrimitiveObject
| Array<PrimitiveValue>;
JsonValue
A valid JSON value.
type JsonValue =
| string
| number
| boolean
| null
| JsonObject
| Array<JsonValue>;
JsonObject
A valid JSON object.
type JsonObject = { [key: string]: JsonValue };
Type checking
isValuePrimitive
Checks if a value is a primitive value (not an object).
function isValuePrimitive(value: unknown): value is Primitive
True if the value is a primitive (string, number, boolean, bigint, symbol, null, or undefined)
import { isValuePrimitive } from "@temelj/value";
console.log(isValuePrimitive("hello")); // true
console.log(isValuePrimitive(42)); // true
console.log(isValuePrimitive(true)); // true
console.log(isValuePrimitive(null)); // true
console.log(isValuePrimitive(undefined)); // true
console.log(isValuePrimitive({})); // false
console.log(isValuePrimitive([])); // false
isObjectPrimitive
Checks if a value is a plain object (not a class instance or special object).
function isObjectPrimitive(obj: unknown): obj is PrimitiveObject
True if the value is a plain object literal
import { isObjectPrimitive } from "@temelj/value";
console.log(isObjectPrimitive({ a: 1 })); // true
console.log(isObjectPrimitive({})); // true
console.log(isObjectPrimitive(new Date())); // false
console.log(isObjectPrimitive(new Map())); // false
console.log(isObjectPrimitive([])); // false
console.log(isObjectPrimitive(null)); // false
isObjectDeepPrimitive
Checks if an object and all its nested values are primitive.
function isObjectDeepPrimitive(obj: unknown): obj is PrimitiveObject
True if the object is a plain object and all nested values are primitive
import { isObjectDeepPrimitive } from "@temelj/value";
console.log(isObjectDeepPrimitive({ a: 1, b: "hello" })); // true
console.log(isObjectDeepPrimitive({ a: 1, b: { c: 2 } })); // true
console.log(isObjectDeepPrimitive({ a: 1, b: new Date() })); // false
console.log(isObjectDeepPrimitive({ a: 1, b: { c: new Date() } })); // false
isPrimitiveValue
Checks if a value is a primitive value (including deeply primitive objects).
function isPrimitiveValue(value: unknown): value is PrimitiveValue
True if the value is primitive or a deeply primitive object/array
import { isPrimitiveValue } from "@temelj/value";
console.log(isPrimitiveValue(42)); // true
console.log(isPrimitiveValue("hello")); // true
console.log(isPrimitiveValue({ a: 1, b: "hello" })); // true
console.log(isPrimitiveValue([1, 2, 3])); // true
console.log(isPrimitiveValue(new Date())); // false
Comparison
deepEquals
Compares two values for deep equality.
function deepEquals(a: unknown, b: unknown): boolean
The first value to compare
The second value to compare
True if the values are deeply equal
import { deepEquals } from "@temelj/value";
// Primitive comparison
console.log(deepEquals(42, 42)); // true
console.log(deepEquals("hello", "hello")); // true
// Object comparison
console.log(deepEquals({ a: 1, b: 2 }, { a: 1, b: 2 })); // true
console.log(deepEquals({ a: 1, b: 2 }, { a: 1, b: 3 })); // false
// Nested object comparison
const obj1 = { a: { b: { c: 1 } } };
const obj2 = { a: { b: { c: 1 } } };
console.log(deepEquals(obj1, obj2)); // true
// Array comparison
console.log(deepEquals([1, 2, 3], [1, 2, 3])); // true
console.log(deepEquals([1, 2, 3], [1, 2, 4])); // false
primitivize
Converts a value to a primitive value by transforming Maps, Sets, and custom objects.
function primitivize(value: unknown): PrimitiveValue
The primitive representation of the value
- Maps → Objects (keys converted to strings)
- Sets → Arrays
- Arrays → Arrays with primitivized elements
- Plain objects → Objects with primitivized values
- Primitives → Unchanged
- Other types → Throws error
Example:
import { primitivize } from "@temelj/value";
// Map to object
const map = new Map([["a", 1], ["b", 2]]);
console.log(primitivize(map)); // { a: 1, b: 2 }
// Set to array
const set = new Set([1, 2, 3]);
console.log(primitivize(set)); // [1, 2, 3]
// Nested structures
const nested = {
map: new Map([["x", 10]]),
set: new Set([1, 2]),
array: [new Set(["a", "b"])]
};
console.log(primitivize(nested));
// {
// map: { x: 10 },
// set: [1, 2],
// array: [["a", "b"]]
// }
Record utilities
recordEquals
Compares two records for equality, optionally using a custom comparison function.
function recordEquals<V>(
a: Record<string, V>,
b: Record<string, V>,
compare?: (a: V, b: V) => boolean
): boolean
a
Record<string, V>
required
The first record to compare
b
Record<string, V>
required
The second record to compare
Optional custom comparison function. Defaults to deepEquals.
True if the records have the same keys and equal values
import { recordEquals } from "@temelj/value";
const a = { x: 1, y: 2 };
const b = { x: 1, y: 2 };
const c = { x: 1, y: 3 };
console.log(recordEquals(a, b)); // true
console.log(recordEquals(a, c)); // false
// Custom comparison
const users1 = { alice: { age: 25 }, bob: { age: 30 } };
const users2 = { alice: { age: 25 }, bob: { age: 30 } };
console.log(recordEquals(users1, users2, (a, b) => a.age === b.age)); // true
recordIsEmpty
Checks if a record has no keys.
function recordIsEmpty<V>(value: Record<string, V>): boolean
value
Record<string, V>
required
The record to check
True if the record has no keys
import { recordIsEmpty } from "@temelj/value";
console.log(recordIsEmpty({})); // true
console.log(recordIsEmpty({ a: 1 })); // false
recordMerge
Merges multiple records into a single record using deep merge.
function recordMerge<T>(
values: Partial<T>[],
options?: RecordMergeOptions
): T
Array of records to merge
Optional merge configuration
import { recordMerge } from "@temelj/value";
const defaults = { port: 3000, host: "localhost" };
const userConfig = { port: 8080 };
const envConfig = { debug: true };
const config = recordMerge([defaults, userConfig, envConfig]);
console.log(config);
// { port: 8080, host: "localhost", debug: true }
RecordMergeOptions
Options for record merging.
interface RecordMergeOptions {
clone?: boolean;
arrayMerge?: <T, S>(target: T[], source: S[]) => (T & S)[];
isMergable?: (value: unknown) => boolean;
}
Whether to clone values during merge. Defaults to true.
Custom function for merging arrays
Custom function to determine if a value should be merged
Common use cases
Configuration merging
import { recordMerge } from "@temelj/value";
function loadConfig() {
const defaults = { timeout: 30000, retries: 3 };
const userConfig = JSON.parse(localStorage.getItem("config") || "{}");
return recordMerge([defaults, userConfig]);
}
Deep comparison
import { deepEquals } from "@temelj/value";
function hasChanged(prev: unknown, next: unknown): boolean {
return !deepEquals(prev, next);
}
Serialization preparation
import { primitivize } from "@temelj/value";
function prepareForSerialization(data: unknown) {
const primitive = primitivize(data);
return JSON.stringify(primitive);
}
Type validation
import { isPrimitiveValue } from "@temelj/value";
function validateInput(value: unknown): value is PrimitiveValue {
if (!isPrimitiveValue(value)) {
throw new Error("Input must be a primitive value");
}
return true;
}