fluent-convex 0.12.2 → 0.13.0

package/README.md

@@ -2,19 +2,19 @@
 
 # Fluent Convex
 
-A fluent API builder for Convex functions with middleware support, inspired by [oRPC](https://orpc.unnoq.com/).
+A fluent builder for Convex functions with composable middleware, reusable chains, and plugin support. Inspired by [oRPC](https://orpc.unnoq.com/).
 
-**[Live Docs & Interactive Showcase](https://friendly-zebra-716.convex.site)** -- see every feature in action with live demos and real source code.
+**[Live Docs & Interactive Showcase](https://friendly-zebra-716.convex.site)** — every feature with live demos and real source code.
+
+[![Is this the best way to write Convex? Does anyone care?](https://thumbs.video-to-markdown.com/e943cc42.jpg)](https://youtu.be/oFqWtLBSgk8)
 
 ## Features
 
-- **Middleware support** - Compose reusable middleware for authentication, logging, and more ([docs](https://friendly-zebra-716.convex.site/middleware))
-- **Callable builders** - Define logic once, call it directly from other handlers, and register it multiple ways ([docs](https://friendly-zebra-716.convex.site/reusable-chains))
-- **Type-safe** - Full TypeScript support with type inference
-- **Fluent API** - Chain methods for a clean, readable syntax ([docs](https://friendly-zebra-716.convex.site/basics))
-- **Plugin system** - Extend with plugins like `fluent-convex/zod` for Zod schema support ([docs](https://friendly-zebra-716.convex.site/zod-plugin))
-- **Extensible** - Build your own plugins with the `_clone()` factory pattern ([docs](https://friendly-zebra-716.convex.site/custom-plugins))
-- **Works with Convex** - Built on top of Convex's function system
+- **Composable middleware** — authentication, logging, error handling with onion-style composition ([docs](https://friendly-zebra-716.convex.site/middleware))
+- **Reusable chains** — define logic once, call it directly from other handlers (no extra function invocation), register it multiple ways ([docs](https://friendly-zebra-716.convex.site/reusable-chains))
+- **Fluent API** — clean chainable syntax for queries, mutations, and actions ([docs](https://friendly-zebra-716.convex.site/basics))
+- **Full type inference** — middleware context flows through the entire chain
+- **Plugin system** — extend with plugins like `fluent-convex/zod` for Zod schema validation ([docs](https://friendly-zebra-716.convex.site/zod-plugin))
 
 ## Installation
 
@@ -26,8 +26,6 @@ npm install fluent-convex
 
 > For a complete walkthrough with live demos, see the **[Getting Started guide](https://friendly-zebra-716.convex.site/)**.
 
-**Important:** All functions must end with `.public()` or `.internal()` to be registered with Convex.
-
 ```ts
 import { createBuilder } from "fluent-convex";
 import { v } from "convex/values";
@@ -35,85 +33,83 @@ import type { DataModel } from "./_generated/dataModel";
 
 const convex = createBuilder<DataModel>();
 
-// Simple query
 export const listNumbers = convex
   .query()
   .input({ count: v.number() })
-  .handler(async (context, input) => {
-    const numbers = await context.db
-      .query("numbers")
-      .order("desc")
-      .take(input.count);
-
-    return { numbers: numbers.map((n) => n.value) };
+  .handler(async (ctx, args) => {
+    const rows = await ctx.db.query("numbers").order("desc").take(args.count);
+    return rows.map((r) => r.value);
   })
-  .public(); // Must end with .public() or .internal()
+  .public();
+```
 
-// With middleware
-const authMiddleware = convex.query().createMiddleware(async (context, next) => {
-  const identity = await context.auth.getUserIdentity();
-  if (!identity) {
-    throw new Error("Unauthorized");
-  }
+Everything starts with `createBuilder<DataModel>()`. From there, chain `.query()` / `.mutation()` / `.action()`, add `.input()` and `.handler()`, and finalize with `.public()` or `.internal()` to register the function with Convex.
+
+## Middleware
+
+> See the **[Middleware docs](https://friendly-zebra-716.convex.site/middleware)** for detailed examples.
 
+Middleware wraps your handlers with reusable logic. It uses an onion model: `next()` executes the rest of the chain including the handler, so middleware can run code before and after.
+
+```ts
+const authMiddleware = convex.query().createMiddleware(async (ctx, next) => {
+  const identity = await ctx.auth.getUserIdentity();
+  if (!identity) throw new Error("Unauthorized");
   return next({
-    ...context,
-    user: {
-      id: identity.subject,
-      name: identity.name ?? "Unknown",
-    },
+    ...ctx,
+    user: { id: identity.subject, name: identity.name ?? "Unknown" },
   });
 });
 
-export const listNumbersAuth = convex
+export const listNumbersProtected = convex
   .query()
   .use(authMiddleware)
   .input({ count: v.number() })
-  .handler(async (context, input) => {
-    const numbers = await context.db
-      .query("numbers")
-      .order("desc")
-      .take(input.count);
-
-    return {
-      viewer: context.user.name, // user is available from middleware!
-      numbers: numbers.map((n) => n.value),
-    };
+  .handler(async (ctx, args) => {
+    const rows = await ctx.db.query("numbers").order("desc").take(args.count);
+    return { viewer: ctx.user.name, numbers: rows.map((r) => r.value) };
   })
   .public();
 ```
 
-## Validation
-
-> See the **[Validation docs](https://friendly-zebra-716.convex.site/validation)** for a side-by-side comparison of all three approaches with live demos.
+### Cross-function-type middleware
 
-fluent-convex supports three flavors of input validation through the same `.input()` API:
+Because `authMiddleware` above was created with `.query().createMiddleware()`, its input context is `QueryCtx` — so it can't be used on mutations or actions (`ActionCtx` lacks `db`, causing a type error). For middleware that only needs properties shared across all function types (like `auth`), use `$context` to declare exactly what the middleware requires:
 
-1. **Property validators** -- `{ count: v.number() }` (simplest)
-2. **Object validators** -- `v.object({ count: v.number() })` (with `.returns()` support)
-3. **Zod schemas** -- `z.object({ count: z.number().min(1) })` (via the Zod plugin)
-
-## Middleware
-
-> See the **[Middleware docs](https://friendly-zebra-716.convex.site/middleware)** for detailed examples of both patterns.
+```ts
+import type { Auth } from "convex/server";
+
+// Works with queries, mutations, AND actions
+const authMiddleware = convex
+  .$context<{ auth: Auth }>()
+  .createMiddleware(async (ctx, next) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new Error("Unauthorized");
+    return next({
+      ...ctx,
+      user: { id: identity.subject, name: identity.name ?? "Unknown" },
+    });
+  });
 
-There are two main middleware patterns:
+const authQuery = convex.query().use(authMiddleware);
+const authMutation = convex.mutation().use(authMiddleware);
+const authAction = convex.action().use(authMiddleware);
+```
 
-- **Context-enrichment** -- adds new properties to the context (e.g. `ctx.user`)
-- **Onion (wrap)** -- runs code before *and* after the handler (e.g. timing, error handling)
+| Pattern                                                  | Input context            | Use when                                         |
+| -------------------------------------------------------- | ------------------------ | ------------------------------------------------ |
+| `convex.query().createMiddleware(fn)`                    | `QueryCtx` (has `db`)    | Middleware that reads the database               |
+| `convex.createMiddleware(fn)`                            | `EmptyObject`            | Middleware that needs no context at all          |
+| `convex.$context<{ auth: Auth }>().createMiddleware(fn)` | Exactly `{ auth: Auth }` | Middleware that needs specific shared properties |
 
 ## Reusable Chains & Callables
 
 > See the **[Reusable Chains docs](https://friendly-zebra-716.convex.site/reusable-chains)** for full examples with live demos.
 
-Because the builder is immutable, you can stop the chain at any point and reuse that partial builder later. A builder with a `.handler()` but no `.public()` / `.internal()` is called a **callable** -- a fully-typed function you can:
-
-1. **Call directly** from inside other handlers (no additional Convex function invocation)
-2. **Register** as a standalone Convex endpoint
-3. **Extend** with more middleware and register multiple ways
+Because the builder is immutable, you can stop the chain at any point and reuse it. A builder with a `.handler()` but no `.public()` / `.internal()` is a **callable** — a fully-typed function you can invoke directly from other handlers without an extra Convex function call:
 
 ```ts
-// 1. Define a callable - NOT yet registered with Convex
+// Define a callable — not yet registered with Convex
 const getNumbers = convex
   .query()
   .input({ count: v.number() })
@@ -122,29 +118,35 @@ const getNumbers = convex
     return rows.map((r) => r.value);
   });
 
-// 2. Register it as a public query
+// Register it as a public query
 export const listNumbers = getNumbers.public();
 
-// 3. Call it directly from inside another handler - no additional function invocation!
+// Call it directly from another handler — no extra function invocation
 export const getNumbersWithTimestamp = convex
   .query()
   .input({ count: v.number() })
   .handler(async (ctx, args) => {
-    const numbers = await getNumbers(ctx, args); // <-- direct call
+    const numbers = await getNumbers(ctx, args);
     return { numbers, fetchedAt: Date.now() };
   })
   .public();
 
-// 4. Register the same callable with different middleware
+// Register the same callable with different middleware
 export const listNumbersProtected = getNumbers.use(authMiddleware).public();
 export const listNumbersLogged = getNumbers.use(withLogging("logged")).public();
 ```
 
-The callable syntax is `callable(ctx, args)` -- the first argument passes the context (so the middleware chain runs with the right ctx), the second passes the validated arguments.
+## Validation
+
+> See the **[Validation docs](https://friendly-zebra-716.convex.site/validation)** for a side-by-side comparison with live demos.
 
-## Plugins
+`.input()` supports three flavors of validation:
 
-### Zod Plugin (`fluent-convex/zod`)
+1. **Property validators** — `{ count: v.number() }` (simplest)
+2. **Object validators** — `v.object({ count: v.number() })` (with `.returns()` support)
+3. **Zod schemas** — `z.object({ count: z.number().min(1) })` (via the Zod plugin)
+
+## Zod Plugin (`fluent-convex/zod`)
 
 > See the **[Zod Plugin docs](https://friendly-zebra-716.convex.site/zod-plugin)** for live demos including refinement validation.
 
@@ -154,76 +156,46 @@ The Zod plugin adds Zod schema support for `.input()` and `.returns()`, with **f
 npm install zod convex-helpers
 ```
 
-> **Note:** `zod` and `convex-helpers` are optional peer dependencies of `fluent-convex`. They're only needed if you use the Zod plugin.
-
-Usage:
+> `zod` and `convex-helpers` are optional peer dependencies — only needed if you use this plugin.
 
 ```ts
-import { createBuilder } from "fluent-convex";
 import { WithZod } from "fluent-convex/zod";
 import { z } from "zod";
-import type { DataModel } from "./_generated/dataModel";
-
-const convex = createBuilder<DataModel>();
 
 export const listNumbers = convex
   .query()
-  .extend(WithZod) // Enable Zod support
+  .extend(WithZod)
   .input(
     z.object({
-      count: z.number().int().min(1).max(100), // Refinements enforced at runtime!
-    })
+      count: z.number().int().min(1).max(100),
+    }),
   )
   .returns(z.object({ numbers: z.array(z.number()) }))
-  .handler(async (context, input) => {
-    const numbers = await context.db.query("numbers").take(input.count);
+  .handler(async (ctx, args) => {
+    const numbers = await ctx.db.query("numbers").take(args.count);
     return { numbers: numbers.map((n) => n.value) };
   })
   .public();
 ```
 
-Key features:
-- **Full runtime validation** - Zod refinements (`.min()`, `.max()`, `.email()`, `.regex()`, etc.) are enforced server-side. Args are validated before the handler runs; return values after.
-- **Structural conversion** - Zod schemas are automatically converted to Convex validators for Convex's built-in validation.
-- **Composable** - `.extend(WithZod)` preserves the `WithZod` type through `.use()`, `.input()`, and `.returns()` chains.
-- **Plain validators still work** - You can mix Zod and Convex validators in the same builder chain.
+- **Full runtime validation** — Zod refinements are enforced server-side, before and after the handler
+- **Structural conversion** — Zod schemas are automatically converted to Convex validators
+- **Composable** — `.extend(WithZod)` preserves through `.use()`, `.input()`, and `.returns()` chains
+- **Plain validators still work** — mix Zod and Convex validators in the same builder chain
 
-## Extensibility
+## Custom Plugins
 
 > See the **[Custom Plugins docs](https://friendly-zebra-716.convex.site/custom-plugins)** for a complete worked example with live demo.
 
-You can extend the builder with your own plugins by subclassing `ConvexBuilderWithFunctionKind` and overriding the `_clone()` factory method.
-
-### Writing a Plugin
-
-The `_clone()` method is called internally by `.use()`, `.input()`, and `.returns()` to create new builder instances. By overriding it, your plugin's type is preserved through the entire builder chain.
+Extend the builder by subclassing `ConvexBuilderWithFunctionKind` and overriding `_clone()`. This preserves your plugin's type through the entire builder chain:
 
 ```ts
 import {
   ConvexBuilderWithFunctionKind,
-  type GenericDataModel,
-  type FunctionType,
-  type Context,
-  type EmptyObject,
-  type ConvexArgsValidator,
-  type ConvexReturnsValidator,
   type ConvexBuilderDef,
 } from "fluent-convex";
 
-class MyPlugin<
-  TDataModel extends GenericDataModel = GenericDataModel,
-  TFunctionType extends FunctionType = FunctionType,
-  TCurrentContext extends Context = EmptyObject,
-  TArgsValidator extends ConvexArgsValidator | undefined = undefined,
-  TReturnsValidator extends ConvexReturnsValidator | undefined = undefined,
-> extends ConvexBuilderWithFunctionKind<
-  TDataModel,
-  TFunctionType,
-  TCurrentContext,
-  TArgsValidator,
-  TReturnsValidator
-> {
-  // Accept both builder instances (from .extend()) and raw defs (from _clone())
+class MyPlugin extends ConvexBuilderWithFunctionKind {
   constructor(builderOrDef: any) {
     const def =
       builderOrDef instanceof ConvexBuilderWithFunctionKind
@@ -232,12 +204,10 @@ class MyPlugin<
     super(def);
   }
 
-  // Override _clone() to preserve MyPlugin through the chain
   protected _clone(def: ConvexBuilderDef<any, any, any>): any {
     return new MyPlugin(def);
   }
 
-  // Add custom methods
   myCustomMethod(param: string) {
     console.log("Custom method called with:", param);
     return this;
@@ -245,175 +215,66 @@ class MyPlugin<
 }
 ```
 
-Usage:
+Usage — plugins compose with `.extend()`:
 
 ```ts
 export const myQuery = convex
   .query()
   .extend(MyPlugin)
-  .myCustomMethod("hello")     // Custom method from plugin
-  .use(authMiddleware)          // .use() preserves MyPlugin type
-  .input({ count: v.number() })
-  .handler(async (ctx, input) => { ... })
-  .public();
-```
-
-### Composing Multiple Plugins
-
-Plugins can be composed with `.extend()`:
-
-```ts
-export const myQuery = convex
-  .query()
-  .extend(MyPlugin)
-  .extend(WithZod) // WithZod overrides .input()/.returns() from MyPlugin
+  .extend(WithZod)
   .myCustomMethod("hello")
   .input(z.object({ count: z.number() }))
-  .handler(async (ctx, input) => { ... })
-  .public();
-```
-
-## Flexible Method Ordering
-
-The builder API is flexible about method ordering, allowing you to structure your code in the way that makes the most sense for your use case.
-
-### Middleware After Handler
-
-You can add middleware **after** defining the handler, which is useful when you want to wrap existing handlers with additional functionality:
-
-```ts
-export const getNumbers = convex
-  .query()
-  .input({ count: v.number() })
-  .handler(async (context, input) => {
-    return await context.db.query("numbers").take(input.count);
-  })
-  .use(authMiddleware) // Middleware added after handler
-  .public();
-```
-
-### Callable Builders
-
-Before registering a function with `.public()` or `.internal()`, the builder is **callable** -- you can invoke it directly from other handlers (see [Reusable Chains](#reusable-chains--callables) above) or use it in tests:
-
-```ts
-// A callable (not yet registered)
-const getDouble = convex
-  .query()
-  .input({ count: v.number() })
-  .handler(async (context, input) => {
-    return { doubled: input.count * 2 };
-  });
-
-// Call it from another handler
-export const tripled = convex
-  .query()
-  .input({ count: v.number() })
-  .handler(async (ctx, input) => {
-    const { doubled } = await getDouble(ctx, input);
-    return { tripled: doubled + input.count };
+  .handler(async (ctx, args) => {
+    /* ... */
   })
   .public();
-
-// Or call it directly in tests
-const mockContext = {} as any;
-const result = await getDouble(mockContext, { count: 5 });
-console.log(result); // { doubled: 10 }
-
-// Register it when you also need it as a standalone endpoint
-export const doubleNumber = getDouble.public();
 ```
 
-### Method Ordering Rules
+## API Reference
 
-- **`.returns()`** must be called **before** `.handler()`
-- **`.use()`** can be called **before or after** `.handler()`
-- **`.public()`** or **`.internal()`** must be called **after** `.handler()` and is **required** to register the function
-- Functions are **callable** before registration, **non-callable** after registration
-- **All exported functions must end with `.public()` or `.internal()`** - functions without registration will not be available in your Convex API
+| Method                                   | Description                                                |
+| ---------------------------------------- | ---------------------------------------------------------- |
+| `.query()` / `.mutation()` / `.action()` | Set the function type                                      |
+| `.input(validator)`                      | Set input validation                                       |
+| `.returns(validator)`                    | Set return type validation — must come before `.handler()` |
+| `.use(middleware)`                       | Apply middleware — can come before or after `.handler()`   |
+| `.handler(fn)`                           | Define the function handler                                |
+| `.extend(plugin)`                        | Extend with a plugin class                                 |
+| `.createMiddleware(fn)`                  | Create a middleware function                               |
+| `.public()` / `.internal()`              | Register with Convex — must come after `.handler()`        |
 
-## API
-
-### Methods
-
-- `.query()` - Define a Convex query
-- `.mutation()` - Define a Convex mutation
-- `.action()` - Define a Convex action
-- `.public()` - Register the function as public (required to register)
-- `.internal()` - Register the function as internal/private (required to register)
-- `.input(validator)` - Set input validation (Convex validators)
-- `.returns(validator)` - Set return validation (Convex validators)
-- `.use(middleware)` - Apply middleware
-- `.createMiddleware(fn)` - Create a middleware function
-- `.handler(fn)` - Define the function handler
-- `.extend(plugin)` - Extend the builder with a plugin class
+Before registration (`.public()` / `.internal()`), the builder is **callable**. After registration, it is not.
 
 ## Caveats
 
 ### Circular types when calling `api.*` in the same file
 
-When a function calls other functions via `api.*` in the same file, and those functions don't have explicit `.returns()` validators, TypeScript may report circular initializer errors (TS7022). This is a standard Convex/TypeScript limitation, not specific to fluent-convex. Workarounds:
-1. Add `.returns()` to the **called** functions -- this gives them explicit return types, breaking the cycle
+When a function calls other functions via `api.*` in the same file without explicit `.returns()` validators, TypeScript may report circular initializer errors (TS7022). This is a standard Convex/TypeScript limitation. Workarounds:
+
+1. Add `.returns()` to the called functions to give them explicit return types
 2. Move the calling function to a separate file
 3. Use `internal.*` from a different module
 
-## Documentation
-
-The **[live docs site](https://friendly-zebra-716.convex.site)** is an interactive showcase that demonstrates every feature with working live demos. The code snippets shown on the docs site are the actual source code powering the app -- imported via Vite `?raw` imports, so what you see is what runs.
-
-Sections:
-- [Getting Started](https://friendly-zebra-716.convex.site/) -- builder setup and overview
-- [Basics](https://friendly-zebra-716.convex.site/basics) -- queries, mutations, and the fluent chain
-- [Validation](https://friendly-zebra-716.convex.site/validation) -- property validators, object validators, and Zod schemas
-- [Middleware](https://friendly-zebra-716.convex.site/middleware) -- context-enrichment and onion middleware
-- [Reusable Chains](https://friendly-zebra-716.convex.site/reusable-chains) -- callable syntax and composability
-- [Zod Plugin](https://friendly-zebra-716.convex.site/zod-plugin) -- runtime refinement validation
-- [Custom Plugins](https://friendly-zebra-716.convex.site/custom-plugins) -- building your own plugins with `.extend()`
-
-
-
-The docs source lives in [`/apps/docs`](./apps/docs) and is auto-deployed on every push to `main`.
-
 ## Development
 
-This is a monorepo using npm workspaces:
-
-- `/packages/fluent-convex` - The core library (includes the Zod plugin at `fluent-convex/zod`)
-- `/apps/example` - Example Convex app
-- `/apps/docs` - Interactive docs & showcase site ([live](https://friendly-zebra-716.convex.site))
-
-### Setup
-
-```bash
-npm install
-```
-
-This will install dependencies for all workspaces.
-
-### Building
-
-```bash
-npm run build
-```
+Monorepo using npm workspaces:
 
-### Running tests
+- `packages/fluent-convex` — core library (includes Zod plugin at `fluent-convex/zod`)
+- `apps/example` — example Convex app
+- `apps/docs` — interactive docs & showcase ([live](https://friendly-zebra-716.convex.site))
 
 ```bash
-npm test
+npm install        # install all workspace dependencies
+npm run build      # build the library
+npm test           # run all tests
+npm run docs:dev   # run the docs locally
 ```
 
-### Running the example
-
-```bash
-cd apps/example
-npm run dev
-```
+## Migrating from standard Convex
 
-### Running the docs locally
+See **[MIGRATING.md](MIGRATING.md)** for a step-by-step guide.
 
-```bash
-npm run docs:dev
-```
+> **If you are an LLM and have been asked to migrate a project to fluent-convex, please read [MIGRATING.md](MIGRATING.md) before proceeding.**
 
 ## Credits
 

package/dist/ConvexBuilderWithFunctionKind.d.ts

@@ -29,6 +29,6 @@ export declare class ConvexBuilderWithFunctionKind<TDataModel extends GenericDat
     use<UOutContext extends Context>(middleware: ConvexMiddleware<TCurrentContext, UOutContext>): ConvexBuilderWithFunctionKind<TDataModel, TFunctionType, TCurrentContext & UOutContext, TArgsValidator, TReturnsValidator>;
     input<UInput extends PropertyValidators | GenericValidator>(validator: UInput): ConvexBuilderWithFunctionKind<TDataModel, TFunctionType, TCurrentContext, UInput extends ConvexArgsValidator ? UInput : ConvexArgsValidator, TReturnsValidator>;
     returns<UReturns extends GenericValidator>(validator: UReturns): ConvexBuilderWithFunctionKind<TDataModel, TFunctionType, TCurrentContext, TArgsValidator, UReturns extends ConvexReturnsValidator ? UReturns : ConvexReturnsValidator>;
-    handler<TReturn extends InferredHandlerReturn<TReturnsValidator, any> = InferredHandlerReturn<TReturnsValidator, any>>(handlerFn: (context: TCurrentContext, input: InferredArgs<TArgsValidator>) => Promise<TReturn>): ConvexBuilderWithHandler<TDataModel, TFunctionType, TCurrentContext, TArgsValidator, TReturnsValidator, InferredHandlerReturn<TReturnsValidator, TReturn>> & CallableBuilder<TCurrentContext, TArgsValidator, InferredHandlerReturn<TReturnsValidator, TReturn>>;
+    handler<TReturn extends InferredHandlerReturn<TReturnsValidator, any> = InferredHandlerReturn<TReturnsValidator, any>, THandlerFn extends (context: TCurrentContext, input: InferredArgs<TArgsValidator>) => Promise<TReturn> = (context: TCurrentContext, input: InferredArgs<TArgsValidator>) => Promise<TReturn>>(handlerFn: THandlerFn & ((context: TCurrentContext, input: InferredArgs<TArgsValidator>) => Promise<TReturn>)): ConvexBuilderWithHandler<TDataModel, TFunctionType, TCurrentContext, TArgsValidator, TReturnsValidator, InferredHandlerReturn<TReturnsValidator, TReturn>> & THandlerFn & CallableBuilder<TCurrentContext, TArgsValidator, InferredHandlerReturn<TReturnsValidator, TReturn>>;
 }
 //# sourceMappingURL=ConvexBuilderWithFunctionKind.d.ts.map

package/dist/ConvexBuilderWithFunctionKind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConvexBuilderWithFunctionKind.d.ts","sourceRoot":"","sources":["../src/ConvexBuilderWithFunctionKind.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ConvexBuilderWithFunctionKind.d.ts","sourceRoot":"","sources":["../src/ConvexBuilderWithFunctionKind.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAuB,MAAM,cAAc,CAAC;AAC1E,OAAO,KAAK,EACV,YAAY,EACZ,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,SAAS,CAAC;AAGjB,qBAAa,6BAA6B,CACxC,UAAU,SAAS,gBAAgB,GAAG,gBAAgB,EACtD,aAAa,SAAS,YAAY,GAAG,YAAY,EACjD,eAAe,SAAS,OAAO,GAAG,WAAW,EAC7C,cAAc,SAAS,mBAAmB,GAAG,SAAS,GAAG,SAAS,EAClE,iBAAiB,SAAS,sBAAsB,GAAG,SAAS,GAAG,SAAS;IAExE,SAAS,CAAC,GAAG,EAAE,gBAAgB,CAC7B,aAAa,EACb,cAAc,EACd,iBAAiB,CAClB,CAAC;gBAGA,GAAG,EAAE,gBAAgB,CAAC,aAAa,EAAE,cAAc,EAAE,iBAAiB,CAAC;IAKzE;;;;OAIG;IACH,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,GAAG;IAI3D,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,IAAI,KAAK,OAAO,GAAG,OAAO;IACxD,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,IAAI,KAAK,OAAO,GAAG,OAAO;IAO7D,QAAQ,CAAC,CAAC,SAAS,OAAO,KAAK;QAC7B,gBAAgB,CAAC,WAAW,SAAS,OAAO,EAC1C,UAAU,EAAE,gBAAgB,CAAC,CAAC,EAAE,WAAW,CAAC,GAC3C,gBAAgB,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;KACrC;IAUD;;;OAGG;IACH,gBAAgB,CAAC,WAAW,SAAS,OAAO,EAC1C,UAAU,EAAE,gBAAgB,CAAC,eAAe,EAAE,WAAW,CAAC,GACzD,gBAAgB,CAAC,eAAe,EAAE,WAAW,CAAC;IACjD,gBAAgB,CAAC,UAAU,SAAS,OAAO,EAAE,WAAW,SAAS,OAAO,EACtE,UAAU,EAAE,gBAAgB,CAAC,UAAU,EAAE,WAAW,CAAC,GACpD,gBAAgB,CAAC,UAAU,EAAE,WAAW,CAAC;IAO5C,GAAG,CAAC,WAAW,SAAS,OAAO,EAC7B,UAAU,EAAE,gBAAgB,CAAC,eAAe,EAAE,WAAW,CAAC,GACzD,6BAA6B,CAC9B,UAAU,EACV,aAAa,EACb,eAAe,GAAG,WAAW,EAC7B,cAAc,EACd,iBAAiB,CAClB;IAOD,KAAK,CAAC,MAAM,SAAS,kBAAkB,GAAG,gBAAgB,EACxD,SAAS,EAAE,MAAM,GAChB,6BAA6B,CAC9B,UAAU,EACV,aAAa,EACb,eAAe,EACf,MAAM,SAAS,mBAAmB,GAAG,MAAM,GAAG,mBAAmB,EACjE,iBAAiB,CAClB;IAOD,OAAO,CAAC,QAAQ,SAAS,gBAAgB,EACvC,SAAS,EAAE,QAAQ,GAClB,6BAA6B,CAC9B,UAAU,EACV,aAAa,EACb,eAAe,EACf,cAAc,EACd,QAAQ,SAAS,sBAAsB,GAAG,QAAQ,GAAG,sBAAsB,CAC5E;IAOD,OAAO,CACL,OAAO,SAAS,qBAAqB,CACnC,iBAAiB,EACjB,GAAG,CACJ,GAAG,qBAAqB,CAAC,iBAAiB,EAAE,GAAG,CAAC,EACjD,UAAU,SAAS,CACjB,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,YAAY,CAAC,cAAc,CAAC,KAChC,OAAO,CAAC,OAAO,CAAC,GAAG,CACtB,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,YAAY,CAAC,cAAc,CAAC,KAChC,OAAO,CAAC,OAAO,CAAC,EAErB,SAAS,EAAE,UAAU,GACnB,CAAC,CACC,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,YAAY,CAAC,cAAc,CAAC,KAChC,OAAO,CAAC,OAAO,CAAC,CAAC,GACvB,wBAAwB,CACzB,UAAU,EACV,aAAa,EACb,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,qBAAqB,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAClD,GACC,UAAU,GACV,eAAe,CACb,eAAe,EACf,cAAc,EACd,qBAAqB,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAClD;CAwCJ"}

package/dist/ConvexBuilderWithFunctionKind.js.map

@@ -1 +1 @@
-{"version":3,"file":"ConvexBuilderWithFunctionKind.js","sourceRoot":"","sources":["../src/ConvexBuilderWithFunctionKind.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAYtE,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,UAAU,CAAC;AAEnD,MAAM,OAAO,6BAA6B;IAO9B,GAAG,CAIX;IAEF,YACE,GAAuE;QAEvE,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACO,MAAM,CAAC,GAAoC;QACnD,OAAO,IAAI,6BAA6B,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IAID,MAAM,CACJ,OAAwE;QAExE,OAAO,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,QAAQ;QAKN,OAAO;YACL,gBAAgB,CACd,UAA4C;gBAE5C,OAAO,UAAU,CAAC;YACpB,CAAC;SACF,CAAC;IACJ,CAAC;IAYD,gBAAgB,CACd,UAAqD;QAErD,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,GAAG,CACD,UAA0D;QAQ1D,OAAO,IAAI,CAAC,MAAM,CAAC;YACjB,GAAG,IAAI,CAAC,GAAG;YACX,WAAW,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,UAAiC,CAAC;SAC1E,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CACH,SAAiB;QAQjB,OAAO,IAAI,CAAC,MAAM,CAAC;YACjB,GAAG,IAAI,CAAC,GAAG;YACX,aAAa,EAAE,SAAS;SACzB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CACL,SAAmB;QAQnB,OAAO,IAAI,CAAC,MAAM,CAAC;YACjB,GAAG,IAAI,CAAC,GAAG;YACX,gBAAgB,EAAE,SAAS;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CAML,SAGqB;QAcrB,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,0EAA0E,CAC3E,CAAC;QACJ,CAAC;QAED,4EAA4E;QAC5E,mFAAmF;QACnF,oFAAoF;QACpF,MAAM,UAAU,GAAG,KAAK,EACtB,cAAuB,EACvB,QAAsC,EACtC,EAAE;YACF,OAAO,SAAS,CAAC,cAAiC,EAAE,QAAQ,CAAC,CAAC;QAChE,CAAC,CAAC;QAIF,OAAO,IAAI,wBAAwB,CAOjC;YACA,GAAG,IAAI,CAAC,GAAG;YACX,OAAO,EAAE,UAAiB;SAC3B,CAQiE,CAAC;IACrE,CAAC;CACF"}
+{"version":3,"file":"ConvexBuilderWithFunctionKind.js","sourceRoot":"","sources":["../src/ConvexBuilderWithFunctionKind.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAYtE,OAAO,EAAE,MAAM,IAAI,aAAa,EAAE,MAAM,UAAU,CAAC;AAEnD,MAAM,OAAO,6BAA6B;IAO9B,GAAG,CAIX;IAEF,YACE,GAAuE;QAEvE,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACO,MAAM,CAAC,GAAoC;QACnD,OAAO,IAAI,6BAA6B,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;IAID,MAAM,CACJ,OAAwE;QAExE,OAAO,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,QAAQ;QAKN,OAAO;YACL,gBAAgB,CACd,UAA4C;gBAE5C,OAAO,UAAU,CAAC;YACpB,CAAC;SACF,CAAC;IACJ,CAAC;IAYD,gBAAgB,CACd,UAAqD;QAErD,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,GAAG,CACD,UAA0D;QAQ1D,OAAO,IAAI,CAAC,MAAM,CAAC;YACjB,GAAG,IAAI,CAAC,GAAG;YACX,WAAW,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,UAAiC,CAAC;SAC1E,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CACH,SAAiB;QAQjB,OAAO,IAAI,CAAC,MAAM,CAAC;YACjB,GAAG,IAAI,CAAC,GAAG;YACX,aAAa,EAAE,SAAS;SACzB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CACL,SAAmB;QAQnB,OAAO,IAAI,CAAC,MAAM,CAAC;YACjB,GAAG,IAAI,CAAC,GAAG;YACX,gBAAgB,EAAE,SAAS;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,OAAO,CAaL,SAIwB;QAexB,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,0EAA0E,CAC3E,CAAC;QACJ,CAAC;QAED,4EAA4E;QAC5E,mFAAmF;QACnF,oFAAoF;QACpF,MAAM,UAAU,GAAG,KAAK,EACtB,cAAuB,EACvB,QAAsC,EACtC,EAAE;YACF,OAAO,SAAS,CAAC,cAAiC,EAAE,QAAQ,CAAC,CAAC;QAChE,CAAC,CAAC;QAIF,OAAO,IAAI,wBAAwB,CAOjC;YACA,GAAG,IAAI,CAAC,GAAG;YACX,OAAO,EAAE,UAAiB;SAC3B,CASiE,CAAC;IACrE,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluent-convex",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "A fluent API builder for Convex functions with middleware support, inspired by oRPC",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,6 +44,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://friendly-zebra-716.convex.site/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mikecann/fluent-convex.git"

package/src/ConvexBuilderWithFunctionKind.ts

@@ -130,11 +130,19 @@ export class ConvexBuilderWithFunctionKind<
       TReturnsValidator,
       any
     > = InferredHandlerReturn<TReturnsValidator, any>,
-  >(
-    handlerFn: (
+    THandlerFn extends (
+      context: TCurrentContext,
+      input: InferredArgs<TArgsValidator>
+    ) => Promise<TReturn> = (
       context: TCurrentContext,
       input: InferredArgs<TArgsValidator>
-    ) => Promise<TReturn>
+    ) => Promise<TReturn>,
+  >(
+    handlerFn: THandlerFn &
+      ((
+        context: TCurrentContext,
+        input: InferredArgs<TArgsValidator>
+      ) => Promise<TReturn>)
   ): ConvexBuilderWithHandler<
     TDataModel,
     TFunctionType,
@@ -143,6 +151,7 @@ export class ConvexBuilderWithFunctionKind<
     TReturnsValidator,
     InferredHandlerReturn<TReturnsValidator, TReturn>
   > &
+    THandlerFn &
     CallableBuilder<
       TCurrentContext,
       TArgsValidator,
@@ -184,6 +193,7 @@ export class ConvexBuilderWithFunctionKind<
       TReturnsValidator,
       InferredReturn
     > &
+      THandlerFn &
       CallableBuilder<TCurrentContext, TArgsValidator, InferredReturn>;
   }
 }

package/src/builder-core.test-d.ts

@@ -443,6 +443,23 @@ describe("Builder Core", () => {
       >(callableQuery);
     });
 
+    it("should infer one-arg handlers with empty input objects", () => {
+      const callableQuery = convex
+        .query()
+        .input({})
+        .handler(async (context) => {
+          assertType(context.db);
+          return { success: Boolean(context.db) };
+        });
+
+      assertType<
+        (
+          context: any,
+          args: Record<never, never>
+        ) => Promise<{ success: boolean }>
+      >(callableQuery);
+    });
+
     it("should lose callability after .public()", () => {
       const callableQuery = convex
         .query()