--- name: bijection-buckets description: "Evaluate and integrate the Buckets component with Bijection." --- # Buckets Ephemeral groups of opaque subject refs — matches, lobbies, cohorts — as a Bijection component - Package: @bijectionhq/buckets - Category: Database & Backend - Status: Preview - License: MIT - Bijection source (repository access required): https://github.com/bijectionhq/buckets/tree/1e470e464960fb77ff3ebf5f9f79970f2a82452e - Upstream: https://github.com/vllnt/convex-buckets/tree/f8e9a392795a423d1dc6bf0af32b5d8e639ae711 - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/buckets ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/buckets.git cd buckets git checkout 1e470e464960fb77ff3ebf5f9f79970f2a82452e ``` ## 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 @vllnt/convex-buckets. 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 Buckets. Follow the installation and configuration steps exactly. # Buckets ## Instructions Use Buckets to convex component that manages capacity-limited ephemeral groups with open/locked/closed lifecycle for game lobbies, cohorts, and shared sessions. This Convex component integrates directly with your backend. ### Installation ```bash npm install @vllnt/convex-buckets ``` Current npm version: `@vllnt/convex-buckets@0.1.0-canary.0` ### Capabilities - Enforce capacity limits on groups using optimistic concurrency control so concurrent joins retry instead of overfilling - Track group lifecycle transitions from open to locked to closed with explicit state management per bucket - Paginate group members efficiently without loading entire membership sets into memory - Isolate group data across features using separate mounts or partition within a mount using named scopes ## Examples ### how to implement a game lobby with player capacity limit in Convex convex-buckets provides a Buckets client with open, join, lock, and close mutations. Call open with a capacity option to create the lobby, join to admit players up to that limit, and lock to stop new joins before a match starts. The component enforces capacity via OCC on a memberCount field so concurrent join mutations retry rather than overfill the lobby. ### how to group users into fixed-size cohorts or sessions in Convex Use convex-buckets to open a bucket with a specific capacity and join opaque subjectRef strings representing users, teams, or devices. The component does not interpret subject references, so your backend controls what entity each ref represents and handles any admission policy or authorization before calling join. ### how to paginate group members in a Convex component convex-buckets exposes a paginateMembers query that accepts standard Convex paginationOpts and returns a page, isDone flag, and continueCursor. For bounded previews, listMembers returns up to 500 members in a single query without requiring cursor handling. ### how to clean up ephemeral groups and remove member data in Convex convex-buckets provides eraseBucket and eraseSubject mutations. eraseBucket closes the bucket and removes members in fenced scheduled batches keyed to the original document ID so stale scheduled work cannot erase a replacement bucket. eraseSubject deletes one bounded batch per call and schedules no continuation, letting the caller control drain timing. ## 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 Buckets is not needed ## Troubleshooting **What is a subjectRef in convex-buckets?** A subjectRef is an opaque string your application provides to identify a group member. convex-buckets does not interpret or validate the value, so it can represent a user ID, team ID, device ID, or any other entity your backend defines. Authorization and identity resolution remain the responsibility of your own Convex mutations before they call join. **How does convex-buckets prevent a group from exceeding its capacity when multiple users join at the same time?** convex-buckets stores memberCount directly on the bucket document and uses Convex optimistic concurrency control to patch it atomically. If two join mutations conflict, Convex retries the losing transaction, so the final count cannot exceed the capacity set when the bucket was opened. **Can I run multiple independent sets of groups in the same Convex app using convex-buckets?** Yes. Mount the component multiple times with distinct names using app.use(bucketsConfig, { name: 'first' }) and app.use(bucketsConfig, { name: 'second' }), then create a separate Buckets client for each mount. Data between mounts is fully isolated at the table level. Within a single mount, scopes can further partition groups without requiring a separate mount. **Does convex-buckets handle authentication or authorization?** No. convex-buckets is auth-agnostic and does not enforce any access control. Your Convex mutations must authenticate the caller, authorize the action, and derive the correct scope and subjectRef before calling the component's join, leave, lock, or close methods. Scopes are namespaces for partitioning data, not security boundaries. **What happens when a bucket is locked versus closed in convex-buckets?** A locked bucket rejects new joins but still allows existing members to leave. A closed bucket is terminal and does not allow joins or leaves. The lifecycle progresses in one direction: open accepts joins and leaves, locked stops joins but allows leaves, and closed ends the group. The join result includes a reason field with values like locked, closed, full, or already_member when a join is rejected. ## Resources - [npm package](https://www.npmjs.com/package/%40vllnt%2Fconvex-buckets) - [GitHub repository](https://github.com/vllnt/convex-buckets) - [Live demo](https://github.com/vllnt/convex-buckets/tree/main/example/convex) - [Convex Components Directory](https://www.convex.dev/components/vllnt/convex-buckets) - [Convex documentation](https://docs.convex.dev)