fix: add transactions and isTransactionsEnabled to ClientWriteOptions

[curfew-marathon]

Summary

ClientWriteOptions.disableTransactions(boolean) and its getter disableTransactions() suffer from a double-negative API design that makes call sites ambiguous — it is not obvious whether to pass true or false to achieve a given outcome, and the getter name reads confusingly in conditionals.

This PR introduces a cleaner API alongside the existing methods, maintaining full backwards compatibility.

New API

transactions(boolean enabled)

A positively-framed alternative to disableTransactions(boolean) — pass true to enable transactions (the default), false to disable them:

// Before — what does true mean here?
new ClientWriteOptions().disableTransactions(true)

// After — unambiguous
new ClientWriteOptions().transactions(false)

isTransactionsEnabled()

A positively-framed alternative to disableTransactions() (the getter), consistent with standard Java boolean getter naming conventions:

// Before
if (options.disableTransactions()) { ... }

// After
if (!options.isTransactionsEnabled()) { ... }

Backwards compatibility

No existing call sites are broken. Both existing methods remain fully functional and are kept as-is alongside the new API.

Related issues

Closes #200
Relates to openfga/sdk-generator#121 (generator-wide tracking issue; left open for the other SDKs)

Summary by CodeRabbit

• New Features

  • Added an explicit option to enable or disable transactions when writing data.
  • Transaction settings now default to enabled, making the behavior clearer and easier to configure.

• Bug Fixes

  • Improved consistency in write options so transaction-related settings behave predictably.
  • Updated option handling to keep existing defaults for chunk size and other write settings.

[coderabbitai]

Walkthrough

ClientWriteOptions replaces the nullable Boolean disableTransactions field with a primitive boolean transactionsEnabled defaulting to true. Two new methods (transactions(boolean) and isTransactionsEnabled()) are added; the existing disableTransactions methods now invert transactionsEnabled. JavaDoc is expanded throughout the class.

ClientWriteOptions Transaction API

Layer / File(s)	Summary
Field model and transaction API src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java	Internal field changes from Boolean disableTransactions to primitive boolean transactionsEnabled = true. New transactions(boolean) and isTransactionsEnabled() methods added; disableTransactions(boolean) and disableTransactions() now derive their effect by inverting transactionsEnabled. JavaDoc updated for all public setters/getters including chunk size and tuple handling options.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• refactor(api): Improve clarity of transaction options in ClientWriteOptions #200: This PR directly addresses the request to improve transaction option clarity in ClientWriteOptions by introducing affirmative transactionsEnabled semantics and explicit getter/setter methods.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately highlights the main API change: adding transactions and isTransactionsEnabled to ClientWriteOptions.
Docstring Coverage	✅ Passed	Docstring coverage is 92.86% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/deprecate-disable-transactions

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov-commenter]

Codecov Report

❌ Patch coverage is 50.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 38.67%. Comparing base (62139f7) to head (5c36649).

Files with missing lines	Patch %	Lines
...nfga/sdk/api/configuration/ClientWriteOptions.java	50.00%	3 Missing ⚠️

❌ Your project status has failed because the head coverage (38.67%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #352      +/-   ##
============================================
- Coverage     38.69%   38.67%   -0.02%     
  Complexity     1289     1289              
============================================
  Files           198      198              
  Lines          7704     7707       +3     
  Branches        900      900              
============================================
  Hits           2981     2981              
- Misses         4576     4579       +3     
  Partials        147      147              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR improves the ClientWriteOptions public API by introducing a positively framed transactions toggle and boolean getter, while deprecating the existing double-negative disableTransactions setter/getter to reduce ambiguity at call sites and provide a clearer migration path.

Changes:

• Added transactions(boolean enabled) as the positively framed replacement for disableTransactions(boolean).
• Added isTransactionsEnabled() as the positively framed replacement for disableTransactions().
• Deprecated both legacy methods with Javadoc describing the migration and inverted semantics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Siddhant-K-code]

Two follow-ups I found:

1. This PR deprecates disableTransactions(...), but the public guidance still teaches it. The README write examples still use .disableTransactions(false) / .disableTransactions(true), and the OpenFgaClient.write Javadocs still describe mode selection with options.disableTransactions(). Since this PR introduces the replacement API, can we update those examples/docs to transactions(true/false) and isTransactionsEnabled() so users do not copy newly deprecated methods?

2. In ClientWriteOptions, the transactionChunkSize Javadoc says the value “must be greater than zero,” but the setter accepts any int and getTransactionChunkSize() silently falls back to 1 when the stored value is <= 0. Could we either reject non-positive values there or document the actual fallback behavior?

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java (1)

71-103: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add direct tests for the new/legacy inversion contract.

Codecov already flags this block as uncovered, and this API is easy to regress because two setters now mutate the same state with opposite semantics. A focused test should cover the default state plus transactions(false) -> disableTransactions() == true and disableTransactions(true) -> isTransactionsEnabled() == false.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java`
around lines 71 - 103, Add focused tests for the opposite-semantic setters in
ClientWriteOptions to lock down the inversion contract and default behavior.
Cover the default state, then verify that calling transactions(false) makes
disableTransactions() return true, and that calling disableTransactions(true)
makes isTransactionsEnabled() return false. Use the ClientWriteOptions methods
transactions(boolean), isTransactionsEnabled(), and
disableTransactions(boolean/()) directly so the shared state mutation is
exercised.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java`:
- Around line 112-129: The ClientWriteOptions transactionChunkSize contract is
inconsistent: transactionChunkSize(int) currently allows zero/negative values
and getTransactionChunkSize() masks them by returning 1. Update the setter to
enforce the documented “greater than zero” requirement by rejecting invalid
values (or, if you prefer the fallback behavior, relax the Javadoc to match it)
and keep getTransactionChunkSize() aligned with that public contract.

---

Nitpick comments:
In `@src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java`:
- Around line 71-103: Add focused tests for the opposite-semantic setters in
ClientWriteOptions to lock down the inversion contract and default behavior.
Cover the default state, then verify that calling transactions(false) makes
disableTransactions() return true, and that calling disableTransactions(true)
makes isTransactionsEnabled() return false. Use the ClientWriteOptions methods
transactions(boolean), isTransactionsEnabled(), and
disableTransactions(boolean/()) directly so the shared state mutation is
exercised.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bbb3a37f-c598-4add-850a-bc2cfd286ff0

📥 Commits

Reviewing files that changed from the base of the PR and between fb6c59f and 244558f.

📒 Files selected for processing (1)

• src/main/java/dev/openfga/sdk/api/configuration/ClientWriteOptions.java

[rhamzeh]

@curfew-marathon 👏🏽 for finally tackling this item (openfga/sdk-generator#121) from Jan 2023.

I like your solution better than what that issue says, can you update the issue accordingly?