---
name: bijection-conflict-free-counter
description: "Evaluate and integrate the Conflict Free Counter component with Bijection."
---

# Conflict Free Counter

An eventually-consistent, contention-free counter component for Bijection.

- Package: @bijectionhq/conflict-free-counter
- Category: Database & Backend
- Status: Reference
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/conflict-free-counter/tree/f95146c796529812ee01dbf2ad763230c4723cb9
- Upstream: https://github.com/stack1ng/convex-conflict-free-counter/tree/1b23f8137d13895105091c40a5835fc02f323144
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/conflict-free-counter

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/conflict-free-counter.git
cd conflict-free-counter
git checkout f95146c796529812ee01dbf2ad763230c4723cb9
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-conflict-free-counter. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Conflict Free Counter. Follow the installation and configuration steps exactly.

# Conflict Free Counter

## Instructions

Conflict Free Counter provides an eventually-consistent, contention-free counter built on a conflict-free log architecture. Every call to `add` appends a row to an internal log rather than updating a shared document, eliminating write contention entirely. A scheduled compaction pipeline periodically folds the log into a snapshot, and reads return `snapshot + visible log entries` along with a `fullyConsistent` flag indicating whether the returned count reflects every committed write.

### Installation

```bash
npm install convex-conflict-free-counter
```

Current npm version: `convex-conflict-free-counter@2.0.0`

## Use cases

- Tracking high-throughput event counts (page views, signups, API calls) where many concurrent mutations would otherwise cause document contention and retries
- Incrementing and decrementing credit or quota balances across concurrent operations without serializing writes through a single document
- Aggregating metrics or tallies in systems using database triggers, where a single mutation may update the same counter key many times and needs to batch those updates efficiently
- Building dashboards or stats queries where reads can tolerate a few seconds of lag in exchange for writes that never block or retry
- Replacing a manually sharded counter when you want throughput to scale automatically without choosing or rebalancing shard counts

## How it works

Install the package and register it in `convex/convex.config.ts` using `app.use(conflictFreeCounter)`. Then instantiate `new ConflictFreeCounter(components.conflictFreeCounter)` once in a shared module and import that instance across your mutations and queries.

Writes use `counter.add(ctx, key, delta)` or `counter.addMany(ctx, entries)` from any mutation or action. Each call appends to an internal log document rather than reading and updating a shared counter, so concurrent mutations never touch the same document and write conflicts are structurally impossible. For hot mutations that update the same key repeatedly, `counter.bindDeltasBuffer(ctx)` and `counter.addBuffered` coalesce increments in memory before a single `flushDeltas` call writes one log row per key.

Reads use `counter.count(ctx, key)` which returns `{ count, fullyConsistent }`. By default, reads scan as much of the uncompacted log as the transaction's read budget allows on top of the latest snapshot. You can cap this with `logScanLimit` to reduce read cost, or set `logScanLimit: 0` to read the snapshot only, which is useful for reactive subscriptions that should update once per compaction rather than on every increment.

Compaction runs on a scheduled background pipeline controlled by `compactionDelay` (default 15 seconds). After a write burst, reads may temporarily report `fullyConsistent: false` until compaction catches up, but no writes are ever lost. The package ships a `/test` entry point for use with `convex-test`, and fake timer support allows controlled compaction stepping in unit tests.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Conflict Free Counter is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-conflict-free-counter)
- [GitHub repository](https://github.com/stack1ng/convex-conflict-free-counter)
- [Live demo](https://convex-conflict-free-counter.vercel.app/)
- [Convex Components Directory](https://www.convex.dev/components/convex-conflict-free-counter)
- [Convex documentation](https://docs.convex.dev)