convex-verify 1.0.5 → 1.2.2

package/README.md

@@ -2,13 +2,14 @@
 
 Type-safe verification and validation for Convex database operations.
 
+
 ## Features
 
 - **Type-safe insert/patch** - Full TypeScript inference for your schema
 - **Default values** - Make fields optional in `insert()` with automatic defaults
 - **Protected columns** - Prevent accidental updates to critical fields in `patch()`
-- **Validation plugins** - Unique row/column enforcement, custom validators
-- **Extensible** - Create your own validation plugins
+- **Unique constraints** - Enforce unique rows and columns using your indexes
+- **Extensible** - Create your own validation extensions
 
 ## Installation
 
@@ -18,48 +19,35 @@ pnpm install convex-verify
 
 **Peer Dependencies:**
 
-- `convex` >= 1.31.3
+- `convex` >= 1.34.1
 
 ## Quick Start
 
 ```ts
-import {
-	defaultValuesConfig,
-	protectedColumnsConfig,
-	uniqueColumnConfig,
-	uniqueRowConfig,
-	verifyConfig,
-} from "convex-verify";
+import { verifyConfig } from "convex-verify";
 
 import schema from "./schema";
 
-export const { insert, patch, dangerouslyPatch } = verifyConfig(schema, {
-	// Make fields optional with defaults
-	defaultValues: defaultValuesConfig(schema, () => ({
+export const { insert, patch, dangerouslyPatch, verify, config } = verifyConfig(schema, {
+	defaultValues: {
 		posts: { status: "draft", views: 0 },
-	})),
+	},
 
-	// Prevent patching critical fields
-	protectedColumns: protectedColumnsConfig(schema, {
+	protectedColumns: {
 		posts: ["authorId"],
-	}),
+	},
 
-	// Enforce unique row combinations
-	uniqueRow: uniqueRowConfig(schema, {
+	uniqueRow: {
 		posts: ["by_author_slug"],
-	}),
+	},
 
-	// Enforce unique column values
-	uniqueColumn: uniqueColumnConfig(schema, {
+	uniqueColumn: {
 		users: ["by_email", "by_username"],
-	}),
-
-	// Custom/third-party plugins (optional)
-	plugins: [],
+	},
 });
 ```
 
-Then use in your mutations:
+Use the returned helpers in mutations:
 
 ```ts
 import { insert, patch } from "./verify";
@@ -67,7 +55,7 @@ import { insert, patch } from "./verify";
 export const createPost = mutation({
 	args: { title: v.string(), content: v.string() },
 	handler: async (ctx, args) => {
-		// status and views are optional - defaults are applied
+		// status and views are optional since defaults have been set
 		return await insert(ctx, "posts", {
 			title: args.title,
 			content: args.content,
@@ -82,337 +70,385 @@ export const updatePost = mutation({
 		// authorId is protected - TypeScript won't allow it here
 		await patch(ctx, "posts", args.id, {
 			title: args.title,
+			// authorId: "someone_else", // TypeScript error!
 		});
 	},
 });
 ```
 
+And use the returned verifier surface directly when you need schema-aware built-in checks outside the insert/patch helpers:
+
+```ts
+await verify.uniqueRow(ctx, "posts", {
+	title: "Hello",
+	slug: "hello",
+	authorId: "author-1",
+});
+
+config.uniqueRow.posts; // typed configured options
+```
+
 ---
 
 ## API Reference
 
 ### `verifyConfig(schema, config)`
 
-Main configuration function that returns typed `insert`, `patch`, and `dangerouslyPatch` functions.
+Main configuration function. It accepts inline schema-aware config and returns typed mutation helpers plus a direct `verify` registry.
 
 ```ts
-const { insert, patch, dangerouslyPatch, configs } = verifyConfig(schema, {
-  // Type-affecting configs
-  defaultValues?: DefaultValuesConfig,
-  protectedColumns?: ProtectedColumnsConfig,
-
-  // Built-in validation configs
-  uniqueRow?: UniqueRowConfig,
-  uniqueColumn?: UniqueColumnConfig,
-
-  // Custom/third-party plugins
-  plugins?: ValidatePlugin[],
+const { insert, patch, dangerouslyPatch, verify, config } = verifyConfig(schema, {
+  defaultValues?: {
+    posts?: { status?: "draft"; views?: number };
+  } | (() => { ... } | Promise<{ ... }>),
+  protectedColumns?: {
+    posts?: ["authorId"];
+  },
+  uniqueRow?: {
+    posts?: ["by_author_slug"];
+  },
+  uniqueColumn?: {
+    users?: ["by_email", "by_username"];
+  },
+  extensions?: Extension[],
 });
 ```
 
 #### Returns
 
-| Function           | Description                                                                         |
+| Function/Value     | Description                                                                         |
 | ------------------ | ----------------------------------------------------------------------------------- |
-| `insert`           | Insert with default values applied and validation plugins run                       |
-| `patch`            | Patch with protected columns removed from type and validation plugins run           |
+| `insert`           | Insert with default values applied and extensions run                               |
+| `patch`            | Patch with protected columns removed and extensions run                             |
 | `dangerouslyPatch` | Patch with full access to all columns (bypasses protected columns type restriction) |
-| `configs`          | The original config object (for debugging)                                          |
+| `verify`           | Built-in verifier functions for configured features only                            |
+| `config`           | Passive typed snapshot of the built-in config that was passed in                    |
 
 ---
 
-## Transforms
-
-Transforms modify the input type of `insert()`.
+## `defaultValues`
 
-### `defaultValuesConfig(schema, config)`
+Makes specified fields optional in `insert()` by providing default values. The types update automatically.
 
-Makes specified fields optional in `insert()` by providing default values.
+### Static Values
 
 ```ts
-import { defaultValuesConfig } from "convex-verify";
-// or
-import { defaultValuesConfig } from "convex-verify/transforms";
-```
-
-#### Static Config
-
-```ts
-const defaults = defaultValuesConfig(schema, {
+const { insert } = verifyConfig(schema, {
+	defaultValues: {
 	posts: { status: "draft", views: 0 },
 	comments: { likes: 0 },
+	},
 });
 ```
 
-#### Dynamic Config (Fresh Values)
+### Dynamic Values
 
-Use a function for values that should be generated fresh on each insert:
+Use a function when values should be generated fresh on each insert:
 
 ```ts
-const defaults = defaultValuesConfig(schema, () => ({
-	posts: {
-		status: "draft",
-		slug: generateRandomSlug(),
-		createdAt: Date.now(),
-	},
-}));
+const { insert } = verifyConfig(schema, {
+	defaultValues: () => ({
+		posts: {
+			status: "draft",
+			slug: generateRandomSlug(),
+			createdAt: Date.now(),
+		},
+	}),
+});
 ```
 
-#### Async Config
+### Async Values
 
 ```ts
-const defaults = defaultValuesConfig(schema, async () => ({
-	posts: {
-		category: await fetchDefaultCategory(),
-	},
-}));
+const { insert } = verifyConfig(schema, {
+	defaultValues: async () => ({
+		posts: {
+			category: await fetchDefaultCategory(),
+		},
+	}),
+});
 ```
 
----
+### Direct Verifier Calls
 
-## Configs
+```ts
+const { verify } = verifyConfig(schema, {
+	defaultValues: {
+		users: { status: "pending" },
+	},
+});
 
-Configs modify the input type of `patch()`.
+const user = await verify.defaultValues("users", {
+	email: "alice@example.com",
+	username: "alice",
+});
+```
 
-### `protectedColumnsConfig(schema, config)`
+---
 
-Removes specified columns from the `patch()` input type, preventing accidental updates.
+## `protectedColumns`
 
-```ts
-import { protectedColumnsConfig } from "convex-verify";
-// or
-import { protectedColumnsConfig } from "convex-verify/configs";
-```
+Removes specified columns from the `patch()` input type, preventing accidental updates to critical fields like `authorId` or `createdAt`.
 
-#### Example
+### Usage
 
 ```ts
-const protected = protectedColumnsConfig(schema, {
-	posts: ["authorId", "createdAt"],
-	comments: ["postId", "authorId"],
+const { patch, dangerouslyPatch } = verifyConfig(schema, {
+	protectedColumns: {
+		posts: ["authorId", "createdAt"],
+		comments: ["postId", "authorId"],
+	},
 });
 ```
 
-#### Bypassing Protection
+### Bypassing Protection
 
-Use `dangerouslyPatch()` when you need to update protected columns:
+Use `dangerouslyPatch()` when you legitimately need to update protected columns:
 
 ```ts
 // Regular patch - authorId not allowed
 await patch(ctx, "posts", id, {
-	authorId: newAuthorId, // ❌ TypeScript error
-	title: "New Title", // ✅ OK
+	authorId: newAuthorId, // TypeScript error!
+	title: "New Title", // OK
 });
 
 // Dangerous patch - full access
 await dangerouslyPatch(ctx, "posts", id, {
-	authorId: newAuthorId, // ✅ OK (bypasses protection)
+	authorId: newAuthorId, // OK (bypasses type restriction)
 	title: "New Title",
 });
 ```
 
-**Note:** `dangerouslyPatch()` still runs validation plugins - only the type restriction is bypassed.
+**Note:** `dangerouslyPatch()` still runs validation extensions - only the type restriction is bypassed.
 
 ---
 
-## Validation
+## `uniqueRow`
 
-Validation configs check data during `insert()` and `patch()` operations. They run after transforms and can throw errors to prevent the operation.
+Enforces uniqueness across multiple columns using composite indexes. Useful for things like "unique slug per author" or "unique name per organization".
 
-### `uniqueRowConfig(schema, config)`
-
-Enforces uniqueness across multiple columns using composite indexes.
+### Usage
 
 ```ts
-import { uniqueRowConfig } from "convex-verify";
-// or
-import { uniqueRowConfig } from "convex-verify/plugins";
-```
-
-#### Usage
-
-```ts
-// As a named config key (recommended)
-verifyConfig(schema, {
-	uniqueRow: uniqueRowConfig(schema, {
-		posts: ["by_author_slug"],
-	}),
-});
-
-// Or in the plugins array
-verifyConfig(schema, {
-	plugins: [
-		uniqueRowConfig(schema, {
-			posts: ["by_author_slug"],
-		}),
-	],
+const { verify } = verifyConfig(schema, {
+	uniqueRow: {
+		posts: ["by_author_slug"], // Unique author + slug combination
+		projects: ["by_org_name"], // Unique org + name combination
+	},
 });
 ```
 
-#### Shorthand (Index Names)
+### With Options
 
 ```ts
-const uniqueRows = uniqueRowConfig(schema, {
-	posts: ["by_author_slug"], // Unique author + slug combo
-	projects: ["by_org_slug"], // Unique org + slug combo
+const { verify } = verifyConfig(schema, {
+	uniqueRow: {
+		posts: [
+			{
+				index: "by_author_slug",
+				identifiers: ["_id", "authorId"], // Fields that identify "same document"
+			},
+		],
+	},
 });
 ```
 
-#### With Options
-
-```ts
-const uniqueRows = uniqueRowConfig(schema, {
-	posts: [
-		{
-			index: "by_author_slug",
-			identifiers: ["_id", "authorId"], // Fields to check for "same document"
-		},
-	],
-});
-```
+The `identifiers` option controls which fields are checked when determining if a conflicting row is actually the same document (useful during patch operations).
 
-### `uniqueColumnConfig(schema, config)`
+---
 
-Enforces uniqueness on single columns using indexes.
+## `uniqueColumn`
 
-```ts
-import { uniqueColumnConfig } from "convex-verify";
-// or
-import { uniqueColumnConfig } from "convex-verify/plugins";
-```
+Enforces uniqueness on single columns using indexes. Useful for email addresses, usernames, slugs, etc.
 
-#### Usage
+### Usage
 
 ```ts
-// As a named config key (recommended)
-verifyConfig(schema, {
-	uniqueColumn: uniqueColumnConfig(schema, {
+const { verify } = verifyConfig(schema, {
+	uniqueColumn: {
 		users: ["by_email", "by_username"],
-	}),
-});
-
-// Or in the plugins array
-verifyConfig(schema, {
-	plugins: [
-		uniqueColumnConfig(schema, {
-			users: ["by_email", "by_username"],
-		}),
-	],
+		organizations: ["by_slug"],
+	},
 });
 ```
 
-The column name is derived from the index name by removing `by_` prefix:
+The column name is derived from the index name by removing the `by_` prefix:
 
 - `by_username` → checks `username` column
 - `by_email` → checks `email` column
 
-#### Shorthand (Index Names)
+### With Options
 
 ```ts
-const uniqueColumns = uniqueColumnConfig(schema, {
-	users: ["by_username", "by_email"],
-	organizations: ["by_slug"],
+const { verify } = verifyConfig(schema, {
+	uniqueColumn: {
+		users: [
+			"by_username",
+			{ index: "by_email", identifiers: ["_id", "clerkId"] },
+		],
+	},
 });
 ```
 
-#### With Options
+### Direct Verifier Calls
 
 ```ts
-const uniqueColumns = uniqueColumnConfig(schema, {
-	users: [
-		"by_username", // shorthand
-		{ index: "by_email", identifiers: ["_id", "clerkId"] }, // with options
-	],
+await verify.uniqueColumn(ctx, "users", {
+	email: "alice@example.com",
 });
 ```
 
-## Custom Plugins
+Patch checks use the document id:
 
-The `plugins` array accepts custom validation plugins for extensibility.
+```ts
+await verify.uniqueColumn(ctx, "users", userId, {
+	username: "alice",
+});
+```
 
-### `createValidatePlugin(name, config, handlers)`
+Direct uniqueness verifier calls may use partial data. Only configured unique fields present in the payload are checked.
 
-Create custom validation plugins.
+### Breaking Change
 
-```ts
-import { createValidatePlugin } from "convex-verify";
-// or
-import { createValidatePlugin } from "convex-verify/core";
-```
+Version `2.0.0` removes the old helper-wrapper API:
 
-#### Example: Required Fields Plugin
+- `defaultValuesConfig`
+- `protectedColumnsConfig`
+- `uniqueRowConfig`
+- `uniqueColumnConfig`
 
-```ts
-const requiredFields = createValidatePlugin(
-	"requiredFields",
-	{ fields: ["title", "content"] },
-	{
-		insert: (context, data) => {
-			for (const field of context.config.fields) {
-				if (!data[field]) {
-					throw new ConvexError({
-						message: `Missing required field: ${field}`,
-					});
-				}
-			}
-			return data;
-		},
-	},
-);
-```
+---
+
+## Custom Extensions
+
+Custom extensions let you add your own validation and transformation logic that runs during `insert()` and `patch()` operations.
+
+### Use Cases
+
+- **Authorization checks** - Verify the user has permission to create/modify a document
+- **Data validation** - Check that values meet business rules (e.g., positive numbers, valid URLs)
+- **Cross-field validation** - Ensure fields are consistent with each other
+- **Normalization / sanitization** - Lowercase emails, trim slugs, clean incoming strings
+- **External validation** - Check against external APIs or services
+- **Audit logging** - Log operations before they complete
 
-#### Example: Async Validation
+### Limitations
+
+- Extensions run **after** type-affecting configs (like `defaultValues`) have been applied
+- Extensions **cannot modify types** - they can change runtime data, but not the TypeScript types
+- Extensions may **return modified data** - use this to sanitize, normalize, or enrich payloads
+- Custom extensions from `extensions: []` run **before** built-in `uniqueRow` / `uniqueColumn` configs
+- `patch()` still strips protected columns at runtime; use `dangerouslyPatch()` if an extension must change them
+- Extension errors should use `ConvexError` for proper error handling on the client
+
+### Execution Order
+
+Custom extensions always run before built-in uniqueness checks.
+
+- `insert()`: `defaultValues` → custom `extensions` → `uniqueRow` → `uniqueColumn`
+- `patch()`: protected-column strip → custom `extensions` → `uniqueRow` → `uniqueColumn` → protected-column strip again
+- `dangerouslyPatch()`: custom `extensions` → `uniqueRow` → `uniqueColumn`
+
+`defaultValues` and protected-column stripping are preprocessing steps, not entries in the custom `extensions` array.
+
+### Creating an Extension
+
+Use `createExtension`. For schema-aware typing in the callback, pass the schema as the first argument:
 
 ```ts
-const checkOwnership = createValidatePlugin(
-	"checkOwnership",
-	{},
-	{
-		patch: async (context, data) => {
-			const existing = await context.ctx.db.get(context.patchId);
-			const user = await getCurrentUser(context.ctx);
-
-			if (existing?.authorId !== user._id) {
-				throw new ConvexError({
-					message: "Not authorized to edit this document",
-				});
-			}
-			return data;
-		},
-	},
-);
+import { createExtension } from "convex-verify";
+import { ConvexError } from "convex/values";
+
+const normalizeEmail = createExtension(schema, (input) => {
+	if (input.tableName !== "users") {
+		return input.data;
+	}
+
+	if (input.operation === "insert") {
+		return {
+			...input.data,
+			email: input.data.email.toLowerCase().trim(),
+		};
+	}
+
+	return {
+		...input.data,
+		...(input.data.email !== undefined && {
+			email: input.data.email.toLowerCase().trim(),
+		}),
+	};
+});
 ```
 
-#### Plugin Context
+Use a single `input` parameter instead of destructuring when you want narrowing.
+That lets TypeScript narrow `data` from both `tableName` and `operation`.
 
-Plugins receive a `ValidateContext` object:
+### Extension Context
+
+Your extension function receives:
 
 ```ts
-type ValidateContext = {
-	ctx: GenericMutationCtx; // Convex mutation context
+type ExtensionInput = {
+	ctx: GenericMutationCtx; // Convex mutation context (has ctx.db, etc.)
 	tableName: string; // Table being operated on
 	operation: "insert" | "patch";
 	patchId?: GenericId; // Document ID (patch only)
-	onFail?: OnFailCallback; // Callback for failure details
-	schema?: SchemaDefinition; // Schema reference
+	schema: SchemaDefinition; // Schema reference
+	data: unknown;
 };
 ```
 
----
+### Example: Required Fields
 
-## Subpath Imports
+```ts
+const requiredFields = createExtension<typeof schema>((input) => {
+	if (input.tableName !== "posts" || input.operation === "patch") {
+		return input.data;
+	}
+
+	for (const field of ["title", "content"]) {
+		if (!input.data[field]) {
+			throw new ConvexError({
+				code: "VALIDATION_ERROR",
+				message: `Missing required field: ${field}`,
+			});
+		}
+	}
+
+	return input.data;
+});
+```
 
-For smaller bundle sizes, you can import from specific subpaths:
+### Example: Async Authorization Check
 
 ```ts
-// Import everything from root
-import { uniqueRowConfig, verifyConfig } from "convex-verify";
-import { protectedColumnsConfig } from "convex-verify/configs";
-// Or import from specific subpaths
-import { createValidatePlugin, verifyConfig } from "convex-verify/core";
-import { uniqueColumnConfig, uniqueRowConfig } from "convex-verify/plugins";
-import { defaultValuesConfig } from "convex-verify/transforms";
-import { getTableIndexes } from "convex-verify/utils";
+const ownership = createExtension<typeof schema>(async (input) => {
+	if (input.tableName !== "posts" || input.operation !== "patch") {
+		return input.data;
+	}
+
+	const doc = await input.ctx.db.get(input.patchId);
+	const identity = await input.ctx.auth.getUserIdentity();
+
+	if (doc?.ownerId !== identity?.subject) {
+		throw new ConvexError({
+			code: "UNAUTHORIZED",
+			message: "You don't have permission to edit this document",
+		});
+	}
+
+	return input.data;
+});
+```
+
+### Using Custom Extensions
+
+Add extensions to the `extensions` array in your config:
+
+```ts
+const { insert, patch } = verifyConfig(schema, {
+	extensions: [requiredFields, ownership],
+});
 ```
 
 ---
@@ -421,7 +457,7 @@ import { getTableIndexes } from "convex-verify/utils";
 
 ### `onFail` Callback
 
-All operations accept an optional `onFail` callback for handling validation failures:
+Operations accept an optional `onFail` callback for handling validation failures:
 
 ```ts
 await insert(ctx, "posts", data, {
@@ -438,7 +474,7 @@ await insert(ctx, "posts", data, {
 
 ### Error Types
 
-Validation plugins throw `ConvexError` with specific codes:
+Built-in validation extensions throw `ConvexError` with these codes:
 
 - `UNIQUE_ROW_VERIFICATION_ERROR` - Duplicate row detected
 - `UNIQUE_COLUMN_VERIFICATION_ERROR` - Duplicate column value detected
@@ -447,11 +483,11 @@ Validation plugins throw `ConvexError` with specific codes:
 
 ## TypeScript
 
-This library is written in TypeScript and provides full type inference:
+This library provides full type inference:
 
 - `insert()` types reflect optional fields from `defaultValues`
 - `patch()` types exclude protected columns
-- Plugin configs are type-checked against your schema
+- All configs are type-checked against your schema
 - Index names are validated against your schema's indexes
 
 ---