x-api-registerer

x-api-registerer provides a standard way to register and call APIs by ID with a consistent result envelope:

• { ok: true, data, meta }
• { ok: false, error, meta }

It is TypeScript-first and works in JavaScript (ESM + CJS).

Install

npm install x-api-registerer

Usage (TypeScript)

import { ApiRegistry, ok, fail } from "x-api-registerer";

const apis = new ApiRegistry();

apis.register("geo.ipLookup", async (ctx) => {
  const ip = String(ctx.args.ip ?? "");
  if (!ip) return fail("bad_args", "Missing args.ip");

  const start = ctx.now();
  // ...call your provider here...
  const data = { ip, country: "US", city: "Miami" };

  return ok(data, { latencyMs: ctx.now() - start, provider: "mock" });
});

const res = await apis.call("geo.ipLookup", {
  input: { tenantId: "t1" },
  args: { ip: "8.8.8.8" }
});

if (res.ok) console.log(res.data);
else console.error(res.error.code, res.error.message);

Usage (JavaScript - CommonJS)

const { ApiRegistry, ok, fail } = require("x-api-registerer");

const apis = new ApiRegistry();

apis.register("directory.lookupUser", async (ctx) => {
  const email = String(ctx.args.email || "");
  if (!email) return fail("bad_args", "Missing args.email");

  return ok({ email, department: "Engineering" }, { provider: "mock" });
});

apis.call("directory.lookupUser", { input: { tenantId: "t1" }, args: { email: "[email protected]" } })
  .then(console.log);

Input contract

• ctx.input is required and must be an object.
• ctx.content is optional and must be a string if provided.

Override behavior

Registering with override: true (or registry.override) replaces an existing API with the same ID. Hosts can combine a system registry + user registry so user APIs override built-ins.