refactor: split from onixbyte/common-toolbox

.editorconfig

@@ -0,0 +1,42 @@
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+max_line_length = 100
+tab_width = 4
+
+[*.less]
+indent_size = 2
+
+[*.proto]
+indent_size = 2
+tab_width = 2
+
+[*.sass]
+indent_size = 2
+
+[*.scss]
+indent_size = 2
+
+[*.vue]
+indent_size = 2
+tab_width = 2
+
+[{*.bash,*.sh,*.zsh}]
+indent_size = 2
+tab_width = 2
+
+[{*.default,*.yaml,*.yml}]
+indent_size = 2
+
+[{*.har,*.jsb2,*.jsb3,*.json,*.jsonc,*.postman_collection,*.postman_collection.json,*.postman_environment,*.postman_environment.json,.babelrc,.eslintrc,.prettierrc,.stylelintrc,.ws-context,jest.config}]
+indent_size = 2
+
+[{*.pb,*.textproto,*.txtpb}]
+indent_size = 2
+tab_width = 2
+
+[{*.ps1,*.psd1,*.psm1}]
+max_line_length = 115

.gitignore

@@ -0,0 +1,42 @@
+target/
+!.mvn/wrapper/maven-wrapper.jar
+!**/src/main/**/target/
+!**/src/test/**/target/
+
+### IntelliJ IDEA ###
+.idea
+.idea/modules.xml
+.idea/jarRepositories.xml
+.idea/compiler.xml
+.idea/libraries/
+*.iws
+*.iml
+*.ipr
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+build/
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store
+
+### Gradle ###
+.gradle

CODE_OF_CONDUCT.md

@@ -0,0 +1,62 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our project
+a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity,
+gender identity and expression, level of experience, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behaviour that contributes to creating a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behaviour by participants include:
+
+- The use of sexualised language or imagery, and unwelcome sexual attention or advances
+- Trolling, insulting, or derogatory comments
+- Personal or political attacks
+- Public or private harassment
+- Publishing others’ private information, such as a physical or electronic address, without
+  explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behaviour and are
+expected to take appropriate and fair corrective action in response to any instances of
+unacceptable behaviour.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits,
+code, wiki edits, issues, and other contributions that do not align with this Code of Conduct, and
+will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is
+representing the project or its community. Examples of representing a project or community include
+using an official project email address, posting via an official social media account, or acting as
+an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or unacceptable behaviour may be reported by contacting the
+project team at [opensource@onixbyte.com](mailto:opensource@onixbyte.com). All complaints will be
+reviewed and investigated and will result in a response that is deemed necessary and appropriate to
+the circumstances. The project team is obligated to maintain confidentiality with regard to the
+reporter of an incident.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face
+temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 1.4, available at https://www.contributor-covenant.org/version/1/4/
+

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to OnixByte Toolbox
+
+We appreciate your interest in contributing to our Java Enterprise Utility Library. Contributions
+are welcome in various forms such as code, documentation, bug reports, and test cases. To ensure a
+smooth collaboration, please follow the guidelines outlined below.
+
+## Getting Started
+
+The OnixByte Toolbox is an open-source Java library designed to ease Java enterprise
+application development. It is built with Java 17, and we require contributors to use OpenJDK 17.
+
+## Development Setup
+
+There is no need for manual setup beyond ensuring you have JDK 17 and a stable internet connection.
+Our project uses Gradle Wrapper for building, simplifying the setup process.
+
+```shell
+./gradlew build
+```
+
+## Branching Strategy
+
+We follow the `git-flow` branching model. Contributors should fork this repository and create their
+work on separate branches prefixed with `feature/` or `hotfix/` as appropriate.
+
+## Code Style
+
+Please adhere to the coding standards specified in our `.editorconfig` file in the root of
+the repository. Consistent style helps in maintaining readability and uniformity across the codebase.
+
+## Commit Messages
+
+We require that commit messages follow this structure:
+
+```text
+type[(scope)]: subject
+
+[body]
+
+[BREAKING CHANGE: breaking changes]
+```
+
+This format helps in auto-generating changelogs and understanding the purpose behind changes.
+
+## Submitting Contributions
+
+1. Fork the repository.
+2. Create a branch: `git checkout -b feature/my-new-feature` or `git checkout -b hotfix/my-fix`.
+3. Make your changes and commit them.
+4. Push to the branch: `git push origin feature/my-new-feature`.
+5. Create a Pull Request with a succinct subject and a detailed body.
+
+## Testing
+
+We encourage using JUnit Jupiter for unit and integration tests. Pull Requests with accompanying
+test reports are prioritised for review and merging.
+
+## License
+
+By contributing to the OnixByte Toolbox, you agree that your contributions will be licensed under the
+MIT license. If you do not agree to this, please refrain from contributing.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 OnixByte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,74 @@
+# Tuple
+
+## Introduction
+
+The `tuple` module provides simple and efficient implementations of mutable and immutable bi-tuples and tri-tuples. These tuples allow you to group two or three values together without creating custom classes, supporting convenient usage in various programming scenarios.
+
+## Features
+
+- Immutable and mutable versions of bi-tuples (pairs) and tri-tuples (triplets);
+- Factory method of() for easy instantiation of all tuple types;
+- Simple, lightweight implementation compatible with standard Java usage;
+- Clear distinction between mutable and immutable tuples for flexibility.
+
+## Installation
+
+### Maven
+
+Add the following dependency to your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>com.onixbyte</groupId>
+    <artifactId>tuple</artifactId>
+    <version>$artefactVersion</version>
+</dependency>
+```
+
+### Gradle
+
+#### Version Catalogue
+
+Add the following codes to you `gradle/libs.versions.toml`:
+
+```toml
+[version]
+onixbyteToolbox = "$artefactVersion"
+
+[libraries]
+onixbyteToolbox-tuple = { group = "com.onixbyte", name = "tuple", version.ref = "onixbyteToolbox" }
+```
+
+Then add the following codes to your `build.gradle.kts` or `build.gradle` dependencies block:
+
+```kotlin
+implementation(libs.onixbyteToolbox.tuple)
+```
+
+```groovy
+implementation libs.onixbyteToolbox.tuple
+```
+
+#### Kotlin DSL
+
+Add the following line to your `build.gradle.kts` dependencies block:
+
+```kotlin
+implementation("com.onixbyte:tuple:$artefactVersion")
+```
+
+#### Groovy DSL
+
+Add the following line to your `build.gradle` dependencies block:
+
+```groovy
+implementation 'com.onixbyte:tuple:${artefactVersion}'
+```
+
+## Dependencies
+
+This module has no external dependencies other than the standard Java SDK.
+
+## Acknowledgement
+
+Thanks to all contributors who helped develop this module, improving its design, performance, and documentation over time.

build.gradle.kts

@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) 2024-2026 OnixByte
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import java.net.URI
+
+plugins {
+    java
+    id("java-library")
+    id("maven-publish")
+    id("signing")
+}
+
+val tupleVersion: String by project
+
+version = tupleVersion
+val projectUrl: String by project
+val projectGithubUrl: String by project
+val licenseName: String by project
+val licenseUrl: String by project
+
+repositories {
+    mavenCentral()
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+    withSourcesJar()
+    withJavadocJar()
+}
+
+tasks.withType<JavaCompile> {
+    options.encoding = "UTF-8"
+}
+
+tasks.withType<Jar> {
+    exclude("logback.xml")
+}
+
+dependencies {
+    compileOnly(libs.slf4j)
+    implementation(libs.logback)
+    testImplementation(platform(libs.junit.bom))
+    testImplementation(libs.junit.jupiter)
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+
+publishing {
+    publications {
+        create<MavenPublication>("tuple") {
+            groupId = group.toString()
+            artifactId = "tuple"
+            version = tupleVersion
+
+            pom {
+                name = "OnixByte Tuple"
+                description =
+                    "The tuple module is designed to offer a convenient and efficient way to handle grouped data."
+                url = projectUrl
+
+                licenses {
+                    license {
+                        name = licenseName
+                        url = licenseUrl
+                    }
+                }
+
+                scm {
+                    connection = "scm:git:git://github.com:onixbyte/onixbyte-toolbox.git"
+                    developerConnection = "scm:git:git://github.com:onixbyte/onixbyte-toolbox.git"
+                    url = projectGithubUrl
+                }
+
+                developers {
+                    developer {
+                        id = "zihluwang"
+                        name = "Zihlu Wang"
+                        email = "really@zihlu.wang"
+                        timezone = "Asia/Hong_Kong"
+                    }
+
+                    developer {
+                        id = "siujamo"
+                        name = "Siu Jam'o"
+                        email = "jamo.siu@outlook.com"
+                        timezone = "Asia/Shanghai"
+                    }
+                }
+            }
+
+            from(components["java"])
+
+            signing {
+                setRequired(project.hasProperty("signing.keyId"))
+                sign(publishing.publications["tuple"])
+            }
+        }
+
+        repositories {
+            maven {
+                name = "sonatypeNexus"
+                url = URI(providers.gradleProperty("repo.maven-central.host").get())
+                credentials {
+                    username = providers.gradleProperty("repo.maven-central.username").get()
+                    password = providers.gradleProperty("repo.maven-central.password").get()
+                }
+            }
+        }
+    }
+}

gradle.properties

@@ -0,0 +1,27 @@
+#
+# Copyright (c) 2024-2025 OnixByte
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+#
+
+artefactVersion=3.3.0
+projectUrl=https://github.com/onixbyte/onixbyte-tuple
+projectGithubUrl=git@github.com:onixbyte/onixbyte-tuple.git
+licenseName=MIT
+licenseUrl=

gradle/libs.versions.toml

@@ -0,0 +1,10 @@
+[versions]
+slf4j = "2.0.17"
+logback = "1.5.26"
+junit = "5.11.4"
+
+[libraries]
+slf4j = { group = "org.slf4j", name = "slf4j-api", version.ref = "slf4j" }
+logback = { group = "ch.qos.logback", name = "logback-classic", version.ref = "logback" }
+junit-bom = { group = "org.junit", name = "junit-bom", version.ref = "junit" }
+junit-jupiter = { group = "org.junit.jupiter", name = "junit-jupiter", version.ref = "junit" }

gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-all.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

gradlew

@@ -0,0 +1,252 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
+' "$PWD" ) || exit
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        org.gradle.wrapper.GradleWrapperMain \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"

gradlew.bat

@@ -0,0 +1,94 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
+
+@if "%DEBUG%"=="" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if %ERRORLEVEL% equ 0 goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if %ERRORLEVEL% equ 0 goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

settings.gradle.kts

@@ -0,0 +1 @@
+rootProject.name = "onixbyte-tuple"

src/main/java/com/onixbyte/tuple/ImmutableTriple.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2024-2026 OnixByte
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package com.onixbyte.tuple;
+
+/**
+ * Represents an immutable triple of three elements, referred to as 'left', 'middle', and 'right'.
+ * This class provides a generic way to group three values without the need to create a custom class
+ * for each specific combination.
+ * <p>
+ * The generic types {@code L}, {@code M}, and {@code R} denote the types of the left, middle, and
+ * right elements, respectively. Instances of this class are immutable once created.
+ *
+ * @param <L>    the type of the left element
+ * @param <M>    the type of the middle element
+ * @param <R>    the type of the right element
+ * @param left   the left element of this triple
+ * @param middle the middle element of this triple
+ * @param right  the right element of this triple
+ * @author siujamo
+ * @author zihluwang
+ */
+public record ImmutableTriple<L, M, R>(
+    L left,
+    M middle,
+    R right
+) {
+
+    /**
+     * Creates a new {@code ImmutableTriple} with the specified left, middle, and right elements.
+     *
+     * @param <L>    the type of the left element
+     * @param <M>    the type of the middle element
+     * @param <R>    the type of the right element
+     * @param left   the left element
+     * @param middle the middle element
+     * @param right  the right element
+     * @return a new {@code ImmutableTriple} containing the specified elements
+     */
+    public static <L, M, R> ImmutableTriple<L, M, R> of(L left, M middle, R right) {
+        return new ImmutableTriple<>(left, middle, right);
+    }
+}

src/main/java/com/onixbyte/tuple/ImmutableTuple.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2024-2026 OnixByte
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package com.onixbyte.tuple;
+
+/**
+ * Represents an immutable pair of two elements, referred to as 'left' and 'right'. This class
+ * provides a simple way to group two values without the need to create a custom class for each
+ * specific pair.
+ * <p>
+ * The generic types {@code L} and {@code R} denote the types of the left and right elements,
+ * respectively. Instances of this class are immutable once created.
+ *
+ * @param <L>   the type of the left element
+ * @param <R>   the type of the right element
+ * @param left  the left element of this tuple
+ * @param right the right element of this tuple
+ * @author siujamo
+ * @author zihluwang
+ */
+public record ImmutableTuple<L, R>(
+    L left,
+    R right
+) {
+
+    /**
+     * Creates a new {@code ImmutableTuple} with the specified left and right elements.
+     *
+     * @param <L>   the type of the left element
+     * @param <R>   the type of the right element
+     * @param left  the left element
+     * @param right the right element
+     * @return a new {@code ImmutableTuple} containing the specified elements
+     */
+    public static <L, R> ImmutableTuple<L, R> of(L left, R right) {
+        return new ImmutableTuple<>(left, right);
+    }
+}

src/main/java/com/onixbyte/tuple/Triple.java

@@ -0,0 +1,168 @@
+/*
+ * Copyright (c) 2024-2026 OnixByte
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package com.onixbyte.tuple;
+
+import java.util.Objects;
+
+/**
+ * Represents a mutable triple of three elements, referred to as 'left', 'middle' and 'right'.
+ * This class provides a way to group three values of different types.
+ * <p>
+ * The generic types {@code L}, {@code M} and {@code R} denote the types of the left, middle and
+ * right elements respectively.
+ *
+ * @param <L> the type of the left element
+ * @param <M> the type of the middle element
+ * @param <R> the type of the right element
+ * @author siujamo
+ * @author zihluwang
+ */
+public final class Triple<L, M, R> {
+
+    private L left;
+    private M middle;
+    private R right;
+
+    /**
+     * Constructs a new {@code Triple} with the given left, middle and right elements.
+     *
+     * @param left   the left element
+     * @param middle the middle element
+     * @param right  the right element
+     */
+    public Triple(L left, M middle, R right) {
+        this.left = left;
+        this.middle = middle;
+        this.right = right;
+    }
+
+    /**
+     * Retrieves the left element of the triple.
+     *
+     * @return the left element
+     */
+    public L getLeft() {
+        return left;
+    }
+
+    /**
+     * Sets the left element of the triple.
+     *
+     * @param left the new left element
+     */
+    public void setLeft(L left) {
+        this.left = left;
+    }
+
+    /**
+     * Retrieves the middle element of the triple.
+     *
+     * @return the middle element
+     */
+    public M getMiddle() {
+        return middle;
+    }
+
+    /**
+     * Sets the middle element of the triple.
+     *
+     * @param middle the new middle element
+     */
+    public void setMiddle(M middle) {
+        this.middle = middle;
+    }
+
+    /**
+     * Retrieves the right element of the triple.
+     *
+     * @return the right element
+     */
+    public R getRight() {
+        return right;
+    }
+
+    /**
+     * Sets the right element of the triple.
+     *
+     * @param right the new right element
+     */
+    public void setRight(R right) {
+        this.right = right;
+    }
+
+    /**
+     * Checks if this {@code Triple} is equal to the specified object. Two {@code Triple}s are
+     * considered equal if their left, middle and right elements are equal.
+     *
+     * @param object the object to compare with
+     * @return {@code true} if the objects are equal, {@code false} otherwise
+     */
+    @Override
+    public boolean equals(Object object) {
+        if (!(object instanceof Triple<?, ?, ?> triple)) return false;
+        return Objects.equals(left, triple.left) &&
+            Objects.equals(middle, triple.middle) &&
+            Objects.equals(right, triple.right);
+    }
+
+    /**
+     * Calculates the hash code for this {@code Triple} based on its left, middle and
+     * right elements.
+     *
+     * @return the hash code value for this object
+     */
+    @Override
+    public int hashCode() {
+        return Objects.hash(left, middle, right);
+    }
+
+    /**
+     * Returns a string representation of this {@code Triple}, including its left, middle and
+     * right elements.
+     *
+     * @return a string representation of the object
+     */
+    @Override
+    public String toString() {
+        return "Triple{" +
+            "left=" + left +
+            ", middle=" + middle +
+            ", right=" + right +
+            '}';
+    }
+
+    /**
+     * Factory method to create a new {@code Triple} instance with the given left, middle and right elements.
+     *
+     * @param left   the left element
+     * @param middle the middle element
+     * @param right  the right element
+     * @param <L>    the type of the left element
+     * @param <M>    the type of the middle element
+     * @param <R>    the type of the right element
+     * @return a new {@code Triple} instance
+     */
+    public static <L, M, R> Triple<L, M, R> of(L left, M middle, R right) {
+        return new Triple<>(left, middle, right);
+    }
+}

src/main/java/com/onixbyte/tuple/Tuple.java

@@ -0,0 +1,149 @@
+/*
+ * Copyright (c) 2024-2026 OnixByte
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package com.onixbyte.tuple;
+
+import java.util.Objects;
+
+/**
+ * Represents an ordered pair of elements, where the first element is of type {@code L} and the
+ * second is of type {@code R}. This class provides a simple way to group two related
+ * values together.
+ * <p>
+ * The class is mutable, allowing the values of the left and right elements to be changed
+ * after creation. It also overrides the {@code equals}, {@code hashCode}, and {@code toString}
+ * methods to provide meaningful comparisons and string representations.
+ *
+ * @param <L> the type of the left element
+ * @param <R> the type of the right element
+ * @author siujamo
+ * @author zihluwang
+ */
+public final class Tuple<L, R> {
+
+    private L left;
+    private R right;
+
+    /**
+     * Constructs a new {@code Tuple} with the specified left and right elements.
+     *
+     * @param left  the left element to be stored in the tuple
+     * @param right the right element to be stored in the tuple
+     */
+    public Tuple(L left, R right) {
+        this.left = left;
+        this.right = right;
+    }
+
+    /**
+     * Retrieves the left element of the tuple.
+     *
+     * @return the left element of the tuple
+     */
+    public L getLeft() {
+        return left;
+    }
+
+    /**
+     * Sets the left element of the tuple to the specified value.
+     *
+     * @param left the new value for the left element of the tuple
+     */
+    public void setLeft(L left) {
+        this.left = left;
+    }
+
+    /**
+     * Retrieves the right element of the tuple.
+     *
+     * @return the right element of the tuple
+     */
+    public R getRight() {
+        return right;
+    }
+
+    /**
+     * Sets the right element of the tuple to the specified value.
+     *
+     * @param right the new value for the right element of the tuple
+     */
+    public void setRight(R right) {
+        this.right = right;
+    }
+
+    /**
+     * Compares this {@code Tuple} with the specified object for equality.
+     * <p>
+     * Two {@code Tuple}s are considered equal if they are of the same type and their left and
+     * right elements are equal according to their respective {@code equals} methods.
+     *
+     * @param object the object to compare with this {@code Tuple}
+     * @return {@code true} if the specified object is equal to this {@code Tuple},
+     * {@code false} otherwise
+     */
+    @Override
+    public boolean equals(Object object) {
+        if (!(object instanceof Tuple<?, ?> tuple)) return false;
+        return Objects.equals(left, tuple.left) && Objects.equals(right, tuple.right);
+    }
+
+    /**
+     * Returns a hash code value for the {@code Tuple}.
+     * <p>
+     * The hash code is calculated based on the hash codes of the left and right elements.
+     *
+     * @return a hash code value for this {@code Tuple}
+     */
+    @Override
+    public int hashCode() {
+        return Objects.hash(left, right);
+    }
+
+    /**
+     * Returns a string representation of the {@code Tuple}.
+     * <p>
+     * The string representation consists of the class name, followed by the values of
+     * the left and right elements in the format {@code "Tuple{left=value1, right=value2}"}.
+     *
+     * @return a string representation of the {@code Tuple}
+     */
+    @Override
+    public String toString() {
+        return "Tuple{" +
+            "left=" + left +
+            ", right=" + right +
+            '}';
+    }
+
+    /**
+     * Creates a new {@code Tuple} with the specified left and right elements.
+     *
+     * @param <L>   the type of the left element
+     * @param <R>   the type of the right element
+     * @param left  the left element
+     * @param right the right element
+     * @return a new {@code Tuple} containing the specified elements
+     */
+    public static <L, R> Tuple<L, R> of(L left, R right) {
+        return new Tuple<>(left, right);
+    }
+}