RblxObject is a utility library for Roblox-TS (TypeScript for Roblox) that provides robust functions for working with objects, arrays, sets, maps, and tables in a consistent and type-safe manner. This library simplifies common object operations such as it
npm install @rbxts/rblx-object-utilsRblxObject is a utility library for Roblox-TS (TypeScript for Roblox) that provides robust functions for working with objects, arrays, sets, maps, and tables in a consistent and type-safe manner. This library simplifies common object operations such as iteration, deep copying, comparison, and serialization.
RblxObject provides functions that mimic and extend JavaScript's Object methods but are fully compatible with Roblox tables and TypeScript types. It allows developers to safely interact with objects, arrays, sets, and maps without relying on external dependencies like Object.keys() or Object.assign().
bash
npm i @rbxts/rblx-object-utils
`
Installing with bun:
`bash
bun i @rbxts/rblx-object-utils
`
Usage:
`ts
import RblxObject from "@rbxts/rblx-object-utils";
`
---
API Reference
$3
`ts
keys(o: ReadonlyArray): number[];
keys(o: ReadonlySet): T[];
keys(o: ReadonlyMap): K[];
keys(o: object): Array;
`
Returns the keys of an object, array, set, or map.
Example:
`ts
const arr = [10, 20, 30];
const obj = { name: "Alice", age: 25 };
const set = new Set(["x", "y", "z"]);
RblxObject.keys(arr); // [0, 1, 2]
RblxObject.keys(obj); // ["name", "age"]
RblxObject.keys(set); // ["x", "y", "z"]
`
$3
`ts
values(o: ReadonlyArray): Array>;
values(o: ReadonlySet): Array;
values(o: ReadonlyMap): Array>;
values(o: object): Array>;
`
Returns an array of values from an array, set, map, or object.
Example:
`ts
const arr = [10, 20, 30];
const obj = { name: "Alice", age: 25 };
const map = new Map([["id", 1], ["score", 100]]);
RblxObject.values(arr); // [10, 20, 30]
RblxObject.values(obj); // ["Alice", 25]
RblxObject.values(map); // [1, 100]
`
$3
`ts
entries(o: ReadonlyArray): Array<[number, NonNullable]>
entries(o: ReadonlySet): Array<[T, true]>
entries(o: ReadonlyMap): Array<[K, NonNullable]>
entries(o: object): Array<[keyof T, NonNullable]>;
`
Returns key/value pairs of an array, set, map, or object.
Example:
`ts
const obj = { name: "Alice", age: 25 };
RblxObject.entries(obj); // [["name", "Alice"], ["age", 25]]
`
$3
`ts
assign(target: A, ...sources: Array): A & B;
`
Copies enumerable properties from one or more source objects to a target object. Returns the modified target.
Example:
`ts
const target = { a: 1 };
const source = { b: 2, c: 3 };
RblxObject.assign(target, source); // { a: 1, b: 2, c: 3 }
`
$3
`ts
copy(o: T): T;
`
Returns a shallow copy of an object.
Example:
`ts
const original = { x: 10, y: 20 };
const cloned = RblxObject.copy(original);
cloned.x = 50;
// original.x remains 10
`
$3
`ts
deepCopy(o: T): DeepWritable;
`
Returns a deep copy of an object, recursively copying nested tables and arrays.
Example:
`ts
const obj = { a: { b: 10 } };
const clone = RblxObject.deepCopy(obj);
clone.a.b = 20;
// obj.a.b remains 10
`
$3
`ts
deepEquals(a: object, b: object): boolean;
`
Checks if two objects or tables are deeply equal, recursively comparing nested tables.
Example:
`ts
const a = { x: { y: 5 } };
const b = { x: { y: 5 } };
RblxObject.deepEquals(a, b); // true
`
$3
`ts
deepFreeze(object: T): DeepReadonly
`
Deep freezes and returns an original frozen object.
Example:
`ts
const object = {
foo: "foo",
bar: "bar",
tar: {
foo: "oof"
}
}
const frozenObject = RblxObject.deepFreeze(object);
frozenObject.foo = "bar" // Cannot write; foo property is read-only!
frozenObject.tar = { bar: "bar" } // Cannot write; tar property is read-only!
`
$3
`ts
toString(data: unknown): string;
`
Converts a value to a JSON string, or returns [Object: type] if conversion fails.
Example:
`ts
RblxObject.toString({ name: "Alice" }); // '{"name":"Alice"}'
`
$3
`ts
isEmpty(o: object): boolean;
`
Returns true if an object has no enumerable properties, otherwise false.
Example:
`ts
RblxObject.isEmpty({}); // true
RblxObject.isEmpty({ a: 1 }); // false
`
$3
`ts
fromEntries(entries: ReadonlyArray): Record;
`
Creates an object from a list of key/value pairs.
Example:
`ts
const entries: [string, number][] = [["a", 1], ["b", 2]];
const obj = RblxObject.fromEntries(entries); // { a: 1, b: 2 }
`
---
Examples
`ts
import RblxObject from "@rbxts/rblx-object-utils";
// Working with objects
const obj = { name: "Alice", age: 25 };
const keys = RblxObject.keys(obj); // ["name", "age"]
const values = RblxObject.values(obj); // ["Alice", 25]
const entries = RblxObject.entries(obj); // [["name", "Alice"], ["age", 25]]
// Deep copy
const nested = { a: { b: 10 } };
const deepClone = RblxObject.deepCopy(nested);
// Deep freeze
const deepFrozen = RblxObject.deepFreeze(obj);
obj.name = "Mark" // Errors because the property is read only.
// Equality check
const equal = RblxObject.deepEquals({ x: 1 }, { x: 1 }); // true
// From entries
const newObj = RblxObject.fromEntries([["foo", 42]]); // { foo: 42 }
``