Memberships

Documentation from vllnt/convex-memberships, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.

@vllnt/convex-memberships

Auth-agnostic membership and relationship graph (ReBAC tuples), as a Convex component.

Copy codeconst memberships = new Memberships(components.memberships);
await memberships.add(ctx, userId, orgId, "admin");
const isAdmin = await memberships.isMember(ctx, userId, orgId, "admin");

A tuple is (memberRef, resourceRef, relation), classified by an opaque memberKind. Domain-neutral: org membership, document sharing, team roles, group nesting — any "who relates to what, and how" question. Edges are flat — transitive expansion (a member of a group that is a member of an org) is not auto-resolved; it is planned for vNext.

Features

• Flat ReBAC tuples — (memberRef, resourceRef, relation) with an opaque memberKind (defaults "user") and optional status.
• Idempotent edges — add dedupes on the full tuple, returning the existing id and patching memberKind / status.
• Paginated listing — members of a resource, and resources of a member, both paginated for guild/workspace scale.
• Relation filtering — list members narrowed to a single relation.
• Bounded membership checks — exact-relation, or any-relation via index (not a full member scan).
• Guarded relation transitions — setRelation moves an edge, guarded against collisions; missing source ⇒ NOT_FOUND.
• Auditable removal — remove returns { removed }; documents exposes stored createdAt and status.
• Opaque refs — every ref/relation/kind/status is an arbitrary host string the component never inspects.

Installation

Copy codepnpm add @vllnt/convex-memberships

Peer dependency: convex@^1.41.0.

Usage

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import memberships from "@vllnt/convex-memberships/convex.config";

const app = defineApp();
app.use(memberships);
export default app;

Copy code// convex/teams.ts — host owns auth; pass opaque refs in.
import { components } from "./_generated/api";
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";
import { Memberships } from "@vllnt/convex-memberships";

const memberships = new Memberships(components.memberships);

export const join = mutation({
  args: { userId: v.string(), orgId: v.string() },
  handler: (ctx, { userId, orgId }) => memberships.add(ctx, userId, orgId),
});

export const isInOrg = query({
  args: { userId: v.string(), orgId: v.string() },
  handler: (ctx, { userId, orgId }) => memberships.isMember(ctx, userId, orgId),
});

Client options: new Memberships(component, { defaultRelation = "member", defaultMemberKind = "user" }).

API Reference

Full reference: docs/API.md.

React

An optional, tree-shakeable ./react entry ships thin hooks over convex/react's useQuery. react is an optional peer dependency — a backend-only consumer pulls zero React. Each hook takes the host app's re-exported query reference.

Copy codeimport { useIsMember } from "@vllnt/convex-memberships/react";
import { api } from "../convex/_generated/api";

const isAdmin = useIsMember(api.memberships.isMember, {
  memberRef: userId,
  resourceRef: orgId,
  relation: "admin",
}); // boolean | undefined (undefined while loading)

Security

• Auth-agnostic — the host resolves identity, decides who may create/read an edge, and passes opaque refs; tables are sandboxed (reached only via the client).
• isMember footgun — called without relation, it returns true for any stored relation ("invited", "suspended", "banned", …). For authz gates, always pass relation or enumerate the relations your policy accepts.

See docs/API.md.

Testing

Copy codepnpm test           # single run
pnpm test:coverage  # enforced 100% on covered files

Tests run against the real component runtime via convex-test (@edge-runtime/vm), not mocks.

Contributing

See CONTRIBUTING.md.

Author

Built by bntvllnt · bntvllnt.com · X @bntvllnt

Part of the @vllnt Convex component fleet — vllnt.com

If this is useful, sponsor the work.

License

MIT — see LICENSE.