convex-verify 0.1.0 → 0.1.1

package/README.md

@@ -13,12 +13,12 @@ Type-safe verification and validation for Convex database operations.
 ## Installation
 
 ```bash
-npm install convex-verify
+pnpm install convex-verify
 ```
 
 **Peer Dependencies:**
 
-- `convex` >= 1.17.4
+- `convex` >= 1.31.3
 
 ## Quick Start
 
@@ -29,43 +29,46 @@ import {
 	uniqueColumnConfig,
 	uniqueRowConfig,
 	verifyConfig,
-} from 'convex-verify';
+} from "convex-verify";
 
-import schema from './schema';
+import schema from "./schema";
 
 export const { insert, patch, dangerouslyPatch } = verifyConfig(schema, {
 	// Make fields optional with defaults
 	defaultValues: defaultValuesConfig(schema, () => ({
-		posts: { status: 'draft', views: 0 },
+		posts: { status: "draft", views: 0 },
 	})),
 
 	// Prevent patching critical fields
 	protectedColumns: protectedColumnsConfig(schema, {
-		posts: ['authorId'],
+		posts: ["authorId"],
 	}),
 
-	// Validation plugins
-	plugins: [
-		uniqueRowConfig(schema, {
-			posts: ['by_author_slug'],
-		}),
-		uniqueColumnConfig(schema, {
-			users: ['by_email', 'by_username'],
-		}),
-	],
+	// 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: [],
 });
 ```
 
 Then use in your mutations:
 
 ```ts
-import { insert, patch } from './verify';
+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
-		return await insert(ctx, 'posts', {
+		return await insert(ctx, "posts", {
 			title: args.title,
 			content: args.content,
 			authorId: ctx.auth.userId,
@@ -74,10 +77,10 @@ export const createPost = mutation({
 });
 
 export const updatePost = mutation({
-	args: { id: v.id('posts'), title: v.string() },
+	args: { id: v.id("posts"), title: v.string() },
 	handler: async (ctx, args) => {
 		// authorId is protected - TypeScript won't allow it here
-		await patch(ctx, 'posts', args.id, {
+		await patch(ctx, "posts", args.id, {
 			title: args.title,
 		});
 	},
@@ -94,8 +97,15 @@ Main configuration function that returns typed `insert`, `patch`, and `dangerous
 
 ```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[],
 });
 ```
@@ -120,16 +130,16 @@ Transforms modify the input type of `insert()`.
 Makes specified fields optional in `insert()` by providing default values.
 
 ```ts
-import { defaultValuesConfig } from 'convex-verify';
+import { defaultValuesConfig } from "convex-verify";
 // or
-import { defaultValuesConfig } from 'convex-verify/transforms';
+import { defaultValuesConfig } from "convex-verify/transforms";
 ```
 
 #### Static Config
 
 ```ts
 const defaults = defaultValuesConfig(schema, {
-	posts: { status: 'draft', views: 0 },
+	posts: { status: "draft", views: 0 },
 	comments: { likes: 0 },
 });
 ```
@@ -141,7 +151,7 @@ Use a function for values that should be generated fresh on each insert:
 ```ts
 const defaults = defaultValuesConfig(schema, () => ({
 	posts: {
-		status: 'draft',
+		status: "draft",
 		slug: generateRandomSlug(),
 		createdAt: Date.now(),
 	},
@@ -169,17 +179,17 @@ Configs modify the input type of `patch()`.
 Removes specified columns from the `patch()` input type, preventing accidental updates.
 
 ```ts
-import { protectedColumnsConfig } from 'convex-verify';
+import { protectedColumnsConfig } from "convex-verify";
 // or
-import { protectedColumnsConfig } from 'convex-verify/configs';
+import { protectedColumnsConfig } from "convex-verify/configs";
 ```
 
 #### Example
 
 ```ts
 const protected = protectedColumnsConfig(schema, {
-	posts: ['authorId', 'createdAt'],
-	comments: ['postId', 'authorId'],
+	posts: ["authorId", "createdAt"],
+	comments: ["postId", "authorId"],
 });
 ```
 
@@ -189,15 +199,15 @@ Use `dangerouslyPatch()` when you need to update protected columns:
 
 ```ts
 // Regular patch - authorId not allowed
-await patch(ctx, 'posts', id, {
+await patch(ctx, "posts", id, {
 	authorId: newAuthorId, // ❌ TypeScript error
-	title: 'New Title', // ✅ OK
+	title: "New Title", // ✅ OK
 });
 
 // Dangerous patch - full access
-await dangerouslyPatch(ctx, 'posts', id, {
+await dangerouslyPatch(ctx, "posts", id, {
 	authorId: newAuthorId, // ✅ OK (bypasses protection)
-	title: 'New Title',
+	title: "New Title",
 });
 ```
 
@@ -205,26 +215,46 @@ await dangerouslyPatch(ctx, 'posts', id, {
 
 ---
 
-## Plugins
+## Validation
 
-Plugins validate data during `insert()` and `patch()` operations. They run after transforms and can throw errors to prevent the operation.
+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.
 
 ```ts
-import { uniqueRowConfig } from 'convex-verify';
+import { uniqueRowConfig } from "convex-verify";
 // or
-import { uniqueRowConfig } from 'convex-verify/plugins';
+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)
 
 ```ts
 const uniqueRows = uniqueRowConfig(schema, {
-	posts: ['by_author_slug'], // Unique author + slug combo
-	projects: ['by_org_slug'], // Unique org + slug combo
+	posts: ["by_author_slug"], // Unique author + slug combo
+	projects: ["by_org_slug"], // Unique org + slug combo
 });
 ```
 
@@ -234,8 +264,8 @@ const uniqueRows = uniqueRowConfig(schema, {
 const uniqueRows = uniqueRowConfig(schema, {
 	posts: [
 		{
-			index: 'by_author_slug',
-			identifiers: ['_id', 'authorId'], // Fields to check for "same document"
+			index: "by_author_slug",
+			identifiers: ["_id", "authorId"], // Fields to check for "same document"
 		},
 	],
 });
@@ -246,9 +276,29 @@ const uniqueRows = uniqueRowConfig(schema, {
 Enforces uniqueness on single columns using indexes.
 
 ```ts
-import { uniqueColumnConfig } from 'convex-verify';
+import { uniqueColumnConfig } from "convex-verify";
 // or
-import { uniqueColumnConfig } from 'convex-verify/plugins';
+import { uniqueColumnConfig } from "convex-verify/plugins";
+```
+
+#### 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"],
+		}),
+	],
+});
 ```
 
 The column name is derived from the index name by removing `by_` prefix:
@@ -256,12 +306,12 @@ The column name is derived from the index name by removing `by_` prefix:
 - `by_username` → checks `username` column
 - `by_email` → checks `email` column
 
-#### Example
+#### Shorthand (Index Names)
 
 ```ts
 const uniqueColumns = uniqueColumnConfig(schema, {
-	users: ['by_username', 'by_email'],
-	organizations: ['by_slug'],
+	users: ["by_username", "by_email"],
+	organizations: ["by_slug"],
 });
 ```
 
@@ -270,38 +320,44 @@ const uniqueColumns = uniqueColumnConfig(schema, {
 ```ts
 const uniqueColumns = uniqueColumnConfig(schema, {
 	users: [
-		'by_username', // shorthand
-		{ index: 'by_email', identifiers: ['_id', 'clerkId'] }, // with options
+		"by_username", // shorthand
+		{ index: "by_email", identifiers: ["_id", "clerkId"] }, // with options
 	],
 });
 ```
 
+## Custom Plugins
+
+The `plugins` array accepts custom validation plugins for extensibility.
+
 ### `createValidatePlugin(name, config, handlers)`
 
 Create custom validation plugins.
 
 ```ts
-import { createValidatePlugin } from 'convex-verify';
+import { createValidatePlugin } from "convex-verify";
 // or
-import { createValidatePlugin } from 'convex-verify/core';
+import { createValidatePlugin } from "convex-verify/core";
 ```
 
 #### Example: Required Fields Plugin
 
 ```ts
 const requiredFields = createValidatePlugin(
-	'requiredFields',
-	{ fields: ['title', 'content'] },
+	"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}` });
+					throw new ConvexError({
+						message: `Missing required field: ${field}`,
+					});
 				}
 			}
 			return data;
 		},
-	}
+	},
 );
 ```
 
@@ -309,7 +365,7 @@ const requiredFields = createValidatePlugin(
 
 ```ts
 const checkOwnership = createValidatePlugin(
-	'checkOwnership',
+	"checkOwnership",
 	{},
 	{
 		patch: async (context, data) => {
@@ -317,11 +373,13 @@ const checkOwnership = createValidatePlugin(
 			const user = await getCurrentUser(context.ctx);
 
 			if (existing?.authorId !== user._id) {
-				throw new ConvexError({ message: 'Not authorized to edit this document' });
+				throw new ConvexError({
+					message: "Not authorized to edit this document",
+				});
 			}
 			return data;
 		},
-	}
+	},
 );
 ```
 
@@ -333,7 +391,7 @@ Plugins receive a `ValidateContext` object:
 type ValidateContext = {
 	ctx: GenericMutationCtx; // Convex mutation context
 	tableName: string; // Table being operated on
-	operation: 'insert' | 'patch';
+	operation: "insert" | "patch";
 	patchId?: GenericId; // Document ID (patch only)
 	onFail?: OnFailCallback; // Callback for failure details
 	schema?: SchemaDefinition; // Schema reference
@@ -348,13 +406,13 @@ For smaller bundle sizes, you can import from specific subpaths:
 
 ```ts
 // Import everything from root
-import { uniqueRowConfig, verifyConfig } from 'convex-verify';
-import { protectedColumnsConfig } from 'convex-verify/configs';
+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';
+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";
 ```
 
 ---
@@ -366,13 +424,13 @@ import { getTableIndexes } from 'convex-verify/utils';
 All operations accept an optional `onFail` callback for handling validation failures:
 
 ```ts
-await insert(ctx, 'posts', data, {
+await insert(ctx, "posts", data, {
 	onFail: (args) => {
 		if (args.uniqueRow) {
-			console.log('Duplicate row:', args.uniqueRow.existingData);
+			console.log("Duplicate row:", args.uniqueRow.existingData);
 		}
 		if (args.uniqueColumn) {
-			console.log('Duplicate column:', args.uniqueColumn.conflictingColumn);
+			console.log("Duplicate column:", args.uniqueColumn.conflictingColumn);
 		}
 	},
 });

package/dist/core/index.d.mts

@@ -1,4 +1,4 @@
-import { SchemaDefinition, GenericSchema, DataModelFromSchemaDefinition, TableNamesInDataModel, DocumentByName, GenericMutationCtx, WithoutSystemFields } from 'convex/server';
+import { GenericSchema, DataModelFromSchemaDefinition, SchemaDefinition, TableNamesInDataModel, DocumentByName, GenericMutationCtx, WithoutSystemFields } from 'convex/server';
 import { GenericId } from 'convex/values';
 import { a as ValidatePlugin } from '../plugin-mHMV2-SG.mjs';
 export { V as ValidateContext, b as ValidatePluginRecord, c as createValidatePlugin, i as isValidatePlugin, r as runValidatePlugins } from '../plugin-mHMV2-SG.mjs';
@@ -10,8 +10,25 @@ export { B as BaseConfigReturn, k as DMGeneric, D as DefaultValuesConfigData, l
  */
 type VerifyConfigInputWithPlugins = VerifyConfigInput & {
     /**
-     * Validate plugins to run after transforms.
+     * Unique row validation config.
+     * Enforces uniqueness across multiple columns using composite indexes.
+     *
+     * Can also be added to the `plugins` array.
+     */
+    uniqueRow?: ValidatePlugin<"uniqueRow", any>;
+    /**
+     * Unique column validation config.
+     * Enforces uniqueness on single columns using indexes.
+     *
+     * Can also be added to the `plugins` array.
+     */
+    uniqueColumn?: ValidatePlugin<"uniqueColumn", any>;
+    /**
+     * Additional validate plugins to run after transforms.
      * These plugins can validate data but don't affect input types.
+     *
+     * Built-in plugins (uniqueRow, uniqueColumn) can be added here
+     * as an alternative to using their dedicated config keys.
      */
     plugins?: ValidatePlugin[];
 };
@@ -24,25 +41,38 @@ type VerifyConfigInputWithPlugins = VerifyConfigInput & {
  *
  * @example
  * ```ts
- * import { verifyConfig, defaultValuesConfig, protectedColumnsConfig, uniqueRowConfig } from 'convex-verify';
+ * import {
+ *   verifyConfig,
+ *   defaultValuesConfig,
+ *   protectedColumnsConfig,
+ *   uniqueRowConfig,
+ *   uniqueColumnConfig,
+ * } from 'convex-verify';
  * import schema from './schema';
  *
  * export const { insert, patch, dangerouslyPatch } = verifyConfig(schema, {
+ *   // Type-affecting configs
  *   defaultValues: defaultValuesConfig(schema, () => ({
  *     posts: { status: 'draft', views: 0 },
  *   })),
  *   protectedColumns: protectedColumnsConfig(schema, {
  *     posts: ['authorId'],
  *   }),
- *   plugins: [
- *     uniqueRowConfig(schema, {
- *       posts: ['by_slug'],
- *     }),
- *   ],
+ *
+ *   // Built-in validation configs
+ *   uniqueRow: uniqueRowConfig(schema, {
+ *     posts: ['by_author_slug'],
+ *   }),
+ *   uniqueColumn: uniqueColumnConfig(schema, {
+ *     users: ['by_email', 'by_username'],
+ *   }),
+ *
+ *   // Custom/third-party plugins
+ *   plugins: [myCustomPlugin()],
  * });
  * ```
  */
-declare const verifyConfig: <S extends SchemaDefinition<GenericSchema, boolean>, DataModel extends DataModelFromSchemaDefinition<S>, const VC extends VerifyConfigInputWithPlugins>(_schema: S, configs: VC) => {
+declare const verifyConfig: <S extends GenericSchema, DataModel extends DataModelFromSchemaDefinition<SchemaDefinition<S, boolean>>, const VC extends VerifyConfigInputWithPlugins>(_schema: SchemaDefinition<S, boolean>, configs: VC) => {
     insert: <const TN extends TableNamesInDataModel<DataModel>, const D extends DocumentByName<DataModel, TN>>(ctx: Omit<GenericMutationCtx<DataModel>, never>, tableName: TN, data: HasKey<VC, "defaultValues"> extends true ? MakeOptional<WithoutSystemFields<D>, OptionalKeysForTable<VC, TN> & keyof WithoutSystemFields<D>> : WithoutSystemFields<D>, options?: {
         onFail?: OnFailCallback<D>;
     }) => Promise<GenericId<TN>>;

package/dist/core/index.d.ts

@@ -1,4 +1,4 @@
-import { SchemaDefinition, GenericSchema, DataModelFromSchemaDefinition, TableNamesInDataModel, DocumentByName, GenericMutationCtx, WithoutSystemFields } from 'convex/server';
+import { GenericSchema, DataModelFromSchemaDefinition, SchemaDefinition, TableNamesInDataModel, DocumentByName, GenericMutationCtx, WithoutSystemFields } from 'convex/server';
 import { GenericId } from 'convex/values';
 import { a as ValidatePlugin } from '../plugin-BjJ7yjrc.js';
 export { V as ValidateContext, b as ValidatePluginRecord, c as createValidatePlugin, i as isValidatePlugin, r as runValidatePlugins } from '../plugin-BjJ7yjrc.js';
@@ -10,8 +10,25 @@ export { B as BaseConfigReturn, k as DMGeneric, D as DefaultValuesConfigData, l
  */
 type VerifyConfigInputWithPlugins = VerifyConfigInput & {
     /**
-     * Validate plugins to run after transforms.
+     * Unique row validation config.
+     * Enforces uniqueness across multiple columns using composite indexes.
+     *
+     * Can also be added to the `plugins` array.
+     */
+    uniqueRow?: ValidatePlugin<"uniqueRow", any>;
+    /**
+     * Unique column validation config.
+     * Enforces uniqueness on single columns using indexes.
+     *
+     * Can also be added to the `plugins` array.
+     */
+    uniqueColumn?: ValidatePlugin<"uniqueColumn", any>;
+    /**
+     * Additional validate plugins to run after transforms.
      * These plugins can validate data but don't affect input types.
+     *
+     * Built-in plugins (uniqueRow, uniqueColumn) can be added here
+     * as an alternative to using their dedicated config keys.
      */
     plugins?: ValidatePlugin[];
 };
@@ -24,25 +41,38 @@ type VerifyConfigInputWithPlugins = VerifyConfigInput & {
  *
  * @example
  * ```ts
- * import { verifyConfig, defaultValuesConfig, protectedColumnsConfig, uniqueRowConfig } from 'convex-verify';
+ * import {
+ *   verifyConfig,
+ *   defaultValuesConfig,
+ *   protectedColumnsConfig,
+ *   uniqueRowConfig,
+ *   uniqueColumnConfig,
+ * } from 'convex-verify';
  * import schema from './schema';
  *
  * export const { insert, patch, dangerouslyPatch } = verifyConfig(schema, {
+ *   // Type-affecting configs
  *   defaultValues: defaultValuesConfig(schema, () => ({
  *     posts: { status: 'draft', views: 0 },
  *   })),
  *   protectedColumns: protectedColumnsConfig(schema, {
  *     posts: ['authorId'],
  *   }),
- *   plugins: [
- *     uniqueRowConfig(schema, {
- *       posts: ['by_slug'],
- *     }),
- *   ],
+ *
+ *   // Built-in validation configs
+ *   uniqueRow: uniqueRowConfig(schema, {
+ *     posts: ['by_author_slug'],
+ *   }),
+ *   uniqueColumn: uniqueColumnConfig(schema, {
+ *     users: ['by_email', 'by_username'],
+ *   }),
+ *
+ *   // Custom/third-party plugins
+ *   plugins: [myCustomPlugin()],
  * });
  * ```
  */
-declare const verifyConfig: <S extends SchemaDefinition<GenericSchema, boolean>, DataModel extends DataModelFromSchemaDefinition<S>, const VC extends VerifyConfigInputWithPlugins>(_schema: S, configs: VC) => {
+declare const verifyConfig: <S extends GenericSchema, DataModel extends DataModelFromSchemaDefinition<SchemaDefinition<S, boolean>>, const VC extends VerifyConfigInputWithPlugins>(_schema: SchemaDefinition<S, boolean>, configs: VC) => {
     insert: <const TN extends TableNamesInDataModel<DataModel>, const D extends DocumentByName<DataModel, TN>>(ctx: Omit<GenericMutationCtx<DataModel>, never>, tableName: TN, data: HasKey<VC, "defaultValues"> extends true ? MakeOptional<WithoutSystemFields<D>, OptionalKeysForTable<VC, TN> & keyof WithoutSystemFields<D>> : WithoutSystemFields<D>, options?: {
         onFail?: OnFailCallback<D>;
     }) => Promise<GenericId<TN>>;

package/dist/core/index.js

@@ -52,11 +52,20 @@ function createValidatePlugin(type, config, verify) {
 
 // src/core/verifyConfig.ts
 var verifyConfig = (_schema, configs) => {
-  const validatePlugins = configs.plugins ?? [];
+  const validatePlugins = [
+    // Built-in validation configs (if provided as named keys)
+    ...configs.uniqueRow ? [configs.uniqueRow] : [],
+    ...configs.uniqueColumn ? [configs.uniqueColumn] : [],
+    // Additional plugins from the plugins array
+    ...configs.plugins ?? []
+  ];
   const insert = async (ctx, tableName, data, options) => {
     let verifiedData = data;
     if (configs.defaultValues) {
-      verifiedData = await configs.defaultValues.verify(tableName, verifiedData);
+      verifiedData = await configs.defaultValues.verify(
+        tableName,
+        verifiedData
+      );
     }
     if (validatePlugins.length > 0) {
       verifiedData = await runValidatePlugins(