npm package: @rbxts/rblx-object-utils
Description: 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
Author: FLOGRE Studio
Latest version: 1.0.3

# 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](#introduction)
* [Installation](#installation)
* [Usage](#usage)
* [API Reference](#api-reference)

  * [keys](#keys)
  * [values](#values)
  * [entries](#entries)
  * [assign](#assign)
  * [copy](#copy)
  * [deepCopy](#deepcopy)
  * [deepEquals](#deepequals)
  * [toString](#tostring)
  * [isEmpty](#isempty)
  * [fromEntries](#fromentries)
* [Examples](#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:

```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

### `keys`

```ts
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:**

```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"]
```

### `values`

```ts
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:**

```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]
```

### `entries`

```ts
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:**

```ts
const obj = { name: "Alice", age: 25 };
RblxObject.entries(obj); // [["name", "Alice"], ["age", 25]]
```

### `assign`

```ts
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:**

```ts
const target = { a: 1 };
const source = { b: 2, c: 3 };
RblxObject.assign(target, source); // { a: 1, b: 2, c: 3 }
```

### `copy`

```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
```

### `deepCopy`

```ts
deepCopy(o: T): DeepWritable<T>;
```

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
```

### `deepEquals`

```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
```

### `deepFreeze`

```ts
deepFreeze(object: T): DeepReadonly<T>
```

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!
```

### `toString`

```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"}'
```

### `isEmpty`

```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
```

### `fromEntries`

```ts
fromEntries<K extends PropertyKey, V>(entries: ReadonlyArray<readonly [K, V]>): Record<K, V>;
```

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 }
```