Functions

Confect functions are defined as a spec and impl 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 function
`FunctionSpec.publicMutation`	Public mutation function
`FunctionSpec.publicAction`	Public action function
`FunctionSpec.internalQuery`	Internal query function
`FunctionSpec.internalPaginatedQuery`	Internal paginated query function
`FunctionSpec.internalMutation`	Internal mutation function
`FunctionSpec.internalAction`	Internal action function

For Node.js actions, see Node Actions. To integrate plain Convex functions (for use with Convex components or other libraries), see Plain Convex Functions.

Defining a spec

Each function spec defines the function’s name, argument fields, and returns schema. The optional args callback returns a Schema.Struct field map and defaults to {} when omitted, while returns and the optional error are callbacks returning schemas. All provided callbacks are 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 for a full walkthrough.

confect/notes.spec.ts

import { GroupSpec, FunctionSpec } from "@confect/core";
import * as Schema from "effect/Schema";

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

const list = FunctionSpec.publicQuery({
  name: "list",
  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 for the full walkthrough.

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: () => ({ 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 field map 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) and wrapping item in a PaginationResult returns schema.

confect/notes.spec.ts

import { FunctionSpec } from "@confect/core";
import * as Schema from "effect/Schema";

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

FunctionSpec.publicPaginatedQuery({
  name: "listByAuthor",
  args: () => ({ 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:

confect/notes.impl.ts

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.

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 (like DatabaseReader, DatabaseWriter, Auth, etc.) inside your handler to interact with Convex.

confect/notes.impl.ts

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.

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.

Getting Started

Concepts

Server

Clients

Guides

Function types

Defining a spec

Typed errors

Paginated queries

Implementing functions

​Function types

​Defining a spec

​Typed errors

​Paginated queries

​Implementing functions

Function types

Defining a spec

Typed errors

Paginated queries

Implementing functions