Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rjdellecese/confect/llms.txt

Use this file to discover all available pages before exploring further.

The @confect/core package provides the foundational types and utilities for defining type-safe Confect specifications.

​
Overview

FunctionSpec

Define type-safe queries, mutations, and actions

GroupSpec

Organize functions into logical groups

Spec

Root specification for your application

Ref

Type-safe references to functions

​
FunctionSpec

The FunctionSpec namespace provides utilities for defining individual functions.

​
Creating Functions

packages/core/src/FunctionSpec.ts
import { FunctionSpec } from "@confect/core";
import { Schema } from "effect";

// Public query
const getUserById = FunctionSpec.publicQuery({
  name: "getUserById",
  args: Schema.Struct({
    id: Schema.String
  }),
  returns: Schema.Struct({
    id: Schema.String,
    name: Schema.String,
    email: Schema.String
  })
});

// Public mutation
const createUser = FunctionSpec.publicMutation({
  name: "createUser",
  args: Schema.Struct({
    name: Schema.String,
    email: Schema.String
  }),
  returns: Schema.String // Returns user ID
});

// Public action
const sendEmail = FunctionSpec.publicAction({
  name: "sendEmail",
  args: Schema.Struct({
    to: Schema.String,
    subject: Schema.String,
    body: Schema.String
  }),
  returns: Schema.Struct({
    success: Schema.Boolean
  })
});

​
Function Creators

publicQuery

Create a public query function

internalQuery

Create an internal query function

publicMutation

Create a public mutation function

internalMutation

Create an internal mutation function

publicAction

Create a public action function

internalAction

Create an internal action function

​
Node Actions

For actions that run in a Node.js environment: 
import { FunctionSpec } from "@confect/core";

const processFile = FunctionSpec.publicNodeAction({
  name: "processFile",
  args: Schema.Struct({
    filePath: Schema.String
  }),
  returns: Schema.Struct({
    processed: Schema.Boolean
  })
});

const internalTask = FunctionSpec.internalNodeAction({
  name: "internalTask",
  args: Schema.Struct({}),
  returns: Schema.Void
});

​
Type Signature

interface FunctionSpec<
  RuntimeAndFunctionType_ extends RuntimeAndFunctionType,
  FunctionVisibility_ extends FunctionVisibility,
  Name_ extends string,
  Args_ extends Schema.Schema.AnyNoContext,
  Returns_ extends Schema.Schema.AnyNoContext,
> {
  readonly runtimeAndFunctionType: RuntimeAndFunctionType_;
  readonly functionVisibility: FunctionVisibility_;
  readonly name: Name_;
  readonly args: Args_;
  readonly returns: Returns_;
}

​
GroupSpec

The GroupSpec namespace helps organize functions into logical groups.

​
Creating Groups

packages/core/src/GroupSpec.ts
import { GroupSpec, FunctionSpec } from "@confect/core";
import { Schema } from "effect";

// Create a group
const users = GroupSpec.make("users")
  .addFunction(
    FunctionSpec.publicQuery({
      name: "list",
      args: Schema.Struct({}),
      returns: Schema.Array(Schema.Struct({
        id: Schema.String,
        name: Schema.String
      }))
    })
  )
  .addFunction(
    FunctionSpec.publicMutation({
      name: "create",
      args: Schema.Struct({
        name: Schema.String,
        email: Schema.String
      }),
      returns: Schema.String
    })
  );

​
Nested Groups

const admin = GroupSpec.make("admin")
  .addGroup(users)
  .addFunction(
    FunctionSpec.internalMutation({
      name: "deleteAll",
      args: Schema.Struct({}),
      returns: Schema.Void
    })
  );

​
Node Groups

For Node.js-specific functionality: 
const fileOperations = GroupSpec.makeNode("fileOperations")
  .addFunction(
    FunctionSpec.publicNodeAction({
      name: "upload",
      args: Schema.Struct({
        fileName: Schema.String,
        content: Schema.String
      }),
      returns: Schema.String
    })
  );

​
Type Signature

interface GroupSpec<
  Runtime extends RuntimeAndFunctionType.Runtime,
  Name_ extends string,
  Functions_ extends FunctionSpec.AnyWithPropsWithRuntime<Runtime> = never,
  Groups_ extends AnyWithPropsWithRuntime<Runtime> = never,
> {
  readonly runtime: Runtime;
  readonly name: Name_;
  readonly functions: Record<string, Functions_>;
  readonly groups: Record<string, Groups_>;
  
  addFunction<Function extends FunctionSpec.AnyWithPropsWithRuntime<Runtime>>(
    function_: Function,
  ): GroupSpec<Runtime, Name_, Functions_ | Function, Groups_>;
  
  addGroup<Group extends AnyWithPropsWithRuntime<Runtime>>(
    group: Group,
  ): GroupSpec<Runtime, Name_, Functions_, Groups_ | Group>;
}

​
Spec

The root specification type that contains all your application’s groups.

​
Creating a Spec

packages/core/src/Spec.ts
import { Spec, GroupSpec } from "@confect/core";

const spec = Spec.make()
  .add(users)
  .add(posts)
  .add(comments);

export default spec;

​
Convex and Node Specs

You can create separate specs for Convex runtime and Node.js runtime, then merge them.
// Convex spec (spec.ts)
const convexSpec = Spec.make()
  .add(usersGroup)
  .add(postsGroup);

export default convexSpec;

// Node spec (nodeSpec.ts)
const nodeSpec = Spec.makeNode()
  .add(fileProcessingGroup)
  .add(emailGroup);

export default nodeSpec;

// Merged at runtime
const mergedSpec = Spec.merge(convexSpec, nodeSpec);

​
Type Signature

interface Spec<
  Runtime extends RuntimeAndFunctionType.Runtime,
  Groups_ extends GroupSpec.AnyWithPropsWithRuntime<Runtime> = never,
> {
  readonly runtime: Runtime;
  readonly groups: Record<string, Groups_>;
  
  add<Group extends GroupSpec.AnyWithPropsWithRuntime<Runtime>>(
    group: Group,
  ): Spec<Runtime, Groups_ | Group>;
}

​
Ref

Type-safe references to functions for use in client code.

​
Reference Types

packages/core/src/Ref.ts
interface Ref<
  _RuntimeAndFunctionType extends RuntimeAndFunctionType,
  _FunctionVisibility extends FunctionVisibility,
  _Args extends Schema.Schema.AnyNoContext,
  _Returns extends Schema.Schema.AnyNoContext,
> {
  readonly _RuntimeAndFunctionType?: _RuntimeAndFunctionType;
  readonly _FunctionVisibility?: _FunctionVisibility;
  readonly _Args?: _Args;
  readonly _Returns?: _Returns;
}

​
Type Helpers

Ref.Args

Extract argument type from a ref

Ref.Returns

Extract return type from a ref

Ref.AnyQuery

Type for any query ref

Ref.AnyMutation

Type for any mutation ref

Ref.AnyAction

Type for any action ref

Ref.AnyPublic

Type for any public function ref

​
Usage with Generated Refs

import { refs } from "../confect/_generated/refs";
import type { Ref } from "@confect/core";

// Type-safe reference
const userQuery: Ref.AnyPublicQuery = refs.public.users.getById;

// Extract types
type UserQueryArgs = Ref.Args<typeof userQuery>["Type"];
type UserQueryReturns = Ref.Returns<typeof userQuery>["Type"];

​
Refs

The Refs namespace provides utilities for creating structured references to all functions.

​
Creating Refs

packages/core/src/Refs.ts
import { Refs } from "@confect/core";
import spec from "./spec";
import nodeSpec from "./nodeSpec";

const { public: publicRefs, internal: internalRefs } = Refs.make(
  spec,
  nodeSpec
);

export const refs = {
  public: publicRefs,
  internal: internalRefs
};

​
Generated Structure

// Generated refs structure
const refs = {
  public: {
    users: {
      list: Ref<...>,
      getById: Ref<...>,
      create: Ref<...>
    },
    posts: {
      list: Ref<...>,
      create: Ref<...>
    },
    node: {
      fileOperations: {
        upload: Ref<...>
      }
    }
  },
  internal: {
    // Internal function refs
  }
};

​
Additional Types

​
GenericId

Type-safe document IDs. 
import { GenericId } from "@confect/core";
import type { Id } from "convex/values";

type UserId = Id<"users">;

​
PaginationResult

Pagination result type for queries. 
import { PaginationResult } from "@confect/core";

type UserPage = PaginationResult<User>;

​
UserIdentity

Authentication identity type. 
import { UserIdentity } from "@confect/core";

interface UserIdentity {
  subject: string;
  name?: string;
  email?: string;
  // ... additional fields
}

​
Next Steps

Server API

Explore server-side implementation APIs

React Hooks

Learn about React integration

Testing

Test your Confect functions

CLI Commands

Use the Confect CLI tool

Build docs developers (and LLMs) love

Get started for freeTalk to us