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

npm install fluent-convex

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FLUENT-CONVEX

fluent-convex

databasejavascriptv0.13.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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.

createBuilder

✓ import { createBuilder } from 'fluent-convex'

✗ const createBuilder = require('fluent-convex')

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

fluent-convex/zod

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

✗ import { zodValidator } from 'fluent-convex'

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

FluconvexBuilder

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

✗ import { createBuilder } from 'fluent-convex'; const b = createBuilder()

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

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 issues

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

fix

Use .$context<{ auth: Auth }>().createMiddleware() for cross-function-type middleware.

affects: >=0.0.0

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

fix

Check changelog for any deprecations.

affects: >=0.13.0

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

fix

Use import syntax (ESM) or upgrade to Node 18+ with { "type": "module" }.

affects: >=0.13.0

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

fix

Always pass your DataModel type to createBuilder<T>()

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'fluent-convex' or its corresponding type declarations.

Missing types due to incorrect import path or missing tsconfig entries.

fix

Install fluent-convex and ensure tsconfig has 'moduleResolution': 'node16' or 'bundler'

Property 'db' does not exist on type 'ActionCtx'.

Using query-type middleware on an action.

fix

Use .$context<{ auth: Auth }>().createMiddleware() to create middleware that works across all function types.

Type 'DataModel' could not be inferred. Please provide explicit type argument.

Missing DataModel type parameter when calling createBuilder.

fix

Import DataModel from your convex _generated folder and pass it: createBuilder<DataModel>()

ERR_REQUIRE_ESM

Using require() on an ESM-only package.

fix

Change to import syntax or set { "type": "module" } in package.json.

Upgrade

Version history

0.13.0latest on npm

Audit

Dependencies

convexrequiredpeer dependency: required for Convex backend types and runtime

zodoptionalpeer dependency: used by zod plugin for input validation

convex-helpersoptionalpeer dependency: provides helper utilities

Agent activity

34 hits · last 30 days

node

OpenAI (training)

Resources

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

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

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