intuit/hooks

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: