Library brief/plans/tasks

[Khaaz]

Dis.ts

Philosophy

This library aims to create an alternative to the current two big libraries: Eris and Discord.js.
⚠️ Disclaimer: This isn't meant for lib fight, both libs have their advantages and disadvanages. The goal of dis.ts is to submit a different fresh vision, with no previous background and built from the ground up with the current API state.
This aims to fix several flaws in one or both libs and use a more up-to-date approach to the Discord API according to the current state of the API.

• Too much reliance on cache
• No way to customise cache (what to cache, where to cache, how to cache)
• Too much abstraction (too many structures and objects linked together at once, cluttered api)
• Not enough abstractions (cluttered code, harder to maintain and use, no separation of concerns)
• Monolithic design that prevents having access to lower level wrapper for a specific use case
• Sharding and clustering support is often not easy/needs an additional library/isn't working well
• Typings separated from implementation which leads to increased maintenance and more errors with TypeScript definitions
• No way to easily integrate in a serverless environment or as a microservice library

Objectives

• Provide a low level wrapper for the REST API and WebSocket which can be used independently.
• Provide a Client covering the whole API with no cache reliance by default.
• Provide a way to dynamically populate cache (only guilds and channels for example, or just roles etc...).
• Provide a strict API wrapper with the minimum abstraction needed to function.
• Provide optional abstractions and helpers for ease of development.
• Provide optional ratelimit handling in order to facilitate clustering with shared ratelimits
• Out of the box clustering solution with no API changes
• Entirely in TypeScript for TS users, IntelliSense, types consistency...
• Easy usage in serverless environments
• Easy integration in micro-service architectures

Organisation

The library will be organised as follows:

• dis.ts/gateway: a low level wrapper around Discord Gateway
  • v8 Discord Gateway
  • all gateway events
  • no cache
  • emits one event per Discord event
  • supports intents efficiently
  • possibility to disable specific events from emitting
  • internal sharding
• dis.ts/rest: a low level wrapper around Discord REST
  • v8 Discord REST
  • all REST endpoints
  • no cache
  • methods for each endpoint to facilitate usage
  • handles ratelimits with optional custom storage (eg: redis, memcached)
  • add your own cache provider to support shared cache
• dis.ts/cache: caching libary
  • customisable cache engine
  • only handle where to cache (customisable), how to handle cache (customisable), not when to cache
  • called on events to cache Discord data in structures
  • async cache / get in order to support async cache (redis / mongo etc)
  • add your own cache providers
• dis.ts/structures: internal package with all Discord structures as classes
  • used in dis.ts/rest, dis.ts/gateway, dis.ts/client...
  • abstraction for every Discord structure
• dis.ts/utils: internal package with a set of utility used accross the lib
• dis.ts/client: default library
  • no cache by default
  • optional cache that can be activated independently
  • uses dis.ts/rest and dis.ts/ws. Listen to ws event, populate dis.ts/cache if needed and re-emit events.
• dis.ts/voice: voice support
• dis.ts/framework: higher level framework around dis.ts/client
  • doesn't come with all features possible: see community made/custom frameworks
  • command and event handler
  • set of general utilities
• dis.ts/clustering: clustering solution on multiple cores with shared ratelimit
  • dis.ts/client or dis.ts/framework but on multiple cores
  • shared ratelimits
  • cross-thread communication
  • smooth transition with no api changes

This will work as a monorepo to facilitate versioning and cross-repo updates which is often needed with Discord API updates.