feat: add support for write conflict settings

[phamhieu]

Description

Adds support for write conflict options in the JavaScript SDK to handle duplicate writes and missing deletes, as introduced in OpenFGA v1.10.0.

This implementation adds onDuplicateWrites and onMissingDeletes options to control behavior when:

• Writing a tuple that already exists (onDuplicateWrites)
• Deleting a tuple that doesn't exist (onMissingDeletes)

References

• generator changes feat(js-sdk): add support for write conflict settings sdk-generator#646
• closes [Feature] Add SDK support for ignoring errors on duplicate writes or missing deletes #268

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

• New Features

  • Added conflict options for write operations: OnDuplicateWrites and OnMissingDeletes to control behavior when duplicates are encountered or tuples are missing during deletes.
  • Options include "ignore" or "error" actions, with error taking precedence in mixed scenarios.
  • Requires OpenFGA v1.10.0+.

• Documentation

  • Updated API documentation with conflict option guidance and configuration examples.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: phamhieu / name: Hieu (06d2d27, 120c42b, 474b87f, 84dc121, 9e9575e, b9b2f3e, c8294ee, f276bdf, f591b33)

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

The PR adds support for write-operation conflict options (on_duplicate for duplicate writes, on_missing for missing deletes) across the SDK by introducing new API model enums, client configuration interfaces, updated method signatures, and comprehensive documentation and test coverage.

Changes

Cohort / File(s)	Summary
API Model Enums & Types apiModel.ts	Added WriteRequestWritesOnDuplicateEnum and WriteRequestDeletesOnMissingEnum enums with 'error' and 'ignore' values. Added optional on_duplicate field to WriteRequestWrites and optional on_missing field to WriteRequestDeletes.
Client Public API client.ts	Introduced OnDuplicateWrites and OnMissingDeletes type aliases. Added ClientWriteConflictOptions, ClientWriteTuplesRequestOpts, and ClientDeleteTuplesRequestOpts interfaces. Extended ClientWriteRequestOpts with optional conflict field. Updated write(), writeTuples(), and deleteTuples() method signatures to accept and propagate conflict options to API calls.
Documentation README.md, api.ts	Added "Conflict Options for Write Operations" documentation block in README describing on_duplicate and on_missing options, precedence rules, transactional behavior, and OpenFGA v1.10.0 requirement. Updated JSDoc comments for Write-related API methods with expanded guidance on conflict options.
Example example/example1/example1.mjs	Updated fgaClient.write() call to include conflict options in options object with onDuplicateWrites: 'ignore'.
Tests tests/client.test.ts	Added test cases verifying conflict options propagation to API calls for write, writeTuples, and deleteTuples methods, including scenarios with onDuplicateWrites only, onMissingDeletes only, combined options, and mixed write/delete operations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

The PR spans multiple files with consistent pattern changes (new enums, interfaces, and option propagation). While the logic is relatively straightforward—adding optional conflict configuration that flows through to API calls—understanding the complete implementation requires reviewing type definitions, client method modifications, documentation, and test scenarios across the codebase.

Possibly related issues

• [All SDKs] Add on_duplicate/on_missing options support for Write operations sdk-generator#610: Directly addresses the feature implementation for on_duplicate/on_missing write-conflict support in the SDK, which this PR fully implements across API models, client options, and method signatures.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "feat: add support for write conflict settings" directly and accurately summarizes the main change across the changeset. The title clearly communicates that this PR adds support for conflict settings related to write operations, which is the primary objective reflected in all the code changes including API model updates, client-side implementation, documentation, examples, and tests. The title is concise, specific, and avoids vague or misleading language.
Linked Issues Check	✅ Passed	The pull request successfully addresses all primary coding requirements from linked issue #268. The changes surface the on_duplicate and on_missing API options introduced in OpenFGA v1.10.0 through new SDK enums (WriteRequestWritesOnDuplicateEnum, WriteRequestDeletesOnMissingEnum) and public interfaces (ClientWriteConflictOptions, ClientWriteTuplesRequestOpts, ClientDeleteTuplesRequestOpts). The client methods (write, writeTuples, deleteTuples) are extended to accept and propagate these conflict options to the API, reducing the need for client-side error handling. Comprehensive documentation updates, example code, and test coverage are included to validate the new functionality and demonstrate correct usage.
Out of Scope Changes Check	✅ Passed	All changes in this pull request are directly scoped to the objective of adding write conflict settings support. The modifications span the full implementation path: API model definitions introducing conflict enums, client-side public interfaces and method signatures, documentation updates, example usage, and comprehensive test coverage. No unrelated refactoring, bug fixes, or feature additions outside this scope are present in the changeset.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

---

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 and usage tips.}

[socket-security]

No dependency changes detected. Learn more about Socket for GitHub.

👍 No dependency changes detected in pull request

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

example/example1/example1.mjs (1)

149-151: Use exported enum for conflict option.

Since we now surface OnDuplicateWrites, please lean on that constant instead of the raw string so the example mirrors the public API surface.

-import { CredentialsMethod, FgaApiValidationError, OpenFgaClient, TypeName } from "@openfga/sdk";
+import { CredentialsMethod, FgaApiValidationError, OnDuplicateWrites, OpenFgaClient, TypeName } from "@openfga/sdk";
@@
   }, {
     authorizationModelId,
-    conflict: { onDuplicateWrites: 'ignore' }
+    conflict: { onDuplicateWrites: OnDuplicateWrites.Ignore }
   });

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3fe33ac and 8a3eb8d.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (6)

• README.md (1 hunks)
• api.ts (4 hunks)
• apiModel.ts (2 hunks)
• client.ts (9 hunks)
• example/example1/example1.mjs (1 hunks)
• tests/client.test.ts (4 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

tests/client.test.ts (2)

client.ts (2)

• OnDuplicateWrites (192-192)
• OnMissingDeletes (194-194)

tests/helpers/default-config.ts (1)

• baseConfig (54-67)

client.ts (1)

apiModel.ts (2)

• TupleKey (1432-1457)
• TupleKeyWithoutCondition (1463-1482)

[dyeam0]

Thanks for your submission @phamhieu. We will assign someone to review your PR.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.45%. Comparing base (9b81c81) to head (06d2d27).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #276      +/-   ##
==========================================
+ Coverage   89.13%   89.45%   +0.32%     
==========================================
  Files          24       24              
  Lines        1288     1299      +11     
  Branches      211      234      +23     
==========================================
+ Hits         1148     1162      +14     
+ Misses         84       81       -3     
  Partials       56       56              

☔ View full report in Codecov by Sentry.
📢 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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull Request Overview

This PR adds support for write conflict handling options introduced in OpenFGA v1.10.0, enabling developers to control behavior when writing duplicate tuples or deleting non-existent tuples.

• Added OnDuplicateWrites and OnMissingDeletes enums with Error and Ignore options
• Extended write, writeTuples, and deleteTuples methods to accept conflict configuration
• Updated API documentation to reflect the new conflict handling behavior

Reviewed Changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
apiModel.ts	Added on_duplicate and on_missing fields to write/delete request interfaces with corresponding enums
client.ts	Extended client interfaces and methods to support conflict options with proper type safety
api.ts	Updated API documentation to describe conflict handling behavior and examples
tests/client.test.ts	Added comprehensive test coverage for conflict options across write, writeTuples, and deleteTuples methods
example/example1/example1.mjs	Demonstrated usage of conflict options in example code
README.md	Added detailed documentation section explaining conflict options usage and behavior

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[SoulPancake]

LG, Thanks a lot @phamhieu

[SoulPancake]

@phamhieu Would it be possible for you to take a look at the lockfile changes once? I think it might be related to the latest merge

https://github.com/openfga/js-sdk/actions/runs/18768778003/job/53559732838#step:4:9

The CI check is currently failing because of this

[phamhieu]

@phamhieu Would it be possible for you to take a look at the lockfile changes once? I think it might be related to the latest merge

https://github.com/openfga/js-sdk/actions/runs/18768778003/job/53559732838#step:4:9

The CI check is currently failing because of this

Fixed! I've resolved the conflicts.

[SoulPancake]

LGTM, Thanks a lot @phamhieu

[daniel-jonathan]

Thank you for the submission—this is a solid PR overall.

I left a few focused comments to avoid overwhelming the review. There are still areas to address, notably:

• Complete test coverage of write/delete conflict combinations and defaults.

• Error-path tests (4xx/5xx mapping), timeouts/abort, and transaction options (chunking/concurrency).

• Naming/typing consistency (singular option names, remove “Enum” suffix, prefer final types).

Happy to re-review once these are incorporated.

[SoulPancake]

LG

[rhamzeh]

Oh and @phamhieu - one more minor thing, would you mind adding the Changelog entry for this change in the unreleased section?

Something like:

- feat: add support for conflict options for Write operations**: (#276)
  The client now supports setting `conflict` on `ClientWriteRequestOpts` to control behavior when writing duplicate tuples or deleting non-existent tuples. This feature requires OpenFGA server [v1.10.0](https://github.com/openfga/openfga/releases/tag/v1.10.0) or later.
  See [Conflict Options for Write Operations](./README.md#conflict-options-for-write-operations) for more.

[rhamzeh]

Thanks @phamhieu !

[phamhieu]

@daniel-jonathan Could you give this a final review? I’d love to get it merged since I need this feature for my project.