Getting started

Deploy

The Deploy to Cloudflare button provisions the Worker + R2 bucket and clones this repo into your GitHub, with Workers Builds wired up so later pushes redeploy.

Add the seed workflow

The deploy button can't copy GitHub Actions workflows into your repo (a GitHub security restriction), so add it once by hand: Add file → Create new file, name it .github/workflows/seed-labels.yml, and paste the contents of seed-labels.yml (use the copy raw file button). Commit it, and seed-labels appears under the repo's Actions tab.

Add credentials

Gather these from the Cloudflare dashboard, then add them on the repo under Settings → Secrets and variables → Actions - SEED_BASE and R2_BUCKET as Variables, the rest as Secrets:

Add labels

Drop RDF into the labels/ folder and commit. A full instance-data dump is fine - only label and description triples are extracted.

Seed

Actions → seed-labels → Run workflow (tick include common ontology labels for the bundled vocabularies).

Clone & install

git clone https://github.com/recalcitrantsupplant/rdf-label-cache && cd rdf-label-cache
pnpm install

Dump the annotation properties you want cached

Labels for your instance data

From your triplestore, CONSTRUCT the labels and descriptions for every IRI your data uses - your own entities and the public-vocabulary terms they reference - and save it as data.ttl:

just extract-labels https://your-endpoint/sparql   # runs the query below → data.ttl

PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
PREFIX skos: <http://www.w3.org/2004/02/skos/core#>
PREFIX dcterms: <http://purl.org/dc/terms/>
PREFIX schema: <https://schema.org/>
CONSTRUCT { ?iri rdfs:label ?l ; rdfs:comment ?c ; skos:prefLabel ?p ; skos:definition ?d ;
            dcterms:title ?t ; dcterms:description ?desc ; schema:name ?n }
WHERE {
  { SELECT DISTINCT ?iri WHERE {
      { ?iri ?px ?ox } UNION { ?sx ?iri ?ox } UNION { ?sx ?px ?iri FILTER(isIRI(?iri)) } } }
  OPTIONAL { ?iri rdfs:label ?l }     OPTIONAL { ?iri rdfs:comment ?c }
  OPTIONAL { ?iri skos:prefLabel ?p } OPTIONAL { ?iri skos:definition ?d }
  OPTIONAL { ?iri dcterms:title ?t }  OPTIONAL { ?iri dcterms:description ?desc }
  OPTIONAL { ?iri schema:name ?n }
  FILTER(BOUND(?l)||BOUND(?c)||BOUND(?p)||BOUND(?d)||BOUND(?t)||BOUND(?desc)||BOUND(?n))
}

curl -sf https://your-endpoint/sparql \
  --data-urlencode query@query.rq \
  -H 'Accept: text/turtle' -o data.ttl

Labelling is usually two steps - your data, then the vocabularies it references.

Labels for the ontologies you use

just seed-public                  # all bundled vocabularies
just seed-public skos,rdf,rdfs    # …or only the ones you name

node scripts/ingest.mjs                    # all bundled vocabularies
node scripts/ingest.mjs --only skos,rdf    # …or only the ones you name
node scripts/upload-seed.mjs

just coverage-report https://your-endpoint/sparql

curl -sf https://your-endpoint/sparql \
  --data-urlencode query@scripts/coverage-report.rq \
  -H 'Accept: text/csv' | column -t -s,

Set up Cloudflare & get credentials

Pick a project name first — your Worker and R2 bucket are both named label-cache-<project>, so each app gets its own isolated instance and two apps never share a bucket. Set it once in .env (PROJECT=orders) or pass project=orders per run.

Sign up for Cloudflare (the free tier is plenty) or log into an existing account, then create the bucket and deploy the Worker:

pnpm wrangler login                  # sign up (free) or log in - opens the browser
# set name + bucket_name to label-cache-orders in wrangler.toml, then:
pnpm wrangler r2 bucket create label-cache-orders
pnpm wrangler deploy                 # prints your Cloudflare Worker URL → SEED_BASE

just login                        # sign up (free) or log in - opens the browser
just project=orders bucket        # create bucket label-cache-orders (one-time)
just project=orders deploy        # prints your Cloudflare Worker URL → SEED_BASE

Then create an R2 API token - dashboard → R2 → Manage API Tokens → Create API Token with Object Read & Write. This gives you R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY. You now have every value the next step needs.

Configuration

Generate & upload your label objects

export SEED_BASE=https://label-cache-orders.<subdomain>.workers.dev
export R2_BUCKET=label-cache-orders
export CLOUDFLARE_ACCOUNT_ID=... R2_ACCESS_KEY_ID=... R2_SECRET_ACCESS_KEY=...
node scripts/ingest.mjs --input data.ttl    # → dist/seed/manifest.ndjson
node scripts/upload-seed.mjs                 # → R2, over the S3 API

# PROJECT + SEED_BASE + R2_* come from your .env (see env.example)
just ingest                       # → dist/seed/manifest.ndjson
just project=orders upload        # → R2, over the S3 API (sets R2_BUCKET)

ingest prints a per-namespace summary of the terms it wrote - no namespace needs registering first.

The client library

The thin, zero-dependency @rdf-label-cache/client is the recommended path: it fires the lookups in parallel, prefers the browser cache, does the untagged-then-language fallback, and picks a label - in a few lines. BASE is your Cloudflare Worker URL and iris the IRIs your view mentions:

npm add @rdf-label-cache/client

import { createLabelClient } from "@rdf-label-cache/client";

// Construct once and reuse it - it keeps the connection warm and caches live.
const labels = createLabelClient({ base: BASE });
labels.preconnect();                        // browser: warm the connection early

// Resolve every IRI your view mentions - parallel, deduped, edge-cached, with
// untagged-then-language fallback and a faithful label pick, all built in.
const resolved = await labels.resolveMany(iris);
// resolved: { "https://schema.org/Person": "Person", "https://schema.org/name": "name" }

Fire the lookups concurrently rather than serially (the library does). See the FAQ for the per-IRI cache rationale.

Without a dependency — plain fetch

The library is thin because the call is simple: one edge-cached GET per IRI, then pick a label from the JSON-LD. If you'd rather not add a dependency, it's a handful of lines. No ?lang= is the untagged label (labels/und/{iri}); add &lang=xx for a language:

// Your preference order across predicate terms; first hit wins.
const ORDER = ["prefLabel", "label", "title", "name"];
const first = (v) => (Array.isArray(v) ? v[0] : v);
const pick = (doc) =>
  ORDER.map((t) => first(doc[t]?.["@none"] ?? Object.values(doc[t] ?? {})[0])).find(Boolean) ?? null;

const resolved = Object.fromEntries(await Promise.all(iris.map(async (iri) => {
  const res = await fetch(`${BASE}/label?iri=${encodeURIComponent(iri)}`);
  return [iri, res.ok ? pick(await res.json()) : null];
})));

Already using n3 — labels as RDF

Keeping your graph in an n3 Store? Expand each label doc to RDF/JS quads with the library's toQuads and add them straight in - no JSON-LD parser (jsonld-streaming-parser and friends) needed. It caches the versioned @context for you, so there's no per-doc context round-trip. Pass n3's DataFactory for native quads; language tags are preserved ("Concept"@en):

import { DataFactory, Store } from "n3";
import { createLabelClient } from "@rdf-label-cache/client";

const store = new Store(/* your parsed graph */);
const labels = createLabelClient({ base: BASE });

const docs = await labels.documentMany(iris);        // { iri: JSON-LD doc | null }
for (const doc of Object.values(docs)) {
  if (doc) store.addQuads(await labels.toQuads(doc, { factory: DataFactory }));
}
// store now holds your data + every label as triples.

Get the most from the cache

The library already does all of this; it matters when you go raw. Every /label response is cached at two layers - the Cloudflare edge (shared across all your users) and the browser - driven by Cache-Control (max-age for browsers, s-maxage for the edge, plus stale-while-revalidate):

• Use the default fetch - never cache: 'no-store' or reload, which bypass both caches. Repeat lookups then return instantly, refreshed in the background.
• Browser apps need no label cache of their own - the HTTP cache already de-dupes across renders; just an in-flight de-dupe so a single render fires each IRI once (the library does this).
• Server-side callers (Node, another Worker) share no HTTP cache - keep a small in-memory LRU keyed by iri|lang (the library's cache: "auto" does this).
• Changed a label? Purge the labels tag; returning browsers pick it up within the hour.