Hooks is a little module for plugins, in Kotlin

---

Hooks represent "pluggable" points in a software model. They provide a mechanism for tapping into such points to get updates, or apply additional functionality to some typed object. Included in the hooks library are:

• A variety of hooks to support different plugin behavior: Basic, Waterfall, Bail, Loop
• Asynchronous support built on Kotlin coroutines
• Support for additional hook context and interceptors

Along with the base library, we created a Kotlin symbol processor to enable hooks to be created with a simple typed-based DSL, limiting the redundancy and overhead required to subclass a hook.

Visit our site for information about how to use hooks.

Inspiration

At Intuit, we're big fans of tapable. We use it in some of our core systems to enable teams to augment and extend our frameworks to solve their customer problems. Since our backend systems are primarily JVM-based, we really missed tapable when working in service code. Hooks is our implementation of tapable as a library for the JVM plus an Arrow Meta Compiler Plugin to make it easier to use.

Structure

• hooks - The actual implementation of the hooks
• processor - A Kotlin Symbol Processor that generates hook subclasses for you
• gradle-plugin - A Gradle plugin to make using the processor easier
• maven-plugin - A Maven Kotlin plugin extension to make using the processor easier
• example-library - A library that exposes extension points for consumers using the hooks' call function
• example-application - The Application that demonstrates extending a library by calling the hooks' tap function

🍻 Contributing 🍻

Feel free to make an issue or open a pull request if you have an improvement and new plugin to propose!

Make sure to read our code of conduct.

🔨 Start Developing 🔨

To get set up, fork and clone the project.

Build

Build and verify all checks:

./gradlew build

Publish locally to use in other projects:

./gradlew publishToMavenLocal

Test

Recompile changes and run all tests:

./gradlew test

Run example app

./gradlew run

Cleaning

./gradlew clean

Linting

Linting is done with ktlint and configured using JLLeitschuh's ktlint Gradle plugin.

Format code according to linting standards:

./gradlew ktlintFormat

Verify code meets linting standards:

./gradlew ktlintCheck

API Validation

To ensure that binary compatibility is maintained across non-breaking releases, the public API is validated using the Kotlin binary compatibility validator tool.

Update the API dumps:

./gradlew apiDump

Verify the public API matches the API dumps:

./gradlew apiCheck

Documentation

The docs site is built using the Orchid tool and takes inspiration from the stikt.io docs site.

Run the docs locally:

./gradlew orchidServe

The knit tool is also used to generate tests driven from markdown snippets to ensure documentation is maintained and up-to-date.

Update all generated markdown tests:

./gradlew knit

Verify the generated tests match the latest markdown changes:

./gradlew knitCheck

Versioning

This project follows the semantic versioning strategy and uses Auto to automate releases on CI. PRs must be labeled with an appropriate Auto label to denote what type of release should occur when merged. With the binary compatibility validator tool, we can follow this set of rules to determine release types:

• Red on an API diff is breaking and requires a major bump
• Green on an API diff is a new feature and requires a minor bump
• No API diff, but has a code change requires a patch bump
• Else, apply the corresponding label for documentation or build, etc.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Jeremiah Zucker ⚠️ 💻 📖 🚇

David Stone 📖 ⚠️ 💻

Andrew Lisowski 📖 🚇 ⚠️ 💻

Kelly Harrop 🎨

brocollie08 ⚠️ 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

License

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).