Chatterino 2: Enhancing Plugin APIs With Modular Design

Hey guys! Let's dive into a discussion about how we can level up Chatterino 2's plugin APIs. Right now, we're working with a global c2 table to hold all the APIs. But since plugins are still in their early stages, it's the perfect time to make some significant improvements. Our goal is to make things more organized, user-friendly, and future-proof. So, let's explore how we can move some of these APIs into modules, making them cleaner and easier to manage. We'll also cover naming conventions and how to handle documentation to ensure everything is crystal clear for our users.

Moving APIs to Modules: A Fresh Approach

One of the main goals here is to make the APIs more modular. This means breaking them down into smaller, more manageable units. By doing so, we're aiming for a cleaner and more organized structure. Imagine the c2.WebSocket API. Currently, it's sitting there in the global table. But wouldn’t it be neat if we could access it as a module? Think of it like this: require('websocket'). This approach not only keeps things tidy but also makes it super clear where to find specific functionalities.

Similarly, we should consider moving the HTTP-related APIs. We're talking about c2.HTTPRequest, c2.HTTPResponse, and c2.HTTPMethod. These could be grouped nicely into an http module. This way, instead of typing out c2.HTTPRequest, you'd simply use http.Request. It's all about making the code more intuitive and easier to read. The practical impact is significant. Developers can quickly find what they need without wading through a massive global table. This reduces the cognitive load, allowing developers to focus more on their plugin's core functionality rather than hunting for APIs. It's a win-win for everyone involved. Plus, the modular approach makes it much simpler to update or modify specific parts of the API without affecting the entire system. If we need to change something in the websocket module, for example, we can do it without worrying about breaking other parts of the plugin ecosystem. This is crucial for maintaining a stable and flexible platform. By adopting modular design, we're setting the stage for more complex and sophisticated plugins in the future. The possibilities are truly exciting, and it all starts with a well-structured API. So, let's make it happen!

This isn't just about tidiness; it's about scalability and maintainability. When everything is in a single global table, it's easy for things to become a mess as the project grows. Modules provide a logical structure that helps developers understand and navigate the codebase more easily. It's like organizing your toolbox: everything has its place, and you know exactly where to find what you need. This is especially important for a project like Chatterino 2, which has a vibrant community of developers. A well-organized API makes it easier for new contributors to get involved and for existing developers to build on each other's work. The modular approach also makes it easier to test individual components of the API. You can write unit tests for each module, ensuring that it behaves as expected. This helps catch bugs early and ensures that the API is reliable and robust. Ultimately, the goal is to create a plugin system that is both powerful and user-friendly. By moving APIs to modules, we're taking a big step toward achieving that goal.

Dealing with Usertypes and Complex APIs

Now, let's talk about the trickier parts. Some APIs involve usertypes, which are used in multiple functions. For example, c2.register_command relies on c2.Channel. If we were to move c2.Channel into a channel module, things could get a little more complicated. You'd need to require('channel') and then use it. The challenge is ensuring that the usertype is correctly created and accessible. This might seem a bit counterintuitive to some users. They'll need to understand how to handle these dependencies properly. It's like setting up a complex machine; you need to connect all the parts in the right order for it to work. We want to avoid causing confusion. We need to think about how tools like Language Server Protocols (LSPs) will handle these changes. Will they provide the correct autocompletion and type checking? That’s something we need to consider. The question is: how can we simplify this process? Can we take inspiration from other applications or games that use Lua as a scripting language? Many successful projects have already solved similar problems, so we don’t have to reinvent the wheel. Learning from their experiences can give us valuable insights and best practices.

We need to make it as easy as possible for users to get started and write effective plugins. One potential solution is to provide clear documentation and examples. Showing how to use these APIs with practical code snippets can make a huge difference. Another approach is to create helper functions or utilities that simplify common tasks. These can abstract away some of the complexity and make the API more user-friendly. We could also consider using a dependency injection system, which would allow us to manage the relationships between different modules more easily. This would ensure that all the required dependencies are loaded correctly and in the right order. Ultimately, the goal is to strike a balance between power and ease of use. We want to provide a robust API that is capable of handling complex tasks while remaining approachable for new developers. By carefully considering these challenges, we can create a plugin system that is both powerful and user-friendly, fostering a thriving community of plugin developers. Remember, the success of any platform depends on the ease with which developers can create and extend its functionality.

Naming Conventions: The Art of Module Names

Let’s talk about naming. It might seem like a small detail, but naming conventions can significantly impact how easy it is to use and understand the API. In the Lua world, we usually see two main styles: luacase or snake_case. But should we go further? Should we add prefixes to our module names? Something like @chatterino/http? The big reason for this is forward compatibility. Imagine a user has a local http.lua file. If we introduce our own http module, it could create conflicts. Our module would take precedence. This could break the user's plugin unexpectedly. Prefixes are a way to avoid these collisions. They add a layer of safety, making sure our modules don't accidentally clash with existing code. So, should we use prefixes? It's a trade-off. Prefixes can make the code look a bit more verbose, but they offer protection against naming conflicts.

Think about how these modules will be used in practice. Will developers easily recognize and remember the names? Will the prefixes make the code more readable or less so? We should also consider how the modules will be organized in the file system. Will the prefixes make it easier to find and manage the files? It’s all about finding a balance that works best for our community. We also need to think about the long-term implications. As Chatterino 2 grows, there will likely be more and more modules. How will these names scale? Will the prefixes help or hinder the growth of the plugin ecosystem? It's a complex decision, but it's important to get it right. Choosing the right naming convention can improve the readability and maintainability of the codebase, which is crucial for the long-term success of the project. There's no one-size-fits-all answer, so we should consider the specific needs and goals of our plugin system. The goal is to make it as easy as possible for developers to create and maintain plugins. A good naming convention is a key part of that goal. Ultimately, the choice of naming convention will depend on the specific needs of the Chatterino 2 project and its community. It's a decision that requires careful consideration of the pros and cons of each approach.

Documentation and Metadata: A Helping Hand

Finally, let’s talk documentation. Currently, we have a documentation/metadata generator. Its main superpower is automatically extracting enum values. But should we adapt it for these new modules? I think we should consider the role of the generator. It's great for things like enums. Those can be tedious to write by hand. But for other parts of the documentation, I prefer writing it manually. I get the benefits of syntax highlighting and editor integration. This lets me create well-formatted and easy-to-read documentation. The question is: How can we best support the documentation needs of the new module system? Should we enhance the generator? Or should we focus on creating excellent manual documentation? Or maybe a combination of both? We want to make sure the documentation is accurate, up-to-date, and easy to find. Clear and comprehensive documentation is essential for plugin developers. It helps them understand how to use the APIs, troubleshoot problems, and contribute to the project. Without good documentation, the plugin ecosystem will suffer. We should also consider how the documentation will be integrated into the development process. Can we automatically generate documentation from the code? Or should we rely on manual documentation? Or should we use a combination of both?

We could integrate documentation tools directly into our development workflow. Tools that generate API references from source code can save developers a ton of time and reduce the likelihood of errors. We can also provide examples, tutorials, and code samples. This gives developers practical guidance on how to use the APIs. By combining automated and manual documentation methods, we can provide the best possible experience for our plugin developers. The goal is to make it as easy as possible for developers to create and maintain plugins. A well-documented API will help achieve this. Good documentation isn’t just about providing information; it’s about creating a welcoming and supportive environment for plugin developers. It’s an ongoing process that requires constant attention and improvement. By thoughtfully addressing the documentation challenges, we can ensure that our plugin system remains user-friendly and successful. Remember, the quality of our documentation directly impacts the success of our plugin ecosystem. It's a key factor in attracting and retaining developers.