feat: add @discordjs/util (#8591)

* feat: add @discordjs/util

* fix: builders test

* refactor: make rest use lazy for ESM import

* chore: make requested changes

* Apply suggestions from code review

Co-authored-by: Parbez <imranbarbhuiya.fsd@gmail.com>
Co-authored-by: A. Román <kyradiscord@gmail.com>

* chore: make requested changes and add tests

* chore: regen lockfile

* test: add type tests

* chore: push missing files

* chore: make requested changes

* chore: update CI stuff

* chore: fix lockfile

* chore: make requested changes

Co-authored-by: Parbez <imranbarbhuiya.fsd@gmail.com>
Co-authored-by: A. Román <kyradiscord@gmail.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

packages/util/__tests__/Equatable.test.ts

@@ -0,0 +1,18 @@
+import { describe, test, expect } from 'vitest';
+import { isEquatable } from '../src/index.js';
+
+describe('isEquatable', () => {
+	test('returns true if the object is equatable', () => {
+		expect(isEquatable({ equals: () => true })).toBeTruthy();
+	});
+
+	test('returns false if the object is not equatable', () => {
+		expect(isEquatable({})).toBeFalsy();
+		expect(isEquatable(null)).toBeFalsy();
+		expect(isEquatable(undefined)).toBeFalsy();
+		expect(isEquatable(1)).toBeFalsy();
+		expect(isEquatable('')).toBeFalsy();
+		expect(isEquatable([])).toBeFalsy();
+		expect(isEquatable(() => {})).toBeFalsy();
+	});
+});

packages/util/__tests__/JSONEncodable.test.ts

@@ -0,0 +1,25 @@
+import { describe, test, expect } from 'vitest';
+import { isJSONEncodable, type JSONEncodable } from '../src/index.js';
+
+class Encodable implements JSONEncodable<{}> {
+	public toJSON() {
+		return {};
+	}
+}
+
+describe('isJSONEncodable', () => {
+	test('returns true if the object is JSON encodable', () => {
+		expect(isJSONEncodable({ toJSON: () => ({}) })).toBeTruthy();
+		expect(isJSONEncodable(new Encodable())).toBeTruthy();
+	});
+
+	test('returns false if the object is not JSON encodable', () => {
+		expect(isJSONEncodable({})).toBeFalsy();
+		expect(isJSONEncodable(null)).toBeFalsy();
+		expect(isJSONEncodable(undefined)).toBeFalsy();
+		expect(isJSONEncodable(1)).toBeFalsy();
+		expect(isJSONEncodable('')).toBeFalsy();
+		expect(isJSONEncodable([])).toBeFalsy();
+		expect(isJSONEncodable(() => {})).toBeFalsy();
+	});
+});

packages/util/__tests__/lazy.test.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright 2020 The Sapphire Community and its contributors
+ *
+ * Use of this source code is governed by an MIT-style
+ * license that can be found in the LICENSE file or at
+ * https://github.com/sapphiredev/utilities/blob/main/LICENSE.md.
+ */
+
+import { describe, test, expect, vi } from 'vitest';
+import { lazy } from '../src/index.js';
+
+describe('lazy', () => {
+	test('GIVEN string callback THEN returns the same', () => {
+		const callback = vi.fn(() => 'Lorem Ipsum');
+
+		const lazyStoredValue = lazy(callback);
+
+		expect(lazyStoredValue()).toEqual('Lorem Ipsum');
+	});
+
+	test('GIVEN string callback with cached value THEN returns the same', () => {
+		const callback = vi.fn(() => 'Lorem Ipsum');
+
+		const lazyStoredValue = lazy(callback);
+
+		lazyStoredValue();
+		const cachedValue = lazyStoredValue();
+
+		expect(callback).toHaveBeenCalledOnce();
+		expect(cachedValue).toEqual('Lorem Ipsum');
+	});
+});

packages/util/__tests__/range.test.ts

@@ -0,0 +1,12 @@
+import { describe, test, expect } from 'vitest';
+import { range } from '../src/index.js';
+
+describe('range', () => {
+	test('GIVEN valid range THEN valid array is returned', () => {
+		expect(range(0, 5)).toEqual([0, 1, 2, 3, 4, 5]);
+	});
+
+	test('GIVEN valid range with step THEN valid array is returned', () => {
+		expect(range(0, 10, 2)).toEqual([0, 2, 4, 6, 8, 10]);
+	});
+});

packages/util/__tests__/types/Equatable.test-d.ts

@@ -0,0 +1,10 @@
+import { expectType } from 'tsd';
+import type { Equatable } from '../../dist';
+import { isEquatable } from '../../src/index.js';
+
+declare const unknownObj: unknown;
+
+if (isEquatable(unknownObj)) {
+	expectType<Equatable<unknown>>(unknownObj);
+	expectType<boolean>(unknownObj.equals(unknownObj));
+}

packages/util/__tests__/types/JSONEncodable.test-d.ts

@@ -0,0 +1,10 @@
+import { expectType } from 'tsd';
+import type { JSONEncodable } from '../../dist';
+import { isJSONEncodable } from '../../src/index.js';
+
+declare const unknownObj: unknown;
+
+if (isJSONEncodable(unknownObj)) {
+	expectType<JSONEncodable<unknown>>(unknownObj);
+	expectType<unknown>(unknownObj.toJSON());
+}