daenamnu/discordeno
1
0
Fork 0
mirror of https://github.com/discordeno/discordeno.git synced 2026-09-17 08:47:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(typedoc): update typedoc configuration and mark internal APIs as private (#4405)

Browse Source 
The typedoc config is now only in the top-level config file instead of also being one per package
and all internal APIs are now marked as private so typedoc won't generate documentation for them, however we still need to export them to avoid typedoc warnings

The new internal APIs that are exported, since are marked as `@private` can have breaking changes without notices
This commit is contained in:
Fleny
2025-09-02 08:17:59 +02:00
committed by GitHub
parent 2a7cd9b2a5
commit ae650a04d9
12 changed files with 67 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/bot/src/desiredProperties.ts
+42 -16
View File
@@ -61,7 +61,7 @@ import type {
/**
* All the objects that support desired properties
*
* @internal This is subject to breaking changes at any time
* @private This is subject to breaking changes at any time
*/
export interface TransformersObjects {
activityInstance: ActivityInstance
@@ -122,8 +122,12 @@ export interface TransformersObjects {
// NOTE: the top-level objects need both the dependencies and alwaysPresents even if empty when the key is specified, this is due the extends & nullability on DesiredPropertiesMetadata
// internal properties needs to be in the alwaysPresents array, depending on an always present value is accepted
/** Metadata for typescript to create the correct types for desired properties */
interface TransformersDesiredPropertiesMetadata extends DesiredPropertiesMetadata {
/**
* Metadata for typescript to create the correct types for desired properties
*
* @private This is subject to breaking changes without notices
*/
export interface TransformersDesiredPropertiesMetadata extends DesiredPropertiesMetadata {
channel: {
dependencies: {
archived: ['toggles']
@@ -852,21 +856,25 @@ export function createDesiredPropertiesObject<T extends RecursivePartial<Transfo
} satisfies TransformersDesiredProperties as CompleteDesiredProperties<T, TDefault>
}
type KeyByValue<TObj, TValue> = {
/** @private This is subject to breaking changes without notices */
export type KeyByValue<TObj, TValue> = {
[Key in keyof TObj]: TObj[Key] extends TValue ? Key : never
}[keyof TObj]
type Complete<TObj, TDefault> = {
/** @private This is subject to breaking changes without notices */
export type Complete<TObj, TDefault> = {
[K in keyof TObj]-?: undefined extends TObj[K] ? TDefault : Exclude<TObj[K], undefined>
}
type JoinTuple<T extends string[], TDelimiter extends string> = T extends readonly [infer F extends string, ...infer R extends string[]]
/** @private This is subject to breaking changes without notices */
export type JoinTuple<T extends string[], TDelimiter extends string> = T extends readonly [infer F extends string, ...infer R extends string[]]
? R['length'] extends 0
? F
: `${F}${TDelimiter}${JoinTuple<R, TDelimiter>}`
: ''
type DesiredPropertiesMetadata = {
/** @private This is subject to breaking changes without notices */
export type DesiredPropertiesMetadata = {
[K in keyof TransformersObjects]: {
dependencies?: {
[Key in keyof TransformersObjects[K]]?: (keyof TransformersObjects[K])[]
@@ -875,7 +883,8 @@ type DesiredPropertiesMetadata = {
}
}
type DesirableProperties<
/** @private This is subject to breaking changes without notices */
export type DesirableProperties<
T extends TransformersObjects[keyof TransformersObjects],
TKey extends keyof TransformersObjects = KeyByValue<TransformersObjects, T>,
> = Exclude<
@@ -888,21 +897,25 @@ type DesirableProperties<
: NonNullable<TransformersDesiredPropertiesMetadata[TKey]['alwaysPresents']>[number])
>
/** @internal This is subject to breaking changes without notices */
/** @private This is subject to breaking changes without notices */
export type DesiredPropertiesMapper<T extends TransformersObjects[keyof TransformersObjects]> = {
[Key in DesirableProperties<T>]: boolean
}
declare const TypeErrorSymbol: unique symbol
interface DesiredPropertiesError<T extends string> {
/** @private This is subject to breaking changes without notices */
export interface DesiredPropertiesError<T extends string> {
[TypeErrorSymbol]: T
}
type AreDependenciesSatisfied<T, TDependencies extends Record<string, string[]> | undefined, TProps> = {
/** @private This is subject to breaking changes without notices */
export type AreDependenciesSatisfied<T, TDependencies extends Record<string, string[]> | undefined, TProps> = {
[K in keyof T]: IsKeyDesired<T[K], TDependencies, TProps> extends true ? true : false
}
type IsKeyDesired<TKey, TDependencies extends Record<string, string[]> | undefined, TProps> = TKey extends keyof TProps // The key has a desired props?
/** @private This is subject to breaking changes without notices */
export type IsKeyDesired<TKey, TDependencies extends Record<string, string[]> | undefined, TProps> = TKey extends keyof TProps // The key has a desired props?
? // Yes, is it true?
TProps[TKey] extends true
? // Yes, this is a key to include
@@ -928,7 +941,8 @@ export enum DesiredPropertiesBehavior {
ChangeType,
}
type RemoveKeyIfUndesired<Key, T, TProps extends TransformersDesiredProperties> = IsKeyDesired<
/** @private This is subject to breaking changes without notices */
export type RemoveKeyIfUndesired<Key, T, TProps extends TransformersDesiredProperties> = IsKeyDesired<
Key,
TransformersDesiredPropertiesMetadata[KeyByValue<TransformersObjects, T>]['dependencies'],
TProps[KeyByValue<TransformersObjects, T>]
@@ -936,7 +950,8 @@ type RemoveKeyIfUndesired<Key, T, TProps extends TransformersDesiredProperties>
? Key
: never
type GetErrorWhenUndesired<
/** @private This is subject to breaking changes without notices */
export type GetErrorWhenUndesired<
Key extends keyof T,
T,
TProps extends TransformersDesiredProperties,
@@ -949,7 +964,8 @@ type GetErrorWhenUndesired<
>,
> = TIsDesired extends true ? TransformProperty<T[Key], TProps, TBehavior> : TIsDesired
type IsObject<T> = T extends object ? (T extends Function ? false : true) : false
/** @private This is subject to breaking changes without notices */
export type IsObject<T> = T extends object ? (T extends Function ? false : true) : false
// If the object is a transformed object, a collection of transformed object or an array of transformed objects we need to apply the desired props to them as well
// NOTE: changing the order of these ternaries can cause bugs, for this reason we check in this order:
@@ -961,6 +977,10 @@ type IsObject<T> = T extends object ? (T extends Function ? false : true) : fals
// - Is it an interaction resolved data channel?
// - Is it an object?
// - It's not an object
/**
* Transform a generic object properties based on the desired properties and behavior for other transformer objects in the object.
*/
export type TransformProperty<T, TProps extends TransformersDesiredProperties, TBehavior extends DesiredPropertiesBehavior> = T extends Array<infer U> // is it an array?
? // Yes, apply the desired props
TransformProperty<U, TProps, TBehavior>[]
@@ -991,6 +1011,9 @@ export type TransformProperty<T, TProps extends TransformersDesiredProperties, T
: // No, this is a normal value such as string / bigint / number
T
/**
* Apply desired properties to a transformer object.
*/
export type SetupDesiredProps<
T extends TransformersObjects[keyof TransformersObjects],
TProps extends TransformersDesiredProperties,
@@ -1005,11 +1028,14 @@ export type SetupDesiredProps<
: TransformProperty<T[Key], TProps, TBehavior>
}
/**
* The desired properties for each transformer object.
*/
export type TransformersDesiredProperties = {
[Key in keyof TransformersObjects]: DesiredPropertiesMapper<TransformersObjects[Key]>
}
/** @internal This is subject to breaking changes without notices */
/** @private This is subject to breaking changes without notices */
export type CompleteDesiredProperties<T extends RecursivePartial<TransformersDesiredProperties>, TTDefault extends boolean = false> = {
[K in keyof TransformersDesiredProperties]: Complete<Partial<TransformersDesiredProperties[K]> & T[K], TTDefault>
}
packages/bot/src/transformers/toggles/guild.ts
+4 -3
View File
@@ -1,7 +1,8 @@
import { type DiscordGuild, GuildFeatures } from '@discordeno/types'
import { ToggleBitfieldBigint } from './ToggleBitfield.js'
const featureNames = [
/** @private This is subject to breaking changes without notices */
export const guildFeatureNames = [
'animatedBanner',
'animatedIcon',
'applicationCommandPermissionsV2',
@@ -169,7 +170,7 @@ export class GuildToggles extends ToggleBitfieldBigint {
get features(): GuildFeatureKeys[] {
const features: GuildFeatureKeys[] = []
for (const key of Object.keys(GuildToggle)) {
if (!featureNames.includes(key as GuildFeatureKeys)) continue
if (!guildFeatureNames.includes(key as GuildFeatureKeys)) continue
if (!super.contains(GuildToggle[key as GuildToggleKeys])) continue
features.push(key as GuildFeatureKeys)
@@ -383,4 +384,4 @@ export class GuildToggles extends ToggleBitfieldBigint {
export type GuildToggleKeys = keyof typeof GuildToggle
export type GuildFeatureKeys = (typeof featureNames)[number]
export type GuildFeatureKeys = (typeof guildFeatureNames)[number]
packages/bot/src/transformers/toggles/member.ts
+2 -1
View File
@@ -1,7 +1,8 @@
import { type DiscordMember, MemberFlags } from '@discordeno/types'
import { ToggleBitfield } from './ToggleBitfield.js'
const memberFlags = ['didRejoin', 'startedOnboarding', 'bypassesVerification', 'completedOnboarding'] as const
/** @private This is subject to breaking changes without notices */
export const memberFlags = ['didRejoin', 'startedOnboarding', 'bypassesVerification', 'completedOnboarding'] as const
export const MemberToggle = {
/** Whether the user is deafened in voice channels */
packages/bot/src/transformers/types.ts
+5 -5
View File
@@ -411,7 +411,7 @@ export interface Channel {
/**
* Thread-specific fields not needed by other channels.
*
* @internal
* @private
* This field is an internal field, subject to breaking changes.
*/
internalThreadMetadata?: InternalChannelThreadMetadata
@@ -425,7 +425,7 @@ export interface Channel {
/**
* Explicit permission overwrites for members and roles
*
* @internal
* @private
* Use channel.permissionOverwrites. This is for internal use only, and prone to breaking changes.
*/
internalOverwrites?: bigint[]
@@ -480,7 +480,7 @@ export interface ForumTag {
}
/**
* @internal
* @private
* This is for internal purposes only, and subject to breaking changes
*/
export interface InternalChannelThreadMetadata {
@@ -1502,7 +1502,7 @@ export interface Role {
/**
* Role tags
*
* @internal
* @private
* Use role.tags. This is for internal use only, and prone to breaking changes.
*/
internalTags?: InternalRoleTags
@@ -1532,7 +1532,7 @@ export interface Role {
}
/**
* @internal
* @private
* This is for internal purposes only, and subject to breaking changes
*/
export interface InternalRoleTags {
packages/bot/typedoc.jsonc
-5
View File
@@ -1,5 +0,0 @@
{
"entryPoints": ["./src/index.ts"],
// Exclude other packages' dist folders to avoid duplicated types in the documentation
"exclude": ["../*/dist/**/*"]
}