fluent-convex

library0.13.0jsnpmunverified

A fluent API builder for Convex functions with composable middleware, reusable chains, and plugin support. Current stable version 0.13.0, actively maintained with monthly releases. Key differentiators: onion-style middleware composition, full type inference across chains, cross-function-type middleware via `$context`, and official plugins (e.g., fluent-convex/zod). Unlike raw Convex functions, provides a developer-friendly chainable syntax and middleware abstraction. Requires peer dependencies convex ^1.31.0, zod ^3.25.0 || ^4.0.0, convex-helpers >=0.1.0.

database web-framework aws llm-agents

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ESM-only. v0.13+ uses pure ESM; CommonJS require will fail.

import { createBuilder } from 'fluent-convex'

Zod plugin is a separate subpath export. Must import from 'fluent-convex/zod'.

import { zodValidator } from 'fluent-convex/zod'

Type parameter for DataModel is required for full type inference. Omitting it loses db query types.

import type { DataModel } from './_generated/dataModel'; import { createBuilder } from 'fluent-convex'; const b = createBuilder<DataModel>()

Creates a Convex query using fluent-convex with input validation and public registration. Demonstrates createBuilder, .query(), .input(), .handler(), and .public().

import { createBuilder } from "fluent-convex"; import { v } from "convex/values"; import type { DataModel } from "./_generated/dataModel"; const convex = createBuilder<DataModel>(); export const listNumbers = convex .query() .input({ count: v.number() }) .handler(async (ctx, args) => { const rows = await ctx.db.query("numbers").order("desc").take(args.count); return rows.map((r) => r.value); }) .public();

Debug

Known footguns

gotchaMiddleware created with .query().createMiddleware() only works on queries (not mutations/actions) because it expects QueryCtx with db property.

deprecatedIn v0.13, some internal APIs may change; always use the public builder methods.

breakingv0.13 requires ESM imports; CommonJS require() will throw.

gotchaForgetting the DataModel type parameter loses type inference on ctx.db queries.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

23 hits · last 30 days

gptbot

bytedance

ahrefsbot

claudebot

script

Resources

githubhttps://github.com/mikecann/fluent-convex ↗

packagehttps://www.npmjs.com/package/fluent-convex ↗

homepagehttps://friendly-zebra-716.convex.site/ ↗