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>

.github/labeler.yml

@@ -37,3 +37,7 @@
 'packages:ws':
   - packages/ws/*
   - packages/ws/**/*
+
+'packages:util':
+  - packages/util/*
+  - packages/util/**/*

.github/labels.yml

@@ -66,6 +66,8 @@
   color: 'fbca04'
 - name: 'packages:ws'
   color: 'fbca04'
+- name: 'packages:util'
+  color: 'fbca04'
 - name: 'performance'
   color: '80c042'
 - name: 'permissions'

packages/actions/src/uploadCoverage/action.yml

@@ -51,6 +51,12 @@ runs:
         files: ./packages/ws/coverage/cobertura-coverage.xml
         flags: ws
 
+    - name: Upload Util Coverage
+      uses: codecov/codecov-action@v3
+      with:
+        files: ./packages/util/coverage/cobertura-coverage.xml
+        flags: util
+
     - name: Upload Utilities Coverage
       uses: codecov/codecov-action@v3
       with:

packages/builders/__tests__/util.test.ts

@@ -1,33 +1,5 @@
 import { describe, test, expect } from 'vitest';
-import {
-	isJSONEncodable,
-	isEquatable,
-	ActionRowBuilder,
-	enableValidators,
-	disableValidators,
-	isValidationEnabled,
-} 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();
-	});
-});
-
-describe('isJSONEncodable', () => {
-	test('returns true if the object is JSON encodable', () => {
-		expect(isJSONEncodable({ toJSON: () => ({}) })).toBeTruthy();
-		expect(isJSONEncodable(new ActionRowBuilder())).toBeTruthy();
-	});
-
-	test('returns false if the object is not JSON encodable', () => {
-		expect(isJSONEncodable({})).toBeFalsy();
-	});
-});
+import { enableValidators, disableValidators, isValidationEnabled } from '../src/index.js';
 
 describe('validation', () => {
 	test('enables validation', () => {

packages/builders/package.json

@@ -54,6 +54,7 @@
 	},
 	"homepage": "https://discord.js.org",
 	"dependencies": {
+		"@discordjs/util": "workspace:^",
 		"@sapphire/shapeshift": "^3.6.0",
 		"discord-api-types": "^0.37.11",
 		"fast-deep-equal": "^3.1.3",

packages/builders/src/components/Component.ts

@@ -1,10 +1,10 @@
+import type { JSONEncodable } from '@discordjs/util';
 import type {
 	APIActionRowComponent,
 	APIActionRowComponentTypes,
 	APIBaseComponent,
 	ComponentType,
 } from 'discord-api-types/v10';
-import type { JSONEncodable } from '../util/jsonEncodable';
 
 export type AnyAPIActionRowComponent = APIActionRowComponent<APIActionRowComponentTypes> | APIActionRowComponentTypes;
 

packages/builders/src/components/selectMenu/SelectMenuOption.ts

@@ -1,5 +1,5 @@
+import type { JSONEncodable } from '@discordjs/util';
 import type { APIMessageComponentEmoji, APISelectMenuOption } from 'discord-api-types/v10';
-import type { JSONEncodable } from '../../util/jsonEncodable.js';
 import {
 	defaultValidator,
 	emojiValidator,

packages/builders/src/components/textInput/TextInput.ts

@@ -1,7 +1,6 @@
+import { isJSONEncodable, type Equatable, type JSONEncodable } from '@discordjs/util';
 import { ComponentType, type TextInputStyle, type APITextInputComponent } from 'discord-api-types/v10';
 import isEqual from 'fast-deep-equal';
-import type { Equatable } from '../../util/equatable';
-import { isJSONEncodable, type JSONEncodable } from '../../util/jsonEncodable.js';
 import { customIdValidator } from '../Assertions.js';
 import { ComponentBuilder } from '../Component.js';
 import {

packages/builders/src/index.ts

@@ -36,8 +36,7 @@ export * from './interactions/slashCommands/mixins/SharedSlashCommandOptions.js'
 export * as ContextMenuCommandAssertions from './interactions/contextMenuCommands/Assertions.js';
 export * from './interactions/contextMenuCommands/ContextMenuCommandBuilder.js';
 
-export * from './util/jsonEncodable.js';
-export * from './util/equatable.js';
 export * from './util/componentUtil.js';
 export * from './util/normalizeArray.js';
 export * from './util/validation.js';
+export * from '@discordjs/util';

packages/builders/src/interactions/modals/Modal.ts

@@ -1,3 +1,4 @@
+import type { JSONEncodable } from '@discordjs/util';
 import type {
 	APIActionRowComponent,
 	APIModalActionRowComponent,
@@ -6,7 +7,6 @@ import type {
 import { ActionRowBuilder, type ModalActionRowComponentBuilder } from '../../components/ActionRow.js';
 import { customIdValidator } from '../../components/Assertions.js';
 import { createComponentBuilder } from '../../components/Components.js';
-import type { JSONEncodable } from '../../util/jsonEncodable';
 import { normalizeArray, type RestOrArray } from '../../util/normalizeArray.js';
 import { titleValidator, validateRequiredParameters } from './Assertions.js';
 

packages/discord.js/package.json

@@ -52,6 +52,7 @@
     "@discordjs/builders": "workspace:^",
     "@discordjs/collection": "workspace:^",
     "@discordjs/rest": "workspace:^",
+    "@discordjs/util": "workspace:^",
     "@sapphire/snowflake": "^3.2.2",
     "@types/ws": "^8.5.3",
     "discord-api-types": "^0.37.11",

packages/discord.js/src/structures/ContextMenuCommandInteraction.js

@@ -1,9 +1,9 @@
 'use strict';
 
+const { lazy } = require('@discordjs/util');
 const { ApplicationCommandOptionType } = require('discord-api-types/v10');
 const CommandInteraction = require('./CommandInteraction');
 const CommandInteractionOptionResolver = require('./CommandInteractionOptionResolver');
-const { lazy } = require('../util/Util');
 
 const getMessage = lazy(() => require('./Message').Message);
 

packages/discord.js/src/structures/MessageComponentInteraction.js

@@ -1,9 +1,9 @@
 'use strict';
 
+const { lazy } = require('@discordjs/util');
 const BaseInteraction = require('./BaseInteraction');
 const InteractionWebhook = require('./InteractionWebhook');
 const InteractionResponses = require('./interfaces/InteractionResponses');
-const { lazy } = require('../util/Util');
 
 const getMessage = lazy(() => require('./Message').Message);
 

packages/discord.js/src/structures/MessagePayload.js

@@ -2,12 +2,13 @@
 
 const { Buffer } = require('node:buffer');
 const { isJSONEncodable } = require('@discordjs/builders');
+const { lazy } = require('@discordjs/util');
 const { MessageFlags } = require('discord-api-types/v10');
 const ActionRowBuilder = require('./ActionRowBuilder');
 const { RangeError, ErrorCodes } = require('../errors');
 const DataResolver = require('../util/DataResolver');
 const MessageFlagsBitField = require('../util/MessageFlagsBitField');
-const { basename, verifyString, lazy } = require('../util/Util');
+const { basename, verifyString } = require('../util/Util');
 
 const getBaseInteraction = lazy(() => require('./BaseInteraction'));
 

packages/discord.js/src/structures/ModalSubmitInteraction.js

@@ -1,10 +1,10 @@
 'use strict';
 
+const { lazy } = require('@discordjs/util');
 const BaseInteraction = require('./BaseInteraction');
 const InteractionWebhook = require('./InteractionWebhook');
 const ModalSubmitFields = require('./ModalSubmitFields');
 const InteractionResponses = require('./interfaces/InteractionResponses');
-const { lazy } = require('../util/Util');
 
 const getMessage = lazy(() => require('./Message').Message);
 

packages/discord.js/src/structures/Webhook.js

@@ -1,12 +1,12 @@
 'use strict';
 
 const { makeURLSearchParams } = require('@discordjs/rest');
+const { lazy } = require('@discordjs/util');
 const { DiscordSnowflake } = require('@sapphire/snowflake');
 const { Routes, WebhookType } = require('discord-api-types/v10');
 const MessagePayload = require('./MessagePayload');
 const { Error, ErrorCodes } = require('../errors');
 const DataResolver = require('../util/DataResolver');
-const { lazy } = require('../util/Util');
 
 const getMessage = lazy(() => require('./Message').Message);
 

packages/discord.js/src/util/Channels.js

@@ -1,7 +1,7 @@
 'use strict';
 
+const { lazy } = require('@discordjs/util');
 const { ChannelType } = require('discord-api-types/v10');
-const { lazy } = require('./Util');
 
 const getCategoryChannel = lazy(() => require('../structures/CategoryChannel'));
 const getDMChannel = lazy(() => require('../structures/DMChannel'));

packages/discord.js/src/util/Util.js

@@ -509,16 +509,6 @@ function cleanCodeBlockContent(text) {
   return text.replaceAll('```', '`\u200b``');
 }
 
-/**
- * Lazily evaluates a callback function
- * @param {Function} cb The callback to lazily evaluate
- * @returns {Function}
- */
-function lazy(cb) {
-  let defaultValue;
-  return () => (defaultValue ??= cb());
-}
-
 /**
  * Parses a webhook URL for the id and token.
  * @param {string} url The URL to parse
@@ -562,7 +552,6 @@ module.exports = {
   basename,
   cleanContent,
   cleanCodeBlockContent,
-  lazy,
   parseWebhookURL,
 };
 

packages/discord.js/typings/index.d.ts

@@ -12,7 +12,6 @@ import {
   hyperlink,
   inlineCode,
   italic,
-  JSONEncodable,
   quote,
   roleMention,
   SelectMenuBuilder as BuilderSelectMenuComponent,
@@ -31,6 +30,7 @@ import {
   ComponentBuilder,
   type RestOrArray,
 } from '@discordjs/builders';
+import { Awaitable, JSONEncodable } from '@discordjs/util';
 import { Collection } from '@discordjs/collection';
 import { BaseImageURLOptions, ImageURLOptions, RawFile, REST, RESTOptions } from '@discordjs/rest';
 import {
@@ -4144,8 +4144,6 @@ export interface AuditLogChange {
   new?: APIAuditLogChange['new_value'];
 }
 
-export type Awaitable<T> = T | PromiseLike<T>;
-
 export type AwaitMessageComponentOptions<T extends CollectedMessageInteraction> = Omit<
   MessageComponentCollectorOptions<T>,
   'max' | 'maxComponents' | 'maxUsers'
@@ -5835,3 +5833,4 @@ export type InternalDiscordGatewayAdapterCreator = (
 export * from 'discord-api-types/v10';
 export * from '@discordjs/builders';
 export * from '@discordjs/rest';
+export * from '@discordjs/util';

packages/proxy/package.json

@@ -55,6 +55,7 @@
 	"homepage": "https://discord.js.org",
 	"dependencies": {
 		"@discordjs/rest": "^1.0.0",
+		"@discordjs/util": "workspace:^",
 		"tslib": "^2.4.0",
 		"undici": "^5.10.0"
 	},

packages/proxy/src/util/util.ts

@@ -1,9 +1,5 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-
-/**
- * Represents a potentially awaitable value
- */
-export type Awaitable<T> = PromiseLike<T> | T;
+import type { Awaitable } from '@discordjs/util';
 
 /**
  * Represents a simple HTTP request handler

packages/rest/package.json

@@ -53,6 +53,7 @@
 	"homepage": "https://discord.js.org",
 	"dependencies": {
 		"@discordjs/collection": "workspace:^",
+		"@discordjs/util": "workspace:^",
 		"@sapphire/async-queue": "^1.5.0",
 		"@sapphire/snowflake": "^3.2.2",
 		"discord-api-types": "^0.37.11",

packages/rest/src/lib/RequestManager.ts

@@ -3,6 +3,7 @@ import { EventEmitter } from 'node:events';
 import { setInterval, clearInterval } from 'node:timers';
 import type { URLSearchParams } from 'node:url';
 import { Collection } from '@discordjs/collection';
+import { lazy } from '@discordjs/util';
 import { DiscordSnowflake } from '@sapphire/snowflake';
 import { FormData, type RequestInit, type BodyInit, type Dispatcher, type Agent } from 'undici';
 import type { RESTOptions, RestEvents, RequestOptions } from './REST.js';
@@ -12,12 +13,7 @@ import { DefaultRestOptions, DefaultUserAgent, RESTEvents } from './utils/consta
 import { resolveBody } from './utils/utils.js';
 
 // Make this a lazy dynamic import as file-type is a pure ESM package
-// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-const getFileType = async (): Promise<typeof import('file-type')> => {
-	// eslint-disable-next-line @typescript-eslint/consistent-type-imports
-	let cached: Promise<typeof import('file-type')>;
-	return (cached ??= import('file-type'));
-};
+const getFileType = lazy(async () => import('file-type'));
 
 /**
  * Represents a file to be added to the request

packages/util/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+	"extends": "../../.eslintrc.json"
+}

packages/util/.gitignore

@@ -0,0 +1,25 @@
+# Packages
+node_modules/
+
+# Log files
+logs/
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Env
+.env
+
+# Dist
+dist/
+typings/
+
+docs/**/*
+
+# Miscellaneous
+.tmp/
+coverage/

packages/util/.lintstagedrc.js

@@ -0,0 +1 @@
+module.exports = require('../../.lintstagedrc.json');

packages/util/.prettierignore

@@ -0,0 +1,8 @@
+# Autogenerated
+CHANGELOG.md
+.turbo
+dist/
+docs/**/*
+!docs/index.yml
+!docs/README.md
+coverage/

packages/util/.prettierrc.js

@@ -0,0 +1 @@
+module.exports = require('../../.prettierrc.json');

packages/util/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2022 Noel Buechler
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

packages/util/README.md

@@ -0,0 +1,34 @@
+<div align="center">
+	<br />
+	<p>
+		<a href="https://discord.js.org"><img src="https://discord.js.org/static/logo.svg" width="546" alt="discord.js" /></a>
+	</p>
+	<br />
+	<p>
+		<a href="https://discord.gg/djs"><img src="https://img.shields.io/discord/222078108977594368?color=5865F2&logo=discord&logoColor=white" alt="Discord server" /></a>
+		<a href="https://github.com/discordjs/discord.js/actions"><img src="https://github.com/discordjs/discord.js/actions/workflows/test.yml/badge.svg" alt="Build status" /></a>
+	</p>
+	<p>
+		<a href="https://vercel.com/?utm_source=discordjs&utm_campaign=oss"><img src="https://raw.githubusercontent.com/discordjs/discord.js/main/.github/powered-by-vercel.svg" alt="Vercel" /></a>
+	</p>
+</div>
+
+## Links
+
+- [Website](https://discord.js.org/) ([source](https://github.com/discordjs/discord.js/tree/main/packages/website))
+- [Documentation](https://discord.js.org/#/docs)
+- [Guide](https://discordjs.guide/) ([source](https://github.com/discordjs/guide))
+  See also the [Update Guide](https://discordjs.guide/additional-info/changes-in-v14.html), including updated and removed items in the library.
+- [discord.js Discord server](https://discord.gg/djs)
+- [Discord API Discord server](https://discord.gg/discord-api)
+- [GitHub](https://github.com/discordjs/discord.js/tree/main/packages/scripts)
+- [Related libraries](https://discord.com/developers/docs/topics/community-resources#libraries)
+
+## Contributing
+
+See [the contribution guide](https://github.com/discordjs/discord.js/blob/main/.github/CONTRIBUTING.md) if you'd like to submit a PR.
+
+## Help
+
+If you don't understand something in the documentation, you are experiencing problems, or you just need a gentle
+nudge in the right direction, please don't hesitate to join our official [discord.js Server](https://discord.gg/djs).

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());
+}

packages/util/package.json

@@ -0,0 +1,70 @@
+{
+	"name": "@discordjs/util",
+	"version": "0.1.0-dev",
+	"description": "Utilities shared across Discord.js packages",
+	"private": true,
+	"scripts": {
+		"build": "tsup",
+		"test": "vitest run && tsd",
+		"lint": "prettier --check . && TIMING=1 eslint src --ext mjs,js,ts",
+		"format": "prettier --write . && TIMING=1 eslint src --ext mjs,js,ts --fix",
+		"fmt": "yarn format"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		"import": "./dist/index.mjs",
+		"require": "./dist/index.js",
+		"types": "./dist/index.d.ts"
+	},
+	"directories": {
+		"lib": "src"
+	},
+	"files": [
+		"dist"
+	],
+	"contributors": [
+		"Crawl <icrawltogo@gmail.com>",
+		"Amish Shah <amishshah.2k@gmail.com>",
+		"Vlad Frangu <kingdgrizzle@gmail.com>",
+		"SpaceEEC <spaceeec@yahoo.com>",
+		"Aura Román <kyradiscord@gmail.com>"
+	],
+	"license": "Apache-2.0",
+	"keywords": [
+		"api",
+		"bot",
+		"client",
+		"node",
+		"discordjs"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/discordjs/discord.js.git"
+	},
+	"bugs": {
+		"url": "https://github.com/discordjs/discord.js/issues"
+	},
+	"homepage": "https://discord.js.org",
+	"devDependencies": {
+		"@types/node": "^16.11.56",
+		"@vitest/coverage-c8": "^0.22.1",
+		"eslint": "^8.23.0",
+		"eslint-config-neon": "^0.1.31",
+		"prettier": "^2.7.1",
+		"tsd": "^0.23.0",
+		"tsup": "^6.2.3",
+		"typescript": "^4.8.2",
+		"vitest": "^0.22.1"
+	},
+	"engines": {
+		"node": ">=16.9.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"tsd": {
+		"directory": "__tests__/types"
+	}
+}

packages/util/src/functions/index.ts

@@ -0,0 +1,2 @@
+export * from './lazy.js';
+export * from './range.js';

packages/util/src/functions/lazy.ts

@@ -0,0 +1,18 @@
+/**
+ * Lazy is a wrapper around a value that is computed lazily. It is useful for
+ * cases where the value is expensive to compute and the computation may not
+ * be needed at all.
+ *
+ * @param cb - The callback to lazily evaluate
+ * @typeParam T - The type of the value
+ * @example
+ * ```ts
+ * const value = lazy(() => computeExpensiveValue());
+ * ```
+ */
+// eslint-disable-next-line promise/prefer-await-to-callbacks
+export function lazy<T>(cb: () => T): () => T {
+	let defaultValue: T;
+	// eslint-disable-next-line promise/prefer-await-to-callbacks
+	return () => (defaultValue ??= cb());
+}

packages/util/src/functions/range.ts

@@ -0,0 +1,20 @@
+/**
+ * Yields the numbers in the given range as an array
+ *
+ * @param start - The start of the range
+ * @param end - The end of the range (inclusive)
+ * @param step - The amount to increment between each number
+ * @example
+ * Basic range
+ * ```ts
+ * range(3, 5); // [3, 4, 5]
+ * ```
+ * @example
+ * Range with a step
+ * ```ts
+ * range(3, 10, 2); // [3, 5, 7, 9]
+ * ```
+ */
+export function range(start: number, end: number, step = 1): number[] {
+	return Array.from({ length: (end - start) / step + 1 }, (_, index) => start + index * step);
+}

packages/util/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './functions/index.js';
+export * from './JSONEncodable.js';
+export * from './Equatable.js';

packages/util/src/types.ts

@@ -0,0 +1,4 @@
+/**
+ * Represents a type that may or may not be a promise
+ */
+export type Awaitable<T> = PromiseLike<T> | T;

packages/util/tsconfig.eslint.json

@@ -0,0 +1,20 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"allowJs": true
+	},
+	"include": [
+		"**/*.ts",
+		"**/*.tsx",
+		"**/*.js",
+		"**/*.mjs",
+		"**/*.jsx",
+		"**/*.test.ts",
+		"**/*.test.js",
+		"**/*.test.mjs",
+		"**/*.spec.ts",
+		"**/*.spec.js",
+		"**/*.spec.mjs"
+	],
+	"exclude": []
+}

packages/util/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "../../tsconfig.json",
+	"include": ["src/**/*.ts"]
+}

packages/util/tsup.config.js

@@ -0,0 +1,3 @@
+import { createTsupConfig } from '../../tsup.config.js';
+
+export default createTsupConfig({});

packages/ws/package.json

@@ -54,6 +54,7 @@
 	"dependencies": {
 		"@discordjs/collection": "workspace:^",
 		"@discordjs/rest": "workspace:^",
+		"@discordjs/util": "workspace:^",
 		"@sapphire/async-queue": "^1.5.0",
 		"@types/ws": "^8.5.3",
 		"@vladfrangu/async_event_emitter": "^2.1.2",

packages/ws/src/index.ts

@@ -8,7 +8,6 @@ export * from './strategies/sharding/WorkerShardingStrategy.js';
 
 export * from './utils/constants.js';
 export * from './utils/IdentifyThrottler.js';
-export * from './utils/utils.js';
 
 export * from './ws/WebSocketManager.js';
 export * from './ws/WebSocketShard.js';

packages/ws/src/strategies/context/IContextFetchingStrategy.ts

@@ -1,4 +1,4 @@
-import type { Awaitable } from '@vladfrangu/async_event_emitter';
+import type { Awaitable } from '@discordjs/util';
 import type { APIGatewayBotInfo } from 'discord-api-types/v10';
 import type { SessionInfo, WebSocketManager, WebSocketManagerOptions } from '../../ws/WebSocketManager';
 

packages/ws/src/strategies/sharding/IShardingStrategy.ts

@@ -1,5 +1,5 @@
+import type { Awaitable } from '@discordjs/util';
 import type { GatewaySendPayload } from 'discord-api-types/v10';
-import type { Awaitable } from '../../utils/utils';
 import type { WebSocketShardDestroyOptions } from '../../ws/WebSocketShard';
 
 /**

packages/ws/src/utils/constants.ts

@@ -2,9 +2,9 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
 import { Collection } from '@discordjs/collection';
+import { lazy } from '@discordjs/util';
 import { APIVersion, GatewayOpcodes } from 'discord-api-types/v10';
 import type { OptionalWebSocketManagerOptions, SessionInfo } from '../ws/WebSocketManager.js';
-import { lazy } from './utils.js';
 
 /**
  * Valid encoding types

packages/ws/src/utils/utils.ts

@@ -1,23 +0,0 @@
-import type { ShardRange } from '../ws/WebSocketManager';
-
-export type Awaitable<T> = Promise<T> | T;
-
-/**
- * Yields the numbers in the given range as an array
- *
- * @example
- * ```ts
- * range({ start: 3, end: 5 }); // [3, 4, 5]
- * ```
- */
-export function range({ start, end }: ShardRange): number[] {
-	return Array.from({ length: end - start + 1 }, (_, index) => index + start);
-}
-
-/**
- * Lazily evaluate a callback, storing its result
- */
-export function lazy<T>(cb: () => T): () => T {
-	let defaultValue: T;
-	return () => (defaultValue ??= cb());
-}

packages/ws/src/ws/WebSocketManager.ts

@@ -1,4 +1,5 @@
 import type { REST } from '@discordjs/rest';
+import { range, type Awaitable } from '@discordjs/util';
 import { AsyncEventEmitter } from '@vladfrangu/async_event_emitter';
 import {
 	Routes,
@@ -12,7 +13,6 @@ import {
 import type { IShardingStrategy } from '../strategies/sharding/IShardingStrategy';
 import { SimpleShardingStrategy } from '../strategies/sharding/SimpleShardingStrategy.js';
 import { DefaultWebSocketManagerOptions, type CompressionMethod, type Encoding } from '../utils/constants.js';
-import { range, type Awaitable } from '../utils/utils.js';
 import type { WebSocketShardDestroyOptions, WebSocketShardEventsMap } from './WebSocketShard.js';
 
 /**
@@ -264,11 +264,11 @@ export class WebSocketManager extends AsyncEventEmitter<ManagerShardEventsMap> {
 			if (Array.isArray(this.options.shardIds)) {
 				shardIds = this.options.shardIds;
 			} else {
-				shardIds = range(this.options.shardIds);
+				shardIds = range(this.options.shardIds.start, this.options.shardIds.end);
 			}
 		} else {
 			const data = await this.fetchGatewayInformation();
-			shardIds = range({ start: 0, end: (this.options.shardCount ?? data.shards) - 1 });
+			shardIds = range(0, (this.options.shardCount ?? data.shards) - 1);
 		}
 
 		this.shardIds = shardIds;

packages/ws/src/ws/WebSocketShard.ts

@@ -7,6 +7,7 @@ import { URLSearchParams } from 'node:url';
 import { TextDecoder } from 'node:util';
 import { inflate } from 'node:zlib';
 import { Collection } from '@discordjs/collection';
+import { lazy } from '@discordjs/util';
 import { AsyncQueue } from '@sapphire/async-queue';
 import { AsyncEventEmitter } from '@vladfrangu/async_event_emitter';
 import {
@@ -22,7 +23,6 @@ import { WebSocket, type RawData } from 'ws';
 import type { Inflate } from 'zlib-sync';
 import type { IContextFetchingStrategy } from '../strategies/context/IContextFetchingStrategy';
 import { ImportantGatewayOpcodes } from '../utils/constants.js';
-import { lazy } from '../utils/utils.js';
 import type { SessionInfo } from './WebSocketManager.js';
 
 // eslint-disable-next-line promise/prefer-await-to-then