Buckets
Ephemeral groups of opaque subject refs — matches, lobbies, cohorts — as a Bijection component
git clone https://github.com/bijectionhq/buckets.git
cd buckets
git checkout 1e470e464960fb77ff3ebf5f9f79970f2a82452eBijection repository access is required. Request access.
Description
Ephemeral groups of opaque subject refs — matches, lobbies, cohorts — as a Bijection component
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: bijectionhq/buckets. Based on vllnt/convex-buckets. License: MIT. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
Ephemeral groups of opaque subject refs — matches, lobbies, cohorts — as a Convex component
Explore the demo ↗Upstream package FAQ
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.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate Buckets with Bijection.
Read: https://bijection.com/components/buckets/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Upstream README.md
View repository ↗Documentation from vllnt/convex-buckets at its recorded upstream revision. APIs and setup may differ in the Bijection adaptation.
Loading package documentation…