API Reference

API reference

Create a client with createBedrockClient(timeoutTicks?) from @mcbe-reciperegistry/client/bedrock (or from drop-in ./recipe-registry-client.js).

Default timeout is 5 ticks if you omit the argument. Timeouts return “unavailable” values — never invented crafts.

Call dispose() when you no longer need the client (unsubscribes discovery listeners).

---

waitReady(): Promise<boolean>

Waits until the host advertises schema 2 (JSON ready and/or IPC hello).

Return	Meaning
true	Host is up
false	Timed out — treat registry as unavailable

---

catalogMinecraft(): string | undefined

Vanilla snapshot version string from the host’s ready / hello, if provided. Not the running game version.

---

match(query): Promise<string[] | undefined>

Which recipe ids match this ask.

Return	Meaning
string[]	Hits (may be [])
undefined	Timeout / host down

Use when you need identity (e.g. pick among duplicates). Ordered by priority, then registration order.

---

result(query): Promise<MatchResult[] | undefined>

What this ask yields (outputs, optional leftover / duration / energy / type / extra). No recipe id in the rows. Duplicate yields collapse to one row.

Return	Meaning
MatchResult[]	Yields (may be [])
undefined	Timeout / host down

---

get(id): Promise<Recipe | undefined>

Full stored recipe by id. undefined if missing or timed out.

---

list(filter?): Promise<ListEntry[]>

Compact rows (id, stations, optional type / leftover). Filter by station, output, and/or leftover item ids (AND when combined). Timeout → [].

await registry.list({ station: "minecraft:furnace" });
await registry.list({ output: "minecraft:stick" });
await registry.list({ leftover: "minecraft:bucket" });
await registry.list({
  station: "minecraft:crafting_table",
  output: "minecraft:stick",
});

No filter lists the whole catalog (can be large). See Asking the catalog.

---

register(recipes, options?): Promise<void>

Add or replace recipes in the host.

• Without source: session-only registration of each document.
• With source + rev: replaces that pack’s persisted set (see Registering recipes).

---

sync(source, rev): Promise<boolean | undefined>

Ask whether the world already has this pack’s rev.

Return	Meaning
true	Same rev — skip register
false	Host wants a full register
undefined	Timeout

Call soon after waitReady() if you persist recipes. Sources that never sync/register after ready can be dropped after a grace period on the host.

---

unregister(ids): Promise<void>

Remove recipes by id. Missing ids are ignored.

---

Query shape (match / result)

Always include station. Include at least one of:

• inputs — bag of ingredients (furnace, many machines)
• grid — 9 cells, row-major, null = empty (crafting)
• pattern + key — vanilla shaped style

If both grid and pattern+key are set, grid wins.

See Asking the catalog.