This BEEP will contain the index of all Booster Evolution Enhancement Proposals, known as BEEPs. BEEP numbers are assigned by the BEEP editors, and once assigned are never changed.
In the future, the BEEPs will be listed here by category. For now, use the sidebar on the left.
A good starting point is BEEP 1, which describes the BEEP process itself.
BEEP stands for Booster Evolution Enhancement Proposal. It is a document that describes a change or addition to Booster.
A BEEP can have one of the following statuses:
This status indicates that the BEEP is still being written and is not ready for review.
This status indicates that the BEEP has been accepted but is still being implemented.
This status indicates that the BEEP has been implemented.
This status is for informational BEEPs that have been accepted.
This status indicates that the BEEP has been rejected.
Everyone is welcome to propose, discuss, and review ideas to improve Booster in the #proposals channel of the Discord server.
Note that the project is in a very early stage, and the contribution to the design process is not well defined.
As some general rules for now, take this into account before submitting a proposal:
Please state explicitly whether you believe that the proposal should be accepted into Booster.
This document defines the target audience and user persona for the Booster Framework project, aligning it with its current usage and user base.
While maintaining a focus on guiding the design and development process of the Booster Framework, this definition is not an exclusionary rule but a strategic tool for decision-making. The framework is inclusive and welcomes a diverse range of users, though particular emphasis is placed on specific user groups in design and functionality.
The primary target audience for the Booster Framework is developers in large-scale enterprise environments, familiar with enterprise technologies like Java, .NET, or similar. This includes those working in Fortune 500 companies, especially those transitioning from traditional enterprise technologies to TypeScript in complex projects such as financial transactions.
Additionally, the Booster Framework is gaining traction among hobbyist developers for personal projects, thanks to its ease of use and efficient learning curve. This secondary audience appreciates the framework for its quick setup, minimal configuration, and straightforward deployment, which are ideal for smaller-scale, personal projects.
This document outlines the dual focus of the Booster Framework's target audience and user personas. Our development and design efforts are directed towards supporting both the enterprise developers transitioning from traditional technologies to TypeScript, and the growing community of hobbyist developers seeking an accessible and easy-to-use framework for personal projects. This approach ensures the Booster Framework remains versatile and relevant across different scales and scopes of software development.
This document lays out the design principles guiding the design and implementation processes of the Booster Framework. These principles are crucial in steering both high-level and low-level decision-making within the project. They are pivotal in ensuring that the project remains focused on the correct aspects of design and implementation, always keeping in mind the target audience and user persona, as they are the most important stakeholders of the project.
The Principle of Least Astonishment, also known as the Principle of Least Surprise, is a fundamental guideline in user interface and software design. It stresses the importance of creating systems that behave in ways consistent with user expectations, minimizing surprise and confusion. This principle is crucial in the Booster Framework, ensuring that the framework's components and functionalities align with the conventions familiar to both enterprise and hobbyist developers, thereby enhancing their experience and usability. It is particularly relevant in a context where developers are transitioning from traditional enterprise technologies to modern TypeScript-based environments, as it aids in reducing the learning curve and preventing user astonishment.
The Principle of Developer Happiness is centered around creating an environment and culture that aligns with developers' professional and personal expectations, thereby enhancing satisfaction and retention. This principle is key in the Booster Framework, focusing on an engaging experience and a supportive culture where developers, regardless of their background, feel valued and connected to the project's mission. It also involves using efficient tools and technologies to streamline the development process and saving time, along with continuously assessing developer efficiency and satisfaction.
The Principle of Least Effort emphasizes the idea that entities will naturally gravitate towards the solution that requires the least amount of work or complexity. In the context of the Booster Framework, this principle is applied to create systems and interfaces that are straightforward, easy to comprehend, and simple to interact with. This reduces the cognitive and operational load on users, particularly those transitioning from different technology backgrounds. For developers, it encourages the creation of code and architectures that are clean, efficient, and easy to understand and modify. By adhering to this principle, the Booster Framework aims to offer user-friendly applications and sustainably maintainable codebases, promoting efficient interactions for all users.
The design principles outlined for the Booster Framework serve as a guiding light for the project's development and implementation processes. The Principle of Least Astonishment ensures system behavior aligns with user expectations, enhancing usability. The Principle of Developer Happiness focuses on creating a fulfilling environment for developers, while the Principle of Least Effort promotes simplicity and efficiency. These principles collectively ensure that the Booster Framework remains attuned to the needs of its diverse user base, from enterprise developers to hobbyist programmers, ensuring a user-centric, efficient, and developer-friendly journey throughout its development.
In the context of the Booster Framework ecosystem, we adopt the Semantic Versioning (SemVer) schema. SemVer is a system of rules and guidelines for assigning and incrementing version numbers within our software development process. By using SemVer, the Booster Framework aims to manage the complexities of dependencies as the ecosystem evolves. The primary goal of implementing Semantic Versioning is to ensure that our version numbers are transparent and informative, effectively communicating the nature of changes in our software to both enterprise and hobbyist developers.
Semantic Versioning positively impacts the Principle of Least Astonishment. It is a widely recognized and used schema in numerous open-source projects. Adhering to a clear and consistent version numbering system (Major.Minor.Patch) reduces confusion and surprise for developers and users alike. This predictability in versioning enhances the user experience and facilitates the management of software dependencies.
Semantic Versioning aligns with the Principle of Developer Happiness by offering a systematic and standardized approach to versioning. This method simplifies the process of releasing and updating software packages, allowing developers to confidently implement changes. Knowing that version numbers accurately reflect the impact of changes reduces the stress related to dependency management and enables developers to concentrate on innovation and software improvement.
Semantic Versioning supports the Principle of Least Effort by making the management of software dependencies more straightforward. By adhering to SemVer, developers can introduce backward-compatible changes without needing new major releases, thereby minimizing the effort needed for maintaining and updating software. Additionally, the clear documentation of public APIs and the use of version numbers to indicate compatibility simplify the integration of dependencies, reducing the effort needed for seamless software interactions.
During the initial development phases of Booster Framework projects, the major version will remain at 0. This indicates that breaking changes are likely to be frequent as the project evolves. Once the project achieves a stable state, the major version will be incremented to 1, signifying a reduction in the frequency of breaking changes.
We advise using the Semantic Versioning schema as a standard across all Booster Framework projects. This uniformity will ensure coherence within the ecosystem. The Booster CLI tool should facilitate version management by inspecting exported functions and types, suggesting the next version based on the changes made.
It's important to note that changes in the implementation of a function, even without altering the API, can produce different results and are considered breaking changes. These should be reflected in the version number accordingly. For more information and examples, please refer to this GitHub thread.
This document proposes a significant reorganization of the Booster Framework's folder structure to address current challenges in codebase management and to align with the principles of modularity and scalability. The current structure, src/{commands,events,entities,read-models}/*.ts, while functional, has shown limitations in managing complexity as the framework and the team grow.
This proposal introduces a new structure based on the concept of "Agents" in event sourcing/event-driven systems, aiming to bring conceptual clarity and improved organization to the codebase. It can be thought as the microservices approach, but more tailored to the event-driven nature of Booster Framework.
The existing folder structure in the Booster Framework presents several challenges:
The new folder structure is organized around the concept of "Agents", where each use case is encapsulated within its own subfolder. This approach mirrors the modular and event-driven nature of the Booster Framework.
src/
agents/
agent-name-1/
commands/events/entities/read-models/agent-name-2/
commands/events/entities/read-models/shared/
common-entities/utilities/shared/ folder will house common entities and utilities, accessible to all agents while maintaining their independence.shared/ folder, then gradually move to the new structure.In line with the event-driven architecture of the Booster Framework, an intriguing extension to the proposed semantic codebase structure is the incorporation of AI agents. These agents, mirroring the structure of traditionally-programmed agents with commands, events, read-models, etc., would have their internal logic powered by Large Language Models (LLMs).
This integration aligns with the scalable and modular design of the framework, allowing AI agents to autonomously handle specific tasks or workflows within their domain. The use of AI agents could significantly enhance the framework's capabilities in areas such as:
Each AI agent would operate within its designated subfolder, ensuring a clear delineation and manageable interaction with regular agents, while adhering to the same communication protocols and interface standards established in the overall framework.
This innovative approach opens new avenues for efficiency, creativity, and advanced functionalities within the Booster Framework ecosystem.
The proposed semantic codebase structure for Booster Framework aims to address current challenges in codebase management while aligning with the principles of modularity and scalability. This reorganization, centered around the concept of "Agents", offers numerous benefits, including improved code separation, easier collaboration, and the potential for scalable codebase management.
This document proposes a novel solution to address the challenges encountered by the team following the restructuring of Booster Framework codebase into distinct agents and separate repositories. The primary challenge involves enabling easy importation of types and classes from other agents without relying on traditional package managers. The proposed solution introduces a new endpoint, /inspect, in Booster services, coupled with an extension to the TypeScript compiler through a specialized plugin (transformer). This approach aims to streamline development, ensure access to up-to-date type definitions, and facilitate seamless agent interaction.
After splitting the project codebase into individual agents and repositories, the team faces the challenge of efficiently importing types and classes across these divided entities. Traditional methods, such as package managers, are not optimal in this scenario due to their complexity and the additional maintenance they require. There is a need for a more agile and integrated solution that aligns with the dynamic nature of Booster Framework.
/inspect Endpoint/inspect endpoint in Booster services will provide direct access to .d.ts files of all project components, organized by agents. This will include types for commands, events, read-models, and other relevant components.import FooEvent from 'booster://agent-name/events/FooEvent'..d.ts file from the /inspect endpoint, streamlining the import process./inspect.d.ts files accessible via the /inspect endpoint.As the first version of this feature, these security concerns will be mitigated through making this feature opt-in. It would be only available for environments where the flag has been enabled. For example, it should be enabled in the local development, testing, and staging environments, but disabled in production.
booster://agent-name import syntax will follow a clear and consistent naming convention, aligning with the overall structure and nomenclature of the Booster Framework.The introduction of the /inspect endpoint and the extension of the TypeScript compiler with a custom plugin represent a significant step forward in addressing the challenges of remote imports in Booster Framework. This solution not only simplifies the development process but also enhances the modularity and flexibility of the framework, ensuring a smooth and efficient experience for developers working across different agents and repositories.
This document proposes an enhancement to Booster Framework, introducing a new component integration mechanism. This enhancement aims not to overhaul the existing architecture but to provide an incremental upgrade, allowing the Framework to retain its current functionality while adding new, more efficient capabilities. This proposal details the transition to a system where components, written with clear interfaces using Effect, can be directly injected into the Booster project, offering improved efficiency and customization.
This component system is not meant to be used by all Booster users, but rather by it's power users who want to extend their apps in ways that are not possible with the current system, as well as Booster contributors who want to add new features to the framework.
The Booster Framework currently relies on users specifying packages to be loaded (like Azure provider or filesystem components) in a JSON configuration, which are then dynamically imported by the framework. While functional, this approach has limitations in efficiency and customization.
This is a draft of the design and implementation of the new component system. It is not final and is subject to change. It hasn't been tested against a compiler, tried in any way, let alone implemented. It is an "off the top of my head" design.
The key idea of the component system is to allow defining transient run-times, which allow specifying the behavior of a component during a specific run-time. We're writing run-time and not runtime, because a component can run during different moments that is not the runtime of an application.
You can think on this as the npm scripts that define the behavior of a package during different moments of the life of a package, like preinstall, postinstall, prepublish, etc. but for components.
The initial defined run-times are:
Of course, this list is not set in stone, and we can add more run-times in the future.
Because the component system is composable, it allows us to define components that are composed of other components. Here is when the run-times become crucial. If a component uses another one, when a run-time of the parent component is triggered, the same run-time of the child component gets triggered too. This is a bit of a tongue-twister, so let's take a look at a more concrete example.
Imagine we're defining a component called EventGenerator that allows us to generate files for events. Yes, this is an already existing feature of the framework, but
it will serve us an example.
Let's assume that there's an already existing component called FileGenerator that allows writing an arbitrary string to a file that will be placed inside of the project src folder. This component would be defined like this (pseudocode):
// This interface allows the users to provide different implementations for the components
interface FileGenerator {
generate(
folder: string,
filename: string,
content: string
): Effect<...>
}
// Concrete implementation for FileGenerator, could do whatever
// as long as it fulfills the contract of `FileGenerator`.
// Could be a mock one, a remote one, etc...
const FileGenerator = defineComponent<FileGenerator>({
// The actual method
generate(folder, fileName, content) {
// Here we specify that the block inside should only be executed during CLI-time
during(RunTimes.CLI, () => {
// ... actual code to generate the file
})
}
})
Now, if we were to define the EventGenerator component, if we used FileGenerator. We wouldn't need to specify the CLI time, because that's
already done at the FileGenerator component:
interface EventGenerator {
generate(
name: string,
fields: Array<[string, string]>
): Effect<...>
}
const EventGenerator = defineComponent<EventGenerator>({
// Effect.gen allows us to define custom async/await syntax that is extensible
// instead of an async function we use a JS generator function,
// and instead of await, we use the `_` helper and the `yield*` JS keyword.
generate: (name, fields) => Effect.gen(function*(_){
const content = ...// generate the content of the file
// We ask the dependency injection mechanism for the FileGenerator component
const fileGen = yield* _(FileGenerator)
// We run the generate method in the file generator component
yield* _(fileGen.generate("events", `${name}.ts`, content))
})
})
The generator function might impress at first, but it is regular JS syntax, and it is a 1:1 mapping to async/await. Even though it introduces a bit of friction, we believe that the advantages outweight the friction by far. You can check the async/await comparison example on the Effect site.
In the example above, we just used the FileGenerator component, and because that one already defined the CLI-time behavior, we didn't need to do
it ourselves.
This is an extremely powerful idea, because with a little subset of primitive components, we allow extending and customizing Booster apps in inimaginable ways. Power users could define their own database component that allows them to configure, deploy and use a database in their app with a single function call.
These components would get injected into the Booster.config block for now, as it gets loaded when
the application starts.
If a Booster application is configured with some components, it's main executable will get extended with an additional CLI flag --exec that
allows specifying the run-time to execute.
To maintain backwards compatibility, if --exec is not specified, it will run the run-time by default, as it is what happens when one runs a
Booster app nowadays.
This way of working allows taking responsibility out of the Booster CLI tool and allow users to create a regular boost (or any more descriptive name)
script in their package.json file, allowing to execute the CLI components right with pnpm (or their preferred Node package manager):
$ pnpm boost event:generate --name AccountCreated --fields 'amount:number'
This proposal lays the groundwork for a progressive enhancement in Booster Framework's component integration mechanism. This proposal balances the need for advanced functionality and efficiency with the necessity of maintaining existing systems, while giving power users a great extensibility tool, and most importantly, increasing the robustness of the framework overall.