convex-verify 1.0.5 → 1.1.0

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,7 +19,7 @@ pnpm install convex-verify
 
 **Peer Dependencies:**
 
-- `convex` >= 1.31.3
+- `convex` >= 1.34.1
 
 ## Quick Start
 
@@ -34,28 +35,21 @@ import {
 import schema from "./schema";
 
 export const { insert, patch, dangerouslyPatch } = verifyConfig(schema, {
-	// Make fields optional with defaults
-	defaultValues: defaultValuesConfig(schema, () => ({
+	defaultValues: defaultValuesConfig(schema, {
 		posts: { status: "draft", views: 0 },
-	})),
+	}),
 
-	// Prevent patching critical fields
 	protectedColumns: protectedColumnsConfig(schema, {
 		posts: ["authorId"],
 	}),
 
-	// Enforce unique row combinations
 	uniqueRow: uniqueRowConfig(schema, {
 		posts: ["by_author_slug"],
 	}),
 
-	// Enforce unique column values
 	uniqueColumn: uniqueColumnConfig(schema, {
 		users: ["by_email", "by_username"],
 	}),
-
-	// Custom/third-party plugins (optional)
-	plugins: [],
 });
 ```
 
@@ -67,7 +61,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,6 +76,7 @@ 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!
 		});
 	},
 });
@@ -96,17 +91,12 @@ export const updatePost = mutation({
 Main configuration function that returns typed `insert`, `patch`, and `dangerouslyPatch` functions.
 
 ```ts
-const { insert, patch, dangerouslyPatch, configs } = verifyConfig(schema, {
-  // Type-affecting configs
+const { insert, patch, dangerouslyPatch } = verifyConfig(schema, {
   defaultValues?: DefaultValuesConfig,
   protectedColumns?: ProtectedColumnsConfig,
-
-  // Built-in validation configs
   uniqueRow?: UniqueRowConfig,
   uniqueColumn?: UniqueColumnConfig,
-
-  // Custom/third-party plugins
-  plugins?: ValidatePlugin[],
+  extensions?: Extension[],
 });
 ```
 
@@ -114,42 +104,35 @@ const { insert, patch, dangerouslyPatch, configs } = verifyConfig(schema, {
 
 | Function           | 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)                                          |
 
 ---
 
-## Transforms
+## `defaultValuesConfig`
 
-Transforms modify the input type of `insert()`.
-
-### `defaultValuesConfig(schema, config)`
-
-Makes specified fields optional in `insert()` by providing default values.
+Makes specified fields optional in `insert()` by providing default values. The types update automatically - fields with defaults become optional.
 
 ```ts
 import { defaultValuesConfig } from "convex-verify";
-// or
-import { defaultValuesConfig } from "convex-verify/transforms";
 ```
 
-#### Static Config
+### Static Values
 
 ```ts
-const defaults = defaultValuesConfig(schema, {
+const config = defaultValuesConfig(schema, {
 	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, () => ({
+const config = defaultValuesConfig(schema, () => ({
 	posts: {
 		status: "draft",
 		slug: generateRandomSlug(),
@@ -158,10 +141,10 @@ const defaults = defaultValuesConfig(schema, () => ({
 }));
 ```
 
-#### Async Config
+### Async Values
 
 ```ts
-const defaults = defaultValuesConfig(schema, async () => ({
+const config = defaultValuesConfig(schema, async () => ({
 	posts: {
 		category: await fetchDefaultCategory(),
 	},
@@ -170,249 +153,234 @@ const defaults = defaultValuesConfig(schema, async () => ({
 
 ---
 
-## Configs
-
-Configs modify the input type of `patch()`.
-
-### `protectedColumnsConfig(schema, config)`
+## `protectedColumnsConfig`
 
-Removes specified columns from the `patch()` input type, preventing accidental updates.
+Removes specified columns from the `patch()` input type, preventing accidental updates to critical fields like `authorId` or `createdAt`.
 
 ```ts
 import { protectedColumnsConfig } from "convex-verify";
-// or
-import { protectedColumnsConfig } from "convex-verify/configs";
 ```
 
-#### Example
+### Usage
 
 ```ts
-const protected = protectedColumnsConfig(schema, {
+const config = protectedColumnsConfig(schema, {
 	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
+## `uniqueRowConfig`
 
-Validation configs check data during `insert()` and `patch()` operations. They run after transforms and can throw errors to prevent the operation.
-
-### `uniqueRowConfig(schema, config)`
-
-Enforces uniqueness across multiple columns using composite indexes.
+Enforces uniqueness across multiple columns using composite indexes. Useful for things like "unique slug per author" or "unique name per organization".
 
 ```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"],
-		}),
-	],
-});
 ```
 
-#### Shorthand (Index Names)
+### Usage
 
 ```ts
-const uniqueRows = uniqueRowConfig(schema, {
-	posts: ["by_author_slug"], // Unique author + slug combo
-	projects: ["by_org_slug"], // Unique org + slug combo
+const config = uniqueRowConfig(schema, {
+	posts: ["by_author_slug"], // Unique author + slug combination
+	projects: ["by_org_name"], // Unique org + name combination
 });
 ```
 
-#### With Options
+### With Options
 
 ```ts
-const uniqueRows = uniqueRowConfig(schema, {
+const config = uniqueRowConfig(schema, {
 	posts: [
 		{
 			index: "by_author_slug",
-			identifiers: ["_id", "authorId"], // Fields to check for "same document"
+			identifiers: ["_id", "authorId"], // Fields that identify "same document"
 		},
 	],
 });
 ```
 
-### `uniqueColumnConfig(schema, config)`
+The `identifiers` option controls which fields are checked when determining if a conflicting row is actually the same document (useful during patch operations).
+
+---
+
+## `uniqueColumnConfig`
 
-Enforces uniqueness on single columns using indexes.
+Enforces uniqueness on single columns using indexes. Useful for email addresses, usernames, slugs, etc.
 
 ```ts
 import { uniqueColumnConfig } from "convex-verify";
-// or
-import { uniqueColumnConfig } from "convex-verify/plugins";
 ```
 
-#### Usage
+### Usage
 
 ```ts
-// As a named config key (recommended)
-verifyConfig(schema, {
-	uniqueColumn: uniqueColumnConfig(schema, {
-		users: ["by_email", "by_username"],
-	}),
-});
-
-// Or in the plugins array
-verifyConfig(schema, {
-	plugins: [
-		uniqueColumnConfig(schema, {
-			users: ["by_email", "by_username"],
-		}),
-	],
+const config = 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"],
-});
-```
-
-#### With Options
-
-```ts
-const uniqueColumns = uniqueColumnConfig(schema, {
+const config = uniqueColumnConfig(schema, {
 	users: [
-		"by_username", // shorthand
-		{ index: "by_email", identifiers: ["_id", "clerkId"] }, // with options
+		"by_username",
+		{ index: "by_email", identifiers: ["_id", "clerkId"] },
 	],
 });
 ```
 
-## Custom Plugins
+---
 
-The `plugins` array accepts custom validation plugins for extensibility.
+## Custom Extensions
 
-### `createValidatePlugin(name, config, handlers)`
+Custom extensions let you add your own validation and transformation logic that runs during `insert()` and `patch()` operations.
 
-Create custom validation plugins.
+### Use Cases
 
-```ts
-import { createValidatePlugin } from "convex-verify";
-// or
-import { createValidatePlugin } from "convex-verify/core";
-```
+- **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: Required Fields Plugin
+### Limitations
 
-```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;
-		},
-	},
-);
-```
+- 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
 
-#### Example: Async Validation
+### Creating an Extension
+
+Use `createExtension`. If you want schema-aware typing in the callback, pass your schema type as the generic:
 
 ```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<typeof 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`.
+
+### Extension Context
 
-Plugins receive a `ValidateContext` object:
+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}`,
+			});
+		}
+	}
 
-For smaller bundle sizes, you can import from specific subpaths:
+	return input.data;
+});
+```
+
+### 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 +389,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 +406,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 +415,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
 
 ---

package/dist/configs/index.d.mts

@@ -1,5 +1,5 @@
 import { SchemaDefinition, GenericSchema, DataModelFromSchemaDefinition, WithoutSystemFields } from 'convex/server';
-import { k as DMGeneric } from '../types-_64SXyva.mjs';
+import { k as DMGeneric } from '../types-DvJMYubf.mjs';
 
 /**
  * Config data type for protected columns.

package/dist/configs/index.d.ts

@@ -1,5 +1,5 @@
 import { SchemaDefinition, GenericSchema, DataModelFromSchemaDefinition, WithoutSystemFields } from 'convex/server';
-import { k as DMGeneric } from '../types-_64SXyva.js';
+import { k as DMGeneric } from '../types-DvJMYubf.js';
 
 /**
  * Config data type for protected columns.