---
title: Services API
description: Generated public TypeScript reference for @relkit/services.
search:
  exclude: true
sidebar:
  icon: braces
---

{/* Generated by apps/docs/scripts/generate.ts. Do not edit. */}

## Common APIs

- [defineService](/docs/api/services#defineservice)

For configuration and examples, read [define](/docs/modules/service/define), [migration](/docs/modules/service/migration), [service](/docs/modules/service).

For a complete workflow, follow [upload product images](/guides/storage/upload-product-images).

## Frontend usage

[Call a public service operation](/docs/modules/service/routes#use-from-the-frontend) shows the client side of this capability.

## Public imports

- `@relkit/services` — 45 exports

## All exported APIs

Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API's inline sample, a maintained repository usage, or the shared module walkthrough.

| API                                                                                       | Kind  | Import from        | Example                                                             |
| ----------------------------------------------------------------------------------------- | ----- | ------------------ | ------------------------------------------------------------------- |
| [assertServiceDescriptor](/docs/api/services#assertservicedescriptor)                     | Value | `@relkit/services` | [API example](/docs/api/services#assertservicedescriptor)           |
| [assertServiceDescriptorEffect](/docs/api/services#assertservicedescriptoreffect)         | Value | `@relkit/services` | [API example](/docs/api/services#assertservicedescriptoreffect)     |
| [assertServiceMemberName](/docs/api/services#assertservicemembername)                     | Value | `@relkit/services` | [API example](/docs/api/services#assertservicemembername)           |
| [assertServiceMemberNameEffect](/docs/api/services#assertservicemembernameeffect)         | Value | `@relkit/services` | [API example](/docs/api/services#assertservicemembernameeffect)     |
| [assertServiceRef](/docs/api/services#assertserviceref)                                   | Value | `@relkit/services` | [API example](/docs/api/services#assertserviceref)                  |
| [assertServiceRefEffect](/docs/api/services#assertservicerefeffect)                       | Value | `@relkit/services` | [API example](/docs/api/services#assertservicerefeffect)            |
| [defineService](/docs/api/services#defineservice)                                         | Value | `@relkit/services` | [API example](/docs/api/services#defineservice)                     |
| [DefineService](/docs/api/services#defineservice-interface)                               | Type  | `@relkit/services` | [API example](/docs/api/services#defineservice-interface)           |
| [defineServiceEffect](/docs/api/services#defineserviceeffect)                             | Value | `@relkit/services` | [API example](/docs/api/services#defineserviceeffect)               |
| [DefineServiceOptions](/docs/api/services#defineserviceoptions-interface)                 | Type  | `@relkit/services` | [API example](/docs/api/services#defineserviceoptions-interface)    |
| [freezeServiceContextValue](/docs/api/services#freezeservicecontextvalue)                 | Value | `@relkit/services` | [API example](/docs/api/services#freezeservicecontextvalue)         |
| [freezeServiceContextValueEffect](/docs/api/services#freezeservicecontextvalueeffect)     | Value | `@relkit/services` | [API example](/docs/api/services#freezeservicecontextvalueeffect)   |
| [freezeServiceDescriptor](/docs/api/services#freezeservicedescriptor)                     | Value | `@relkit/services` | [API example](/docs/api/services#freezeservicedescriptor)           |
| [freezeServiceDescriptorEffect](/docs/api/services#freezeservicedescriptoreffect)         | Value | `@relkit/services` | [API example](/docs/api/services#freezeservicedescriptoreffect)     |
| [isFunctionDescriptor](/docs/api/services#isfunctiondescriptor)                           | Value | `@relkit/services` | [API example](/docs/api/services#isfunctiondescriptor)              |
| [isFunctionDescriptorEffect](/docs/api/services#isfunctiondescriptoreffect)               | Value | `@relkit/services` | [API example](/docs/api/services#isfunctiondescriptoreffect)        |
| [isReservedServiceMemberName](/docs/api/services#isreservedservicemembername)             | Value | `@relkit/services` | [API example](/docs/api/services#isreservedservicemembername)       |
| [isReservedServiceMemberNameEffect](/docs/api/services#isreservedservicemembernameeffect) | Value | `@relkit/services` | [API example](/docs/api/services#isreservedservicemembernameeffect) |
| [isServiceDescriptor](/docs/api/services#isservicedescriptor)                             | Value | `@relkit/services` | [API example](/docs/api/services#isservicedescriptor)               |
| [isServiceDescriptorEffect](/docs/api/services#isservicedescriptoreffect)                 | Value | `@relkit/services` | [API example](/docs/api/services#isservicedescriptoreffect)         |
| [isServiceRef](/docs/api/services#isserviceref)                                           | Value | `@relkit/services` | [API example](/docs/api/services#isserviceref)                      |
| [isServiceRefEffect](/docs/api/services#isservicerefeffect)                               | Value | `@relkit/services` | [API example](/docs/api/services#isservicerefeffect)                |
| [normalizeServiceMemberName](/docs/api/services#normalizeservicemembername)               | Value | `@relkit/services` | [API example](/docs/api/services#normalizeservicemembername)        |
| [normalizeServiceMemberNameEffect](/docs/api/services#normalizeservicemembernameeffect)   | Value | `@relkit/services` | [API example](/docs/api/services#normalizeservicemembernameeffect)  |
| [observeService](/docs/api/services#observeservice)                                       | Value | `@relkit/services` | [API example](/docs/api/services#observeservice)                    |
| [RESERVED_SERVICE_MEMBER_NAMES](/docs/api/services#reserved_service_member_names)         | Value | `@relkit/services` | [Module example](/docs/modules/service/define)                      |
| [runServiceSync](/docs/api/services#runservicesync)                                       | Value | `@relkit/services` | [API example](/docs/api/services#runservicesync)                    |
| [SERVICE_RESERVED_MEMBER_NAMES](/docs/api/services#service_reserved_member_names)         | Value | `@relkit/services` | [Module example](/docs/modules/service/define)                      |
| [ServiceDescriptor](/docs/api/services#servicedescriptor-type-alias)                      | Type  | `@relkit/services` | [API example](/docs/api/services#servicedescriptor-type-alias)      |
| [ServiceDescriptorAny](/docs/api/services#servicedescriptorany-type-alias)                | Type  | `@relkit/services` | [API example](/docs/api/services#servicedescriptorany-type-alias)   |
| [ServiceEventMap](/docs/api/services#serviceeventmap-type-alias)                          | Type  | `@relkit/services` | [API example](/docs/api/services#serviceeventmap-type-alias)        |
| [ServiceEvents](/docs/api/services#serviceevents-type-alias)                              | Type  | `@relkit/services` | [API example](/docs/api/services#serviceevents-type-alias)          |
| [ServiceFunctionMap](/docs/api/services#servicefunctionmap-type-alias)                    | Type  | `@relkit/services` | [API example](/docs/api/services#servicefunctionmap-type-alias)     |
| [ServiceFunctions](/docs/api/services#servicefunctions-type-alias)                        | Type  | `@relkit/services` | [API example](/docs/api/services#servicefunctions-type-alias)       |
| [ServiceJobMap](/docs/api/services#servicejobmap-type-alias)                              | Type  | `@relkit/services` | [API example](/docs/api/services#servicejobmap-type-alias)          |
| [ServiceJobs](/docs/api/services#servicejobs-type-alias)                                  | Type  | `@relkit/services` | [API example](/docs/api/services#servicejobs-type-alias)            |
| [serviceMemberEntries](/docs/api/services#servicememberentries)                           | Value | `@relkit/services` | [API example](/docs/api/services#servicememberentries)              |
| [serviceMemberEntriesEffect](/docs/api/services#servicememberentrieseffect)               | Value | `@relkit/services` | [API example](/docs/api/services#servicememberentrieseffect)        |
| [ServiceRef](/docs/api/services#serviceref-interface)                                     | Type  | `@relkit/services` | [API example](/docs/api/services#serviceref-interface)              |
| [ServiceRefAny](/docs/api/services#servicerefany-type-alias)                              | Type  | `@relkit/services` | [API example](/docs/api/services#servicerefany-type-alias)          |
| [ServiceTaskMap](/docs/api/services#servicetaskmap-type-alias)                            | Type  | `@relkit/services` | [API example](/docs/api/services#servicetaskmap-type-alias)         |
| [ServiceTasks](/docs/api/services#servicetasks-type-alias)                                | Type  | `@relkit/services` | [API example](/docs/api/services#servicetasks-type-alias)           |
| [ServiceTelemetry](/docs/api/services#servicetelemetry-class)                             | Value | `@relkit/services` | [API example](/docs/api/services#servicetelemetry-class)            |
| [ServiceTelemetryLive](/docs/api/services#servicetelemetrylive)                           | Value | `@relkit/services` | [API example](/docs/api/services#servicetelemetrylive)              |
| [ServiceValidationError](/docs/api/services#servicevalidationerror-class)                 | Value | `@relkit/services` | [API example](/docs/api/services#servicevalidationerror-class)      |

## `define-service.ts`

### defineService

Define a service synchronously for authoring and preserve member identity.

**Throws**

TypeError for malformed local input, or the original identity/ID error.

**Example**

```ts
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**

```ts
declare const defineService: DefineService;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.ts#L114)

Since v0.1.0

#### Backend and frontend example

**Backend** — these maintained files define the operation used by the frontend below.

```ts title="examples/commerce/src/services/orders/service.ts"
/** Declares the orders service boundary without acquiring native clients. */
import { defineService } from "@relkit/app/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 },
});
```

```ts title="examples/commerce/src/routes/orders/route.ts"
/**
 * 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/app/routes";
import { z } from "@relkit/app/schema";
import orders from "../../services/orders/service.js";

export const { GET, POST } = 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,
  },
});
```

**Frontend**

After [frontend setup and pulling this backend's contract](/guides/frontend/connect-react),
render this component under `RelkitClientProvider`. Each exported service-route method produces
its own typed operation: `GET /orders` reads the search count, while `POST /orders` creates an order.

```tsx title="src/Orders.tsx"
"use client";

/** Calls both commerce service-route methods using their generated domain inputs inside the frontend provider. */
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("GET /orders", { input: { status: "pending" } });
  const create = useRouteMutation("POST /orders");

  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 !== "ready" || !create.isIdle}
        onClick={() =>
          create.mutate({
            orderId: crypto.randomUUID(),
            customerEmail: "reader@example.com",
            sku: "book",
            quantity: 1,
          })
        }
      >
        Create an order
      </button>
      {create.isPending && <p role="status">Creating…</p>}
      {create.isSuccess && <p>Created: {create.data.orderId}</p>}
      {create.isError && (
        <p role="alert">{create.error.message}. Check the outcome before retrying.</p>
      )}
    </section>
  );
}
```

`status`, `count`, and the creation input come from the selected functions' schemas. RPC receives
`orderId` and `customerEmail` as input fields even though REST maps them from headers. A service's
public member alone is not a browser endpoint: the client-exposed route supplies that boundary.

Reference: [`useRoute`](/docs/api/client#useroute), [`useRouteMutation`](/docs/api/client#useroutemutation).
See [request mapping](/docs/modules/http/requests) for the REST side and
[mutations](/docs/modules/client/mutations) for submission and recovery behavior.

### defineServiceEffect

Define a service without cloning its member descriptors.

**Example**

```ts
Effect.runSync(defineServiceEffect({ id: "orders", functions: { lookup } }));
```

**Signature**

```ts
declare const defineServiceEffect: <
  const Id extends string,
  const Functions extends ServiceFunctionMap = Readonly<Record<never, never>>,
  const Events extends ServiceEventMap = Readonly<Record<never, never>>,
  const Tasks extends ServiceTaskMap = Readonly<Record<never, never>>,
  const Jobs extends ServiceJobMap = Readonly<Record<never, never>>,
>(
  options: DefineServiceOptions<Id, Functions, Events, Tasks, Jobs>,
) => Effect.Effect<
  ServiceDescriptor<Id, Functions, Events, Tasks, Jobs>,
  ServiceValidationError,
  never
>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.ts#L29)

## `define-service.types.ts`

### DefineService (interface)

Generic synchronous service factory preserving member inference.

**Throws**

TypeError for malformed local input, or the original identity/ID error.

**Example**

```ts
const orders = defineService({ id: "orders", functions: { lookup } });
```

**Signature**

```ts
export interface DefineService {
  <
    const Id extends string,
    const Functions extends ServiceFunctionMap = Readonly<Record<never, never>>,
    const Events extends ServiceEventMap = Readonly<Record<never, never>>,
    const Tasks extends ServiceTaskMap = Readonly<Record<never, never>>,
    const Jobs extends ServiceJobMap = Readonly<Record<never, never>>,
  >(
    options: DefineServiceOptions<Id, Functions, Events, Tasks, Jobs>,
  ): ServiceDescriptor<Id, Functions, Events, Tasks, Jobs>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L122)

### DefineServiceOptions (interface)

Metadata and optional descriptor members accepted by defineService.

**Example**

```ts
const options: DefineServiceOptions<"orders"> = { id: "orders" };
```

**Signature**

```ts
export interface DefineServiceOptions<
  Id extends string,
  Functions extends ServiceFunctionMap = Readonly<Record<never, never>>,
  Events extends ServiceEventMap = Readonly<Record<never, never>>,
  Tasks extends ServiceTaskMap = Readonly<Record<never, never>>,
  Jobs extends ServiceJobMap = Readonly<Record<never, never>>,
> extends DescriptorMetadata {
  readonly id?: Id;
  readonly functions?: Functions;
  readonly events?: Events;
  readonly tasks?: Tasks;
  readonly jobs?: Jobs;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L102)

### ServiceDescriptor (type alias)

Frozen service descriptor with identity-preserving public members.

**Example**

```ts
type Orders = ServiceDescriptor<"orders", { lookup: typeof lookup }>;
```

**Signature**

```ts
type ServiceDescriptor<
  Id extends string,
  Functions extends ServiceFunctionMap = Readonly<Record<never, never>>,
  Events extends ServiceEventMap = Readonly<Record<never, never>>,
  Tasks extends ServiceTaskMap = Readonly<Record<never, never>>,
  Jobs extends ServiceJobMap = Readonly<Record<never, never>>,
> = DescriptorBase<"service", Id> &
  PublicMembers<Functions, Events, Tasks, Jobs> & {
    readonly [serviceTypes]: ServiceTypeMembers<Functions, Events, Tasks, Jobs>;
  };
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L47)

### ServiceDescriptorAny (type alias)

Service descriptor with an unspecified ID and member set.

**Example**

```ts
function inspect(service: ServiceDescriptorAny) {
  return service.id;
}
```

**Signature**

```ts
type ServiceDescriptorAny = DescriptorBase<"service", string>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L61)

### ServiceEventMap (type alias)

Named event members on a service.

**Example**

```ts
type Events = ServiceEventMap;
```

**Signature**

```ts
type ServiceEventMap = Readonly<Record<string, EventDescriptorAny>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L13)

### ServiceEvents (type alias)

Extracts the event members recorded in a service type.

**Example**

```ts
type Events = ServiceEvents<typeof orders>;
```

**Signature**

```ts
type ServiceEvents<Service> = Service extends {
  readonly [serviceTypes]: { readonly events: infer Events };
}
  ? Events
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L75)

### ServiceFunctionMap (type alias)

Named function members on a service.

**Example**

```ts
type Functions = ServiceFunctionMap;
```

**Signature**

```ts
type ServiceFunctionMap = Readonly<Record<string, FunctionRefAny>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L9)

### ServiceFunctions (type alias)

Extracts the function members recorded in a service type.

**Example**

```ts
type Functions = ServiceFunctions<typeof orders>;
```

**Signature**

```ts
type ServiceFunctions<Service> = Service extends {
  readonly [serviceTypes]: { readonly functions: infer Functions };
}
  ? Functions
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L66)

### ServiceJobMap (type alias)

Named job members on a service.

**Example**

```ts
type Jobs = ServiceJobMap;
```

**Signature**

```ts
type ServiceJobMap = Readonly<Record<string, JobDescriptorAny>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L21)

### ServiceJobs (type alias)

Extracts the job members recorded in a service type.

**Example**

```ts
type Jobs = ServiceJobs<typeof orders>;
```

**Signature**

```ts
type ServiceJobs<Service> = Service extends {
  readonly [serviceTypes]: { readonly jobs: infer Jobs };
}
  ? Jobs
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L93)

### ServiceTaskMap (type alias)

Named task members on a service.

**Example**

```ts
type Tasks = ServiceTaskMap;
```

**Signature**

```ts
type ServiceTaskMap = Readonly<Record<string, TaskDescriptorAny>>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L17)

### ServiceTasks (type alias)

Extracts the task members recorded in a service type.

**Example**

```ts
type Tasks = ServiceTasks<typeof orders>;
```

**Signature**

```ts
type ServiceTasks<Service> = Service extends {
  readonly [serviceTypes]: { readonly tasks: infer Tasks };
}
  ? Tasks
  : never;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/define-service.types.ts#L84)

## `descriptor-guards.ts`

### assertServiceDescriptor

Require a valid service descriptor synchronously.

**Throws**

TypeError when invalid.

**Example**

```ts
assertServiceDescriptor(candidate);
```

**Signature**

```ts
declare const assertServiceDescriptor: (value: unknown) => asserts value is ServiceDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L67)

### assertServiceDescriptorEffect

Require a valid service descriptor in Effect.

**Example**

```ts
Effect.runSync(assertServiceDescriptorEffect(candidate));
```

**Signature**

```ts
declare const assertServiceDescriptorEffect: (
  value: unknown,
) => Effect.Effect<ServiceDescriptorAny, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L49)

### freezeServiceDescriptor

Validate and freeze a descriptor synchronously.

**Throws**

TypeError when the descriptor is invalid.

**Example**

```ts
freezeServiceDescriptor(service);
```

**Signature**

```ts
declare const freezeServiceDescriptor: <T extends ServiceDescriptorAny>(value: T) => T;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L93)

### freezeServiceDescriptorEffect

Validate and recursively freeze a descriptor in Effect.

**Example**

```ts
Effect.runSync(freezeServiceDescriptorEffect(service));
```

**Signature**

```ts
declare const freezeServiceDescriptorEffect: <T extends ServiceDescriptorAny>(
  value: T,
) => Effect.Effect<T, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L76)

### isServiceDescriptor

Check a service descriptor synchronously.

**Example**

```ts
isServiceDescriptor(candidate);
```

**Signature**

```ts
declare const isServiceDescriptor: (value: unknown) => value is ServiceDescriptorAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L40)

### isServiceDescriptorEffect

Check a service descriptor and every public member in Effect.

**Example**

```ts
Effect.runSync(isServiceDescriptorEffect(candidate));
```

**Signature**

```ts
declare const isServiceDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L15)

### serviceMemberEntries

Enumerate public descriptor members synchronously.

**Example**

```ts
serviceMemberEntries(service);
```

**Signature**

```ts
declare const serviceMemberEntries: (service: ServiceDescriptorAny) => [string, unknown][];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L120)

### serviceMemberEntriesEffect

Enumerate public descriptor members in Effect.

**Example**

```ts
Effect.runSync(serviceMemberEntriesEffect(service));
```

**Signature**

```ts
declare const serviceMemberEntriesEffect: (
  service: ServiceDescriptorAny,
) => Effect.Effect<Array<[string, unknown]>, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/descriptor-guards.ts#L102)

## `function-guards.ts`

### isFunctionDescriptor

Check a function member synchronously.

**Example**

```ts
isFunctionDescriptor(candidate);
```

**Signature**

```ts
declare const isFunctionDescriptor: (value: unknown) => value is FunctionRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/function-guards.ts#L34)

### isFunctionDescriptorEffect

Check a function member's descriptor contract in Effect.

**Example**

```ts
Effect.runSync(isFunctionDescriptorEffect(candidate));
```

**Signature**

```ts
declare const isFunctionDescriptorEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/function-guards.ts#L11)

## `guards.ts`

Public guard relay.

### "./descriptor-guards.js" (namespace export)

Re-exports all named exports from the "./descriptor-guards.js" module.

**Signature**

```ts
export * from "./descriptor-guards.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/guards.ts#L2)

### "./function-guards.js" (namespace export)

Re-exports all named exports from the "./function-guards.js" module.

**Signature**

```ts
export * from "./function-guards.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/guards.ts#L3)

### "./member-name.js" (namespace export)

Re-exports all named exports from the "./member-name.js" module.

**Signature**

```ts
export * from "./member-name.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/guards.ts#L4)

### "./reference-guards.js" (namespace export)

Re-exports all named exports from the "./reference-guards.js" module.

**Signature**

```ts
export * from "./reference-guards.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/guards.ts#L5)

## `index.ts`

### "./define-service.js" (namespace export)

Re-exports all named exports from the "./define-service.js" module.

**Signature**

```ts
export * from "./define-service.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L1)

### "./guards.js" (namespace export)

Re-exports all named exports from the "./guards.js" module.

**Signature**

```ts
export * from "./guards.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L2)

### "./service-context.js" (namespace export)

Re-exports all named exports from the "./service-context.js" module.

**Signature**

```ts
export * from "./service-context.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L3)

### "./service-error.js" (namespace export)

Re-exports all named exports from the "./service-error.js" module.

**Signature**

```ts
export * from "./service-error.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L4)

### "./service-observability.js" (namespace export)

Re-exports all named exports from the "./service-observability.js" module.

**Signature**

```ts
export * from "./service-observability.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L5)

### "./types.js" (namespace export)

Re-exports all named exports from the "./types.js" module.

**Signature**

```ts
export * from "./types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/index.ts#L6)

## `member-name.ts`

### RESERVED_SERVICE_MEMBER_NAMES

Compatibility alias for the reserved member list.

**Signature**

```ts
declare const RESERVED_SERVICE_MEMBER_NAMES: readonly [
  "kind",
  "id",
  "ref",
  "functions",
  "events",
  "tasks",
  "jobs",
  "capability",
  "title",
  "description",
  "tags",
  "handler",
  "constructor",
  "prototype",
  "__proto__",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L25)

### SERVICE_RESERVED_MEMBER_NAMES

Names disallowed as service members because they collide with descriptor metadata.

**Signature**

```ts
declare const SERVICE_RESERVED_MEMBER_NAMES: readonly [
  "kind",
  "id",
  "ref",
  "functions",
  "events",
  "tasks",
  "jobs",
  "capability",
  "title",
  "description",
  "tags",
  "handler",
  "constructor",
  "prototype",
  "__proto__",
];
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L6)

### assertServiceMemberName

Assert a canonical, nonreserved member name synchronously.

**Throws**

TypeError for invalid names.

**Example**

```ts
assertServiceMemberName("lookup");
```

**Signature**

```ts
declare const assertServiceMemberName: (value: unknown) => asserts value is string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L119)

### assertServiceMemberNameEffect

Validate one member name with a tagged Effect failure.

**Example**

```ts
Effect.runSync(assertServiceMemberNameEffect("lookup"));
```

**Signature**

```ts
declare const assertServiceMemberNameEffect: (
  value: unknown,
) => Effect.Effect<string, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L94)

### isReservedServiceMemberName

Check a candidate against the reserved member list.

**Example**

```ts
isReservedServiceMemberName(" id ");
```

**Signature**

```ts
declare const isReservedServiceMemberName: (value: unknown) => boolean;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L85)

### isReservedServiceMemberNameEffect

Check whether a candidate is a reserved member name in Effect.

**Example**

```ts
Effect.runSync(isReservedServiceMemberNameEffect("id"));
```

**Signature**

```ts
declare const isReservedServiceMemberNameEffect: (
  value: unknown,
) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L66)

### normalizeServiceMemberName

Normalize a service member name synchronously.

**Throws**

TypeError for non-string or empty input.

**Example**

```ts
normalizeServiceMemberName(" lookup ");
```

**Signature**

```ts
declare const normalizeServiceMemberName: (value: unknown) => string;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L57)

### normalizeServiceMemberNameEffect

Normalize a service member name inside Effect.

**Example**

```ts
Effect.runSync(normalizeServiceMemberNameEffect("lookup"));
```

**Signature**

```ts
declare const normalizeServiceMemberNameEffect: (
  value: unknown,
) => Effect.Effect<string, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/member-name.ts#L32)

## `reference-guards.ts`

### assertServiceRef

Require a service reference synchronously.

**Throws**

TypeError when invalid.

**Example**

```ts
assertServiceRef(candidate);
```

**Signature**

```ts
declare const assertServiceRef: (value: unknown) => asserts value is ServiceRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.ts#L53)

### assertServiceRefEffect

Require a service reference in Effect.

**Example**

```ts
Effect.runSync(assertServiceRefEffect(candidate));
```

**Signature**

```ts
declare const assertServiceRefEffect: (
  value: unknown,
) => Effect.Effect<ServiceRefAny, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.ts#L36)

### isServiceRef

Check a service reference synchronously.

**Example**

```ts
isServiceRef({ ref: createRef("service", "orders") });
```

**Signature**

```ts
declare const isServiceRef: (value: unknown) => value is ServiceRefAny;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.ts#L27)

### isServiceRefEffect

Check a service reference in Effect.

**Example**

```ts
Effect.runSync(isServiceRefEffect({ ref: createRef("service", "orders") }));
```

**Signature**

```ts
declare const isServiceRefEffect: (value: unknown) => Effect.Effect<boolean, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.ts#L12)

## `reference-guards.types.ts`

### ServiceRef (interface)

A stable reference to one service descriptor.

**Example**

```ts
const ref: ServiceRef<"orders"> = { ref: createRef("service", "orders") };
```

**Signature**

```ts
export interface ServiceRef<Id extends string = string> {
  readonly ref: Ref<"service", Id>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.types.ts#L6)

### ServiceRefAny (type alias)

Any service reference regardless of its stable ID.

**Example**

```ts
function inspect(value: ServiceRefAny) {
  return value.ref.id;
}
```

**Signature**

```ts
type ServiceRefAny = ServiceRef;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/reference-guards.types.ts#L13)

## `service-context.ts`

### freezeServiceContextValue

Copy and freeze a plain service context graph synchronously.

**Throws**

When a proxy or getter prevents graph inspection.

**Example**

```ts
freezeServiceContextValue({ enabled: true }, new WeakMap());
```

**Signature**

```ts
declare const freezeServiceContextValue: (value: unknown, seen: WeakMap<object, object>) => unknown;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-context.ts#L22)

### freezeServiceContextValueEffect

Copy and freeze a plain service context graph, preserving cycles and identity.

**Example**

```ts
Effect.runSync(freezeServiceContextValueEffect({ enabled: true }, new WeakMap()));
```

**Signature**

```ts
declare const freezeServiceContextValueEffect: (
  value: unknown,
  seen: WeakMap<object, object>,
) => Effect.Effect<unknown, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-context.ts#L10)

## `service-error.ts`

### ServiceValidationError (class)

Expected malformed service input or dependency rejection in an Effect operation.

**Example**

```ts
Effect.catchTag(defineServiceEffect(input), "ServiceValidationError", () => Effect.void);
```

**Signature**

```ts
declare class ServiceValidationError
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-error.ts#L7)

## `service-members.ts`

### assertUniqueServiceMembersEffect

Reject member names appearing in more than one category.

**Example**

```ts
Effect.runSync(assertUniqueServiceMembersEffect({ lookup }, {}));
```

**Signature**

```ts
declare const assertUniqueServiceMembersEffect: (
  ...args: Array<any>
) => Effect.Effect<undefined, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-members.ts#L47)

### copyServiceMembersEffect

Copy and validate one category of service members in insertion order.

**Example**

```ts
Effect.runSync(copyServiceMembersEffect({ lookup }, isFunctionDescriptorEffect, "function"));
```

**Signature**

```ts
declare const copyServiceMembersEffect: <T>(
  value: Readonly<Record<string, T>> | undefined,
  validate: ServiceMemberValidator<T>,
  kind: ServiceMemberKind,
) => Effect.Effect<Record<string, T>, ServiceValidationError, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-members.ts#L14)

## `service-members.types.ts`

### ServiceMemberKind (type alias)

Kinds accepted by service authoring.

**Example**

```ts
const kind: ServiceMemberKind = "function";
```

**Signature**

```ts
type ServiceMemberKind = "function" | "event" | "task" | "job";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-members.types.ts#L6)

### ServiceMemberValidator (type alias)

Predicate for one member category during Effect validation.

**Example**

```ts
const valid: ServiceMemberValidator<number> = (value) => Effect.succeed(typeof value === "number");
```

**Signature**

```ts
type ServiceMemberValidator<T> = (value: unknown) => Effect.Effect<boolean>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-members.types.ts#L13)

## `service-observability.ts`

### ServiceTelemetry (class)

Substitutable telemetry for all service operations.

**Example**

```ts
Effect.provide(isServiceRefEffect(value), ServiceTelemetryLive);
```

**Signature**

```ts
declare class ServiceTelemetry
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.ts#L8)

### ServiceTelemetryLive

Live span, call, duration, and failure instrumentation.

**Example**

```ts
Effect.provide(isServiceRefEffect(value), ServiceTelemetryLive);
```

**Signature**

```ts
declare const ServiceTelemetryLive: Layer.Layer<ServiceTelemetry, never, never>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.ts#L15)

### observeService

Observe one service operation using an injected or live observer.

**Example**

```ts
observeService("ref.is", Effect.succeed(true));
```

**Signature**

```ts
declare const observeService: <A, E, R>(
  operation: ServiceOperation,
  effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.ts#L29)

### runServiceSync

Run a dependency-free Effect for a synchronous compatibility caller.

**Throws**

TypeError for local validation, an original dependency error, or a defect.

**Example**

```ts
runServiceSync(Effect.succeed(1));
```

**Signature**

```ts
declare const runServiceSync: <A, E>(effect: Effect.Effect<A, E>) => A;
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.ts#L68)

## `service-observability.types.ts`

### ServiceOperation (type alias)

Fixed service operation labels keep telemetry dimensions bounded.

**Example**

```ts
const operation: ServiceOperation = "descriptor.is";
```

**Signature**

```ts
type ServiceOperation =
  | "define"
  | "members.copy"
  | "members.unique"
  | "member.normalize"
  | "member.is-reserved"
  | "member.assert"
  | "ref.is"
  | "ref.assert"
  | "descriptor.is"
  | "descriptor.assert"
  | "descriptor.freeze"
  | "descriptor.entries"
  | "function.is"
  | "context.freeze";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.types.ts#L6)

### ServiceTelemetryService (interface)

Injectable observation boundary for service operations.

**Example**

```ts
const telemetry: ServiceTelemetryService = { observe: (_, effect) => effect };
```

**Signature**

```ts
export interface ServiceTelemetryService {
  /** Observe one operation while preserving its channels.
   * @param operation - Fixed operation label.
   * @param effect - Operation to measure.
   * @returns The observed Effect with unchanged success and error channels.
   * @example telemetry.observe("ref.is", Effect.succeed(true));
   */
  readonly observe: <A, E, R>(
    operation: ServiceOperation,
    effect: Effect.Effect<A, E, R>,
  ) => Effect.Effect<A, E, R>;
}
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/service-observability.types.ts#L25)

## `types.ts`

Public declaration relay retained for package source compatibility.

### "./define-service.types.js" (namespace export)

Re-exports all named exports from the "./define-service.types.js" module.

**Signature**

```ts
export * from "./define-service.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/types.ts#L2)

### "./reference-guards.types.js" (namespace export)

Re-exports all named exports from the "./reference-guards.types.js" module.

**Signature**

```ts
export * from "./reference-guards.types.js";
```

[Source](https://github.com/rel-kit/relkit/blob/main/packages/services/src/types.ts#L3)