diff --git a/site/docs/architecture.mdx b/site/docs/architecture.mdx index d3306f149..e3745e4c9 100644 --- a/site/docs/architecture.mdx +++ b/site/docs/architecture.mdx @@ -12,7 +12,7 @@ import FlowChart from '@site/src/components/architecture/FlowChart' {() => } -Discordeno have three main components/process, gateway, bot and rest. The Gateway process is responsible for handling and maintaining the websocket with discord, the websocket events from discord, such as connection, resuming, heartbeating and sending websocket message to discord. The Bot process is responsible for handling and converting all events from discord and trigger your code, like run function on message create. The Rest process is responsible for handling/fetching all http requests to discord, such as ratelimiting and proxying. +Discordeno have three main components/process, gateway, bot and rest. Websocket events from Discord, such as connecting, restarting, heartbeating, and transmitting websocket messages to Discord, are handled and maintained by the Gateway process. All Discord events are handled and converted by the Bot process, which also activates your code, such as the execute function upon message creation. All http requests to Discord, including proxying and ratelimiting, are handled by the Rest process. ## Gateway Process import FlowChart2 from '@site/src/components/architecture/FlowChart2' @@ -21,15 +21,15 @@ import FlowChart2 from '@site/src/components/architecture/FlowChart2' {() => } -The Gateway process have two part the gateway manager and the gateway [shard](https://discord.com/developers/docs/topics/gateway#sharding), the gateway manager oversee the gateway shard. +The Gateway process have two part the gateway manager and the gateway [shard](https://discord.com/developers/docs/topics/gateway#sharding), the gateway manager oversees the gateway shard. ### Gateway Manager -The gateway manager spawn the right amount of shard acording to data from discord's [getGatewayBot](https://discord.com/developers/docs/topics/gateway#get-gateway-bot) endpoint, user can override the value of gatewayBot by directly passing the value. The manager control the order or sequence of shard identifying base on the session start limit listed in the getGatewayBot to prevent hitting the ratelimiting. By default the manager will check the getGatewayBot endpoint every 8 hours and reshard if the number of shard changed shard. Check [here](/tutorial/big-bot-guide/gateway#understanding-gateway-manager) for more information about the gateway manager. +The gateway manager spawns the right amount of shard acording to data from discord's [getGatewayBot](https://discord.com/developers/docs/topics/gateway#get-gateway-bot) endpoint, user can override the value of gatewayBot by directly passing the value. The manager control the order or sequence of shard identifying base on the session start limit listed in the getGatewayBot to prevent hitting the ratelimiting. By default the manager will check the getGatewayBot endpoint every 8 hours and reshard if the number of shard changed shard. Check [here](/tutorial/big-bot-guide/gateway#understanding-gateway-manager) for more information about the gateway manager. ### Gateway Shard -The gateway shard create a websocket connect to discord, and pass any event to the handleMessage function. The handleMessage function will check the event and intercept/process websocket related event like hello, resume, heartbeat, ready, only pass real event to the bot. You may customize the handleMessage to you own case, but it is not recommand unless you know what youd doing, as it is vital for the connection. After the function processed the event, the function will pass the event to the Bot proceess either directly (in same process), with rest api, with message queue, or with other method depend on the user customiztion. +Any event is passed to the handleMessage method by the gateway shard, which also establishes a websocket connection to Discord. The handleMessage method will examine the event and only deliver genuine events to the bot by intercepting and processing websocket-related events like hello, resume, heartbeat, and ready. You can modify the handleMessage to suit your needs, but it is not advised unless you are certain of your actions because the connection depends on it. After the function has finished processing the event, it will either pass the event directly (in the same process), via the rest api, a message queue, or another mechanism depending on the user's customization. ## Bot Process import FlowChart3 from '@site/src/components/architecture/FlowChart3' @@ -42,7 +42,7 @@ A simplified version of function used inside of the bot process, showing only th ### Bot -The Bot process receive event from gateway and pass all the event to the handleDiscordPayload function. The handleDiscordPayload function will call raw event for all event, and route to three layer for process the event, the handler, transformers and event. The handler will transformer the data of event with transformers and call the event with the transformed data. The transformer will remove useless property, change the name, abstractify bitwise permission flags change transform the data to a javascript. +When an event arrives from the gateway, the bot process receives it and passes it all to the handleDiscordPayload method. The handleDiscordPayload method will invoke raw events for each event and route calls to handlers, transformers, and events at three different layers for processing. The handler will use transformers to alter the event's contents before calling the event. The data will be transformed into typescript after being stripped of pointless properties, given a new name, and having bitwise permission flags abstracted. ## Rest Process diff --git a/site/docs/frequently-asked-questions.md b/site/docs/frequently-asked-questions.md index f32a4d688..b1956207b 100644 --- a/site/docs/frequently-asked-questions.md +++ b/site/docs/frequently-asked-questions.md @@ -6,31 +6,18 @@ sidebar_position: 5 ## Does Discordeno Support TypeScript? -Discordeno provides first class support for TypeScript! Since Deno provides support for TypeScript, that also comes into -Discordeno. This means you don't need to compile TypeScript before you use it. However, this isn't really why Discordeno -is the best library for TypeScript developers. When I developed this library, I was experimenting with a lot of -different things and one of them was automated typings. +TypeScript is supported to the highest standard by Discordeno. TypeScript is included in Discordeno since Deno supports it. This implies that before using TypeScript, you do not need to compile it. But this isn't the main reason Discordeno is the ideal library for TypeScript programmers. I was experimenting with a lot of various things when I created this library, and automatic typings was one of them. -Whenever I used other libraries, I was always seeing typings being inaccurate or problematic. This is because in any -Discord API library, the majority is not used by the library itself so TypeScript doesn't warn the library developers. -This makes it extremely likely that those typings become inaccurate or out of date because of simple mistakes like -forgetting to update typings. Sometimes libraries will add a property and forget to add that on their typings. This -makes it usable for JavaScript developers but not for TypeScript devs. For TypeScript developers, typings are -everything! Discordeno treats typings as part of it's code! A breaking change in typings is a breaking change for the -library! +When I utilised other libraries, I frequently observed incorrect or troublesome typings. This is so that TypeScript won't alert the library developers because most of the Discord API typings aren't utilised by the libraries themselves. + +It is quite unlikely that these typings would become wrong or outdated as a result of minor errors like forgetting to update typings because Discordeno utilises them as part of the rest process. Libraries occasionally add a property without also adding it to their typings. Because of this, TypeScript developers cannot use it, only JavaScript developers can. Typings are crucial for TypeScript developers. Typings are treated as a component of the code by Discordeno! A breaking change in typings is a breaking change for the library! ## How Stable Is Discordeno? -One of the biggest issues with almost every library (that I have used) is stability. None of the libraries gave much -love and attention to TypeScript developers the way it deserves. Sometimes TypeScript projects would break because -breaking changes to typings did not make a MAJOR bump so TypeScript bots in production would break. Sometimes I was -personally maintaining the typings because no one else was for that lib. Some libs were pre 1.0 and didn't even have a -stable branch/version where I would not have to worry about breaking changes. +Stability is one of the main problems with practically every library (I have used). None of the libraries showed TypeScript developers the love and care that they deserve. Because breaking changes to typings occasionally occurred without producing a MAJOR bump, TypeScript projects would occasionally fail. As a result, production TypeScript bots would fail. At times, I was the only one keeping the typings up to date for that library. Some libraries that were older than 1.0 didn't even have a stable branch or version, so I didn't have to worry about them undergoing breaking changes. -This is why I made it one of my foundational goals of this library to have the best stability for TypeScript developers. -No matter how small, a breaking change is a breaking change when it affects the public API. I could care less if we end -up at version 500. Being afraid to bump a MAJOR because it's a small change or a typing change is a terrible decision as -a library maintainer and destroys the experience for end users. +The finest stability for TypeScript developers is one of my basic goals for this library. +No matter how little, a change that impacts the public API qualifies as a breaking change. I don't care whether we reach version 500. As a library maintainer, you should never be scared to bump a MAJOR because it just involves a tiny modification or a type change because doing so will ruin the end user's experience. ## Why Doesn't Discordeno Use Classes or EventEmitter?