{"id":37016279,"url":"https://github.com/soulcodingmatt/equilibrium","last_synced_at":"2026-04-02T13:39:05.868Z","repository":{"id":298896575,"uuid":"964022929","full_name":"soulcodingmatt/equilibrium","owner":"soulcodingmatt","description":"A Java annotation processor for generating DTOs and other value container classes.","archived":false,"fork":false,"pushed_at":"2026-03-21T23:17:06.000Z","size":337,"stargazers_count":2,"open_issues_count":10,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-22T03:54:05.034Z","etag":null,"topics":["annotation","annotation-processing","annotation-processor","annotations","data-transfer","data-transfer-object","dto","dto-generator","dtos","generator","record","records","transfer-object","transfer-objects","value-object","vos"],"latest_commit_sha":null,"homepage":"https://central.sonatype.com/artifact/io.github.soulcodingmatt/equilibrium","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soulcodingmatt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-10T15:12:55.000Z","updated_at":"2026-03-21T13:34:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"7e200c4e-d28f-4e8a-8cd0-ebc1c73a7a6f","html_url":"https://github.com/soulcodingmatt/equilibrium","commit_stats":null,"previous_names":["soulcodingmatt/equilibrium"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/soulcodingmatt/equilibrium","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulcodingmatt%2Fequilibrium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulcodingmatt%2Fequilibrium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulcodingmatt%2Fequilibrium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulcodingmatt%2Fequilibrium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soulcodingmatt","download_url":"https://codeload.github.com/soulcodingmatt/equilibrium/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soulcodingmatt%2Fequilibrium/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation","annotation-processing","annotation-processor","annotations","data-transfer","data-transfer-object","dto","dto-generator","dtos","generator","record","records","transfer-object","transfer-objects","value-object","vos"],"created_at":"2026-01-14T01:49:55.465Z","updated_at":"2026-04-02T13:39:05.861Z","avatar_url":"https://github.com/soulcodingmatt.png","language":"Java","funding_links":["https://www.buymeacoffee.com/soulcodingmatt"],"categories":[],"sub_categories":[],"readme":"# Project Equilibrium\n\n#### **Compile-time** generation of DTOs, Java records, and value objects — fast, type-safe, **no reflection**.\n\n![Project Equilibrium summary output](docs/images/equilibrium-logo-v1.0.0.png)\n\n[![Maven Central](https://img.shields.io/maven-central/v/io.github.soulcodingmatt/equilibrium.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/io.github.soulcodingmatt/equilibrium)\n[![License](https://img.shields.io/github/license/soulcodingmatt/equilibrium)](https://github.com/soulcodingmatt/equilibrium/blob/main/LICENSE)\n\nAnnotate your domain model once; Project Equilibrium’s **annotation processor** generates matching **transfer types** so names, packages, and structure stay aligned. You still map *data* however you like (constructors, MapStruct, hand-written code) — this project focuses on **generating the shapes** with compile-time validation and optional Jakarta constraints on generated members.\n\nIf you find this project useful, consider supporting me ☕  \n[![Buy Me a Coffee](https://img.shields.io/badge/-Buy%20me%20a%20coffee-orange?logo=buy-me-a-coffee\u0026logoColor=white)](https://www.buymeacoffee.com/soulcodingmatt)\n\n---\n\n## Why Project Equilibrium?\n\nHand-maintained DTOs and cousins often mean:\n\n- 😩  Boilerplate and copy-paste types that drift from the domain\n- 💥  Surprises at runtime** when something no longer lines up\n- 🔧  Refactors that sprawl across many files\n\n**Project Equilibrium pushes that work to compilation:** generated Java sources, consistent defaults, and errors when configuration is impossible — not when a user hits an edge case.\n\n✔ No reflection for generation  \n✔ No extra runtime library for *creating* those type definitions  \n✔ Full type safety on the processor’s configuration surface  \n✔ Clean model: annotate the domain, consume generated types\n\nDeeper rationale, trade-offs, and “when not to use it”: [Why Project Equilibrium?](docs/why-equilibrium.md).\n\n---\n\n## Quickstart\n\n**1. Add the dependency** (version from [Maven Central](https://central.sonatype.com/artifact/io.github.soulcodingmatt/equilibrium)):\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.soulcodingmatt\u003c/groupId\u003e\n  \u003cartifactId\u003eequilibrium\u003c/artifactId\u003e\n  \u003cversion\u003e\u003c!-- latest --\u003e\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**2. Register the processor** and set defaults (packages / postfixes). Full `pom.xml` snippet: [Build tooling](docs/build-tooling.md).\n\n**3. Mark the domain class:**\n\n```java\nimport io.github.soulcodingmatt.equilibrium.annotations.dto.GenerateDto;\n\n@GenerateDto\npublic class User {\n    private String name;\n    private int age;\n    // getters / setters\n}\n```\n\n**4. Compile** — use the generated `UserDto` (or your configured package/postfix).\n\n👉 Extended copy-paste flow: [Quickstart](docs/quickstart.md).\n\n🧪 **Working example project:** [equilibrium-test](https://github.com/soulcodingmatt/equilibrium-test) — a ready-to-clone project that demonstrates how the annotations work in practice.\n\n---\n\n## How it works\n\nProject Equilibrium runs as a standard **Java annotation processor**: it emits **plain source files** during `javac`, so builds stay predictable and debuggable. Details: [How it works](docs/how-it-works.md).\n\n---\n\n## Works well with other tools\n\nUse Project Equilibrium **alongside** mappers and frameworks — for example **MapStruct** for field-to-field mapping between types you already have. Summary and build notes: [Ecosystem](docs/ecosystem.md).\n\n---\n\n## Documentation\n\n**Index of all guides:** [docs/README.md](docs/README.md)\n\n|                         Topic                         |                                    Guide                                     |\n|-------------------------------------------------------|------------------------------------------------------------------------------|\n| Why / when / benefits                                 | [Why Project Equilibrium?](docs/why-equilibrium.md)                          |\n| Quickstart                                            | [docs/quickstart.md](docs/quickstart.md)                                     |\n| Maven, IDE, Lombok, Gradle                            | [docs/build-tooling.md](docs/build-tooling.md)                               |\n| Compiler `-A` options                                 | [docs/configuration.md](docs/configuration.md)                               |\n| All annotations (generate / ignore / nest / validate) | [docs/annotations-reference.md](docs/annotations-reference.md)               |\n| MapStruct and complements                             | [docs/ecosystem.md](docs/ecosystem.md)                                       |\n| DTO builder + Lombok                                  | [docs/dto-builder-pattern.md](docs/dto-builder-pattern.md)                   |\n| Experimental Jakarta validation                       | [docs/experimental-validation.md](docs/experimental-validation.md)           |\n| DTOs + interfaces (wrapper pattern)                   | [docs/dto-interface-pattern.md](docs/dto-interface-pattern.md)               |\n| Custom fields and methods on generated DTOs           | [docs/custom-fields-and-methods.md](docs/custom-fields-and-methods.md)       |\n| Troubleshooting and pitfalls                          | [docs/troubleshooting-and-pitfalls.md](docs/troubleshooting-and-pitfalls.md) |\n\n---\n\n## Commercial use (GPL)\n\nYou can use this annotation processor in **commercial or closed-source projects** when it runs only at **compile time** and is not shipped inside your artifacts. In that typical setup, **GPL-3.0 does not require you to open-source your own application code**.\n\n## Requirements\n\n- **Java 21** or higher (the processor targets the Java 21 language level)\n- A build tool that can **resolve dependencies** from Maven Central (or your repository) and run **annotation processing** (for example Maven 3.x or Gradle 8.x)\n\nOlder tool versions may work but are not validated. **Building Project Equilibrium** uses Maven in this repository; consuming projects do not need to run this project’s `pom.xml`.\n\n## Features\n\n- Generation of DTOs, records, and VOs with `@GenerateDto`, `@GenerateRecord`, and `@GenerateVo` (including **multiple generations per source class** via `id`, `pkg`, and `name`)\n- **Global defaults** via compiler options (`-Aequilibrium.*`), with **per-annotation overrides** where supported\n- Field exclusion with `@IgnoreDto`, `@IgnoreRecord`, `@IgnoreVo`, and `@IgnoreAll`, including **selective exclusion** with `ids` when you generate several variants from one class\n- **Nested DTO wiring** with `@NestedMapping` (class reference) and **`@NestedDtoMapping`** (string class names, including **per–DTO-id** mappings when you use multiple `@GenerateDto` ids)\n- Optional **Lombok `@SuperBuilder`** on generated DTOs (`@GenerateDto(builder=true)`), plus **`@DtoBuilderDefault`** for builder default values where applicable\n- Field type preservation (including generics) and **inheritance**: generated types include fields from superclasses\n- Optional **experimental** compile-time validation helpers (`@ValidateDto`, `@ValidateRecord`, `@ValidateVo`) that emit Jakarta Bean Validation constraints on generated members\n- **Compile-time summary output**: optional banner and statistics — see [Configuration](docs/configuration.md) (compile output)\n\n## Consuming vs building this project\n\n**In your application:** add the published Maven dependency (`artifactId` **equilibrium**), put the processor on **`annotationProcessorPaths`**, and pass **`-Aequilibrium.*`** flags (or rely on annotation parameters) for packages and postfixes. Any tool that resolves Maven artifacts and runs Java annotation processing can consume the JAR.\n\n**From this repository:** build with **Maven** (`mvn verify` or `mvn install`) to compile, run tests, and produce the same artifact layout this project publishes — including metadata stamped from the POM. Porting that to another build system means replicating dependency scopes, processor path, and resource packaging.\n\n## 🤖 Usage of AI\n\nAI tools were used throughout the development of this project — including prototyping, testing, bug fixing, and refactoring.\nThe primary author has over 25 years of experience with Java and more than 10 years as a professional software developer. AI was used as a productivity tool, not as a substitute for expertise.\nAll architectural decisions, design, and final validation were carried out by a human. AI assisted the process, but responsibility and ownership remain human.\n\nUsing tools that improve efficiency is a natural part of modern software development.\n\n## Contributing\n\nContributions are welcome — issues, ideas, and pull requests.\n\n## Changelog\n\nSee [**CHANGELOG**](CHANGELOG.md).\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 — see the [LICENSE](LICENSE) file.\n\n## Contact\n\nFor questions or issues, please use the repository’s issue tracker.\n\n## Third-party software\n\nDependency names, how they are used (for example provided, test, or tooling scopes), and license families are documented in **[NOTICE](NOTICE)**. The published JAR includes the same text as **`META-INF/NOTICE`**. For exact artifact versions, see **`pom.xml`**.\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoulcodingmatt%2Fequilibrium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoulcodingmatt%2Fequilibrium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoulcodingmatt%2Fequilibrium/lists"}