Services API
Generated public TypeScript reference for relkit/services.
Common APIs
For configuration and examples, read define, migration, service.
For a complete workflow, follow upload product images.
Frontend usage
Call a public service operation shows the client side of this capability.
Most-used APIs
These entries carry each API’s contract and example. The complete reference follows.
defineService
Define a service synchronously for authoring and preserve member identity.
Throws
TypeError for malformed local input, or the original identity/ID error.
Example
import { defineFunction } from "relkit/functions";
import { z } from "relkit/schema";
import { defineService } from "relkit/services";
const lookup = defineFunction({
input: z.string(),
output: z.string(),
handler: (id) => id,
});
const orders = defineService({ id: "orders", functions: { lookup } });
Signature
declare const defineService: DefineService;
Since v0.1.0
Backend and frontend example
Backend — these maintained files define the operation used by the frontend below.
/** Declares the orders service boundary without acquiring native clients. */
import { defineService } from "relkit/services";
import createOrder from "./functions/create-order.function.js";
import deleteOrder from "./functions/delete-order.function.js";
import getOrder from "./functions/get-order.function.js";
import searchOrders from "./functions/search-orders.function.js";
import updateOrder from "./functions/update-order.function.js";
import authorizeOrder from "./functions/authorize-order.function.js";
import streamOrderReport from "./functions/stream-order-report.function.js";
import cleanupOrders from "./jobs/cleanup-orders.job.js";
import exportOrders from "./jobs/export-orders.job.js";
import cleanupOrdersTask from "./tasks/cleanup-orders.task.js";
import exportOrdersTask from "./tasks/export-orders.task.js";
export default defineService({
functions: {
createOrder,
deleteOrder,
getOrder,
searchOrders,
updateOrder,
authorizeOrder,
streamOrderReport,
},
tasks: { cleanupOrdersTask, exportOrdersTask },
jobs: { cleanupOrders, exportOrders },
});
/**
* Maps order HTTP operations to public service members with the existing request
* and rate-limit policies. The rate-limit reference addresses the declared cache
* by its stable identity without importing a private service implementation.
*/
import { defineServiceRoutes, http } from "relkit/routes";
import { z } from "zod";
import orders from "../../services/orders/service.js";
export default defineServiceRoutes(orders, {
GET: "searchOrders",
POST: {
member: "createOrder",
request: http.input({
orderId: http.header("idempotency-key"),
customerEmail: http.header("x-customer-email"),
sku: http.body("sku"),
quantity: http.body("quantity"),
}),
rateLimit: {
limit: 20,
windowMs: 60_000,
key: http.header("x-customer-email"),
store: {
ref: { kind: "cache", id: "orders.rate-limits" },
key: z.string(),
value: z.number().int().nonnegative(),
},
},
successStatus: 201,
response: (order) => ({ headers: { location: `/orders/${order.orderId}` } }),
},
});
Frontend
After frontend setup and pulling this backend’s contract,
render this component under RelkitClientProvider. Each exported service-route method produces
its own api property, named after its target function: GET /orders targets
orders.search-orders and becomes api.orders.searchOrders, while POST /orders targets
orders.create-order and becomes api.orders.createOrder.
"use client";
/** Calls both commerce service-route methods using their generated domain inputs inside the frontend provider. */
import { api } from "@relkit/client";
import { useRelkitClient, useRoute, useRouteMutation } from "@relkit/client/react";
/** Reads the Orders search count and submits one explicit creation without replaying a failed write.
* @returns Typed query results, creation feedback, and an action available after identity is ready. */
export function Orders() {
const { status } = useRelkitClient();
const orders = useRoute(api.orders.searchOrders, { input: { status: "pending" } });
const create = useRouteMutation(api.orders.createOrder);
return (
<section>
{orders.isPending && <p role="status">Loading orders…</p>}
{orders.data && <p>{orders.data.count} orders</p>}
{orders.isError && <p role="alert">{orders.error.message}</p>}
<button
disabled={status !==