RblxObject

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 iteration, deep copying, comparison, and serialization.

Table of Contents

• Introduction

• Installation

• Usage

• API Reference

  • keys
  • values
  • entries
  • assign
  • copy
  • deepCopy
  • deepEquals
  • toString
  • isEmpty
  • fromEntries

• Examples

Introduction

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().

Key features:

• Type-safe operations on objects and tables
• Shallow and deep copy utilities
• Deep equality comparison
• Conversion between entries and objects
• JSON serialization compatible with Roblox

Installation

Installing with Npm:

npm i @rbxts/rblx-object-utils

Installing with bun:

bun i @rbxts/rblx-object-utils

Usage:

import RblxObject from "@rbxts/rblx-object-utils";

API Reference

keys

keys(o: ReadonlyArray<T>): number[];
keys(o: ReadonlySet<T>): T[];
keys(o: ReadonlyMap<K, V>): K[];
keys(o: object): Array<keyof typeof o>;

Returns the keys of an object, array, set, or map.

Example:

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"]

values

values(o: ReadonlyArray<T>): Array<NonNullable<T>>;
values(o: ReadonlySet<T>): Array<true>;
values(o: ReadonlyMap<K, V>): Array<NonNullable<V>>;
values(o: object): Array<NonNullable<T[keyof T]>>;

Returns an array of values from an array, set, map, or object.

Example:

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]

entries

entries(o: ReadonlyArray<T>): Array<[number, NonNullable<T>]>
entries(o: ReadonlySet<T>): Array<[T, true]>
entries(o: ReadonlyMap<K, V>): Array<[K, NonNullable<V>]>
entries(o: object): Array<[keyof T, NonNullable<T[keyof T]>]>;

Returns key/value pairs of an array, set, map, or object.

Example:

const obj = { name: "Alice", age: 25 };
RblxObject.entries(obj); // [["name", "Alice"], ["age", 25]]

assign

assign(target: A, ...sources: Array<B>): A & B;

Copies enumerable properties from one or more source objects to a target object. Returns the modified target.

Example:

const target = { a: 1 };
const source = { b: 2, c: 3 };
RblxObject.assign(target, source); // { a: 1, b: 2, c: 3 }

copy

copy(o: T): T;

Returns a shallow copy of an object.

Example:

const original = { x: 10, y: 20 };
const cloned = RblxObject.copy(original);
cloned.x = 50;
// original.x remains 10

deepCopy

deepCopy(o: T): DeepWritable<T>;

Returns a deep copy of an object, recursively copying nested tables and arrays.

Example:

const obj = { a: { b: 10 } };
const clone = RblxObject.deepCopy(obj);
clone.a.b = 20;
// obj.a.b remains 10

deepEquals

deepEquals(a: object, b: object): boolean;

Checks if two objects or tables are deeply equal, recursively comparing nested tables.

Example:

const a = { x: { y: 5 } };
const b = { x: { y: 5 } };
RblxObject.deepEquals(a, b); // true

deepFreeze

deepFreeze(object: T): DeepReadonly<T>

Deep freezes and returns an original frozen object.

Example:

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!

toString

toString(data: unknown): string;

Converts a value to a JSON string, or returns [Object: type] if conversion fails.

Example:

RblxObject.toString({ name: "Alice" }); // '{"name":"Alice"}'

isEmpty

isEmpty(o: object): boolean;

Returns true if an object has no enumerable properties, otherwise false.

Example:

RblxObject.isEmpty({}); // true
RblxObject.isEmpty({ a: 1 }); // false

fromEntries

fromEntries<K extends PropertyKey, V>(entries: ReadonlyArray<readonly [K, V]>): Record<K, V>;

Creates an object from a list of key/value pairs.

Example:

const entries: [string, number][] = [["a", 1], ["b", 2]];
const obj = RblxObject.fromEntries(entries); // { a: 1, b: 2 }

Examples

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 }