@vllnt/convex-slugs

Unique slug and handle registry with rename redirects, as a Convex component.

const slugs = new Slugs(components.slugs);
await slugs.reserve(ctx, "ada", userId); // { ok: true } | { ok: false, reason }
const ref = await slugs.resolve(ctx, "ada"); // resourceRef | null

Reserve a unique string (slug, @handle, username) against an opaque resourceRef, enforce uniqueness inside a scope, resolve it back, release it, and redirect on rename. Domain-neutral: article slugs, profile handles, workspace slugs — any public-URL key.

Features

• Atomic uniqueness per (scope, slug) — rides the Convex mutation transaction, no double-reserve.
• Scopes — global by default, or namespace per tenant / locale / type.
• Rename + redirects — renaming records an old → new redirect for link preservation.
• Chain-safe redirects — chains collapse (A→B→C ⇒ redirectFor(A) === C), one row per source.
• Reverse lookup — find the slug currently held by a resourceRef.
• Case folding + NFC — case-insensitive (opt-out) and Unicode NFC-normalized to kill homoglyph collisions.
• Configurable input rules — length bounds, charset pattern, reservedWords; typed rejection reasons.
• Degrades, never throws — reads use .first(); release cleans up inbound redirects; opaque resourceRef.

Installation

pnpm add @vllnt/convex-slugs

Peer dependency: convex@^1.41.0 (optionally react@>=18 for the ./react hooks).

Usage

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

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

// convex/handles.ts — host owns auth; pass an opaque resourceRef in.
import { components } from "./_generated/api";
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";
import { Slugs } from "@vllnt/convex-slugs";

const slugs = new Slugs(components.slugs);

export const claim = mutation({
  args: { handle: v.string(), userId: v.string() },
  handler: (ctx, { handle, userId }) => slugs.reserve(ctx, handle, userId),
});

export const lookup = query({
  args: { handle: v.string() },
  handler: (ctx, { handle }) => slugs.resolve(ctx, handle),
});

Client options: new Slugs(component, { defaultScope = "global", foldCase = true, minLength = 1, maxLength = 256, pattern?, reservedWords = [] }).

API Reference

Method	Kind	Result
reserve(ctx, slug, resourceRef, scope?)	mutation	{ ok: true } or { ok: false, reason } (SLUG_INVALID | SLUG_RESERVED | SLUG_TAKEN)
release(ctx, slug, scope?)	mutation	null (idempotent)
rename(ctx, fromSlug, toSlug, scope?)	mutation	{ ok } (SLUG_INVALID | SLUG_NOT_FOUND | SLUG_TAKEN)
resolve(ctx, slug, scope?)	query	resourceRef | null
redirectFor(ctx, slug, scope?)	query	toSlug | null
slugForResource(ctx, resourceRef, scope?)	query	slug | null

Full reference: docs/API.md.

React

Optional, tree-shakeable hooks from @vllnt/convex-slugs/react — thin wrappers over useQuery; react is an optional peer dep. Each takes the host's re-exported resolve query reference.

import { useSlugAvailable } from "@vllnt/convex-slugs/react";
import { api } from "../convex/_generated/api";

// `available` is undefined while loading, true when free, false when held.
const { available, resourceRef } = useSlugAvailable(api.handles.resolveHandle, { slug });

Hook	Returns
useSlugAvailable(resolveRef, { slug, scope? })	{ available, resourceRef } — available undefined while loading, true free, false held
useResolve(resolveRef, { slug, scope? })	resourceRef | null | undefined (undefined while loading)

Security

• Auth-agnostic — the host authenticates the caller, decides who may claim a handle, and passes an opaque resourceRef.
• Opaque refs only — resourceRef and scope are arbitrary strings; tables are sandboxed (reached only via the client).
• Boundary re-guard — the component re-guards length at the trust boundary even if a caller bypasses the client.

See docs/API.md.

Testing

pnpm 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.