Skip to content
RelKit
Esc
↑↓navigate↵open⌘Jpreview
On this page

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;

Source

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 !==