feat: @discordjs/structures (#10900)

* chore: init /structures

* feat: base structure

* feat: initial structures design attempt

* refactor(Structure): use unknown to store in kData

* feat(Structure): add Invite

refactor(Structure): patch to _patch

* refactor: symbol names and override location

* fix: don't possibly return 0 if discord borks

Co-authored-by: Synbulat Biishev <signin@syjalo.dev>

* refactor: use getter value instead of api

Co-authored-by: Synbulat Biishev <signin@syjalo.dev>

* refactor: cache createdTimestamp value

Co-authored-by: Qjuh <76154676+Qjuh@users.noreply.github.com>

* docs: better docs for what's done so far

* feat: add Mixin

* refactor(User): remove bitfield getters and add displayName

* feat(structures): add Connection

* feat(structures): add Channel base

* refactor(Mixin): trace prototype chain, allow construction

* fix(structures): fix mixin behavior

* fix(structures): data optimization call behavior from perf testing

* feat: channel mixins

* chore: update deps

* feat: channels and mixins

* chore: more typeguard tests

* fix: tests and some other issues

* feat: add ChannelWebhookMixin

* fix: more tests

* chore: tests and docs

* chore: docs

* fix: remove unneccessary omitted

* chore: apply code suggestions

* refactor: change how extended invite works

* fix: type imports

* Apply suggestions from code review

Co-authored-by: Almeida <github@almeidx.dev>

* fix: tests

* chore: add jsdoc

* refactor: apply code suggestions

* fix: don't instantiate sub-structures

* fix: don't do null default twice

* chore: use formatters, add _cache

* chore: lockfile

* chore: move MixinTypes to declaratiion file

* fix: tests

* fix: don't include source d.ts files for docs

* feat: bitfields

* feat: more bitfields

* refactor: remove DirectoryChannel structure

* chore: apply suggestions from code review

* chore: remove unused import

* refactor: use symbol for mixin toJSON, remove _ prefix

* chore: apply suggestions from code review

* refactor: remove bitfield casts

* refactor: remove special case for threadchannel types

* fix: apply code review suggestions

* refactor: bitfields always store bigint

* fix: tests

* chore: apply suggestions from code review

* fix: lint

* refactor: conditional structuredClone

* Apply suggestions from code review

Co-authored-by: ckohen <chaikohen@gmail.com>

* fix: code review errors

* fix: lint

* chore: bump dtypes

* Update packages/structures/cliff.toml

Co-authored-by: Jiralite <33201955+Jiralite@users.noreply.github.com>

* docs: link to VideoQualityMode

* chore: typo in comment

* chore: small nits in docs links

* chore: small nits

* docs: forgot one

* chore: update template

* chore: typos and things

* chore: apply suggestions from code review

* fix: tests and typeguards

* chore: don't clone appliedTags

* refactor: use a symbol for patch method

* fix: add missing readonly

* chore: remove todo comment

* refactor: use symbol for clone

* fix: add constraint to DataType

* chore: apply suggestions

* fix: dtypes bump

* chore: fix comment

* chore: add todo comment

* chore: mark bitfield as todo
chore: mark bit field as todo and edit readme

---------

Co-authored-by: ckohen <chaikohen@gmail.com>
Co-authored-by: Synbulat Biishev <signin@syjalo.dev>
Co-authored-by: Almeida <github@almeidx.dev>
Co-authored-by: Jiralite <33201955+Jiralite@users.noreply.github.com>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

packages/structures/src/utils/optimization.ts

@@ -0,0 +1,10 @@
+export function extendTemplate<SuperTemplate extends Record<string, unknown>>(
+	superTemplate: SuperTemplate,
+	additions: Record<string, unknown>,
+): Record<string, unknown> & SuperTemplate {
+	return Object.defineProperties(additions, Object.getOwnPropertyDescriptors(superTemplate)) as Record<
+		string,
+		unknown
+	> &
+		SuperTemplate;
+}

packages/structures/src/utils/symbols.ts

@@ -0,0 +1,15 @@
+export const kData = Symbol.for('djs.structures.data');
+export const kClone = Symbol.for('djs.structures.clone');
+export const kPatch = Symbol.for('djs.structures.patch');
+export const kExpiresTimestamp = Symbol.for('djs.structures.expiresTimestamp');
+export const kCreatedTimestamp = Symbol.for('djs.structures.createdTimestamp');
+export const kEditedTimestamp = Symbol.for('djs.structures.editedTimestamp');
+export const kArchiveTimestamp = Symbol.for('djs.structures.archiveTimestamp');
+
+export const kAllow = Symbol.for('djs.structures.allow');
+export const kDeny = Symbol.for('djs.structures.deny');
+
+export const kLastPinTimestamp = Symbol.for('djs.structures.lastPinTimestamp');
+
+export const kMixinConstruct = Symbol.for('djs.structures.mixin.construct');
+export const kMixinToJSON = Symbol.for('djs.structures.mixin.toJSON');

packages/structures/src/utils/type-guards.ts

@@ -0,0 +1,3 @@
+export function isIdSet(id: unknown): id is bigint | string {
+	return typeof id === 'string' || typeof id === 'bigint';
+}

packages/structures/src/utils/types.ts

@@ -0,0 +1,36 @@
+export type ReplaceOmittedWithUnknown<Omitted extends keyof Data | '', Data> = {
+	[Key in keyof Data]: Key extends Omitted ? unknown : Data[Key];
+};
+
+export type CollapseUnion<Type> = Type extends infer Union ? { [Key in keyof Union]: Union[Key] } : never;
+
+export type OptionalPropertyNames<Type> = {
+	[Key in keyof Type]-?: {} extends { [Prop in Key]: Type[Key] } ? Key : never;
+}[keyof Type];
+
+export type MergePrototype<Class1, Class2> = Pick<Class1, Exclude<keyof Class1, keyof Class2>> &
+	Pick<Class2, Exclude<keyof Class2, OptionalPropertyNames<Class2>>> &
+	Pick<Class2, Exclude<OptionalPropertyNames<Class2>, keyof Class1>> & {
+		[Prop in OptionalPropertyNames<Class2> & keyof Class1]: Class1[Prop] | Exclude<Class2[Prop], undefined>;
+	};
+
+export type MergePrototypes<ClassArray extends readonly unknown[]> = ClassArray extends [infer Class1]
+	? Class1
+	: ClassArray extends [infer Class1, ...infer Rest]
+		? MergePrototype<Class1, MergePrototypes<Rest>>
+		: never;
+
+export interface RecursiveReadonlyArray<ItemType> extends ReadonlyArray<ItemType | RecursiveReadonlyArray<ItemType>> {}
+
+export type EnumLike<Enum, Value> = Record<keyof Enum, Value>;
+
+export type If<Check, Value, True, False = never> = Check extends Value ? (Value extends Check ? True : False) : False;
+
+export type NonAbstract<Type extends abstract new (...args: any) => any> = Type extends abstract new (
+	...args: infer Args
+) => infer Instance
+	? Pick<Type, keyof Type> & (new (...args: Args) => Instance)
+	: never;
+
+export type Partialize<Type, Omitted extends keyof Type | ''> = Omit<Type, Omitted> &
+	Partial<Pick<Type, Exclude<Omitted, ''>>>;