# HTTP
Source: https://confect.dev/clients/js/http

Call your Confect functions over HTTP from any JavaScript runtime.

`HttpClient` is an [Effect service](https://effect.website/docs/requirements-management/services/) that wraps Convex's [`ConvexHttpClient`](https://docs.convex.dev/api/classes/browser.ConvexHttpClient). It provides `query`, `mutation`, and `action` methods that accept refs and automatically encode args and decode return values through the schemas defined in your function specs. It works in any JavaScript runtime that supports `fetch`.

## Setup

Create the `HttpClient` layer by passing your Convex deployment URL.

```ts theme={null}
import { HttpClient } from "@confect/js";
import * as Effect from "effect/Effect";

const HttpClientLive = HttpClient.layer("https://example-123.convex.cloud");
```

The layer can then be provided to any Effect that uses the `HttpClient` service.

## Calling functions

Use the `HttpClient` service inside `Effect.gen` to call your functions with refs, the same way you would with `@confect/react` hooks or `@confect/test`.

```ts theme={null}
import { HttpClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const program = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  const notes = yield* client.query(refs.public.notes.list);

  const noteId = yield* client.mutation(refs.public.notes.insert, {
    text: "Hello from the server",
  });

  const result = yield* client.action(refs.public.random.getNumber);
});
```

Each method returns an `Effect` that can fail with `HttpClientError` (wrapping transport-level errors) or `ParseResult.ParseError` (if schema encoding or decoding fails).

## Typed errors

When a ref's spec declares an `error` schema, the decoded error is added to the returned `Effect`'s error channel alongside `HttpClientError` and `ParseError`. See [Error Handling](/server/error-handling) for how to declare error schemas.

```ts theme={null}
import { HttpClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const lookup = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  return yield* client.query(refs.public.notes.getOrFail, { noteId });
});
// Effect.Effect<Note, NoteNotFound | HttpClientError | ParseError, HttpClient.HttpClient>
```

Recover from a typed failure with `Effect.catchTag` (or any other `Effect` error combinator).

```ts theme={null}
lookup.pipe(
  Effect.catchTag("NoteNotFound", (error) =>
    Effect.succeed(`Note ${error.noteId} not found.`),
  ),
);
```

## Authentication

Set or clear the auth token before making authenticated requests.

```ts theme={null}
Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  yield* client.setAuth(token);

  const identity = yield* client.query(refs.public.auth.getIdentity);

  yield* client.clearAuth;
});
```

## Running programs

Provide the `HttpClient` layer when running your program.

```ts theme={null}
import { HttpClient } from "@confect/js";
import * as Console from "effect/Console";
import * as Effect from "effect/Effect";

const HttpClientLive = HttpClient.layer("https://example-123.convex.cloud");

const program = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  const notes = yield* client.query(refs.public.notes.list);
  yield* Console.log(notes);
});

Effect.runPromise(program.pipe(Effect.provide(HttpClientLive)));
```

## Differences from `ConvexHttpClient`

| `ConvexHttpClient`                       | `HttpClient`                                                    |
| ---------------------------------------- | --------------------------------------------------------------- |
| Functions referenced via `api.module.fn` | Functions referenced via `refs`                                 |
| Args passed directly to Convex as-is     | Args are schema-encoded from `Type` to `Encoded` before sending |
| Return values received directly as-is    | Return values are schema-decoded from `Encoded` to `Type`       |
| Methods return `Promise`                 | Methods return `Effect` with typed errors                       |


# WebSocket
Source: https://confect.dev/clients/js/websocket

Call your Confect functions and subscribe to reactive queries over a persistent WebSocket connection.

`WebSocketClient` is an [Effect service](https://effect.website/docs/requirements-management/services/) that wraps Convex's [`ConvexClient`](https://docs.convex.dev/api/classes/browser.ConvexClient). It provides the same `query`, `mutation`, and `action` methods as [`HttpClient`](/clients/js/http), plus a `reactiveQuery` method that returns a [`Stream`](https://effect.website/docs/stream/introduction/) of live results. It works in any JavaScript environment that supports `WebSocket`.

The WebSocket connection is managed as a [scoped resource](https://effect.website/docs/resource-management/scope/)—it is opened when the layer is provided and closed automatically when the scope ends.

## Setup

Create the `WebSocketClient` layer by passing your Convex deployment URL.

```ts theme={null}
import { WebSocketClient } from "@confect/js";

const WebSocketClientLive = WebSocketClient.layer(
  "https://example-123.convex.cloud",
);
```

The layer can then be provided to any Effect that uses the `WebSocketClient` service. The underlying WebSocket connection is closed automatically when the layer's scope ends—there is no need to close it manually.

## Calling functions

Use the `WebSocketClient` service inside `Effect.gen` to call your functions with refs, the same way you would with `HttpClient`, `@confect/react` hooks, or `@confect/test`.

```ts theme={null}
import { WebSocketClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const program = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  const notes = yield* client.query(refs.public.notes.list);

  const noteId = yield* client.mutation(refs.public.notes.insert, {
    text: "Hello from the server",
  });

  const result = yield* client.action(refs.public.random.getNumber);
});
```

Each method returns an `Effect` that can fail with `WebSocketClientError` (wrapping transport-level errors) or `ParseResult.ParseError` (if schema encoding or decoding fails).

## Reactive queries

`reactiveQuery` subscribes to a query over the WebSocket connection and returns a `Stream` that emits a new value whenever the query result changes on the server.

```ts theme={null}
import { WebSocketClient } from "@confect/js";
import * as Console from "effect/Console";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";

import refs from "./confect/_generated/refs";

const program = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  yield* client
    .reactiveQuery(refs.public.notes.list)
    .pipe(Stream.runForEach((notes) => Console.log(notes)));
});
```

The underlying WebSocket subscription is cleaned up automatically when the stream's scope ends (for example, when the consuming Effect is interrupted or when an operator like `Stream.take` completes).

## Typed errors

When a ref's spec declares an `error` schema, the decoded error is added to the error channel of `query`, `mutation`, `action`, and `reactiveQuery` alongside `WebSocketClientError` and `ParseError`. See [Error Handling](/server/error-handling) for how to declare error schemas.

```ts theme={null}
import { WebSocketClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const lookup = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  return yield* client.query(refs.public.notes.getOrFail, { noteId });
});
// Effect.Effect<Note, NoteNotFound | WebSocketClientError | ParseError, WebSocketClient.WebSocketClient>
```

For `reactiveQuery`, a typed failure terminates the `Stream` with the decoded value in its error channel—the subscription does not stay open across failures. Recover with `Stream.catchTag` (or any other `Stream` error combinator) to keep the stream alive across typed failures.

```ts theme={null}
import { WebSocketClient } from "@confect/js";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";

import refs from "./confect/_generated/refs";

const lookups = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  return client
    .reactiveQuery(refs.public.notes.getOrFail, { noteId })
    .pipe(
      Stream.catchTag("NoteNotFound", (error) =>
        Stream.succeed(`Note ${error.noteId} not found.`),
      ),
    );
});
```

## Authentication

Set the authentication token provider before making authenticated requests. `setAuth` accepts an Effect-returning function that is called whenever a token is needed or expires.

```ts theme={null}
Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  yield* client.setAuth(
    ({ forceRefreshToken }) =>
      Effect.promise(() => getToken({ forceRefreshToken })),
    (isAuthenticated) => Console.log(`Auth state changed: ${isAuthenticated}`),
  );

  const identity = yield* client.query(refs.public.auth.getIdentity);
});
```

The optional second argument is a function that receives the current `isAuthenticated` status and returns an `Effect` to run whenever the authentication state changes.

## Running programs

Provide the `WebSocketClient` layer when running your program.

```ts theme={null}
import { WebSocketClient } from "@confect/js";
import * as Console from "effect/Console";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";

const WebSocketClientLive = WebSocketClient.layer(
  "https://example-123.convex.cloud",
);

const program = Effect.gen(function* () {
  const client = yield* WebSocketClient.WebSocketClient;

  yield* client.reactiveQuery(refs.public.notes.list).pipe(
    Stream.take(10),
    Stream.runForEach((notes) => Console.log(notes)),
  );
});

Effect.runPromise(program.pipe(Effect.provide(WebSocketClientLive)));
```

## Differences from `ConvexClient`

| `ConvexClient`                                                | `WebSocketClient`                                               |
| ------------------------------------------------------------- | --------------------------------------------------------------- |
| Functions referenced via `api.module.fn`                      | Functions referenced via `refs`                                 |
| Args passed directly to Convex as-is                          | Args are schema-encoded from `Type` to `Encoded` before sending |
| Return values received directly as-is                         | Return values are schema-decoded from `Encoded` to `Type`       |
| `query`/`mutation`/`action` return `Promise`                  | `query`/`mutation`/`action` return `Effect` with typed errors   |
| `onUpdate` uses callbacks and returns an unsubscribe function | `reactiveQuery` returns a `Stream` with automatic cleanup       |
| Must call `close()` manually                                  | Connection closed automatically when the layer's scope ends     |
| `setAuth` takes a `Promise`-returning callback                | `setAuth` takes an `Effect`-returning function                  |


# React
Source: https://confect.dev/clients/react

Use Confect's React hooks to call your functions from the client.

`@confect/react` provides drop-in replacements for Convex's React hooks. Each hook automatically encodes your args and decodes return values through the [Effect Schemas](/concepts/schema-restrictions) defined in your [function specs](/concepts/spec-impl-model). You work with the Schema `Type` (decoded) values on both sides—the hooks handle the round-trip to Convex's `Encoded` representation transparently.

Functions are referenced via `refs` (from `confect/_generated/refs`) instead of Convex's `api` object. Each ref carries the `args`, `returns`, and (optionally) `error` schemas from the corresponding function spec, which is what enables the automatic encoding and decoding.

## Setup

The React provider setup is the same as vanilla Convex.

```tsx src/main.tsx theme={null}
import { ConvexProvider, ConvexReactClient } from "convex/react";
import React from "react";
import ReactDOM from "react-dom/client";

import App from "./App";

const convexClient = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <ConvexProvider client={convexClient}>
      <App />
    </ConvexProvider>
  </React.StrictMode>,
);
```

## `useQuery`

Encodes args using the spec's `args` schema, passes them to Convex, and decodes the result using the spec's `returns` schema. Returns a `QueryResult<A, E>`—a tagged union with `Loading`, `Success`, and `Failure` variants.

Given this spec:

```ts confect/notes.spec.ts theme={null}
import { FunctionSpec, GroupSpec } from "@confect/core";
import * as Schema from "effect/Schema";

import notes from "./_generated/tables/notes";

export default GroupSpec.make().addFunction(
  FunctionSpec.publicQuery({
    name: "list",
    args: () => Schema.Struct({}),
    returns: () => Schema.Array(notes.Doc),
  }),
);
```

The hook accepts `{}` (the `Type` of `Schema.Struct({})`) as args and returns a `QueryResult<readonly notes.Doc["Type"][]>`. Match it with `QueryResult.match`:

```tsx theme={null}
import { QueryResult, useQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const NoteList = () => {
  const notes = useQuery(refs.public.notes.list, {});

  return QueryResult.match(notes, {
    onLoading: () => <p>Loading…</p>,
    onSuccess: (notes) => (
      <ul>
        {notes.map((note) => (
          <li key={note._id}>{note.text}</li>
        ))}
      </ul>
    ),
  });
};
```

`QueryResult` also exposes the lower-level predicates `QueryResult.isLoading`, `QueryResult.isSuccess`, and `QueryResult.isFailure` for cases where pattern matching is awkward.

### Typed errors

When the ref's spec declares an `error` schema, `useQuery` returns `QueryResult<A, E>` and `QueryResult.match` requires an `onFailure` handler that receives the decoded typed error. See [Error Handling](/server/error-handling) for how to declare error schemas.

```tsx theme={null}
import { QueryResult, useQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const NoteLookup = ({ noteId }: { noteId: string }) => {
  const lookup = useQuery(refs.public.notes.getOrFail, { noteId });

  return (
    <div>
      {QueryResult.match(lookup, {
        onLoading: () => "Looking up…",
        onSuccess: (note) => `Found: ${note.text}`,
        onFailure: (error) => `Note ${error.noteId} not found.`,
      })}
    </div>
  );
};
```

Failures that are not declared in the `error` schema are not surfaced as `Failure`. They propagate the same way they do with `convex/react`'s `useQuery` (typically reaching the nearest [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)).

### Skipping queries

Pass `"skip"` instead of args to disable the query subscription. The hook returns a `Loading` variant whose `skipped` flag is `true`, which lets you distinguish a query that is genuinely in flight from one sitting idle because no args have been provided.

```tsx theme={null}
import { QueryResult, useQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const NoteDetail = ({ selectedId }: { selectedId: string | undefined }) => {
  const note = useQuery(
    refs.public.notes.get,
    selectedId !== undefined ? { id: selectedId } : "skip",
  );

  return QueryResult.match(note, {
    onLoading: (skipped) => <p>{skipped ? "Select a note" : "Loading…"}</p>,
    onSuccess: (note) => <p>{note.text}</p>,
  });
};
```

## `usePaginatedQuery`

Loads data reactively from a [paginated query](/server/functions#paginated-queries), mirroring the ergonomics of `usePaginatedQuery` from `convex/react`. The ref must come from a spec defined with `FunctionSpec.publicPaginatedQuery` — passing any other ref fails at runtime with an error pointing at the constructor.

Args are encoded using the spec's user-args schema (`paginationOpts` is managed by the hook, not the caller), and each loaded page is decoded using the spec's `item` schema. Pass `"skip"` instead of args to disable the query, like `useQuery`.

Returns a `PaginatedQueryResult<Item, E>`. The loaded variants — `LoadingFirstPage`, `LoadingMore`, `CanLoadMore`, and `Exhausted` — all carry `results` and `isLoading`, and `CanLoadMore` additionally carries `loadMore`, so the common UI needs only field access and a couple of predicates:

```tsx theme={null}
import { PaginatedQueryResult, usePaginatedQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const PaginatedNoteList = () => {
  const notes = usePaginatedQuery(
    refs.public.notes.listByAuthor,
    { author: "ada" },
    { initialNumItems: 10 },
  );

  return (
    <div>
      <ul>
        {notes.results.map((note) => (
          <li key={note._id}>{note.text}</li>
        ))}
      </ul>
      {notes.isLoading && <p>Loading…</p>}
      {PaginatedQueryResult.isCanLoadMore(notes) && (
        <button type="button" onClick={() => notes.loadMore(10)}>
          Load more
        </button>
      )}
    </div>
  );
};
```

`loadMore` lives only on `CanLoadMore`, the one state it can make progress from — the underlying Convex hook exposes it on every status, but calling it while a page is in flight, once the list is exhausted, or after a failure is an intentional no-op there. Narrowing with `isCanLoadMore` (or `match`'s `onCanLoadMore`) makes that statically apparent instead of silently dropping the call.

`PaginatedQueryResult` also provides `match` for exhaustive pattern matching, and the predicates `isLoadingFirstPage`, `isLoadingMore`, `isExhausted`, `isLoading`, and `isFailure`.

### Typed errors

When the spec declares an `error` schema, the result type gains a `Failure` variant carrying the decoded typed error — errors are values, consistent with `useQuery`. Narrow with `PaginatedQueryResult.isFailure` (or handle `onFailure` in `match`) to reach it:

```tsx theme={null}
const notes = usePaginatedQuery(
  refs.public.notes.listOrFail,
  {},
  { initialNumItems: 10 },
);

if (PaginatedQueryResult.isFailure(notes)) {
  // `results` holds the pages loaded before the failure, so they can still
  // be rendered alongside the error.
  return (
    <div>
      <NoteList notes={notes.results} />
      <p>Failed to load more: {notes.error.reason}</p>
    </div>
  );
}
// notes: narrowed to the non-`Failure` variants — isLoading is available too.
```

Every variant carries `results`, `Failure` included: when a later page fails, the pages already loaded are not discarded.

Without an `error` schema, the `Failure` variant is excluded from the type entirely, so no narrowing is needed. Failures not declared in the `error` schema are thrown during render and propagate to the nearest [error boundary](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary).

<Note>`usePaginatedQuery` requires `convex` 1.36.0 or newer.</Note>

## `useMutation`

Returns a function that encodes args using the spec's `args` schema, calls the Convex mutation, and decodes the result using the spec's `returns` schema. The returned promise's shape depends on whether the spec declares an `error` schema.

### Without an `error` schema

The function returns `Promise<A>`, matching `convex/react`'s `useMutation`. Undeclared failures still reject the promise.

```ts confect/notes.spec.ts theme={null}
import { Id } from "./_generated/id";

FunctionSpec.publicMutation({
  name: "insert",
  args: () => Schema.Struct({ text: Schema.String }),
  returns: () => Id("notes"),
});
```

```tsx theme={null}
import { useMutation } from "@confect/react";
import refs from "../confect/_generated/refs";

const InsertNote = () => {
  const insertNote = useMutation(refs.public.notes.insert);

  return (
    <button onClick={() => void insertNote({ text: "Hello" })}>
      Insert note
    </button>
  );
};
```

### With an `error` schema

When the spec declares an `error` schema, the function returns `Promise<Either<A, E>>`. Unwrap with `Either.match` (or another `Either` combinator) to handle both branches. Undeclared failures still reject the promise.

```ts confect/notes.spec.ts theme={null}
import { Id } from "./_generated/id";

FunctionSpec.publicMutation({
  name: "deleteOrFail",
  args: () => Schema.Struct({ noteId: Id("notes") }),
  returns: () => Schema.Null,
  error: () => Schema.Union(NoteNotFound, Forbidden),
});
```

```tsx theme={null}
import { useMutation } from "@confect/react";
import * as Either from "effect/Either";
import refs from "../confect/_generated/refs";

const DeleteNote = ({ noteId }: { noteId: string }) => {
  const deleteOrFail = useMutation(refs.public.notes.deleteOrFail);

  const handleClick = async () => {
    const result = await deleteOrFail({ noteId });
    Either.match(result, {
      onLeft: (error) => console.error(error._tag, error),
      onRight: () => console.log("deleted"),
    });
  };

  return <button onClick={handleClick}>Delete</button>;
};
```

## `useAction`

Same shape as `useMutation`: returns `Promise<A>` when the ref has no `error` schema, and `Promise<Either<A, E>>` when it does.

```ts confect/random.spec.ts theme={null}
FunctionSpec.publicAction({
  name: "getNumber",
  args: () => Schema.Struct({}),
  returns: () => Schema.Number,
});
```

```tsx theme={null}
import { useAction } from "@confect/react";
import refs from "../confect/_generated/refs";

const RandomNumber = () => {
  const getRandom = useAction(refs.public.random.getNumber);

  const handleClick = () => {
    void getRandom({}).then(console.log);
  };

  return <button onClick={handleClick}>Get random</button>;
};
```

## Differences from vanilla Convex hooks

| Vanilla Convex                                        | Confect                                                                                                 |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Functions referenced via `api.module.fn`              | Functions referenced via `refs`                                                                         |
| Args passed directly to Convex as-is                  | Args are schema-encoded from `Type` to `Encoded` before sending to Convex                               |
| Return values received directly from Convex as-is     | Return values are schema-decoded from `Encoded` to `Type` before returning                              |
| `useQuery` returns `T \| undefined`                   | `useQuery` returns `QueryResult<A, E>`                                                                  |
| Cannot distinguish loading from skipped               | `Loading` carries a `skipped: boolean` flag                                                             |
| `useMutation`/`useAction` always return `Promise<T>`  | Refs with an `error` schema return `Promise<Either<A, E>>`; refs without one still return `Promise<A>`  |
| `usePaginatedQuery` throws query errors during render | `usePaginatedQuery` returns `PaginatedQueryResult<Item, E>` with declared errors as a `Failure` variant |
| Pass `"skip"` to disable query subscription           | Same—pass `"skip"` to disable query subscription                                                        |


# File Naming Conventions
Source: https://confect.dev/concepts/file-naming-conventions

Recommended patterns for organizing spec, impl, and related files in your confect directory.

Confect requires a small number of fixed entry-point files in your `confect/` directory (see [Project Structure](/concepts/project-structure)). Beyond those, organize your API as colocated `*.spec.ts`/`*.impl.ts` pairs, one pair per group. The group's name is the file's path within `confect/` (its stem for top-level groups, the dot-joined directory path for nested groups).

## Spec and impl files

Name each group's spec and impl with `.spec.ts` and `.impl.ts` suffixes. Each file must default-export its `GroupSpec` or `GroupImpl`; additional named exports on `.spec.ts` (for example error classes) are fine.

A complete pair looks like this. The impl default-imports its sibling spec, passes it to `FunctionImpl.make` and `GroupImpl.make`, and finalizes the resulting layer with `GroupImpl.finalize`:

```ts confect/notes.spec.ts theme={null}
import { GroupSpec, FunctionSpec } from "@confect/core";
import * as Schema from "effect/Schema";

import notes from "./_generated/tables/notes";

const list = FunctionSpec.publicQuery({
  name: "list",
  args: () => Schema.Struct({}),
  returns: () => Schema.Array(notes.Doc),
});

export default GroupSpec.make().addFunction(list);
```

```ts confect/notes.impl.ts theme={null}
import { FunctionImpl, GroupImpl } from "@confect/server";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";

import databaseSchema from "./_generated/schema";
import { DatabaseReader } from "./_generated/services";
import notes from "./notes.spec";

const list = FunctionImpl.make(databaseSchema, notes, "list", () =>
  Effect.gen(function* () {
    const reader = yield* DatabaseReader;

    return yield* reader
      .table("notes")
      .index("by_creation_time", "desc")
      .collect();
  }).pipe(Effect.orDie),
);

export default GroupImpl.make(databaseSchema, notes).pipe(
  Layer.provide(list),
  GroupImpl.finalize,
);
```

Run `confect codegen` after adding or changing specs and impls.

<Note>
  A file's path within `confect/` determines the public Convex API path it
  produces—`confect/notes_and_random/notes.spec.ts` becomes
  `internal.notes_and_random.notes.list`. Renaming a file or directory renames
  the API path, so treat these paths as part of your API's contract.
</Note>

<Warning>
  Some test runners (such as Vitest and Jest) treat `.spec.ts` files as test
  files by default. If your test runner is picking up Confect spec files,
  configure it to exclude them. For example, in Vitest you can add
  `"**/*.spec.ts"` to the `test.exclude` array in your config.
</Warning>

## Native Convex functions

When a group wraps [native Convex functions](/server/plain-convex-functions) (for use with components or other libraries), place the plain function definitions in a file named after the group—without a suffix. This puts all three files for a group side by side:

```
confect/
  workpool.ts          ← native Convex function definitions
  workpool.spec.ts     ← spec (type-only imports from workpool.ts)
  workpool.impl.ts     ← impl (runtime imports from workpool.ts)
```

## Node actions

[Node action](/server/node-actions) groups follow the same `.spec.ts`/`.impl.ts` naming and nesting conventions as any other group. A group is Node-runtime when its spec is built with `GroupSpec.makeNode()` (rather than `GroupSpec.make()`); its impl is otherwise identical to a non-node impl, passing the database schema from `_generated/schema`. Confect emits Convex's `"use node"` directive into the generated module based on the spec.

```
confect/
  email.spec.ts
  email.impl.ts
```

## Nested groups

When a group contains subgroups, place each subgroup's `.spec.ts`/`.impl.ts` pair inside a subdirectory named after the parent group. The parent group itself does not need a spec or impl file—it is composed from its subgroups by their paths.

```
confect/
  billing/
    invoices.spec.ts        ← group path billing.invoices
    invoices.impl.ts
    subscriptions.spec.ts   ← group path billing.subscriptions
    subscriptions.impl.ts
```

## Full example

Putting it all together, a project using all of these conventions might look like this:

<Tree>
  <Tree.Folder name="confect">
    <Tree.Folder name="_generated">
      <Tree.File name="convexSchema.ts" />

      <Tree.File name="refs.ts" />

      <Tree.File name="schema.ts" />

      <Tree.File name="services.ts" />

      <Tree.File name="spec.ts" />

      <Tree.Folder name="registeredFunctions">
        <Tree.File name="env.ts" />

        <Tree.Folder name="notes_and_random">
          <Tree.File name="notes.ts" />

          <Tree.File name="random.ts" />
        </Tree.Folder>

        <Tree.File name="workpool.ts" />

        <Tree.File name="email.ts" />
      </Tree.Folder>

      <Tree.Folder name="tables">
        <Tree.File name="notes.ts" />

        <Tree.File name="users.ts" />
      </Tree.Folder>

      <Tree.File name="id.ts" />
    </Tree.Folder>

    <Tree.Folder name="notes_and_random">
      <Tree.File name="notes.spec.ts" />

      <Tree.File name="notes.impl.ts" />

      <Tree.File name="random.spec.ts" />

      <Tree.File name="random.impl.ts" />
    </Tree.Folder>

    <Tree.Folder name="tables">
      <Tree.File name="notes.ts" />

      <Tree.File name="users.ts" />
    </Tree.Folder>

    <Tree.File name="email.spec.ts" />

    <Tree.File name="email.impl.ts" />

    <Tree.File name="env.spec.ts" />

    <Tree.File name="env.impl.ts" />

    <Tree.File name="http.ts" />

    <Tree.File name="workpool.ts" />

    <Tree.File name="workpool.spec.ts" />

    <Tree.File name="workpool.impl.ts" />
  </Tree.Folder>
</Tree>


# Packages
Source: https://confect.dev/concepts/packages

Understand the packages that make up the Confect ecosystem.

| Package                                                            | Description                                                      |
| ------------------------------------------------------------------ | ---------------------------------------------------------------- |
| [`@confect/core`](https://www.npmjs.com/package/@confect/core)     | Shared specs and schemas used by all Confect packages            |
| [`@confect/cli`](https://www.npmjs.com/package/@confect/cli)       | Developer tooling for codegen and sync                           |
| [`@confect/server`](https://www.npmjs.com/package/@confect/server) | Backend bindings to the Convex platform                          |
| [`@confect/js`](https://www.npmjs.com/package/@confect/js)         | JavaScript client bindings for any JS runtime                    |
| [`@confect/react`](https://www.npmjs.com/package/@confect/react)   | Client-side bindings for React apps                              |
| [`@confect/test`](https://www.npmjs.com/package/@confect/test)     | Utilities for testing Confect apps without a live Convex backend |


# Project Structure
Source: https://confect.dev/concepts/project-structure

Understand the structure of a Confect project.

<Tree>
  <Tree.Folder name="confect">
    <Tree.Folder name="_generated">
      <Tree.File name="components.ts" />

      <Tree.File name="convexSchema.ts" />

      <Tree.File name="docs.ts" />

      <Tree.File name="id.ts" />

      <Tree.File name="refs.ts" />

      <Tree.File name="schema.ts" />

      <Tree.File name="services.ts" />

      <Tree.File name="spec.ts" />

      <Tree.Folder name="registeredFunctions">
        <Tree.File name="env.ts" />

        <Tree.Folder name="notes_and_random">
          <Tree.File name="notes.ts" />

          <Tree.File name="random.ts" />
        </Tree.Folder>

        <Tree.File name="workpool.ts" />
      </Tree.Folder>

      <Tree.Folder name="tables">
        <Tree.File name="notes.ts" />

        <Tree.File name="users.ts" />
      </Tree.Folder>
    </Tree.Folder>

    <Tree.Folder name="notes_and_random">
      <Tree.File name="notes.spec.ts" />

      <Tree.File name="notes.impl.ts" />

      <Tree.File name="random.spec.ts" />

      <Tree.File name="random.impl.ts" />
    </Tree.Folder>

    <Tree.Folder name="tables">
      <Tree.File name="notes.ts" />

      <Tree.File name="users.ts" />
    </Tree.Folder>

    <Tree.File name="auth.ts" />

    <Tree.File name="crons.ts" />

    <Tree.File name="env.spec.ts" />

    <Tree.File name="env.impl.ts" />

    <Tree.File name="http.ts" />

    <Tree.File name="workpool.spec.ts" />

    <Tree.File name="workpool.impl.ts" />
  </Tree.Folder>

  <Tree.Folder name="convex" />
</Tree>

## `confect/`

### `_generated/`

#### `components.ts`

Contains a typed `components` registry with one entry per Convex [component](https://docs.convex.dev/components) installed via `app.use(...)` in `convex/convex.config.ts`. Use it wherever a component client expects a component reference (e.g. `new Workpool(components.workpool, ...)`). Unlike the `components` export of `convex/_generated/api`, this file is safe to import from your impl files' import graphs. See [Components](/server/components).

#### `convexSchema.ts`

Contains the Convex deploy-time `SchemaDefinition` (a single `defineSchema({...})` call) assembled from every `confect/tables/*.ts` module. `convex/schema.ts` re-exports its default so Convex's CLI and `convex-test` find it where they expect. You should never import this file directly from your own code — use `_generated/schema.ts` for runtime needs.

#### `docs.ts`

Contains a named TypeScript `interface` for each table's document — `NotesDoc`, `UsersDoc`, etc. — plus a `Docs` registry mapping each table name to its interface. These are pure types (no runtime code): use them to annotate a value with a table's document type, e.g. `const note: NotesDoc = …`. The `Docs` registry is what lets the `DatabaseReader`/`DatabaseWriter` services hand documents back under their named types. See [Document types](/server/database/schema#document-types).

#### `id.ts`

Contains a type-constrained `Id` constructor whose only argument is the union of your table names — for example, `Id("users")` returns the `Schema` for an `_id` value in the `users` table. Use this when defining cross-table references (e.g. a `userId: Id("users")` field) and inside spec `args`/`returns` schemas. The type-level constraint catches typos at compile time, replacing the loosely-typed `GenericId.GenericId("users")` form.

#### `registeredFunctions/`

Contains one module per group (for example `registeredFunctions/notes_and_random/notes.ts`), each exporting that group's functions in a form the Convex CLI can consume. These modules are consumed by the generated `convex/` files; you should not need to import them directly.

#### `refs.ts`

Contains a single default `Refs` export, which is a map of your Convex functions and their [function names](https://docs.convex.dev/api/modules/server#getfunctionname) and args/returns `Schema`s. Use this to invoke your Convex functions from the client or inside Convex functions using the `*Runner` services (`QueryRunner`, `MutationRunner`, and `ActionRunner`).

#### `schema.ts`

Contains the runtime `DatabaseSchema` — the codec-lookup view of your tables. Impls import it and pass it to `FunctionImpl.make` / `GroupImpl.make`. It is generated from `confect/tables/*.ts` and intentionally avoids any `convex/server` import so a runtime cold start never evaluates `defineSchema(...)`. Each table's field-schema is constructed lazily on the first access to its `Fields`, `Doc`, or `tableDefinition` and then cached, so a function only pays the schema-construction cost at cold start for the tables it actually touches via `db.table(name)`. Use this when a test or a non-codegen-generated module needs to refer to your `DatabaseSchema` type or value.

#### `tables/`

Contains one wrapper module per user-authored table (for example `tables/notes.ts` for `confect/tables/notes.ts`). Each wrapper applies the filename-derived table name to the `Table` defined in `confect/tables/<name>.ts` and re-exports it as the default. Specs, impls, and other consumers should default-import from `confect/_generated/tables/<name>` to reach a table's `Doc`, `Fields`, and `tableName` properties — for example, `import notes from "../_generated/tables/notes"` and then `notes.Doc`.

#### `services.ts`

Contains Effect service wrappers for Convex platform capabilities, scoped to your app's database schema. Use these in your function implementation handlers. See [Services](/concepts/services) for a full list.

#### `spec.ts`

Contains your assembled Confect spec — every function group, of any runtime (including Node action groups) — used to build `refs.ts`.

### `auth.ts`

<Badge>Optional</Badge>

Corresponds 1:1 with `convex/auth.config.ts`. Use this to [configure auth](https://docs.convex.dev/auth).

### `crons.ts`

<Badge>Optional</Badge>

Expects a default `CronJobs` export defining your [cron jobs](/server/cron-jobs).

### `http.ts`

<Badge>Optional</Badge>

Expects a default Convex `HttpRouter` export. Construct this using Confect's `HttpApi.make` and `@effect/platform`'s [HTTP API modules](https://github.com/Effect-TS/effect/blob/main/packages/platform/README.md#http-api).

### `tables/`

<Badge>Required</Badge>

Defines your database tables, one file per table. The **filename is the table name** — `confect/tables/notes.ts` defines a table called `notes` — so filenames must be valid JS identifiers and may not start with `_` (Convex reserves underscore-prefixed names for system tables). Each module **must default-export a `Table`** (built with `Table.make(...)`); codegen reads `module.default`, validates the filename, and applies it as the table name to produce `_generated/tables/<name>.ts`. Other modules import from the wrapper, not directly from `tables/`. Codegen also scans this directory to produce `_generated/schema.ts` (runtime), `_generated/convexSchema.ts` (deploy), and `_generated/id.ts` (the cross-table `Id` constructor). See [Schema](/server/database/schema).

### `*.spec.ts`/`*.impl.ts`

<Badge>Required</Badge>

Your Convex API is defined as colocated `*.spec.ts`/`*.impl.ts` pairs, one pair per group. Each file's path within `confect/` becomes the group's name. See [File Naming Conventions](/concepts/file-naming-conventions) and [The Spec/Impl Model](/concepts/spec-impl-model).

## Rules

* Your `confect/` directory should always be a sibling of your `convex/` directory.
* The `confect/_generated/` directory is generated by the Confect CLI. You should never modify files in this directory directly.
* Confect treats the `convex` directory as a codegen target. While using Confect, you should never modify files in the `convex` folder directly, except for `tsconfig.json` and `convex.config.ts`.


# Schema Restrictions
Source: https://confect.dev/concepts/schema-restrictions

Understand the restrictions on Effect schemas that can be used in Confect.

Not every Effect `Schema` is valid for use in Confect. Remember that an Effect `Schema` looks like this:

```typescript theme={null}
type Schema<Type, Encoded, Context>
```

For `Schema`s used in Confect:

* `Type` represents the value that you'll be operating on in your code. Any TypeScript type is permitted here.
* `Encoded` represents the value that is stored in the database or serialized as the argument/output of a Convex function. This must be a valid [Convex value](https://docs.convex.dev/database/types#convex-values).
* `Context` is not currently supported. It should always be `never`.

## Additional caveats

### No-op returns from Convex functions

Unlike the vanilla APIs, Convex functions defined with Confect may not return `undefined` or `void`—use `null` (`Schema.Null` as the `returns` validator) instead. Convex coerces `undefined`/`void` returns to `null` anyways—this just makes that more explicit.

```typescript ✅ theme={null}
FunctionSpec.publicQuery({
  name: "myQuery",
  args: () => Schema.Struct({}),
  returns: () => Schema.Null,
});
```

```typescript ❌ theme={null}
FunctionSpec.publicQuery({
  name: "myQuery",
  args: () => Schema.Struct({}),
  returns: () => Schema.Undefined,
});
```

```typescript ❌ theme={null}
FunctionSpec.publicQuery({
  name: "myQuery",
  args: () => Schema.Struct({}),
  returns: () => Schema.Void,
});
```


# Services
Source: https://confect.dev/concepts/services

Understand which Effect services Confect provides.

Confect exposes Effect services that wrap Convex platform capabilities. These services are generated in `confect/_generated/services.ts` and are available when implementing your Confect functions.

```ts theme={null}
import {
  ActionRunner,
  Auth,
  DatabaseReader,
  DatabaseWriter,
  MutationRunner,
  QueryRunner,
  Scheduler,
  StorageReader,
  StorageWriter,
  StorageActionWriter,
  VectorSearch,
} from "./_generated/services";
```

## Database

### `DatabaseReader`

<ContextBadges />

Read documents from the database.

### `DatabaseWriter`

<ContextBadges />

Insert, edit, and delete documents from the database.

## Function invocation

### `QueryRunner`

<ContextBadges />

Run Confect queries.

### `MutationRunner`

<ContextBadges />

Run Confect mutations.

### `ActionRunner`

<ContextBadges />

Run Confect actions.

## Storage

### `StorageReader`

<ContextBadges />

Retrieve URLs for blobs in storage.

### `StorageWriter`

<ContextBadges />

Generate upload URLs and delete blobs.

### `StorageActionWriter`

<ContextBadges />

Get and store blobs.

## Authentication

### `Auth`

<ContextBadges />

Access the current user's identity.

## Scheduling

### `Scheduler`

<ContextBadges />

Schedule Confect functions to run after a delay or at a specific time.

## Search

### `VectorSearch`

<ContextBadges />

Query vector indexes for semantic similarity search.

## Convex context

### `QueryCtx`

<ContextBadges />

Raw Convex query context.

### `MutationCtx`

<ContextBadges />

Raw Convex mutation context.

### `ActionCtx`

<ContextBadges />

Raw Convex action context.


# The Spec/Impl Model
Source: https://confect.dev/concepts/spec-impl-model

Understand how Confect separates function interfaces from their implementations.

Your Confect API is broken up into two parts: a **spec** and its implementation (or **impl**).

## Spec

A spec defines the interface of your Confect API. It is made up of group specs and function specs. Each function spec defines the function's name, arguments schema, and returns schema—but not the function's logic. The `args` and `returns` schemas (and an optional `error` schema) are passed as `() => Schema` callbacks, evaluated lazily on first invocation.

Specs are built using `@confect/core`, which means they can be shared between the server and client. This separation is what enables end-to-end schema decoding and encoding: the client knows the exact shape of every function's arguments and return value without importing any server code.

Each group spec is the default export of a `*.spec.ts` file. The group's name comes from the file's path—its stem for top-level groups, or the dot-joined directory path for nested groups:

```ts confect/notes_and_random/notes.spec.ts theme={null}
import { GroupSpec, FunctionSpec } from "@confect/core";
import * as Schema from "effect/Schema";

import notes from "../_generated/tables/notes";

export default GroupSpec.make().addFunction(
  FunctionSpec.publicQuery({
    name: "list",
    args: () => Schema.Struct({}),
    returns: () => Schema.Array(notes.Doc),
  }),
);
```

## Impl

An impl provides the logic for each function declared in your spec. Each impl is the default export of a `*.impl.ts` file colocated with its sibling spec. It default-imports that sibling spec, passes it to `FunctionImpl.make` and `GroupImpl.make`, and finalizes the resulting layer with `GroupImpl.finalize`:

```ts confect/notes_and_random/notes.impl.ts theme={null}
import { FunctionImpl, GroupImpl } from "@confect/server";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";

import databaseSchema from "../_generated/schema";
import { DatabaseReader } from "../_generated/services";
import notes from "./notes.spec";

const list = FunctionImpl.make(databaseSchema, notes, "list", () =>
  Effect.gen(function* () {
    const reader = yield* DatabaseReader;

    return yield* reader
      .table("notes")
      .index("by_creation_time", "desc")
      .collect();
  }).pipe(Effect.orDie),
);

export default GroupImpl.make(databaseSchema, notes).pipe(
  Layer.provide(list),
  GroupImpl.finalize,
);
```

`GroupImpl.finalize` rejects, at compile time, any pipeline that has not provided a `FunctionImpl` for every function declared by the spec. This guarantees that the group is fully implemented before it is handed to the generated `convex/` module.

Run `confect codegen` after adding or changing specs and impls.


# Introduction
Source: https://confect.dev/getting-started/introduction

Confect deeply integrates Effect with Convex for end-to-end type-safe full-stack apps.

Confect is a framework that deeply integrates [Effect](https://effect.website) with [Convex](https://convex.dev). It's more than just Effect bindings! Confect allows you to:

* Define your Convex database schema using Effect schemas.
* Write Convex function args and returns validators using Effect's schema library.
* Use Confect functions to automatically decode and encode your data according to your Effect schema definitions for end-to-end rich types, from client to function to database (and back).
* Use Effect's HTTP API modules to define your HTTP API(s). Includes interactive OpenAPI documentation powered by [Scalar](https://github.com/scalar/scalar).
* Access Convex platform capabilities via Effect services.

## Prerequisites

It's recommended that you have some familiarity with both Effect and Convex, including the vanilla `convex` APIs, before getting started with Confect.

<CardGroup>
  <Card title="Effect documentation" icon="layers" href="https://effect.website/docs">
    Learn about Effect's core concepts.
  </Card>

  <Card title="Convex documentation" icon="database" href="https://docs.convex.dev">
    Learn about Convex's platform and APIs.
  </Card>
</CardGroup>

## Supported platforms

Confect requires Node.js 22 or later, and runs on Linux, macOS, and Windows.

<Note>
  On Windows, the `confect` CLI (`confect codegen`, `confect dev`) runs
  natively. Convex's own [local
  deployments](https://docs.convex.dev/cli/local-deployments) — anonymous
  development and self-hosting — depend on a `convex-local-backend` binary that
  Convex does not publish for Windows, so those workflows need WSL or Docker.
  Developing against a Convex cloud deployment is unaffected.
</Note>

## Next steps

<Card title="Quickstart" icon="rocket" href="/getting-started/quickstart">
  Install Confect and build your first app.
</Card>


# Quickstart
Source: https://confect.dev/getting-started/quickstart

Install Confect and build a type-safe Convex app with Effect schemas in minutes.

## Installation

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm add convex @confect/core @confect/server @confect/cli @confect/react
  ```

  ```bash npm theme={null}
  npm install convex @confect/core @confect/server @confect/cli @confect/react
  ```

  ```bash yarn theme={null}
  yarn add convex @confect/core @confect/server @confect/cli @confect/react
  ```

  ```bash bun theme={null}
  bun add convex @confect/core @confect/server @confect/cli @confect/react
  ```
</CodeGroup>

## Usage

<Steps>
  <Step title="Set up your Convex dev deployment">
    Run `convex dev` to set up your Convex dev deployment.
  </Step>

  <Step title="Define your database schema">
    <Note>
      Not every Effect `Schema` is valid for use in Confect. See
      [Schema Restrictions](/concepts/schema-restrictions) for more
      information about what's permitted and what's not.
    </Note>

    Define a table — one file per table under `confect/tables/`, where the **filename is the table name** (so filenames must be valid JS identifiers and may not start with `_`). Each file **must default-export** a `Table`; codegen reads `module.default` and applies the filename as the table name. From other modules (e.g. specs), default-import the codegen-emitted wrapper at `confect/_generated/tables/<name>` to reach the table's derived `Schema`s (`notes.Doc`, `notes.Fields`).

    ```ts confect/tables/notes.ts theme={null}
    import { Table } from "@confect/server";
    import * as Schema from "effect/Schema";

    export default Table.make(() =>
      Schema.Struct({
        text: Schema.String,
      }),
    );
    ```

    Codegen will assemble every `confect/tables/*.ts` into a `DatabaseSchema` (in `confect/_generated/schema.ts`) and a Convex deploy `SchemaDefinition` (in `confect/_generated/convexSchema.ts`) for you — you never write a `confect/schema.ts`. It also emits a `confect/_generated/id.ts` module exporting a type-safe `Id` constructor (`Id("notes")`) for cross-table references.
  </Step>

  <Step title="Define your Confect API spec">
    Create a `GroupSpec` and add some functions to it.

    ```ts confect/notes.spec.ts theme={null}
    import { FunctionSpec, GroupSpec } from "@confect/core";
    import * as Schema from "effect/Schema";

    import { Id } from "./_generated/id";
    import notes from "./_generated/tables/notes";

    export default GroupSpec.make()
      .addFunction(
        FunctionSpec.publicQuery({
          name: "list",
          args: () => Schema.Struct({}),
          returns: () => Schema.Array(notes.Doc),
        }),
      )
      .addFunction(
        FunctionSpec.publicMutation({
          name: "create",
          args: () => Schema.Struct({ text: Schema.String }),
          returns: () => Id("notes"),
        }),
      );
    ```
  </Step>

  <Step title="Run the codegen command">
    Generate your app's `confect/_generated/` files.

    ```bash theme={null}
    confect codegen
    ```
  </Step>

  <Step title="Implement your Confect functions">
    Create a `GroupImpl` and implement its functions.

    ```ts confect/notes.impl.ts theme={null}
    import { FunctionImpl, GroupImpl } from "@confect/server";
    import * as Effect from "effect/Effect";
    import * as Layer from "effect/Layer";

    import databaseSchema from "./_generated/schema";
    import { DatabaseReader, DatabaseWriter } from "./_generated/services";
    import notes from "./notes.spec";

    const list = FunctionImpl.make(databaseSchema, notes, "list", () =>
      Effect.gen(function* () {
        const reader = yield* DatabaseReader;

        return yield* reader
          .table("notes")
          .index("by_creation_time", "desc")
          .collect();
      }).pipe(Effect.orDie),
    );

    const create = FunctionImpl.make(databaseSchema, notes, "create", ({ text }) =>
      Effect.gen(function* () {
        const writer = yield* DatabaseWriter;

        return yield* writer.table("notes").insert({ text });
      }).pipe(Effect.orDie),
    );

    export default GroupImpl.make(databaseSchema, notes).pipe(
      Layer.provide(list),
      Layer.provide(create),
      GroupImpl.finalize,
    );
    ```

    `GroupImpl.finalize` only typechecks once every function declared by the spec has a corresponding `FunctionImpl`, so it acts as a per-group completeness check.

    Run `confect codegen` again to pick up the new impl.
  </Step>

  <Step title="Start your Confect app">
    Run the `confect dev` command to generate your app's Convex functions.

    ```bash theme={null}
    confect dev
    ```

    In another terminal, run the `convex dev` command to start your Convex dev deployment.

    ```bash theme={null}
    convex dev
    ```
  </Step>

  <Step title="Call your Confect functions from your React app">
    Set up the Convex React client and provider.

    ```tsx src/main.tsx theme={null}
    import { ConvexProvider, ConvexReactClient } from "convex/react";
    import React from "react";
    import ReactDOM from "react-dom/client";

    import App from "./App";

    const convexClient = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

    ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
      <React.StrictMode>
        <ConvexProvider client={convexClient}>
          <App />
        </ConvexProvider>
      </React.StrictMode>,
    );
    ```

    Use Confect's React hooks alongside your Confect public refs to call your Confect functions.

    ```tsx src/App.tsx theme={null}
    import { QueryResult, useMutation, useQuery } from "@confect/react";
    import * as Array from "effect/Array";
    import { useState } from "react";

    import refs from "../confect/_generated/refs";

    const App = () => {
      const notes = useQuery(refs.public.notes.list, {});

      const createNote = useMutation(refs.public.notes.create);

      const [newNote, setNewNote] = useState("");

      return (
        <div>
          <ul>
            {QueryResult.match(notes, {
              onLoading: () => <p>Loading…</p>,
              onSuccess: (notes) =>
                Array.map(notes, (note) => (
                  <li key={note._id}>{note.text}</li>
                )),
            })}
          </ul>

          <br />

          <textarea
            rows={4}
            cols={50}
            value={newNote}
            onChange={(e) => setNewNote(e.target.value)}
          />
          <br />
          <button
            onClick={() =>
              void createNote({ text: newNote }).then(() => setNewNote(""))
            }
          >
            Create note
          </button>
        </div>
      );
    };

    export default App;
    ```
  </Step>
</Steps>

## Example project

See a full, working example project [here](https://github.com/rjdellecese/confect/tree/main/apps/example).


# Testing
Source: https://confect.dev/guides/testing

Test your Confect functions without a live Convex backend.

`@confect/test` wraps [`convex-test`](https://docs.convex.dev/testing) with Effect-native APIs. It provides a `TestConfect` service that lets you call your Confect functions using refs, run arbitrary mutation-context code for test setup, and test with user identities.

## Installation

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm add -D @confect/test convex-test @effect/vitest
  ```

  ```bash npm theme={null}
  npm install -D @confect/test convex-test @effect/vitest
  ```

  ```bash yarn theme={null}
  yarn add -D @confect/test convex-test @effect/vitest
  ```

  ```bash bun theme={null}
  bun add -D @confect/test convex-test @effect/vitest
  ```
</CodeGroup>

## Setup

Create a `TestConfect.ts` file that configures the test layer with your generated runtime schema, generated Convex schema definition, and Convex modules. Both schemas are emitted by `confect codegen` from `confect/tables/*.ts`; you never edit them by hand.

```ts test/TestConfect.ts theme={null}
/// <reference types="vite/client" />

import { TestConfect as TestConfect_ } from "@confect/test";

import confectSchema from "./confect/_generated/schema";
import convexSchema from "./confect/_generated/convexSchema";

export const TestConfect = TestConfect_.TestConfect<typeof confectSchema>();

export const layer = TestConfect_.layer(
  confectSchema,
  convexSchema,
  import.meta.glob("./convex/**/!(*.*.*)*.*s"),
);
```

Every time the `TestConfect` layer is constructed, a new test database is created. If you want a clean database for each test, provide the layer on a per-test basis (as shown below). If you want to share state across tests in a describe block, you can provide the layer at a higher scope instead.

## Writing tests

Use `@effect/vitest`'s `it.effect` to write effectful tests. Yield `TestConfect` from the service, then call your functions using refs.

```ts test/notes.test.ts theme={null}
import { describe, it } from "@effect/vitest";
import { assertEquals } from "@effect/vitest/utils";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";
import * as TestConfect from "./TestConfect";

describe("notes", () => {
  it.effect("can insert and list notes", () =>
    Effect.gen(function* () {
      const c = yield* TestConfect.TestConfect;

      yield* c.mutation(refs.public.notes.insert, {
        text: "Hello",
      });

      const notes = yield* c.query(refs.public.notes.list, {});

      assertEquals(notes.length, 1);
      assertEquals(notes[0]?.text, "Hello");
    }).pipe(Effect.provide(TestConfect.layer())),
  );
});
```

## Calling functions

`TestConfect` provides `query`, `mutation`, and `action` methods that accept a ref and args, returning an `Effect` with the decoded result.

```ts theme={null}
Effect.gen(function* () {
  const c = yield* TestConfect.TestConfect;

  const notes = yield* c.query(refs.public.notes.list, {});

  const noteId = yield* c.mutation(refs.public.notes.insert, {
    text: "Hello",
  });

  const result = yield* c.action(refs.public.random.getNumber, {});
});
```

## Typed errors

When a ref's spec declares an `error` schema, the decoded error is added to the error channel of `query`, `mutation`, and `action` alongside `ParseError`. See [Error Handling](/server/error-handling) for how to declare error schemas.

```ts theme={null}
import { describe, it } from "@effect/vitest";
import { assertLeft } from "@effect/vitest/utils";
import type { GenericId } from "convex/values";
import * as Effect from "effect/Effect";

import { NoteNotFound } from "./confect/notes.spec";
import refs from "./confect/_generated/refs";
import * as TestConfect from "./TestConfect";

describe("notes", () => {
  it.effect("returns NoteNotFound for a missing id", () =>
    Effect.gen(function* () {
      const c = yield* TestConfect.TestConfect;

      const result = yield* c
        .query(refs.public.notes.getOrFail, {
          noteId: "missing" as GenericId<"notes">,
        })
        .pipe(Effect.either);

      assertLeft(result, new NoteNotFound({ noteId: "missing" }));
    }).pipe(Effect.provide(TestConfect.layer())),
  );
});
```

## Running setup code

Use `run` to execute arbitrary code with mutation-context services (like `DatabaseWriter`) for test setup. When the handler returns a value, pass a `Schema` as the second argument for decoding.

```ts theme={null}
import { Id } from "./confect/_generated/id";
import { DatabaseWriter } from "./confect/_generated/services";

Effect.gen(function* () {
  const c = yield* TestConfect.TestConfect;

  const noteId = yield* c.run(
    Effect.gen(function* () {
      const writer = yield* DatabaseWriter;

      return yield* writer.table("notes").insert({ text: "seed data" });
    }),
    Id("notes"),
  );
});
```

When the handler returns `void`, the second argument can be omitted.

```ts theme={null}
Effect.gen(function* () {
  const c = yield* TestConfect.TestConfect;

  yield* c.run(
    Effect.gen(function* () {
      const writer = yield* DatabaseWriter;

      yield* Effect.forEach(items, (item) =>
        writer.table("notes").insert(item),
      );
    }),
  );
});
```

## Testing with user identity

Use `withIdentity` to scope function calls to a specific user identity.

```ts theme={null}
Effect.gen(function* () {
  const c = yield* TestConfect.TestConfect;

  const asUser = c.withIdentity({
    subject: "user-123",
    tokenIdentifier: "https://example.com|user-123",
    email: "user@example.com",
  });

  const identity = yield* asUser.query(refs.public.auth.getIdentity, {});
});
```

## Testing HTTP endpoints

Use `fetch` to test your [HTTP API](/server/http-api) endpoints.

```ts theme={null}
Effect.gen(function* () {
  const c = yield* TestConfect.TestConfect;

  const response = yield* c.fetch("/api/get-first");
  const body = yield* Effect.promise(() => response.json());
});
```

## Testing scheduled functions

`TestConfect` provides helpers for advancing scheduled functions in tests.

```ts theme={null}
Effect.gen(function* () {
  const c = yield* TestConfect.TestConfect;

  yield* c.finishInProgressScheduledFunctions();

  yield* c.finishAllScheduledFunctions(() => {
    vi.advanceTimersByTime(5000);
  });
});
```


# Authentication
Source: https://confect.dev/server/authentication

Access the current user's identity in your Confect functions.

The `Auth` service provides access to the current user's identity. Unlike vanilla Convex (which returns `UserIdentity | null`), the Confect `Auth` service returns an `Effect` that fails with a typed error when no user is authenticated.

## Getting the user identity

```ts theme={null}
import * as Effect from "effect/Effect";
import { Auth } from "./confect/_generated/services";

Effect.gen(function* () {
  const auth = yield* Auth;

  const identity = yield* auth.getUserIdentity;
});
```

`getUserIdentity` succeeds with the user's [`UserIdentity`](https://docs.convex.dev/api/interfaces/server.UserIdentity) or fails with `NoUserIdentityFoundError`.

## Handling unauthenticated requests

Use `Effect.catchTag` to handle the case where no user is logged in.

```ts theme={null}
Effect.gen(function* () {
  const auth = yield* Auth;

  const identity = yield* auth.getUserIdentity.pipe(
    Effect.catchTag("NoUserIdentityFoundError", () => Effect.succeed(null)),
  );
});
```

## Configuration

Auth provider configuration goes in `confect/auth.ts`, which is passed through to Convex as-is. See the [Convex auth documentation](https://docs.convex.dev/auth) for setup details.


# Components
Source: https://confect.dev/server/components

Use Convex components in your Confect app.

Convex [components](https://docs.convex.dev/components) are configured in `convex/convex.config.ts`, which is one of the files in the `convex/` directory that Confect does not manage. Configure components using the vanilla Convex API.

```ts convex/convex.config.ts theme={null}
import { defineApp } from "convex/server";
import workpool from "@convex-dev/workpool/convex.config";

const app = defineApp();
app.use(workpool, { name: "workpool" });

export default app;
```

## Referencing components

Component clients (like `Workpool`) take a component reference. Import the typed `components` registry that Confect generates at `confect/_generated/components.ts`:

```ts confect/workpool.ts theme={null}
import { Workpool } from "@convex-dev/workpool";
import { components } from "./_generated/components";

const pool = new Workpool(components.workpool, {
  maxParallelism: 3,
});
```

<Note>
  Use this registry rather than the `components` export of
  `convex/_generated/api`, which doesn't exist yet when `confect codegen`
  evaluates your code and so breaks codegen on a clean checkout. Confect's
  registry is equivalent, but is derived directly from
  `convex/convex.config.ts`, so it is safe to import anywhere in your `confect/`
  directory.
</Note>

<Note>
  Each component is typed with the `ComponentApi` type that component packages
  export from `_generated/component.js`. Recently published versions of the
  official `@convex-dev/*` components all follow this convention; a component
  that predates it will still work at runtime but won't get precise types.
</Note>

## Defining functions for components

Some components (such as [Workflow](https://www.convex.dev/components/workflow), [Migrations](https://www.convex.dev/components/migrations), and [Workpool](https://www.convex.dev/components/workpool)) expect you to define Convex functions in your project that they can reference. You can integrate these into your Confect spec and impl using [plain Convex functions](/server/plain-convex-functions).

See the [Convex components documentation](https://docs.convex.dev/components) for details on installing and using components.


# Cron Jobs
Source: https://confect.dev/server/cron-jobs

Schedule recurring tasks with cron jobs.

Define cron jobs in `confect/crons.ts` using `CronJob` and `CronJobs` from `@confect/server`. Each job has a unique identifier, a schedule, and a ref to an internal mutation or action.

Schedules are either an Effect [`Cron`](https://effect.website/docs/scheduling/cron) (cron expression) or a [`Duration`](https://effect.website/docs/data-types/duration/) (fixed interval). The Confect CLI re-exports the result into `convex/crons.ts`.

<Note>
  `Cron` schedules must not use a custom `seconds` field—Convex cron expressions
  only support minute-level granularity. For sub-minute scheduling, use a
  `Duration` interval instead.
</Note>

<Note>
  Non-UTC timezones are not supported by Convex. A schedule with no timezone is
  treated as UTC.
</Note>

<Note>
  `Duration` intervals must be a positive, whole number of seconds, minutes, or
  hours. Sub-second durations (e.g. `Duration.millis(500)`) are not supported.
</Note>

```ts confect/crons.ts theme={null}
import * as Cron from "effect/Cron";
import * as Duration from "effect/Duration";
import { CronJob, CronJobs } from "@confect/server";
import refs from "./_generated/refs";

export default CronJobs.make()
  .add(
    CronJob.make(
      "clear stale sessions",
      Cron.make({
        minutes: [0],
        hours: [],
        days: [],
        months: [],
        weekdays: [],
      }),
      refs.internal.sessions.clearStale,
    ),
  )
  .add(
    CronJob.make(
      "send weekly digest",
      Cron.unsafeParse("0 9 * * 1"),
      refs.internal.emails.sendDigest,
    ),
  )
  .add(
    CronJob.make(
      "send hourly reminder",
      Duration.hours(1),
      refs.internal.notifications.sendReminder,
    ),
  )
  .add(
    CronJob.make(
      "payment reminder",
      Cron.unsafeParse("0 16 1 * *"),
      refs.internal.payments.sendPaymentEmail,
      { email: "billing@example.com" },
    ),
  );
```

`CronJob.make` accepts a unique identifier, a schedule (`Cron` or `Duration`), a ref to an internal mutation or action, and an optional args object matching the ref's args schema. `CronJobs.make()` creates an empty collection; each `.add()` call returns a new `CronJobs` object, so calls can be chained.

For the full scheduling APIs, see the [Effect `Cron` documentation](https://effect.website/docs/scheduling/cron), the [Effect `Duration` documentation](https://effect.website/docs/data-types/duration/), and the [Convex cron jobs documentation](https://docs.convex.dev/scheduling/cron-jobs).


# Determinism
Source: https://confect.dev/server/database/determinism

How Confect keeps queries cacheable by default.

Convex caches the result of every query, keyed on its arguments and on everything the handler reads—including real wall-clock time. A query that observes time (directly via `Date.now()`, or indirectly through APIs that read it) is [evicted from the cache much more aggressively](https://docs.convex.dev/production/best-practices/) and is re-executed on subsequent calls, even when its inputs are unchanged.

Effect programs touch the clock far more often than ordinary JavaScript: forking a fiber, emitting a log, or opening a span all read the current time internally. Without intervention, every Confect-wrapped query would defeat the cache.

To keep queries cacheable by default, Confect stubs the clock for the span of a query handler:

* `Date.now()` returns `0`.
* The `unsafe*` methods on Effect's `Clock` service (used internally by logging, span events, the default scheduler, and `Fiber` construction) return constants (`0` and `0n`).
* The user-facing `Clock.currentTimeMillis` and `Clock.currentTimeNanos` effects are the **only** way to read real time, and they are an **explicit opt-in to cache invalidation**.

Mutations and actions are not affected by any of this. Real time is always available there, with no caching trade-offs.

## What stays cached

The following do **not** observe real time from within a query handler and so do not interfere with caching:

* `Effect.log`/`Effect.logInfo`/etc.
* `Effect.withSpan` and other tracing primitives
* Forking fibers, the default scheduler, and other Effect internals
* A bare `Date.now()` call inside the handler (returns `0`)

## Opting in to real time

Use Effect's `Clock` service when you need the real timestamp:

```ts theme={null}
import * as Clock from "effect/Clock";
import * as Effect from "effect/Effect";
import { DatabaseReader } from "./confect/_generated/services";

Effect.gen(function* () {
  const reader = yield* DatabaseReader;
  const rows = yield* reader.table("notes").index("by_creation_time").collect();
  const fetchedAt = yield* Clock.currentTimeMillis;

  return { fetchedAt, rows };
});
```

Any query that reads `Clock.currentTimeMillis` or `Clock.currentTimeNanos` will be evicted from Convex's cache and re-executed on every subscription update, matching Convex's behavior for any query that observes real time.

## Preferring cacheable alternatives

If you don't actually need sub-second accuracy inside the query, follow Convex's [recommended patterns](https://docs.convex.dev/production/best-practices/) to preserve caching:

* Pass a coarse timestamp (e.g. rounded to the minute or hour) as a query argument from the client.
* Maintain a boolean or status field on the document, updated by a scheduled function or mutation.
* Compute time-dependent values in a mutation or action and persist the result.

## Caveats

Stubbing `Date.now()` inside the handler means library code that calls it during a query—logging timestamps, cache keys, ID generation—will see `0` rather than the real time. This is almost always what you want for a deterministic, cacheable query, but it can surprise code that was written assuming a real clock. If such code must run inside a query, route it through `Clock.currentTimeMillis` instead and accept the cache trade-off.


# Reading
Source: https://confect.dev/server/database/reading

Retrieve documents from the database.

The `DatabaseReader` service is used to read documents from the database.

```ts theme={null}
import * as Effect from "effect/Effect";
import { DatabaseReader } from "./confect/_generated/services";

Effect.gen(function* () {
  const reader = yield* DatabaseReader;

  return yield* reader.table("notes").index("by_creation_time").collect();
});
```

## Retrieve a single document

### By ID

```ts theme={null}
reader.table("notes").get(noteId);
```

### By index

#### Single field

```ts theme={null}
reader.table("notes").get("by_author", "John Doe");
```

#### Multiple fields

```ts theme={null}
reader.table("users").get("by_name_and_age", "John Doe", 21);
```

## Retrieve multiple documents

### Indexes

Every query must specify either a standard index or a search index.

#### Standard indexes

Standard indexes are what you'll use most of the time. There are two default standard indexes, which exist for every table: `by_creation_time` and `by_id`. The rest are defined in your schema.

Standard indexes determine both the sort order of the results and which fields may be filtered on. Fields must be filtered in the order they are defined in the index.

Order is ascending by default, but can be specified in the final argument to the `index` method.

```ts Users sorted by name and age, ascending theme={null}
reader.table("users").index("by_name_and_age");
```

```ts Users sorted by name and age, descending theme={null}
reader.table("users").index("by_name_and_age", "desc");
```

```ts Users sorted by name and age, where name equals "John Doe", ascending theme={null}
reader.table("users").index("by_name_and_age", (q) => q.eq("name", "John Doe"));
```

```ts Users sorted by name and age, where name equals "John Doe", and age equals 21, descending theme={null}
reader
  .table("users")
  .index(
    "by_name_and_age",
    (q) => q.eq("name", "John Doe").eq("age", 21),
    "desc",
  );
```

#### Search indexes

Search indexes are used for full-text search, and are defined in your schema. The results are always sorted by relevance, descending.

```ts theme={null}
reader
  .table("notes")
  .search("text", (q) => q.search("text", "hello").eq("tag", "colors"));
```

### Methods

The following methods are available for queries using both database indexes and search indexes.

#### Collect

Collect all documents matching the query.

```ts theme={null}
reader.table("notes").index("by_creation_time").collect();
```

#### First

Retrieve the first document matching the query.

```ts theme={null}
reader.table("notes").index("by_creation_time").first();
```

#### Take

Take the first `n` documents matching the query.

```ts theme={null}
reader.table("notes").index("by_creation_time").take(10);
```

#### Paginate

Retrieve a page of documents matching the query. Expects a [`PaginationOptions`](https://docs.convex.dev/api/interfaces/server.PaginationOptions) object, including Convex's optional pagination protocol fields. A [paginated query](/server/functions#paginated-queries) handler typically forwards its decoded `paginationOpts` argument unchanged.

```ts theme={null}
reader.table("notes").index("by_creation_time").paginate(paginationOpts);
```

#### Stream

Get a `Stream` of documents matching the query.

```ts theme={null}
reader.table("notes").index("by_creation_time").stream();
```

### Accessing the current time

Reading real time inside a query handler affects how aggressively Convex caches the result. See [Determinism](/server/database/determinism) for how Confect keeps queries cacheable by default and how to opt in to real time via Effect's `Clock` service.


# Schema
Source: https://confect.dev/server/database/schema

Define your database schema using Effect schemas.

Your database schema lives in `confect/tables/`: one file per table, each default-exporting a `Table.make(...)` value, where the **filename is the table name** (`confect/tables/notes.ts` defines a table called `notes`). The Confect CLI's codegen combines these files into a single schema behind the scenes — and generates the per-table helpers your code imports — so you never assemble or edit a schema definition by hand. (For the full layout of what codegen emits, see [Project Structure](/concepts/project-structure).)

Each table is defined with `Table.make`, which takes a callback returning the table's fields. The callback runs lazily — only the first time the table's `Fields`, `Doc`, or `tableDefinition` is accessed — so a function that never touches a table pays no schema-construction cost for it at cold start. Indexes are defined on tables the same way as in the base Convex APIs. Cross-table `Id` references are constructed with the codegen-emitted `Id` helper from `confect/_generated/id.ts`, whose argument is type-constrained to the set of declared table names.

```ts confect/tables/notes.ts theme={null}
import { Table } from "@confect/server";
import * as Schema from "effect/Schema";
import { Id } from "../_generated/id";

export default Table.make(() =>
  Schema.Struct({
    userId: Schema.optional(Id("users")),
    text: Schema.String.pipe(Schema.maxLength(100)),
    tag: Schema.optional(Schema.String),
    author: Schema.optional(
      Schema.Struct({
        role: Schema.Literal("admin", "user"),
        name: Schema.String,
      }),
    ),
    embedding: Schema.optional(Schema.Array(Schema.Number)),
  }),
)
  .index("by_text", ["text"])
  .index("by_role", ["author.role"])
  .searchIndex("text", {
    searchField: "text",
    filterFields: ["tag"],
  })
  .vectorIndex("embedding", {
    vectorField: "embedding",
    filterFields: ["author.name", "tag"],
    dimensions: 1536,
  });
```

```ts confect/tables/users.ts theme={null}
import { Table } from "@confect/server";
import * as Schema from "effect/Schema";

export default Table.make(() =>
  Schema.Struct({
    username: Schema.String,
  }),
);
```

Each `confect/tables/*.ts` file **must default-export a `Table`** — codegen reads `module.default` and applies the filename as the table name. Consumers (specs, impls, HTTP handlers, etc.) reach a table's derived `Schema`s through the generated wrapper at `confect/_generated/tables/<name>`, e.g. `import notes from "../_generated/tables/notes"` and then `notes.Doc`.

## Deriving table `Schema`s

### Fields

A `Table`'s `Fields` property contains an Effect `Schema` for the user-defined fields of a table.

### Doc

A `Table`'s `Doc` property contains an Effect `Schema` for the table's document, meaning the table's user-defined `Fields` plus its system fields (`_id` and `_creationTime`).

## Document types

`Fields` and `Doc` are runtime `Schema`s — *values*. Reach for them whenever you need a value: a spec's `returns`, an HTTP endpoint's `addSuccess`, or decoding. Their TypeScript types are available as `typeof notes.Doc.Type` and `typeof notes.Fields.Type`.

When you only need to annotate something with a table's document *type*, codegen also emits named document types in `confect/_generated/docs.ts` — one per table (`NotesDoc`, `UsersDoc`, …) plus a `Docs` registry:

```ts confect/_generated/docs.ts theme={null}
import type { Document } from "@confect/server";
import type schemaDefinition from "./schema";

export type NotesDoc = Document.Document<typeof schemaDefinition, "notes">;
export type UsersDoc = Document.Document<typeof schemaDefinition, "users">;

export interface Docs {
  notes: NotesDoc;
  users: UsersDoc;
}
```

`NotesDoc` is the decoded document — the table's fields plus its system fields — exactly the same type as `typeof notes.Doc.Type`, but as a *named* type. Because it's named, it keeps editor hovers and emitted `.d.ts` files readable (`NotesDoc` rather than the fully-expanded row), and it's what lets the `DatabaseReader`/`DatabaseWriter` services hand documents back under their table's name.

```ts theme={null}
import type { NotesDoc } from "./confect/_generated/docs";

const renderNote = (note: NotesDoc) => note.text;
```

You can also write the type inline with the same helper the generated types alias, `Document.Document<typeof schemaDefinition, "notes">`, and drop the system fields with `Document.WithoutSystemFields<NotesDoc>`.

As a rule of thumb: reach for `notes.Doc` when you need a **value** (a `Schema`), and `NotesDoc` when you need a **type**.

<Note>
  Each type's name is the table name folded to PascalCase, so `user_profiles`
  and `userProfiles` would both produce `UserProfilesDoc`. Codegen reports an
  error if two tables would collide on the same name.
</Note>


# System Tables
Source: https://confect.dev/server/database/system-tables

Query system tables using the same API as regular tables.

Unlike the vanilla Convex API, system tables (`_storage`, `_scheduled_functions`) are queryable using the exact same API as regular tables. These tables contain metadata for built-in Convex features, and are read-only.

```ts theme={null}
reader.table("_storage").get(storageId);
```

```ts theme={null}
reader.table("_scheduled_functions").index("by_creation_time", "desc").take(10);
```


# Writing
Source: https://confect.dev/server/database/writing

Insert, modify, and delete documents in the database.

The `DatabaseWriter` service is used to insert, modify, and delete documents in the database.

```ts theme={null}
import * as Effect from "effect/Effect";
import { DatabaseWriter } from "./confect/_generated/services";

Effect.gen(function* () {
  const writer = yield* DatabaseWriter;

  return yield* writer.table("notes").insert({
    title: "My first note",
    text: "This is my first note",
  });
});
```

## Methods

### Insert

Insert a new document.

```ts theme={null}
writer.table("notes").insert({
  title: "My first note",
  text: "This is my first note",
});
```

### Patch

Shallow merge the provided object with the existing document. New fields are added. Existing fields are overwritten. Fields set to `undefined` are removed.

```ts theme={null}
writer.table("notes").patch(noteId, {
  title: "Patched title",
  author: "John Doe",
  text: undefined,
});
```

### Replace

Replace the entire document.

```ts theme={null}
writer.table("notes").replace(noteId, {
  title: "Replaced title",
  text: "I'm replacing the whole document",
});
```

### Delete

Delete the document with the given ID.

```ts theme={null}
writer.table("notes").delete(noteId);
```


# Environment Variables
Source: https://confect.dev/server/environment-variables

Read environment variables using Effect's Config module.

Confect provides a `ConfigProvider` that is compatible with the Convex runtime, where `process.env` is not enumerable. This provider is automatically set for all Confect functions (queries, mutations, actions, and HTTP API handlers), so Effect's [`Config`](https://effect.website/docs/configuration/) module works out of the box.

## Reading environment variables

Use `Config` from Effect to read [Convex environment variables](https://docs.convex.dev/production/environment-variables) in your function handlers.

```ts confect/settings.impl.ts theme={null}
import { FunctionImpl } from "@confect/server";
import * as Config from "effect/Config";
import * as Effect from "effect/Effect";

import databaseSchema from "./_generated/schema";
import settings from "./settings.spec";

const getApiKey = FunctionImpl.make(databaseSchema, settings, "getApiKey", () =>
  Config.string("API_KEY").pipe(Effect.orDie),
);
```

All of Effect's `Config` combinators work as expected—`Config.string`, `Config.number`, `Config.boolean`, `Config.withDefault`, `Config.option`, etc.

```ts theme={null}
Config.integer("MAX_RESULTS").pipe(Config.withDefault(100));
```

## Limitations

Config operations that require enumerating `process.env` are unsupported in the Convex runtime. This includes `Config.hashMap` and other combinators that need to discover keys dynamically. Attempting to use them will result in an `Unsupported` config error.

## Custom config provider

The `ConvexConfigProvider` module is exported from `@confect/server` if you need to create a provider with custom options. It supports the same options as Effect's default [`ConfigProvider.fromEnv`](https://effect.website/docs/configuration/#loading-configuration-from-environment-variables).

```ts theme={null}
import { ConvexConfigProvider } from "@confect/server";

const provider = ConvexConfigProvider.make({
  pathDelim: "__",
  seqDelim: ";",
});
```

To use a custom provider in a function handler, pass it to `Effect.withConfigProvider`.

```ts theme={null}
const getApiKey = FunctionImpl.make(databaseSchema, settings, "getApiKey", () =>
  Config.string("API_KEY").pipe(
    Effect.withConfigProvider(provider),
    Effect.orDie,
  ),
);
```


# Error Handling
Source: https://confect.dev/server/error-handling

Declare typed errors on Confect functions and consume them at every call site.

A Confect function can declare a typed error in its spec. When the handler fails with a value matching that schema, the error travels across the function boundary and surfaces—already decoded—at every call site (React hooks, JS clients, and tests).

Typed errors are transported as Convex's native [`ConvexError`](https://docs.convex.dev/functions/error-handling/application-errors#throwing-application-errors), with the encoded error stored in `ConvexError.data`. The `returns` channel is left untouched, and non-Confect callers of the same Convex API see ordinary `ConvexError`s. For mutations, throwing a `ConvexError` triggers Convex's transaction rollback as usual.

Error schemas are optional. When omitted, the error type defaults to `never` and every call site keeps its prior shape.

## Declaring an error schema

Add an `error` field to any `FunctionSpec` constructor. The schema is an ordinary Effect `Schema`, so a `Schema.TaggedError` class works well for a single failure mode.

```ts confect/notes.spec.ts theme={null}
import { FunctionSpec, GroupSpec } from "@confect/core";
import * as Schema from "effect/Schema";

import { Id } from "./_generated/id";
import notes from "./_generated/tables/notes";

export class NoteNotFound extends Schema.TaggedError<NoteNotFound>()(
  "NoteNotFound",
  { noteId: Id("notes") },
) {}

export default GroupSpec.make().addFunction(
  FunctionSpec.publicQuery({
    name: "getOrFail",
    args: () => Schema.Struct({ noteId: Id("notes") }),
    returns: () => notes.Doc,
    error: () => NoteNotFound,
  }),
);
```

To declare more than one failure mode, combine them with `Schema.Union`.

```ts theme={null}
import * as Schema from "effect/Schema";

import { Id } from "./_generated/id";

export class NoteNotFound extends Schema.TaggedError<NoteNotFound>()(
  "NoteNotFound",
  { noteId: Id("notes") },
) {}

export class Forbidden extends Schema.TaggedError<Forbidden>()(
  "Forbidden",
  {},
) {}

FunctionSpec.publicMutation({
  name: "deleteOrFail",
  args: () => Schema.Struct({ noteId: Id("notes") }),
  returns: () => Schema.Null,
  error: () => Schema.Union(NoteNotFound, Forbidden),
});
```

## Failing from a handler

When a spec declares an `error` schema, the corresponding `FunctionImpl` handler's `Effect` error channel is typed as that schema's `Type`. Use `Effect.fail` (or `Effect.mapError`) to fail with any value matching the schema.

```ts confect/notes.impl.ts theme={null}
import { FunctionImpl } from "@confect/server";
import * as Effect from "effect/Effect";

import databaseSchema from "./_generated/schema";
import { DatabaseReader } from "./_generated/services";
import notes, { NoteNotFound } from "./notes.spec";

const getOrFail = FunctionImpl.make(
  databaseSchema,
  notes,
  "getOrFail",
  ({ noteId }) =>
    Effect.gen(function* () {
      const reader = yield* DatabaseReader;

      return yield* reader
        .table("notes")
        .get(noteId)
        .pipe(Effect.mapError(() => new NoteNotFound({ noteId })));
    }),
);
```

Without an `error` schema, the handler's error channel is `never` and any unmapped failure must still be cleared (typically with `Effect.orDie`). With one, declared failures travel through, and any other failure (a defect) still rejects/dies as before.

## Consuming typed errors

The decoded error is surfaced at every call site. The exact shape depends on the client.

### `@confect/react`

* **`useQuery`** returns a `QueryResult<A, E>`. Match it with `QueryResult.match`, where `onFailure` is required when the ref declares an `error` schema.
* **`useMutation`** and **`useAction`** return `Promise<Either<A, E>>` when the ref declares an `error` schema (and `Promise<A>` otherwise).

See [React](/clients/react) for full examples.

```tsx theme={null}
import { QueryResult, useQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const lookup = useQuery(refs.public.notes.getOrFail, { noteId });

QueryResult.match(lookup, {
  onLoading: (skipped) => (skipped ? null : "Looking up…"),
  onSuccess: (note) => `Found: ${note.text}`,
  onFailure: (error) => `Note ${error.noteId} not found.`,
});
```

### `@confect/js`

Both `HttpClient` and `WebSocketClient` add the decoded error to the returned `Effect`'s error channel, alongside the existing transport error and `ParseError`.

```ts theme={null}
HttpClient.query(refs.public.notes.getOrFail, { noteId });
// Effect.Effect<Note, NoteNotFound | HttpClientError | ParseError>
```

`WebSocketClient.reactiveQuery` carries typed errors too: when the subscribed query fails with a typed error, the returned `Stream` terminates with the decoded value in its error channel. See [HTTP](/clients/js/http) and [WebSocket](/clients/js/websocket).

### `@confect/test`

`TestConfect`'s `query`, `mutation`, and `action` decode typed errors into the `Effect` error channel, so test bridges see the same shape as the JS clients. See [Testing](/guides/testing).

## Non-typed failures

Failures that are not declared in the `error` schema are not silently swallowed. They propagate through Convex's normal failure path: they reject promises in `@convex/react`, fail `Effect`s with `HttpClientError`/`WebSocketClientError` in `@confect/js`, and surface as defects (cause) in `TestConfect`. Use a typed `error` schema for failures you want callers to handle, and let everything else die.


# Functions
Source: https://confect.dev/server/functions

Define and implement Convex queries, mutations, and actions with Confect.

Confect functions are defined as a [spec and impl](/concepts/spec-impl-model) pair. The spec declares each function's name, arguments, and return type. The impl provides the handler logic.

## Function types

| Constructor                           | Description                                             |
| ------------------------------------- | ------------------------------------------------------- |
| `FunctionSpec.publicQuery`            | Public query function                                   |
| `FunctionSpec.publicPaginatedQuery`   | Public [paginated query](#paginated-queries) function   |
| `FunctionSpec.publicMutation`         | Public mutation function                                |
| `FunctionSpec.publicAction`           | Public action function                                  |
| `FunctionSpec.internalQuery`          | Internal query function                                 |
| `FunctionSpec.internalPaginatedQuery` | Internal [paginated query](#paginated-queries) function |
| `FunctionSpec.internalMutation`       | Internal mutation function                              |
| `FunctionSpec.internalAction`         | Internal action function                                |

For Node.js actions, see [Node Actions](/server/node-actions). To integrate plain Convex functions (for use with Convex components or other libraries), see [Plain Convex Functions](/server/plain-convex-functions).

## Defining a spec

Each function spec defines the function's name, arguments schema, and returns schema. The `args`, `returns`, and (optional) `error` schemas are passed as `() => Schema` callbacks, evaluated lazily the first time the function is invoked. Function specs are added to a `GroupSpec` and default-exported from a `*.spec.ts` file. See [The Spec/Impl Model](/concepts/spec-impl-model) for a full walkthrough.

```ts confect/notes.spec.ts theme={null}
import { GroupSpec, FunctionSpec } from "@confect/core";
import * as Schema from "effect/Schema";

import notes from "./_generated/tables/notes";

const list = FunctionSpec.publicQuery({
  name: "list",
  args: () => Schema.Struct({}),
  returns: () => Schema.Array(notes.Doc),
});

export default GroupSpec.make().addFunction(list);
```

Run `confect codegen` after adding or changing specs.

### Typed errors

A spec can also declare an optional `error` schema. When it does, the corresponding handler's `Effect` error channel is typed as that schema, and the failure is decoded for callers at every call site (React hooks, JS clients, and tests). See [Error Handling](/server/error-handling) for the full walkthrough.

```ts theme={null}
import { FunctionSpec } from "@confect/core";
import * as Schema from "effect/Schema";

import { Id } from "./_generated/id";
import notes from "./_generated/tables/notes";

class NoteNotFound extends Schema.TaggedError<NoteNotFound>()("NoteNotFound", {
  noteId: Id("notes"),
}) {}

FunctionSpec.publicQuery({
  name: "getOrFail",
  args: () => Schema.Struct({ noteId: Id("notes") }),
  returns: () => notes.Doc,
  error: () => NoteNotFound,
});
```

### Paginated queries

Define a paginated query with `FunctionSpec.publicPaginatedQuery` (or `internalPaginatedQuery`). Instead of `returns`, pass an `item` schema — the type of one element in a page. The optional `args` schema declares only your own arguments; Confect composes the Convex-facing schemas for you, adding the `paginationOpts` argument (with all of Convex's [pagination protocol fields](https://docs.convex.dev/database/pagination)) and wrapping `item` in a `PaginationResult` returns schema.

```ts confect/notes.spec.ts theme={null}
import { FunctionSpec } from "@confect/core";
import * as Schema from "effect/Schema";

import notes from "./_generated/tables/notes";

FunctionSpec.publicPaginatedQuery({
  name: "listByAuthor",
  args: () => Schema.Struct({ author: Schema.String }), // optional; omit for no extra args
  item: () => notes.Doc,
});
```

Do not declare `paginationOpts` in `args` — it is added automatically, and declaring it yourself is a type (and runtime) error.

The handler receives the decoded args including `paginationOpts`, which it typically forwards directly to [`paginate`](/server/database/reading#paginate):

```ts confect/notes.impl.ts theme={null}
FunctionImpl.make(
  databaseSchema,
  notes,
  "listByAuthor",
  ({ author, paginationOpts }) =>
    Effect.gen(function* () {
      const reader = yield* DatabaseReader;

      return yield* reader
        .table("notes")
        .index("by_creation_time", "desc")
        .paginate(paginationOpts, (q) => q.eq(q.field("author"), author));
    }).pipe(Effect.orDie),
);
```

Paginated queries support the optional `error` schema like any other function. On the client, consume them with [`usePaginatedQuery`](/clients/react#usepaginatedquery).

## Implementing functions

Each function impl contains a handler that implements the function's logic. Function impls are composed into group impls using Effect layers.

The handler receives the decoded arguments as its first parameter and returns an `Effect`. Use the generated [services](/concepts/services) (like `DatabaseReader`, `DatabaseWriter`, `Auth`, etc.) inside your handler to interact with Convex.

```ts confect/notes.impl.ts theme={null}
import { FunctionImpl, GroupImpl } from "@confect/server";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";

import databaseSchema from "./_generated/schema";
import { DatabaseReader } from "./_generated/services";
import notes from "./notes.spec";

const list = FunctionImpl.make(databaseSchema, notes, "list", () =>
  Effect.gen(function* () {
    const reader = yield* DatabaseReader;

    return yield* reader
      .table("notes")
      .index("by_creation_time", "desc")
      .collect();
  }).pipe(Effect.orDie),
);

export default GroupImpl.make(databaseSchema, notes).pipe(
  Layer.provide(list),
  GroupImpl.finalize,
);
```

`GroupImpl.finalize` is the per-group completeness check: it only typechecks once every function declared by the spec has been provided to the group layer.

<Note>
  Convex bundles a deployment into a single artifact, but a function's cold
  start only evaluates the module graph reachable from its entry point. Confect
  emits one Convex module per group, so cold-starting a function only evaluates
  its own group's spec, impl, and the tables it touches. To keep that cold start
  fast, import Effect from its submodule paths (`import * as Schema from
      "effect/Schema"`) rather than the `effect` barrel in your `confect/` files—a
  barrel import pulls the whole `Schema` namespace into the module graph your
  function evaluates at cold start, even when you use only a small part of it.
</Note>


# HTTP API
Source: https://confect.dev/server/http-api

Define HTTP endpoints using Effect's HTTP API modules.

Confect's HTTP API integration lets you define HTTP endpoints using [`@effect/platform`'s HTTP API modules](https://github.com/Effect-TS/effect/blob/main/packages/platform/README.md#http-api) and mount them onto Convex's HTTP router. It includes built-in interactive API documentation powered by [Scalar](https://github.com/scalar/scalar).

## Defining endpoints

Define your API groups and endpoints using `@effect/platform`.

```ts confect/http/notes.ts theme={null}
import {
  HttpApi,
  HttpApiBuilder,
  HttpApiEndpoint,
  HttpApiGroup,
  OpenApi,
} from "@effect/platform";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import * as Schema from "effect/Schema";

import refs from "../_generated/refs";
import { QueryRunner } from "../_generated/services";
import notes from "../_generated/tables/notes";

class NotesGroup extends HttpApiGroup.make("notes")
  .add(
    HttpApiEndpoint.get("getFirst", "/get-first")
      .annotate(OpenApi.Description, "Get the first note, if there is one.")
      .addSuccess(Schema.Option(notes.Doc)),
  )
  .annotate(OpenApi.Title, "Notes")
  .annotate(OpenApi.Description, "Operations on notes.") {}

export class Api extends HttpApi.make("Api")
  .annotate(OpenApi.Title, "My App")
  .add(NotesGroup)
  .prefix("/api") {}
```

## Implementing handlers

Implement your endpoint handlers in the same file using `HttpApiBuilder`. All Confect action [services](/concepts/services) (`QueryRunner`, `MutationRunner`, `ActionRunner`, `Scheduler`, `Auth`, `StorageReader`, `StorageWriter`, `StorageActionWriter`) are available in handlers.

```ts confect/http/notes.ts (continued) theme={null}
const NotesGroupLive = HttpApiBuilder.group(Api, "notes", (handlers) =>
  handlers.handle("getFirst", () =>
    Effect.gen(function* () {
      const runQuery = yield* QueryRunner;

      return yield* runQuery(refs.public.notes.getFirst, {});
    }).pipe(Effect.orDie),
  ),
);

export const ApiLive = HttpApiBuilder.api(Api).pipe(
  Layer.provide(NotesGroupLive),
);
```

## Creating the router

Create the Convex HTTP router in `confect/http.ts` using `HttpApi.make` from `@confect/server`. Each key is a path prefix that must be either `"/"` or end with a trailing slash (e.g. `"/api/"`).

```ts confect/http.ts theme={null}
import { HttpApi } from "@confect/server";
import { HttpMiddleware } from "@effect/platform";
import { flow } from "effect/Function";

import { ApiLive } from "./http/notes";

export default HttpApi.make({
  "/api/": {
    apiLive: ApiLive,
    middleware: flow(HttpMiddleware.cors(), HttpMiddleware.logger),
  },
});
```

Each path prefix entry accepts:

| Property     | Description                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------- |
| `apiLive`    | A `Layer` providing `HttpApi.Api`, built with `HttpApiBuilder.api`                                      |
| `middleware` | Optional middleware function (e.g. `HttpMiddleware.cors()`, `HttpMiddleware.logger`)                    |
| `scalar`     | Optional [Scalar configuration](https://github.com/scalar/scalar) to customize the interactive API docs |

## API documentation

Interactive API docs are automatically served at `{pathPrefix}docs` (e.g. `/api/docs`). The docs are powered by Scalar and generated from your endpoint definitions and OpenApi annotations.


# Node Actions
Source: https://confect.dev/server/node-actions

Define actions that run in the Node.js runtime.

Node actions are like regular actions, but they are executed in the Node.js runtime, so their handlers can use Node's built-in modules and npm packages that depend on them. You declare a node action group by building its spec with `GroupSpec.makeNode()` (rather than `GroupSpec.make()`); that marks the group as Node-runtime, and Confect adds Convex's [`"use node"`](https://docs.convex.dev/functions/runtimes#nodejs-runtime) directive to the generated module accordingly. A node action group is otherwise an ordinary group — the same colocated `.spec.ts`/`.impl.ts` files, following the same [naming and nesting conventions](/concepts/file-naming-conventions).

## Node Spec

A node spec uses `GroupSpec.makeNode()` and one of `FunctionSpec.publicNodeAction()` or `FunctionSpec.internalNodeAction()` to define functions.

```ts confect/email.spec.ts theme={null}
import { FunctionSpec, GroupSpec } from "@confect/core";
import * as Schema from "effect/Schema";

export default GroupSpec.makeNode().addFunction(
  FunctionSpec.publicNodeAction({
    name: "send",
    args: () =>
      Schema.Struct({
        to: Schema.String,
        subject: Schema.String,
        body: Schema.String,
      }),
    returns: () => Schema.Null,
  }),
);
```

## Node Impl

A node impl default-imports its sibling spec and passes the database schema from `_generated/schema` to `FunctionImpl.make` and `GroupImpl.make` — exactly like a non-node impl; only the spec differs (`GroupSpec.makeNode()`). Each handler runs in the Node.js runtime, so it has access to [`NodeContext` services](https://effect-ts.github.io/effect/platform-node/NodeContext.ts.html#nodecontext-type-alias) from the `@effect/platform` package.

```ts confect/email.impl.ts theme={null}
import { FunctionImpl, GroupImpl } from "@confect/server";
import { Command } from "@effect/platform";
import * as Console from "effect/Console";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import databaseSchema from "./_generated/schema";
import email from "./email.spec";

const send = FunctionImpl.make(
  databaseSchema,
  email,
  "send",
  Effect.fn(function* ({ to, subject, body }) {
    const result = yield* Command.make(
      "echo",
      `Sending email to ${to} with subject ${subject} and body ${body}…`,
    ).pipe(Command.stdout("pipe"), Command.string, Effect.orDie);

    yield* Console.log(result);
    yield* Effect.sleep(Duration.seconds(1));
    yield* Console.log("Email sent!");

    return null;
  }),
);

export default GroupImpl.make(databaseSchema, email).pipe(
  Layer.provide(send),
  GroupImpl.finalize,
);
```

## Calling Node Actions

Node actions are referenced like any other function. A node group at `confect/email.spec.ts` is reached at `refs.public.email`.

```ts theme={null}
import { useAction } from "@confect/react";
import refs from "../confect/_generated/refs";

const sendEmail = useAction(refs.public.email.send);

sendEmail({
  to: "user@example.com",
  subject: "Hello",
  body: "Hello from Confect!",
});
```


# Plain Convex Functions
Source: https://confect.dev/server/plain-convex-functions

Integrate plain Convex functions into your Confect spec and impl tree.

Some Convex libraries and [components](https://docs.convex.dev/components) expect you to define standard Convex functions in your project. For example, [Workpool](https://www.convex.dev/components/workpool), [Workflow](https://www.convex.dev/components/workflow), and [Migrations](https://www.convex.dev/components/migrations) all require user-defined Convex functions.

Confect lets you include these plain Convex function definitions in your spec and impl tree so that they are registered, routed, and callable through refs alongside your Effect-based Confect functions.

## Spec constructors

| Constructor                             | Description                |
| --------------------------------------- | -------------------------- |
| `FunctionSpec.convexPublicQuery`        | Public query function      |
| `FunctionSpec.convexPublicMutation`     | Public mutation function   |
| `FunctionSpec.convexPublicAction`       | Public action function     |
| `FunctionSpec.convexPublicNodeAction`   | Public Node.js action      |
| `FunctionSpec.convexInternalQuery`      | Internal query function    |
| `FunctionSpec.convexInternalMutation`   | Internal mutation function |
| `FunctionSpec.convexInternalAction`     | Internal action function   |
| `FunctionSpec.convexInternalNodeAction` | Internal Node.js action    |

## Workpool component example

The [Workpool](https://www.convex.dev/components/workpool) component pools actions and mutations with configurable parallelism and retries. It requires you to define Convex functions that it can reference—such as the action to run and an `onComplete` callback. This walkthrough shows how to integrate those functions into Confect.

### Install the component

```bash theme={null}
npm install @convex-dev/workpool
```

Register it in `convex/convex.config.ts`:

```ts convex/convex.config.ts theme={null}
import { defineApp } from "convex/server";
import workpool from "@convex-dev/workpool/convex.config";

const app = defineApp();
app.use(workpool, { name: "workpool" });

export default app;
```

### Write the Convex functions

Write standard Convex functions using the Convex API and place them in your `confect/` directory. By [convention](/concepts/file-naming-conventions), they go adjacent to their corresponding spec and impl files—for example, `workpool.ts` alongside `workpool.spec.ts` and `workpool.impl.ts`. The component reference comes from Confect's generated [components registry](/server/components#referencing-components).

```ts confect/workpool.ts theme={null}
import {
  type WorkId,
  Workpool,
  vWorkId,
  vOnCompleteArgs,
} from "@convex-dev/workpool";
import { v } from "convex/values";
import { internal } from "../convex/_generated/api";
import {
  internalAction,
  internalMutation,
  mutation,
  query,
} from "../convex/_generated/server";
import { components } from "./_generated/components";

const pool = new Workpool(components.workpool, {
  maxParallelism: 3,
});

export const enqueue = mutation({
  args: {},
  returns: vWorkId,
  handler: async (ctx): Promise<WorkId> => {
    return await pool.enqueueAction(
      ctx,
      internal.workpool.backgroundWork,
      {},
      { onComplete: internal.workpool.onComplete },
    );
  },
});

export const status = query({
  args: { workId: vWorkId },
  returns: v.union(
    v.object({
      state: v.literal("pending"),
      previousAttempts: v.number(),
    }),
    v.object({
      state: v.literal("running"),
      previousAttempts: v.number(),
    }),
    v.object({ state: v.literal("finished") }),
  ),
  handler: async (ctx, { workId }) => {
    return await pool.status(ctx, workId);
  },
});

export const backgroundWork = internalAction({
  args: {},
  returns: v.null(),
  handler: async (): Promise<null> => {
    await new Promise((resolve) =>
      setTimeout(resolve, 2000 + Math.random() * 3000),
    );
    return null;
  },
});

export const onComplete = internalMutation({
  args: vOnCompleteArgs(),
  returns: v.null(),
  handler: async (_ctx, { result }): Promise<null> => {
    if (result.kind === "success") {
      console.log("Background work completed successfully");
    } else if (result.kind === "failed") {
      console.error("Background work failed:", result.error);
    }
    return null;
  },
});
```

### Define the spec

Use the `convex*` spec constructors and pass each Convex function's type as a type argument. Confect extracts argument and return types from the Convex `RegisteredQuery`, `RegisteredMutation`, or `RegisteredAction` type so that refs are fully typed.

```ts confect/workpool.spec.ts theme={null}
import { FunctionSpec, GroupSpec } from "@confect/core";
import type { backgroundWork, enqueue, onComplete, status } from "./workpool";

export default GroupSpec.make()
  .addFunction(FunctionSpec.convexPublicMutation<typeof enqueue>()("enqueue"))
  .addFunction(FunctionSpec.convexPublicQuery<typeof status>()("status"))
  .addFunction(
    FunctionSpec.convexInternalAction<typeof backgroundWork>()(
      "backgroundWork",
    ),
  )
  .addFunction(
    FunctionSpec.convexInternalMutation<typeof onComplete>()("onComplete"),
  );
```

<Note>
  Import the Convex functions as **type-only** imports (`import type`). The spec
  is shared between the server and client, so a runtime import here would leak
  the function implementation to the client bundle.
</Note>

Run `confect codegen` to pick up the new spec.

### Implement the functions

For plain Convex functions, the impl is the Convex function value itself. Pass each one directly to `FunctionImpl.make`.

```ts confect/workpool.impl.ts theme={null}
import { FunctionImpl, GroupImpl } from "@confect/server";
import * as Layer from "effect/Layer";
import databaseSchema from "./_generated/schema";
import { backgroundWork, enqueue, onComplete, status } from "./workpool";
import workpool from "./workpool.spec";

const enqueueImpl = FunctionImpl.make(
  databaseSchema,
  workpool,
  "enqueue",
  enqueue,
);
const statusImpl = FunctionImpl.make(
  databaseSchema,
  workpool,
  "status",
  status,
);
const backgroundWorkImpl = FunctionImpl.make(
  databaseSchema,
  workpool,
  "backgroundWork",
  backgroundWork,
);
const onCompleteImpl = FunctionImpl.make(
  databaseSchema,
  workpool,
  "onComplete",
  onComplete,
);

export default GroupImpl.make(databaseSchema, workpool).pipe(
  Layer.provide(enqueueImpl),
  Layer.provide(statusImpl),
  Layer.provide(backgroundWorkImpl),
  Layer.provide(onCompleteImpl),
  GroupImpl.finalize,
);
```

Run `confect codegen` to pick up the new impl.

### Call plain functions from the client

Plain Convex functions are available through refs just like Confect functions.

```tsx theme={null}
import { useMutation, useQuery } from "@confect/react";
import refs from "../confect/_generated/refs";

const enqueue = useMutation(refs.public.workpool.enqueue);
const status = useQuery(refs.public.workpool.status, { workId });
```

## Mixing Confect and plain functions

A single group can contain both Confect functions (with Effect schemas) and plain Convex functions. Each function's spec constructor determines how it is registered and called.

```ts confect/notes.spec.ts theme={null}
import { FunctionSpec, GroupSpec } from "@confect/core";
import * as Schema from "effect/Schema";
import type { search } from "./search";
import notes from "./_generated/tables/notes";

const list = FunctionSpec.publicQuery({
  name: "list",
  args: () => Schema.Struct({}),
  returns: () => Schema.Array(notes.Doc),
});

const searchSpec = FunctionSpec.convexPublicQuery<typeof search>()("search");

export default GroupSpec.make().addFunction(list).addFunction(searchSpec);
```

In the impl, Confect functions use Effect handlers while plain functions pass through the Convex function value directly.


# Scheduling
Source: https://confect.dev/server/scheduling

Schedule functions to run after a delay or at a specific time.

The `Scheduler` service schedules Confect functions to run in the future. It wraps Convex's scheduler with Effect-native types: delays use [`Duration`](https://effect.website/docs/data-types/duration/) and timestamps use [`DateTime`](https://effect.website/docs/data-types/datetime/).

Both `runAfter` and `runAt` accept a ref to a mutation or action and an optional args object matching the ref's args schema.

## Run after a delay

```ts theme={null}
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import refs from "./confect/_generated/refs";
import { Scheduler } from "./confect/_generated/services";

Effect.gen(function* () {
  const scheduler = yield* Scheduler;

  yield* scheduler.runAfter(Duration.minutes(5), refs.internal.messages.send, {
    text: "Hello",
  });
});
```

## Run at a specific time

```ts theme={null}
Effect.gen(function* () {
  const scheduler = yield* Scheduler;

  const dateTime = yield* DateTime.make("2030-01-01T00:00:00Z");

  yield* scheduler.runAt(dateTime, refs.internal.messages.send, {
    text: "Happy new year",
  });
});
```

For the full scheduling APIs, see the [Effect `Duration` documentation](https://effect.website/docs/data-types/duration/), the [Effect `DateTime` documentation](https://effect.website/docs/data-types/datetime/), and the [Convex scheduling documentation](https://docs.convex.dev/scheduling/scheduled-functions).


# Search
Source: https://confect.dev/server/search

Query vector indexes for semantic similarity search.

## Vector search

The `VectorSearch` service queries vector indexes defined in your [schema](/server/database/schema). It is only available in actions.

```ts theme={null}
import * as Effect from "effect/Effect";
import { VectorSearch } from "./confect/_generated/services";

Effect.gen(function* () {
  const vectorSearch = yield* VectorSearch;

  const results = yield* vectorSearch("notes", "embedding", {
    vector: embeddingVector,
    limit: 10,
    filter: (q) => q.eq("tag", "colors"),
  });
});
```

Each result contains the document's `_id` and a `_score` representing similarity (higher is more similar).

```ts theme={null}
Array<{ _id: GenericId<TableName>; _score: number }>;
```

Vector indexes are defined on tables using the `vectorIndex` method. See the [Schema](/server/database/schema) page for an example.

For more details on vector search queries and index configuration, see the [Convex vector search documentation](https://docs.convex.dev/search/vector-search).

## Full-text search

Full-text search uses search indexes via the `DatabaseReader` service, not the `VectorSearch` service. See the [Reading](/server/database/reading) page for usage.


# Storage
Source: https://confect.dev/server/storage

Store and retrieve blobs using Convex file storage.

## Reading

The `StorageReader` service is used to retrieve the URLs of blobs in storage.

```ts theme={null}
import * as Effect from "effect/Effect";
import { StorageReader } from "./confect/_generated/services";

Effect.gen(function* () {
  const reader = yield* StorageReader;

  return yield* reader.getUrl(storageId);
});
```

## Writing in mutations

The `StorageWriter` service is used to write blobs to storage in mutations.

```ts theme={null}
import * as Effect from "effect/Effect";
import { StorageWriter } from "./confect/_generated/services";

Effect.gen(function* () {
  const storage = yield* StorageWriter;

  // ...
});
```

### Methods

#### Generate an upload URL

```ts theme={null}
storage.generateUploadUrl();
```

#### Delete a blob

```ts theme={null}
storage.delete(storageId);
```

## Writing in actions

The `StorageActionWriter` service is used to read and write blobs to storage in actions.

```ts theme={null}
import * as Effect from "effect/Effect";
import { StorageActionWriter } from "./confect/_generated/services";

Effect.gen(function* () {
  const storage = yield* StorageActionWriter;

  // ...
});
```

### Methods

#### Get a blob

```ts theme={null}
storage.get(storageId);
```

#### Store a blob

```ts theme={null}
storage.store(blob, { sha256: optionalHash });
```