convex-verify 0.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,58 @@
+import { SchemaDefinition, GenericSchema, DataModelFromSchemaDefinition, 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';
+import { V as VerifyConfigInput, H as HasKey, M as MakeOptional, b as OptionalKeysForTable, a as OnFailCallback, d as ProtectedKeysForTable } from '../types-_64SXyva.js';
+export { B as BaseConfigReturn, k as DMGeneric, D as DefaultValuesConfigData, l as DefaultValuesInput, E as ExtractDefaultValuesConfig, c as ExtractProtectedColumnsConfig, I as IndexConfigBaseOptions, j as IndexConfigEntry, N as NormalizedIndexConfig, O as OnFailArgs, P as Prettify, m as ProtectedColumnsInput, g as UniqueColumnConfigData, h as UniqueColumnConfigEntry, i as UniqueColumnConfigOptions, U as UniqueRowConfigData, e as UniqueRowConfigEntry, f as UniqueRowConfigOptions, n as normalizeIndexConfigEntry } from '../types-_64SXyva.js';
+
+/**
+ * Extended config input that includes optional validate plugins
+ */
+type VerifyConfigInputWithPlugins = VerifyConfigInput & {
+    /**
+     * Validate plugins to run after transforms.
+     * These plugins can validate data but don't affect input types.
+     */
+    plugins?: ValidatePlugin[];
+};
+/**
+ * Configure type-safe insert and patch functions with validation and transforms.
+ *
+ * @param schema - Your Convex schema definition
+ * @param configs - Configuration object with transforms, configs, and plugins
+ * @returns Object with `insert`, `patch`, and `dangerouslyPatch` functions
+ *
+ * @example
+ * ```ts
+ * import { verifyConfig, defaultValuesConfig, protectedColumnsConfig, uniqueRowConfig } from 'convex-verify';
+ * import schema from './schema';
+ *
+ * export const { insert, patch, dangerouslyPatch } = verifyConfig(schema, {
+ *   defaultValues: defaultValuesConfig(schema, () => ({
+ *     posts: { status: 'draft', views: 0 },
+ *   })),
+ *   protectedColumns: protectedColumnsConfig(schema, {
+ *     posts: ['authorId'],
+ *   }),
+ *   plugins: [
+ *     uniqueRowConfig(schema, {
+ *       posts: ['by_slug'],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare const verifyConfig: <S extends SchemaDefinition<GenericSchema, boolean>, DataModel extends DataModelFromSchemaDefinition<S>, const VC extends VerifyConfigInputWithPlugins>(_schema: S, 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>>;
+    patch: <const TN extends TableNamesInDataModel<DataModel>, const D_1 extends DocumentByName<DataModel, TN>>(ctx: Omit<GenericMutationCtx<DataModel>, never>, tableName: TN, id: GenericId<TN>, data: HasKey<VC, "protectedColumns"> extends true ? Omit<Partial<WithoutSystemFields<D_1>>, ProtectedKeysForTable<VC, TN> & keyof WithoutSystemFields<D_1>> : Partial<WithoutSystemFields<D_1>>, options?: {
+        onFail?: OnFailCallback<D_1>;
+    }) => Promise<void>;
+    dangerouslyPatch: <const TN extends TableNamesInDataModel<DataModel>, const D_2 extends DocumentByName<DataModel, TN>>(ctx: Omit<GenericMutationCtx<DataModel>, never>, tableName: TN, id: GenericId<TN>, data: Partial<WithoutSystemFields<D_2>>, options?: {
+        onFail?: OnFailCallback<D_2>;
+    }) => Promise<void>;
+    configs: VC;
+};
+
+export { HasKey, MakeOptional, OnFailCallback, OptionalKeysForTable, ProtectedKeysForTable, ValidatePlugin, VerifyConfigInput, verifyConfig };

package/dist/core/index.js

@@ -0,0 +1,144 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/index.ts
+var core_exports = {};
+__export(core_exports, {
+  createValidatePlugin: () => createValidatePlugin,
+  isValidatePlugin: () => isValidatePlugin,
+  normalizeIndexConfigEntry: () => normalizeIndexConfigEntry,
+  runValidatePlugins: () => runValidatePlugins,
+  verifyConfig: () => verifyConfig
+});
+module.exports = __toCommonJS(core_exports);
+
+// src/core/plugin.ts
+function isValidatePlugin(obj) {
+  return typeof obj === "object" && obj !== null && "_type" in obj && typeof obj._type === "string" && "verify" in obj && typeof obj.verify === "object";
+}
+async function runValidatePlugins(plugins, context, data) {
+  let result = data;
+  for (const plugin of plugins) {
+    const verifyFn = context.operation === "insert" ? plugin.verify.insert : plugin.verify.patch;
+    if (verifyFn) {
+      result = await verifyFn(context, result);
+    }
+  }
+  return result;
+}
+function createValidatePlugin(type, config, verify) {
+  return {
+    _type: type,
+    config,
+    verify
+  };
+}
+
+// src/core/verifyConfig.ts
+var verifyConfig = (_schema, configs) => {
+  const validatePlugins = configs.plugins ?? [];
+  const insert = async (ctx, tableName, data, options) => {
+    let verifiedData = data;
+    if (configs.defaultValues) {
+      verifiedData = await configs.defaultValues.verify(tableName, verifiedData);
+    }
+    if (validatePlugins.length > 0) {
+      verifiedData = await runValidatePlugins(
+        validatePlugins,
+        {
+          ctx,
+          tableName,
+          operation: "insert",
+          onFail: options?.onFail,
+          schema: _schema
+        },
+        verifiedData
+      );
+    }
+    return await ctx.db.insert(tableName, verifiedData);
+  };
+  const patch = async (ctx, tableName, id, data, options) => {
+    let verifiedData = data;
+    if (validatePlugins.length > 0) {
+      verifiedData = await runValidatePlugins(
+        validatePlugins,
+        {
+          ctx,
+          tableName,
+          operation: "patch",
+          patchId: id,
+          onFail: options?.onFail,
+          schema: _schema
+        },
+        verifiedData
+      );
+    }
+    await ctx.db.patch(id, verifiedData);
+  };
+  const dangerouslyPatch = async (ctx, tableName, id, data, options) => {
+    let verifiedData = data;
+    if (validatePlugins.length > 0) {
+      verifiedData = await runValidatePlugins(
+        validatePlugins,
+        {
+          ctx,
+          tableName,
+          operation: "patch",
+          patchId: id,
+          onFail: options?.onFail,
+          schema: _schema
+        },
+        verifiedData
+      );
+    }
+    await ctx.db.patch(id, verifiedData);
+  };
+  return {
+    insert,
+    patch,
+    dangerouslyPatch,
+    // Expose configs for debugging/advanced usage
+    configs
+  };
+};
+
+// src/core/types.ts
+function normalizeIndexConfigEntry(entry, defaultIdentifiers = ["_id"]) {
+  if (typeof entry === "string") {
+    return {
+      index: entry,
+      identifiers: defaultIdentifiers
+    };
+  }
+  const { index, identifiers, ...rest } = entry;
+  return {
+    index: String(index),
+    identifiers: identifiers?.map(String) ?? defaultIdentifiers,
+    ...rest
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createValidatePlugin,
+  isValidatePlugin,
+  normalizeIndexConfigEntry,
+  runValidatePlugins,
+  verifyConfig
+});
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/index.ts","../../src/core/plugin.ts","../../src/core/verifyConfig.ts","../../src/core/types.ts"],"sourcesContent":["// Main verifyConfig function\nexport { verifyConfig } from './verifyConfig';\n\n// Plugin system\nexport { createValidatePlugin, isValidatePlugin, runValidatePlugins } from './plugin';\nexport type { ValidateContext, ValidatePlugin, ValidatePluginRecord } from './plugin';\n\n// All types\nexport type {\n\t// Utility types\n\tPrettify,\n\tMakeOptional,\n\t// Base types\n\tBaseConfigReturn,\n\t// OnFail types\n\tOnFailArgs,\n\tOnFailCallback,\n\t// Config data types\n\tDMGeneric,\n\tDefaultValuesConfigData,\n\t// Index-based config types\n\tIndexConfigBaseOptions,\n\tIndexConfigEntry,\n\tNormalizedIndexConfig,\n\t// UniqueRow types\n\tUniqueRowConfigOptions,\n\tUniqueRowConfigEntry,\n\tUniqueRowConfigData,\n\t// UniqueColumn types\n\tUniqueColumnConfigOptions,\n\tUniqueColumnConfigEntry,\n\tUniqueColumnConfigData,\n\t// Input types\n\tDefaultValuesInput,\n\tProtectedColumnsInput,\n\t// VerifyConfig types\n\tVerifyConfigInput,\n\t// Type extraction helpers\n\tExtractDefaultValuesConfig,\n\tOptionalKeysForTable,\n\tHasKey,\n\tExtractProtectedColumnsConfig,\n\tProtectedKeysForTable,\n} from './types';\n\n// Utility function\nexport { normalizeIndexConfigEntry } from './types';\n","import { GenericMutationCtx, GenericSchema, SchemaDefinition } from 'convex/server';\nimport { GenericId } from 'convex/values';\n\nimport { OnFailCallback } from './types';\n\n// =============================================================================\n// Plugin Types\n// =============================================================================\n\n/**\n * Context passed to validate plugin functions.\n *\n * Provides access to:\n * - `ctx` - Full Convex mutation context (includes `ctx.db` for queries)\n * - `tableName` - The table being operated on\n * - `operation` - 'insert' or 'patch'\n * - `patchId` - Document ID (only for patch operations)\n * - `onFail` - Callback to report validation failures before throwing\n * - `schema` - Optional schema reference (if provided by verifyConfig)\n */\nexport type ValidateContext<TN extends string = string> = {\n\t/** Full Convex mutation context - use ctx.db for database queries */\n\tctx: Omit<GenericMutationCtx<any>, never>;\n\t/** Table name being operated on */\n\ttableName: TN;\n\t/** Operation type: 'insert' or 'patch' */\n\toperation: 'insert' | 'patch';\n\t/** Document ID (only available for patch operations) */\n\tpatchId?: GenericId<any>;\n\t/** Callback for validation failures - call before throwing to provide details */\n\tonFail?: OnFailCallback<any>;\n\t/** Schema reference (if provided to verifyConfig) */\n\tschema?: SchemaDefinition<GenericSchema, boolean>;\n};\n\n/**\n * A validate plugin that can check data during insert/patch operations.\n *\n * Validate plugins:\n * - Run AFTER transform plugins (like defaultValues)\n * - Can be async (use await for API calls, db queries, etc.)\n * - Can throw errors to prevent the operation\n * - Should return the data unchanged (validation only, no transformation)\n * - Do NOT affect the TypeScript types of the input data\n *\n * @example\n * ```ts\n * // Simple sync plugin\n * const requiredFields = createValidatePlugin(\n *   'requiredFields',\n *   { fields: ['title', 'content'] },\n *   {\n *     insert: (context, data) => {\n *       for (const field of config.fields) {\n *         if (!data[field]) {\n *           throw new ConvexError({ message: `Missing required field: ${field}` });\n *         }\n *       }\n *       return data;\n *     },\n *   }\n * );\n *\n * // Async plugin with database query\n * const checkOwnership = createValidatePlugin(\n *   'checkOwnership',\n *   {},\n *   {\n *     patch: async (context, data) => {\n *       const existing = await context.ctx.db.get(context.patchId);\n *       if (existing?.ownerId !== getCurrentUserId()) {\n *         throw new ConvexError({ message: 'Not authorized' });\n *       }\n *       return data;\n *     },\n *   }\n * );\n * ```\n */\nexport interface ValidatePlugin<Type extends string = string, Config = unknown> {\n\t/** Unique identifier for this plugin */\n\treadonly _type: Type;\n\n\t/** Plugin configuration */\n\treadonly config: Config;\n\n\t/** Verify functions for insert and/or patch operations */\n\tverify: {\n\t\t/**\n\t\t * Validate data for insert operations.\n\t\t * Can be sync or async.\n\t\t *\n\t\t * @param context - Plugin context with ctx, tableName, schema, etc.\n\t\t * @param data - The data to validate (after transforms applied)\n\t\t * @returns The data unchanged (or Promise resolving to data)\n\t\t * @throws ConvexError if validation fails\n\t\t */\n\t\tinsert?: (context: ValidateContext, data: any) => Promise<any> | any;\n\n\t\t/**\n\t\t * Validate data for patch operations.\n\t\t * Can be sync or async.\n\t\t *\n\t\t * @param context - Plugin context with ctx, tableName, patchId, schema, etc.\n\t\t * @param data - The partial data to validate\n\t\t * @returns The data unchanged (or Promise resolving to data)\n\t\t * @throws ConvexError if validation fails\n\t\t */\n\t\tpatch?: (context: ValidateContext, data: any) => Promise<any> | any;\n\t};\n}\n\n/**\n * Type guard to check if something is a ValidatePlugin\n */\nexport function isValidatePlugin(obj: unknown): obj is ValidatePlugin {\n\treturn (\n\t\ttypeof obj === 'object' &&\n\t\tobj !== null &&\n\t\t'_type' in obj &&\n\t\ttypeof (obj as any)._type === 'string' &&\n\t\t'verify' in obj &&\n\t\ttypeof (obj as any).verify === 'object'\n\t);\n}\n\n// =============================================================================\n// Plugin Collection Types\n// =============================================================================\n\n/**\n * A collection of validate plugins\n */\nexport type ValidatePluginRecord = Record<string, ValidatePlugin>;\n\n// =============================================================================\n// Plugin Helpers\n// =============================================================================\n\n/**\n * Run all validate plugins for an operation.\n * Plugins are run in order and each receives the output of the previous.\n * All plugin verify functions are awaited (supports async plugins).\n */\nexport async function runValidatePlugins(\n\tplugins: ValidatePlugin[],\n\tcontext: ValidateContext,\n\tdata: any\n): Promise<any> {\n\tlet result = data;\n\n\tfor (const plugin of plugins) {\n\t\tconst verifyFn = context.operation === 'insert' ? plugin.verify.insert : plugin.verify.patch;\n\n\t\tif (verifyFn) {\n\t\t\t// Always await - works for both sync and async functions\n\t\t\tresult = await verifyFn(context, result);\n\t\t}\n\t}\n\n\treturn result;\n}\n\n/**\n * Helper to create a validate plugin with proper typing.\n *\n * @param type - Unique identifier for this plugin type\n * @param config - Plugin configuration data\n * @param verify - Object with insert and/or patch verify functions\n * @returns A ValidatePlugin instance\n *\n * @example\n * ```ts\n * const myPlugin = createValidatePlugin(\n *   'myPlugin',\n *   { maxLength: 100 },\n *   {\n *     insert: async (context, data) => {\n *       // Validation logic here\n *       return data;\n *     },\n *   }\n * );\n * ```\n */\nexport function createValidatePlugin<Type extends string, Config>(\n\ttype: Type,\n\tconfig: Config,\n\tverify: ValidatePlugin<Type, Config>['verify']\n): ValidatePlugin<Type, Config> {\n\treturn {\n\t\t_type: type,\n\t\tconfig,\n\t\tverify,\n\t};\n}\n","import {\n\tDataModelFromSchemaDefinition,\n\tDocumentByName,\n\tGenericMutationCtx,\n\tGenericSchema,\n\tSchemaDefinition,\n\tTableNamesInDataModel,\n\tWithoutSystemFields,\n} from 'convex/server';\nimport { GenericId } from 'convex/values';\n\nimport { runValidatePlugins, ValidatePlugin } from './plugin';\nimport {\n\tHasKey,\n\tMakeOptional,\n\tOnFailCallback,\n\tOptionalKeysForTable,\n\tProtectedKeysForTable,\n\tVerifyConfigInput,\n} from './types';\n\n/**\n * Extended config input that includes optional validate plugins\n */\ntype VerifyConfigInputWithPlugins = VerifyConfigInput & {\n\t/**\n\t * Validate plugins to run after transforms.\n\t * These plugins can validate data but don't affect input types.\n\t */\n\tplugins?: ValidatePlugin[];\n};\n\n/**\n * Configure type-safe insert and patch functions with validation and transforms.\n *\n * @param schema - Your Convex schema definition\n * @param configs - Configuration object with transforms, configs, and plugins\n * @returns Object with `insert`, `patch`, and `dangerouslyPatch` functions\n *\n * @example\n * ```ts\n * import { verifyConfig, defaultValuesConfig, protectedColumnsConfig, uniqueRowConfig } from 'convex-verify';\n * import schema from './schema';\n *\n * export const { insert, patch, dangerouslyPatch } = verifyConfig(schema, {\n *   defaultValues: defaultValuesConfig(schema, () => ({\n *     posts: { status: 'draft', views: 0 },\n *   })),\n *   protectedColumns: protectedColumnsConfig(schema, {\n *     posts: ['authorId'],\n *   }),\n *   plugins: [\n *     uniqueRowConfig(schema, {\n *       posts: ['by_slug'],\n *     }),\n *   ],\n * });\n * ```\n */\nexport const verifyConfig = <\n\tS extends SchemaDefinition<GenericSchema, boolean>,\n\tDataModel extends DataModelFromSchemaDefinition<S>,\n\tconst VC extends VerifyConfigInputWithPlugins,\n>(\n\t_schema: S,\n\tconfigs: VC\n) => {\n\t// Get all validate plugins\n\tconst validatePlugins = configs.plugins ?? [];\n\n\t/**\n\t * Insert a document with all configured verifications applied.\n\t *\n\t * Execution order:\n\t * 1. Transform: defaultValues (makes fields optional, applies defaults)\n\t * 2. Validate: plugins (in order provided)\n\t * 3. Insert into database\n\t */\n\tconst insert = async <\n\t\tconst TN extends TableNamesInDataModel<DataModel>,\n\t\tconst D extends DocumentByName<DataModel, TN>,\n\t>(\n\t\tctx: Omit<GenericMutationCtx<DataModel>, never>,\n\t\ttableName: TN,\n\t\tdata: HasKey<VC, 'defaultValues'> extends true\n\t\t\t? MakeOptional<\n\t\t\t\t\tWithoutSystemFields<D>,\n\t\t\t\t\tOptionalKeysForTable<VC, TN> & keyof WithoutSystemFields<D>\n\t\t\t\t>\n\t\t\t: WithoutSystemFields<D>,\n\t\toptions?: {\n\t\t\tonFail?: OnFailCallback<D>;\n\t\t}\n\t): Promise<GenericId<TN>> => {\n\t\tlet verifiedData = data as WithoutSystemFields<DocumentByName<DataModel, TN>>;\n\n\t\t// === TRANSFORM PHASE ===\n\n\t\t// Apply default values (transforms data)\n\t\tif (configs.defaultValues) {\n\t\t\tverifiedData = await configs.defaultValues.verify(tableName, verifiedData);\n\t\t}\n\n\t\t// === VALIDATE PHASE ===\n\n\t\t// Run all validate plugins\n\t\tif (validatePlugins.length > 0) {\n\t\t\tverifiedData = await runValidatePlugins(\n\t\t\t\tvalidatePlugins,\n\t\t\t\t{\n\t\t\t\t\tctx,\n\t\t\t\t\ttableName: tableName as string,\n\t\t\t\t\toperation: 'insert',\n\t\t\t\t\tonFail: options?.onFail,\n\t\t\t\t\tschema: _schema,\n\t\t\t\t},\n\t\t\t\tverifiedData\n\t\t\t);\n\t\t}\n\n\t\t// Final insert\n\t\treturn await ctx.db.insert(tableName, verifiedData);\n\t};\n\n\t/**\n\t * Patch a document with all configured verifications applied.\n\t *\n\t * Protected columns (if configured) are removed from the input type.\n\t * Use dangerouslyPatch() to bypass protected column restrictions.\n\t *\n\t * Execution order:\n\t * 1. Validate: plugins (in order provided)\n\t * 2. Patch in database\n\t *\n\t * Note: defaultValues is skipped for patch operations\n\t */\n\tconst patch = async <\n\t\tconst TN extends TableNamesInDataModel<DataModel>,\n\t\tconst D extends DocumentByName<DataModel, TN>,\n\t>(\n\t\tctx: Omit<GenericMutationCtx<DataModel>, never>,\n\t\ttableName: TN,\n\t\tid: GenericId<TN>,\n\t\tdata: HasKey<VC, 'protectedColumns'> extends true\n\t\t\t? Omit<\n\t\t\t\t\tPartial<WithoutSystemFields<D>>,\n\t\t\t\t\tProtectedKeysForTable<VC, TN> & keyof WithoutSystemFields<D>\n\t\t\t\t>\n\t\t\t: Partial<WithoutSystemFields<D>>,\n\t\toptions?: {\n\t\t\tonFail?: OnFailCallback<D>;\n\t\t}\n\t): Promise<void> => {\n\t\tlet verifiedData = data as Partial<WithoutSystemFields<DocumentByName<DataModel, TN>>>;\n\n\t\t// === VALIDATE PHASE ===\n\n\t\t// Run all validate plugins\n\t\tif (validatePlugins.length > 0) {\n\t\t\tverifiedData = await runValidatePlugins(\n\t\t\t\tvalidatePlugins,\n\t\t\t\t{\n\t\t\t\t\tctx,\n\t\t\t\t\ttableName: tableName as string,\n\t\t\t\t\toperation: 'patch',\n\t\t\t\t\tpatchId: id,\n\t\t\t\t\tonFail: options?.onFail,\n\t\t\t\t\tschema: _schema,\n\t\t\t\t},\n\t\t\t\tverifiedData\n\t\t\t);\n\t\t}\n\n\t\tawait ctx.db.patch(id, verifiedData);\n\t};\n\n\t/**\n\t * Patch a document bypassing protected column restrictions.\n\t *\n\t * WARNING: This allows patching ANY column, including protected ones.\n\t * Only use this when you explicitly need to update a protected column.\n\t *\n\t * Validation plugins still run - only type restrictions are bypassed.\n\t */\n\tconst dangerouslyPatch = async <\n\t\tconst TN extends TableNamesInDataModel<DataModel>,\n\t\tconst D extends DocumentByName<DataModel, TN>,\n\t>(\n\t\tctx: Omit<GenericMutationCtx<DataModel>, never>,\n\t\ttableName: TN,\n\t\tid: GenericId<TN>,\n\t\tdata: Partial<WithoutSystemFields<D>>,\n\t\toptions?: {\n\t\t\tonFail?: OnFailCallback<D>;\n\t\t}\n\t): Promise<void> => {\n\t\tlet verifiedData = data;\n\n\t\t// === VALIDATE PHASE ===\n\n\t\t// Run all validate plugins (protection is bypassed, but validation still runs)\n\t\tif (validatePlugins.length > 0) {\n\t\t\tverifiedData = await runValidatePlugins(\n\t\t\t\tvalidatePlugins,\n\t\t\t\t{\n\t\t\t\t\tctx,\n\t\t\t\t\ttableName: tableName as string,\n\t\t\t\t\toperation: 'patch',\n\t\t\t\t\tpatchId: id,\n\t\t\t\t\tonFail: options?.onFail,\n\t\t\t\t\tschema: _schema,\n\t\t\t\t},\n\t\t\t\tverifiedData\n\t\t\t);\n\t\t}\n\n\t\tawait ctx.db.patch(id, verifiedData);\n\t};\n\n\treturn {\n\t\tinsert,\n\t\tpatch,\n\t\tdangerouslyPatch,\n\t\t// Expose configs for debugging/advanced usage\n\t\tconfigs,\n\t};\n};\n","import {\n\tDataModelFromSchemaDefinition,\n\tIndexes,\n\tNamedTableInfo,\n\tSchemaDefinition,\n\tWithoutSystemFields,\n} from 'convex/server';\n\n// =============================================================================\n// Utility Types\n// =============================================================================\n\nexport type Prettify<T> = { [K in keyof T]: T[K] } & {};\n\nexport type MakeOptional<T, K extends PropertyKey> = Prettify<\n\tOmit<T, K & keyof T> & Partial<Pick<T, K & keyof T>>\n>;\n\n// =============================================================================\n// Base Types for Config Functions\n// =============================================================================\n\n/**\n * Base interface that all config functions should return.\n * Each config type can have its own `verify` signature and additional properties.\n */\nexport type BaseConfigReturn = {\n\tconfig: Record<string, any>;\n};\n\n// =============================================================================\n// OnFail Types\n// =============================================================================\n\nexport type OnFailArgs<D> = {\n\tuniqueColumn?: {\n\t\tconflictingColumn: keyof D;\n\t\texistingData: D;\n\t};\n\tuniqueRow?: {\n\t\texistingData: D | null;\n\t};\n\teditableColumn?: {\n\t\tremovedColumns: string[];\n\t\tfilteredData: D;\n\t};\n\trequiredColumn?: {\n\t\tmissingColumn: keyof D;\n\t};\n};\n\nexport type OnFailCallback<D> = (args: OnFailArgs<D>) => void;\n\n// =============================================================================\n// Config Data Types (what the user provides)\n// =============================================================================\n\nexport type DMGeneric = DataModelFromSchemaDefinition<SchemaDefinition<any, boolean>>;\n\nexport type DefaultValuesConfigData<DM extends DMGeneric> = {\n\t[K in keyof DM]?: {\n\t\t[column in keyof WithoutSystemFields<DM[K]['document']>]?: DM[K]['document'][column];\n\t};\n};\n\n// =============================================================================\n// Index-Based Config Types (shared between uniqueRow, uniqueColumn, etc.)\n// =============================================================================\n\n/**\n * Base options shared by all index-based config entries.\n * Individual plugins can extend this with their own options.\n */\nexport type IndexConfigBaseOptions = {\n\t/** Additional identifiers to check if the existing row is the same document being updated */\n\tidentifiers?: string[];\n};\n\n/**\n * A config entry that can be either:\n * - A string (index name) for shorthand\n * - An object with `index` and additional options\n *\n * @example\n * ```ts\n * // These are equivalent:\n * 'by_username'\n * { index: 'by_username' }\n *\n * // With options:\n * { index: 'by_username', identifiers: ['_id', 'userId'] }\n * ```\n */\nexport type IndexConfigEntry<\n\tDM extends DMGeneric,\n\tK extends keyof DM,\n\tOptions extends IndexConfigBaseOptions = IndexConfigBaseOptions,\n> =\n\t| keyof Indexes<NamedTableInfo<DM, K>>\n\t| ({\n\t\t\tindex: keyof Indexes<NamedTableInfo<DM, K>>;\n\t\t\tidentifiers?: (keyof NamedTableInfo<DM, K>['document'])[];\n\t  } & Omit<Options, 'identifiers'>);\n\n/**\n * Normalized form of an index config entry (always an object)\n */\nexport type NormalizedIndexConfig<Options extends IndexConfigBaseOptions = IndexConfigBaseOptions> =\n\t{\n\t\tindex: string;\n\t\tidentifiers: string[];\n\t} & Omit<Options, 'identifiers'>;\n\n/**\n * Normalize a config entry to always have index and identifiers.\n * Works for both string shorthand and full object configs.\n */\nexport function normalizeIndexConfigEntry<\n\tOptions extends IndexConfigBaseOptions = IndexConfigBaseOptions,\n>(\n\tentry: string | ({ index: string; identifiers?: string[] } & Omit<Options, 'identifiers'>),\n\tdefaultIdentifiers: string[] = ['_id']\n): NormalizedIndexConfig<Options> {\n\tif (typeof entry === 'string') {\n\t\treturn {\n\t\t\tindex: entry,\n\t\t\tidentifiers: defaultIdentifiers,\n\t\t} as NormalizedIndexConfig<Options>;\n\t}\n\n\tconst { index, identifiers, ...rest } = entry;\n\treturn {\n\t\tindex: String(index),\n\t\tidentifiers: identifiers?.map(String) ?? defaultIdentifiers,\n\t\t...rest,\n\t} as NormalizedIndexConfig<Options>;\n}\n\n// =============================================================================\n// UniqueRow Config Types\n// =============================================================================\n\nexport type UniqueRowConfigOptions = IndexConfigBaseOptions & {\n\tqueryExistingWithNullish?: boolean;\n};\n\nexport type UniqueRowConfigEntry<DM extends DMGeneric, K extends keyof DM> = IndexConfigEntry<\n\tDM,\n\tK,\n\tUniqueRowConfigOptions\n>;\n\nexport type UniqueRowConfigData<DM extends DMGeneric> = {\n\t[K in keyof DM]?: UniqueRowConfigEntry<DM, K>[];\n};\n\n// =============================================================================\n// UniqueColumn Config Types\n// =============================================================================\n\nexport type UniqueColumnConfigOptions = IndexConfigBaseOptions;\n\nexport type UniqueColumnConfigEntry<DM extends DMGeneric, K extends keyof DM> = IndexConfigEntry<\n\tDM,\n\tK,\n\tUniqueColumnConfigOptions\n>;\n\nexport type UniqueColumnConfigData<DM extends DMGeneric> = {\n\t[K in keyof DM]?: UniqueColumnConfigEntry<DM, K>[];\n};\n\n// =============================================================================\n// Input Types (loose types for verifyConfig to accept)\n// =============================================================================\n\n/**\n * Loose input types that accept any return from config functions.\n * We use loose types here to avoid complex generic matching,\n * then extract the specific config types using conditional types.\n */\nexport type DefaultValuesInput = {\n\t_type: 'defaultValues';\n\tverify: (tableName: any, data: any) => Promise<any>;\n\tconfig:\n\t\t| Record<string, Record<string, any>>\n\t\t| (() => Record<string, Record<string, any>> | Promise<Record<string, Record<string, any>>>);\n};\n\n/**\n * Loose input type for protectedColumnsConfig return value.\n */\nexport type ProtectedColumnsInput = {\n\t_type: 'protectedColumns';\n\tconfig: Record<string, string[]>;\n};\n\n// =============================================================================\n// Object-Based Types (for verifyConfig)\n// =============================================================================\n\n/**\n * Config input for verifyConfig.\n *\n * - `defaultValues`: Transform plugin that makes fields optional (affects types)\n * - `protectedColumns`: Columns that cannot be patched (affects patch() types)\n * - `plugins`: Array of validate plugins (use for uniqueRow, uniqueColumn, custom plugins, etc.)\n */\nexport type VerifyConfigInput = {\n\tdefaultValues?: DefaultValuesInput;\n\tprotectedColumns?: ProtectedColumnsInput;\n};\n\n// =============================================================================\n// Type Extraction Helpers\n// =============================================================================\n\n/**\n * Extract the config type from defaultValues.config.\n * Handles both direct object and function forms.\n */\nexport type ExtractDefaultValuesConfig<VC> = VC extends {\n\tdefaultValues: { config: infer C };\n}\n\t? C extends () => infer R\n\t\t? Awaited<R>\n\t\t: C\n\t: Record<string, never>;\n\n/**\n * Compute which keys should be optional for a given table based on all configs.\n * Currently only defaultValues affects optionality.\n */\nexport type OptionalKeysForTable<VC, TN> = TN extends keyof ExtractDefaultValuesConfig<VC>\n\t? keyof ExtractDefaultValuesConfig<VC>[TN]\n\t: never;\n\n/**\n * Helper to check if a key exists in a type\n */\nexport type HasKey<T, K extends PropertyKey> = K extends keyof T ? true : false;\n\n// =============================================================================\n// Protected Columns Type Extraction\n// =============================================================================\n\n/**\n * Extract the config type from protectedColumns.config\n */\nexport type ExtractProtectedColumnsConfig<VC> = VC extends {\n\tprotectedColumns: { config: infer C };\n}\n\t? C\n\t: Record<string, never>;\n\n/**\n * Get protected column keys for a specific table.\n * Returns the column names that should be omitted from patch() input.\n */\nexport type ProtectedKeysForTable<VC, TN> = TN extends keyof ExtractProtectedColumnsConfig<VC>\n\t? ExtractProtectedColumnsConfig<VC>[TN] extends readonly (infer K)[]\n\t\t? K\n\t\t: never\n\t: never;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACmHO,SAAS,iBAAiB,KAAqC;AACrE,SACC,OAAO,QAAQ,YACf,QAAQ,QACR,WAAW,OACX,OAAQ,IAAY,UAAU,YAC9B,YAAY,OACZ,OAAQ,IAAY,WAAW;AAEjC;AAoBA,eAAsB,mBACrB,SACA,SACA,MACe;AACf,MAAI,SAAS;AAEb,aAAW,UAAU,SAAS;AAC7B,UAAM,WAAW,QAAQ,cAAc,WAAW,OAAO,OAAO,SAAS,OAAO,OAAO;AAEvF,QAAI,UAAU;AAEb,eAAS,MAAM,SAAS,SAAS,MAAM;AAAA,IACxC;AAAA,EACD;AAEA,SAAO;AACR;AAwBO,SAAS,qBACf,MACA,QACA,QAC+B;AAC/B,SAAO;AAAA,IACN,OAAO;AAAA,IACP;AAAA,IACA;AAAA,EACD;AACD;;;ACxIO,IAAM,eAAe,CAK3B,SACA,YACI;AAEJ,QAAM,kBAAkB,QAAQ,WAAW,CAAC;AAU5C,QAAM,SAAS,OAId,KACA,WACA,MAMA,YAG4B;AAC5B,QAAI,eAAe;AAKnB,QAAI,QAAQ,eAAe;AAC1B,qBAAe,MAAM,QAAQ,cAAc,OAAO,WAAW,YAAY;AAAA,IAC1E;AAKA,QAAI,gBAAgB,SAAS,GAAG;AAC/B,qBAAe,MAAM;AAAA,QACpB;AAAA,QACA;AAAA,UACC;AAAA,UACA;AAAA,UACA,WAAW;AAAA,UACX,QAAQ,SAAS;AAAA,UACjB,QAAQ;AAAA,QACT;AAAA,QACA;AAAA,MACD;AAAA,IACD;AAGA,WAAO,MAAM,IAAI,GAAG,OAAO,WAAW,YAAY;AAAA,EACnD;AAcA,QAAM,QAAQ,OAIb,KACA,WACA,IACA,MAMA,YAGmB;AACnB,QAAI,eAAe;AAKnB,QAAI,gBAAgB,SAAS,GAAG;AAC/B,qBAAe,MAAM;AAAA,QACpB;AAAA,QACA;AAAA,UACC;AAAA,UACA;AAAA,UACA,WAAW;AAAA,UACX,SAAS;AAAA,UACT,QAAQ,SAAS;AAAA,UACjB,QAAQ;AAAA,QACT;AAAA,QACA;AAAA,MACD;AAAA,IACD;AAEA,UAAM,IAAI,GAAG,MAAM,IAAI,YAAY;AAAA,EACpC;AAUA,QAAM,mBAAmB,OAIxB,KACA,WACA,IACA,MACA,YAGmB;AACnB,QAAI,eAAe;AAKnB,QAAI,gBAAgB,SAAS,GAAG;AAC/B,qBAAe,MAAM;AAAA,QACpB;AAAA,QACA;AAAA,UACC;AAAA,UACA;AAAA,UACA,WAAW;AAAA,UACX,SAAS;AAAA,UACT,QAAQ,SAAS;AAAA,UACjB,QAAQ;AAAA,QACT;AAAA,QACA;AAAA,MACD;AAAA,IACD;AAEA,UAAM,IAAI,GAAG,MAAM,IAAI,YAAY;AAAA,EACpC;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA;AAAA,IAEA;AAAA,EACD;AACD;;;AC7GO,SAAS,0BAGf,OACA,qBAA+B,CAAC,KAAK,GACJ;AACjC,MAAI,OAAO,UAAU,UAAU;AAC9B,WAAO;AAAA,MACN,OAAO;AAAA,MACP,aAAa;AAAA,IACd;AAAA,EACD;AAEA,QAAM,EAAE,OAAO,aAAa,GAAG,KAAK,IAAI;AACxC,SAAO;AAAA,IACN,OAAO,OAAO,KAAK;AAAA,IACnB,aAAa,aAAa,IAAI,MAAM,KAAK;AAAA,IACzC,GAAG;AAAA,EACJ;AACD;","names":[]}

package/dist/core/index.mjs

@@ -0,0 +1,113 @@
+// src/core/plugin.ts
+function isValidatePlugin(obj) {
+  return typeof obj === "object" && obj !== null && "_type" in obj && typeof obj._type === "string" && "verify" in obj && typeof obj.verify === "object";
+}
+async function runValidatePlugins(plugins, context, data) {
+  let result = data;
+  for (const plugin of plugins) {
+    const verifyFn = context.operation === "insert" ? plugin.verify.insert : plugin.verify.patch;
+    if (verifyFn) {
+      result = await verifyFn(context, result);
+    }
+  }
+  return result;
+}
+function createValidatePlugin(type, config, verify) {
+  return {
+    _type: type,
+    config,
+    verify
+  };
+}
+
+// src/core/verifyConfig.ts
+var verifyConfig = (_schema, configs) => {
+  const validatePlugins = configs.plugins ?? [];
+  const insert = async (ctx, tableName, data, options) => {
+    let verifiedData = data;
+    if (configs.defaultValues) {
+      verifiedData = await configs.defaultValues.verify(tableName, verifiedData);
+    }
+    if (validatePlugins.length > 0) {
+      verifiedData = await runValidatePlugins(
+        validatePlugins,
+        {
+          ctx,
+          tableName,
+          operation: "insert",
+          onFail: options?.onFail,
+          schema: _schema
+        },
+        verifiedData
+      );
+    }
+    return await ctx.db.insert(tableName, verifiedData);
+  };
+  const patch = async (ctx, tableName, id, data, options) => {
+    let verifiedData = data;
+    if (validatePlugins.length > 0) {
+      verifiedData = await runValidatePlugins(
+        validatePlugins,
+        {
+          ctx,
+          tableName,
+          operation: "patch",
+          patchId: id,
+          onFail: options?.onFail,
+          schema: _schema
+        },
+        verifiedData
+      );
+    }
+    await ctx.db.patch(id, verifiedData);
+  };
+  const dangerouslyPatch = async (ctx, tableName, id, data, options) => {
+    let verifiedData = data;
+    if (validatePlugins.length > 0) {
+      verifiedData = await runValidatePlugins(
+        validatePlugins,
+        {
+          ctx,
+          tableName,
+          operation: "patch",
+          patchId: id,
+          onFail: options?.onFail,
+          schema: _schema
+        },
+        verifiedData
+      );
+    }
+    await ctx.db.patch(id, verifiedData);
+  };
+  return {
+    insert,
+    patch,
+    dangerouslyPatch,
+    // Expose configs for debugging/advanced usage
+    configs
+  };
+};
+
+// src/core/types.ts
+function normalizeIndexConfigEntry(entry, defaultIdentifiers = ["_id"]) {
+  if (typeof entry === "string") {
+    return {
+      index: entry,
+      identifiers: defaultIdentifiers
+    };
+  }
+  const { index, identifiers, ...rest } = entry;
+  return {
+    index: String(index),
+    identifiers: identifiers?.map(String) ?? defaultIdentifiers,
+    ...rest
+  };
+}
+export {
+  createValidatePlugin,
+  isValidatePlugin,
+  normalizeIndexConfigEntry,
+  runValidatePlugins,
+  verifyConfig
+};
+//# sourceMappingURL=index.mjs.map

package/dist/core/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/plugin.ts","../../src/core/verifyConfig.ts","../../src/core/types.ts"],"sourcesContent":["import { GenericMutationCtx, GenericSchema, SchemaDefinition } from 'convex/server';\nimport { GenericId } from 'convex/values';\n\nimport { OnFailCallback } from './types';\n\n// =============================================================================\n// Plugin Types\n// =============================================================================\n\n/**\n * Context passed to validate plugin functions.\n *\n * Provides access to:\n * - `ctx` - Full Convex mutation context (includes `ctx.db` for queries)\n * - `tableName` - The table being operated on\n * - `operation` - 'insert' or 'patch'\n * - `patchId` - Document ID (only for patch operations)\n * - `onFail` - Callback to report validation failures before throwing\n * - `schema` - Optional schema reference (if provided by verifyConfig)\n */\nexport type ValidateContext<TN extends string = string> = {\n\t/** Full Convex mutation context - use ctx.db for database queries */\n\tctx: Omit<GenericMutationCtx<any>, never>;\n\t/** Table name being operated on */\n\ttableName: TN;\n\t/** Operation type: 'insert' or 'patch' */\n\toperation: 'insert' | 'patch';\n\t/** Document ID (only available for patch operations) */\n\tpatchId?: GenericId<any>;\n\t/** Callback for validation failures - call before throwing to provide details */\n\tonFail?: OnFailCallback<any>;\n\t/** Schema reference (if provided to verifyConfig) */\n\tschema?: SchemaDefinition<GenericSchema, boolean>;\n};\n\n/**\n * A validate plugin that can check data during insert/patch operations.\n *\n * Validate plugins:\n * - Run AFTER transform plugins (like defaultValues)\n * - Can be async (use await for API calls, db queries, etc.)\n * - Can throw errors to prevent the operation\n * - Should return the data unchanged (validation only, no transformation)\n * - Do NOT affect the TypeScript types of the input data\n *\n * @example\n * ```ts\n * // Simple sync plugin\n * const requiredFields = createValidatePlugin(\n *   'requiredFields',\n *   { fields: ['title', 'content'] },\n *   {\n *     insert: (context, data) => {\n *       for (const field of config.fields) {\n *         if (!data[field]) {\n *           throw new ConvexError({ message: `Missing required field: ${field}` });\n *         }\n *       }\n *       return data;\n *     },\n *   }\n * );\n *\n * // Async plugin with database query\n * const checkOwnership = createValidatePlugin(\n *   'checkOwnership',\n *   {},\n *   {\n *     patch: async (context, data) => {\n *       const existing = await context.ctx.db.get(context.patchId);\n *       if (existing?.ownerId !== getCurrentUserId()) {\n *         throw new ConvexError({ message: 'Not authorized' });\n *       }\n *       return data;\n *     },\n *   }\n * );\n * ```\n */\nexport interface ValidatePlugin<Type extends string = string, Config = unknown> {\n\t/** Unique identifier for this plugin */\n\treadonly _type: Type;\n\n\t/** Plugin configuration */\n\treadonly config: Config;\n\n\t/** Verify functions for insert and/or patch operations */\n\tverify: {\n\t\t/**\n\t\t * Validate data for insert operations.\n\t\t * Can be sync or async.\n\t\t *\n\t\t * @param context - Plugin context with ctx, tableName, schema, etc.\n\t\t * @param data - The data to validate (after transforms applied)\n\t\t * @returns The data unchanged (or Promise resolving to data)\n\t\t * @throws ConvexError if validation fails\n\t\t */\n\t\tinsert?: (context: ValidateContext, data: any) => Promise<any> | any;\n\n\t\t/**\n\t\t * Validate data for patch operations.\n\t\t * Can be sync or async.\n\t\t *\n\t\t * @param context - Plugin context with ctx, tableName, patchId, schema, etc.\n\t\t * @param data - The partial data to validate\n\t\t * @returns The data unchanged (or Promise resolving to data)\n\t\t * @throws ConvexError if validation fails\n\t\t */\n\t\tpatch?: (context: ValidateContext, data: any) => Promise<any> | any;\n\t};\n}\n\n/**\n * Type guard to check if something is a ValidatePlugin\n */\nexport function isValidatePlugin(obj: unknown): obj is ValidatePlugin {\n\treturn (\n\t\ttypeof obj === 'object' &&\n\t\tobj !== null &&\n\t\t'_type' in obj &&\n\t\ttypeof (obj as any)._type === 'string' &&\n\t\t'verify' in obj &&\n\t\ttypeof (obj as any).verify === 'object'\n\t);\n}\n\n// =============================================================================\n// Plugin Collection Types\n// =============================================================================\n\n/**\n * A collection of validate plugins\n */\nexport type ValidatePluginRecord = Record<string, ValidatePlugin>;\n\n// =============================================================================\n// Plugin Helpers\n// =============================================================================\n\n/**\n * Run all validate plugins for an operation.\n * Plugins are run in order and each receives the output of the previous.\n * All plugin verify functions are awaited (supports async plugins).\n */\nexport async function runValidatePlugins(\n\tplugins: ValidatePlugin[],\n\tcontext: ValidateContext,\n\tdata: any\n): Promise<any> {\n\tlet result = data;\n\n\tfor (const plugin of plugins) {\n\t\tconst verifyFn = context.operation === 'insert' ? plugin.verify.insert : plugin.verify.patch;\n\n\t\tif (verifyFn) {\n\t\t\t// Always await - works for both sync and async functions\n\t\t\tresult = await verifyFn(context, result);\n\t\t}\n\t}\n\n\treturn result;\n}\n\n/**\n * Helper to create a validate plugin with proper typing.\n *\n * @param type - Unique identifier for this plugin type\n * @param config - Plugin configuration data\n * @param verify - Object with insert and/or patch verify functions\n * @returns A ValidatePlugin instance\n *\n * @example\n * ```ts\n * const myPlugin = createValidatePlugin(\n *   'myPlugin',\n *   { maxLength: 100 },\n *   {\n *     insert: async (context, data) => {\n *       // Validation logic here\n *       return data;\n *     },\n *   }\n * );\n * ```\n */\nexport function createValidatePlugin<Type extends string, Config>(\n\ttype: Type,\n\tconfig: Config,\n\tverify: ValidatePlugin<Type, Config>['verify']\n): ValidatePlugin<Type, Config> {\n\treturn {\n\t\t_type: type,\n\t\tconfig,\n\t\tverify,\n\t};\n}\n","import {\n\tDataModelFromSchemaDefinition,\n\tDocumentByName,\n\tGenericMutationCtx,\n\tGenericSchema,\n\tSchemaDefinition,\n\tTableNamesInDataModel,\n\tWithoutSystemFields,\n} from 'convex/server';\nimport { GenericId } from 'convex/values';\n\nimport { runValidatePlugins, ValidatePlugin } from './plugin';\nimport {\n\tHasKey,\n\tMakeOptional,\n\tOnFailCallback,\n\tOptionalKeysForTable,\n\tProtectedKeysForTable,\n\tVerifyConfigInput,\n} from './types';\n\n/**\n * Extended config input that includes optional validate plugins\n */\ntype VerifyConfigInputWithPlugins = VerifyConfigInput & {\n\t/**\n\t * Validate plugins to run after transforms.\n\t * These plugins can validate data but don't affect input types.\n\t */\n\tplugins?: ValidatePlugin[];\n};\n\n/**\n * Configure type-safe insert and patch functions with validation and transforms.\n *\n * @param schema - Your Convex schema definition\n * @param configs - Configuration object with transforms, configs, and plugins\n * @returns Object with `insert`, `patch`, and `dangerouslyPatch` functions\n *\n * @example\n * ```ts\n * import { verifyConfig, defaultValuesConfig, protectedColumnsConfig, uniqueRowConfig } from 'convex-verify';\n * import schema from './schema';\n *\n * export const { insert, patch, dangerouslyPatch } = verifyConfig(schema, {\n *   defaultValues: defaultValuesConfig(schema, () => ({\n *     posts: { status: 'draft', views: 0 },\n *   })),\n *   protectedColumns: protectedColumnsConfig(schema, {\n *     posts: ['authorId'],\n *   }),\n *   plugins: [\n *     uniqueRowConfig(schema, {\n *       posts: ['by_slug'],\n *     }),\n *   ],\n * });\n * ```\n */\nexport const verifyConfig = <\n\tS extends SchemaDefinition<GenericSchema, boolean>,\n\tDataModel extends DataModelFromSchemaDefinition<S>,\n\tconst VC extends VerifyConfigInputWithPlugins,\n>(\n\t_schema: S,\n\tconfigs: VC\n) => {\n\t// Get all validate plugins\n\tconst validatePlugins = configs.plugins ?? [];\n\n\t/**\n\t * Insert a document with all configured verifications applied.\n\t *\n\t * Execution order:\n\t * 1. Transform: defaultValues (makes fields optional, applies defaults)\n\t * 2. Validate: plugins (in order provided)\n\t * 3. Insert into database\n\t */\n\tconst insert = async <\n\t\tconst TN extends TableNamesInDataModel<DataModel>,\n\t\tconst D extends DocumentByName<DataModel, TN>,\n\t>(\n\t\tctx: Omit<GenericMutationCtx<DataModel>, never>,\n\t\ttableName: TN,\n\t\tdata: HasKey<VC, 'defaultValues'> extends true\n\t\t\t? MakeOptional<\n\t\t\t\t\tWithoutSystemFields<D>,\n\t\t\t\t\tOptionalKeysForTable<VC, TN> & keyof WithoutSystemFields<D>\n\t\t\t\t>\n\t\t\t: WithoutSystemFields<D>,\n\t\toptions?: {\n\t\t\tonFail?: OnFailCallback<D>;\n\t\t}\n\t): Promise<GenericId<TN>> => {\n\t\tlet verifiedData = data as WithoutSystemFields<DocumentByName<DataModel, TN>>;\n\n\t\t// === TRANSFORM PHASE ===\n\n\t\t// Apply default values (transforms data)\n\t\tif (configs.defaultValues) {\n\t\t\tverifiedData = await configs.defaultValues.verify(tableName, verifiedData);\n\t\t}\n\n\t\t// === VALIDATE PHASE ===\n\n\t\t// Run all validate plugins\n\t\tif (validatePlugins.length > 0) {\n\t\t\tverifiedData = await runValidatePlugins(\n\t\t\t\tvalidatePlugins,\n\t\t\t\t{\n\t\t\t\t\tctx,\n\t\t\t\t\ttableName: tableName as string,\n\t\t\t\t\toperation: 'insert',\n\t\t\t\t\tonFail: options?.onFail,\n\t\t\t\t\tschema: _schema,\n\t\t\t\t},\n\t\t\t\tverifiedData\n\t\t\t);\n\t\t}\n\n\t\t// Final insert\n\t\treturn await ctx.db.insert(tableName, verifiedData);\n\t};\n\n\t/**\n\t * Patch a document with all configured verifications applied.\n\t *\n\t * Protected columns (if configured) are removed from the input type.\n\t * Use dangerouslyPatch() to bypass protected column restrictions.\n\t *\n\t * Execution order:\n\t * 1. Validate: plugins (in order provided)\n\t * 2. Patch in database\n\t *\n\t * Note: defaultValues is skipped for patch operations\n\t */\n\tconst patch = async <\n\t\tconst TN extends TableNamesInDataModel<DataModel>,\n\t\tconst D extends DocumentByName<DataModel, TN>,\n\t>(\n\t\tctx: Omit<GenericMutationCtx<DataModel>, never>,\n\t\ttableName: TN,\n\t\tid: GenericId<TN>,\n\t\tdata: HasKey<VC, 'protectedColumns'> extends true\n\t\t\t? Omit<\n\t\t\t\t\tPartial<WithoutSystemFields<D>>,\n\t\t\t\t\tProtectedKeysForTable<VC, TN> & keyof WithoutSystemFields<D>\n\t\t\t\t>\n\t\t\t: Partial<WithoutSystemFields<D>>,\n\t\toptions?: {\n\t\t\tonFail?: OnFailCallback<D>;\n\t\t}\n\t): Promise<void> => {\n\t\tlet verifiedData = data as Partial<WithoutSystemFields<DocumentByName<DataModel, TN>>>;\n\n\t\t// === VALIDATE PHASE ===\n\n\t\t// Run all validate plugins\n\t\tif (validatePlugins.length > 0) {\n\t\t\tverifiedData = await runValidatePlugins(\n\t\t\t\tvalidatePlugins,\n\t\t\t\t{\n\t\t\t\t\tctx,\n\t\t\t\t\ttableName: tableName as string,\n\t\t\t\t\toperation: 'patch',\n\t\t\t\t\tpatchId: id,\n\t\t\t\t\tonFail: options?.onFail,\n\t\t\t\t\tschema: _schema,\n\t\t\t\t},\n\t\t\t\tverifiedData\n\t\t\t);\n\t\t}\n\n\t\tawait ctx.db.patch(id, verifiedData);\n\t};\n\n\t/**\n\t * Patch a document bypassing protected column restrictions.\n\t *\n\t * WARNING: This allows patching ANY column, including protected ones.\n\t * Only use this when you explicitly need to update a protected column.\n\t *\n\t * Validation plugins still run - only type restrictions are bypassed.\n\t */\n\tconst dangerouslyPatch = async <\n\t\tconst TN extends TableNamesInDataModel<DataModel>,\n\t\tconst D extends DocumentByName<DataModel, TN>,\n\t>(\n\t\tctx: Omit<GenericMutationCtx<DataModel>, never>,\n\t\ttableName: TN,\n\t\tid: GenericId<TN>,\n\t\tdata: Partial<WithoutSystemFields<D>>,\n\t\toptions?: {\n\t\t\tonFail?: OnFailCallback<D>;\n\t\t}\n\t): Promise<void> => {\n\t\tlet verifiedData = data;\n\n\t\t// === VALIDATE PHASE ===\n\n\t\t// Run all validate plugins (protection is bypassed, but validation still runs)\n\t\tif (validatePlugins.length > 0) {\n\t\t\tverifiedData = await runValidatePlugins(\n\t\t\t\tvalidatePlugins,\n\t\t\t\t{\n\t\t\t\t\tctx,\n\t\t\t\t\ttableName: tableName as string,\n\t\t\t\t\toperation: 'patch',\n\t\t\t\t\tpatchId: id,\n\t\t\t\t\tonFail: options?.onFail,\n\t\t\t\t\tschema: _schema,\n\t\t\t\t},\n\t\t\t\tverifiedData\n\t\t\t);\n\t\t}\n\n\t\tawait ctx.db.patch(id, verifiedData);\n\t};\n\n\treturn {\n\t\tinsert,\n\t\tpatch,\n\t\tdangerouslyPatch,\n\t\t// Expose configs for debugging/advanced usage\n\t\tconfigs,\n\t};\n};\n","import {\n\tDataModelFromSchemaDefinition,\n\tIndexes,\n\tNamedTableInfo,\n\tSchemaDefinition,\n\tWithoutSystemFields,\n} from 'convex/server';\n\n// =============================================================================\n// Utility Types\n// =============================================================================\n\nexport type Prettify<T> = { [K in keyof T]: T[K] } & {};\n\nexport type MakeOptional<T, K extends PropertyKey> = Prettify<\n\tOmit<T, K & keyof T> & Partial<Pick<T, K & keyof T>>\n>;\n\n// =============================================================================\n// Base Types for Config Functions\n// =============================================================================\n\n/**\n * Base interface that all config functions should return.\n * Each config type can have its own `verify` signature and additional properties.\n */\nexport type BaseConfigReturn = {\n\tconfig: Record<string, any>;\n};\n\n// =============================================================================\n// OnFail Types\n// =============================================================================\n\nexport type OnFailArgs<D> = {\n\tuniqueColumn?: {\n\t\tconflictingColumn: keyof D;\n\t\texistingData: D;\n\t};\n\tuniqueRow?: {\n\t\texistingData: D | null;\n\t};\n\teditableColumn?: {\n\t\tremovedColumns: string[];\n\t\tfilteredData: D;\n\t};\n\trequiredColumn?: {\n\t\tmissingColumn: keyof D;\n\t};\n};\n\nexport type OnFailCallback<D> = (args: OnFailArgs<D>) => void;\n\n// =============================================================================\n// Config Data Types (what the user provides)\n// =============================================================================\n\nexport type DMGeneric = DataModelFromSchemaDefinition<SchemaDefinition<any, boolean>>;\n\nexport type DefaultValuesConfigData<DM extends DMGeneric> = {\n\t[K in keyof DM]?: {\n\t\t[column in keyof WithoutSystemFields<DM[K]['document']>]?: DM[K]['document'][column];\n\t};\n};\n\n// =============================================================================\n// Index-Based Config Types (shared between uniqueRow, uniqueColumn, etc.)\n// =============================================================================\n\n/**\n * Base options shared by all index-based config entries.\n * Individual plugins can extend this with their own options.\n */\nexport type IndexConfigBaseOptions = {\n\t/** Additional identifiers to check if the existing row is the same document being updated */\n\tidentifiers?: string[];\n};\n\n/**\n * A config entry that can be either:\n * - A string (index name) for shorthand\n * - An object with `index` and additional options\n *\n * @example\n * ```ts\n * // These are equivalent:\n * 'by_username'\n * { index: 'by_username' }\n *\n * // With options:\n * { index: 'by_username', identifiers: ['_id', 'userId'] }\n * ```\n */\nexport type IndexConfigEntry<\n\tDM extends DMGeneric,\n\tK extends keyof DM,\n\tOptions extends IndexConfigBaseOptions = IndexConfigBaseOptions,\n> =\n\t| keyof Indexes<NamedTableInfo<DM, K>>\n\t| ({\n\t\t\tindex: keyof Indexes<NamedTableInfo<DM, K>>;\n\t\t\tidentifiers?: (keyof NamedTableInfo<DM, K>['document'])[];\n\t  } & Omit<Options, 'identifiers'>);\n\n/**\n * Normalized form of an index config entry (always an object)\n */\nexport type NormalizedIndexConfig<Options extends IndexConfigBaseOptions = IndexConfigBaseOptions> =\n\t{\n\t\tindex: string;\n\t\tidentifiers: string[];\n\t} & Omit<Options, 'identifiers'>;\n\n/**\n * Normalize a config entry to always have index and identifiers.\n * Works for both string shorthand and full object configs.\n */\nexport function normalizeIndexConfigEntry<\n\tOptions extends IndexConfigBaseOptions = IndexConfigBaseOptions,\n>(\n\tentry: string | ({ index: string; identifiers?: string[] } & Omit<Options, 'identifiers'>),\n\tdefaultIdentifiers: string[] = ['_id']\n): NormalizedIndexConfig<Options> {\n\tif (typeof entry === 'string') {\n\t\treturn {\n\t\t\tindex: entry,\n\t\t\tidentifiers: defaultIdentifiers,\n\t\t} as NormalizedIndexConfig<Options>;\n\t}\n\n\tconst { index, identifiers, ...rest } = entry;\n\treturn {\n\t\tindex: String(index),\n\t\tidentifiers: identifiers?.map(String) ?? defaultIdentifiers,\n\t\t...rest,\n\t} as NormalizedIndexConfig<Options>;\n}\n\n// =============================================================================\n// UniqueRow Config Types\n// =============================================================================\n\nexport type UniqueRowConfigOptions = IndexConfigBaseOptions & {\n\tqueryExistingWithNullish?: boolean;\n};\n\nexport type UniqueRowConfigEntry<DM extends DMGeneric, K extends keyof DM> = IndexConfigEntry<\n\tDM,\n\tK,\n\tUniqueRowConfigOptions\n>;\n\nexport type UniqueRowConfigData<DM extends DMGeneric> = {\n\t[K in keyof DM]?: UniqueRowConfigEntry<DM, K>[];\n};\n\n// =============================================================================\n// UniqueColumn Config Types\n// =============================================================================\n\nexport type UniqueColumnConfigOptions = IndexConfigBaseOptions;\n\nexport type UniqueColumnConfigEntry<DM extends DMGeneric, K extends keyof DM> = IndexConfigEntry<\n\tDM,\n\tK,\n\tUniqueColumnConfigOptions\n>;\n\nexport type UniqueColumnConfigData<DM extends DMGeneric> = {\n\t[K in keyof DM]?: UniqueColumnConfigEntry<DM, K>[];\n};\n\n// =============================================================================\n// Input Types (loose types for verifyConfig to accept)\n// =============================================================================\n\n/**\n * Loose input types that accept any return from config functions.\n * We use loose types here to avoid complex generic matching,\n * then extract the specific config types using conditional types.\n */\nexport type DefaultValuesInput = {\n\t_type: 'defaultValues';\n\tverify: (tableName: any, data: any) => Promise<any>;\n\tconfig:\n\t\t| Record<string, Record<string, any>>\n\t\t| (() => Record<string, Record<string, any>> | Promise<Record<string, Record<string, any>>>);\n};\n\n/**\n * Loose input type for protectedColumnsConfig return value.\n */\nexport type ProtectedColumnsInput = {\n\t_type: 'protectedColumns';\n\tconfig: Record<string, string[]>;\n};\n\n// =============================================================================\n// Object-Based Types (for verifyConfig)\n// =============================================================================\n\n/**\n * Config input for verifyConfig.\n *\n * - `defaultValues`: Transform plugin that makes fields optional (affects types)\n * - `protectedColumns`: Columns that cannot be patched (affects patch() types)\n * - `plugins`: Array of validate plugins (use for uniqueRow, uniqueColumn, custom plugins, etc.)\n */\nexport type VerifyConfigInput = {\n\tdefaultValues?: DefaultValuesInput;\n\tprotectedColumns?: ProtectedColumnsInput;\n};\n\n// =============================================================================\n// Type Extraction Helpers\n// =============================================================================\n\n/**\n * Extract the config type from defaultValues.config.\n * Handles both direct object and function forms.\n */\nexport type ExtractDefaultValuesConfig<VC> = VC extends {\n\tdefaultValues: { config: infer C };\n}\n\t? C extends () => infer R\n\t\t? Awaited<R>\n\t\t: C\n\t: Record<string, never>;\n\n/**\n * Compute which keys should be optional for a given table based on all configs.\n * Currently only defaultValues affects optionality.\n */\nexport type OptionalKeysForTable<VC, TN> = TN extends keyof ExtractDefaultValuesConfig<VC>\n\t? keyof ExtractDefaultValuesConfig<VC>[TN]\n\t: never;\n\n/**\n * Helper to check if a key exists in a type\n */\nexport type HasKey<T, K extends PropertyKey> = K extends keyof T ? true : false;\n\n// =============================================================================\n// Protected Columns Type Extraction\n// =============================================================================\n\n/**\n * Extract the config type from protectedColumns.config\n */\nexport type ExtractProtectedColumnsConfig<VC> = VC extends {\n\tprotectedColumns: { config: infer C };\n}\n\t? C\n\t: Record<string, never>;\n\n/**\n * Get protected column keys for a specific table.\n * Returns the column names that should be omitted from patch() input.\n */\nexport type ProtectedKeysForTable<VC, TN> = TN extends keyof ExtractProtectedColumnsConfig<VC>\n\t? ExtractProtectedColumnsConfig<VC>[TN] extends readonly (infer K)[]\n\t\t? K\n\t\t: never\n\t: never;\n"],"mappings":";AAmHO,SAAS,iBAAiB,KAAqC;AACrE,SACC,OAAO,QAAQ,YACf,QAAQ,QACR,WAAW,OACX,OAAQ,IAAY,UAAU,YAC9B,YAAY,OACZ,OAAQ,IAAY,WAAW;AAEjC;AAoBA,eAAsB,mBACrB,SACA,SACA,MACe;AACf,MAAI,SAAS;AAEb,aAAW,UAAU,SAAS;AAC7B,UAAM,WAAW,QAAQ,cAAc,WAAW,OAAO,OAAO,SAAS,OAAO,OAAO;AAEvF,QAAI,UAAU;AAEb,eAAS,MAAM,SAAS,SAAS,MAAM;AAAA,IACxC;AAAA,EACD;AAEA,SAAO;AACR;AAwBO,SAAS,qBACf,MACA,QACA,QAC+B;AAC/B,SAAO;AAAA,IACN,OAAO;AAAA,IACP;AAAA,IACA;AAAA,EACD;AACD;;;ACxIO,IAAM,eAAe,CAK3B,SACA,YACI;AAEJ,QAAM,kBAAkB,QAAQ,WAAW,CAAC;AAU5C,QAAM,SAAS,OAId,KACA,WACA,MAMA,YAG4B;AAC5B,QAAI,eAAe;AAKnB,QAAI,QAAQ,eAAe;AAC1B,qBAAe,MAAM,QAAQ,cAAc,OAAO,WAAW,YAAY;AAAA,IAC1E;AAKA,QAAI,gBAAgB,SAAS,GAAG;AAC/B,qBAAe,MAAM;AAAA,QACpB;AAAA,QACA;AAAA,UACC;AAAA,UACA;AAAA,UACA,WAAW;AAAA,UACX,QAAQ,SAAS;AAAA,UACjB,QAAQ;AAAA,QACT;AAAA,QACA;AAAA,MACD;AAAA,IACD;AAGA,WAAO,MAAM,IAAI,GAAG,OAAO,WAAW,YAAY;AAAA,EACnD;AAcA,QAAM,QAAQ,OAIb,KACA,WACA,IACA,MAMA,YAGmB;AACnB,QAAI,eAAe;AAKnB,QAAI,gBAAgB,SAAS,GAAG;AAC/B,qBAAe,MAAM;AAAA,QACpB;AAAA,QACA;AAAA,UACC;AAAA,UACA;AAAA,UACA,WAAW;AAAA,UACX,SAAS;AAAA,UACT,QAAQ,SAAS;AAAA,UACjB,QAAQ;AAAA,QACT;AAAA,QACA;AAAA,MACD;AAAA,IACD;AAEA,UAAM,IAAI,GAAG,MAAM,IAAI,YAAY;AAAA,EACpC;AAUA,QAAM,mBAAmB,OAIxB,KACA,WACA,IACA,MACA,YAGmB;AACnB,QAAI,eAAe;AAKnB,QAAI,gBAAgB,SAAS,GAAG;AAC/B,qBAAe,MAAM;AAAA,QACpB;AAAA,QACA;AAAA,UACC;AAAA,UACA;AAAA,UACA,WAAW;AAAA,UACX,SAAS;AAAA,UACT,QAAQ,SAAS;AAAA,UACjB,QAAQ;AAAA,QACT;AAAA,QACA;AAAA,MACD;AAAA,IACD;AAEA,UAAM,IAAI,GAAG,MAAM,IAAI,YAAY;AAAA,EACpC;AAEA,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA;AAAA,IAEA;AAAA,EACD;AACD;;;AC7GO,SAAS,0BAGf,OACA,qBAA+B,CAAC,KAAK,GACJ;AACjC,MAAI,OAAO,UAAU,UAAU;AAC9B,WAAO;AAAA,MACN,OAAO;AAAA,MACP,aAAa;AAAA,IACd;AAAA,EACD;AAEA,QAAM,EAAE,OAAO,aAAa,GAAG,KAAK,IAAI;AACxC,SAAO;AAAA,IACN,OAAO,OAAO,KAAK;AAAA,IACnB,aAAa,aAAa,IAAI,MAAM,KAAK;AAAA,IACzC,GAAG;AAAA,EACJ;AACD;","names":[]}

package/dist/index.d.mts

@@ -0,0 +1,9 @@
+export { verifyConfig } from './core/index.mjs';
+export { V as ValidateContext, a as ValidatePlugin, b as ValidatePluginRecord, c as createValidatePlugin, i as isValidatePlugin, r as runValidatePlugins } from './plugin-mHMV2-SG.mjs';
+export { D as DefaultValuesConfigData, E as ExtractDefaultValuesConfig, c as ExtractProtectedColumnsConfig, H as HasKey, I as IndexConfigBaseOptions, j as IndexConfigEntry, M as MakeOptional, N as NormalizedIndexConfig, O as OnFailArgs, a as OnFailCallback, b as OptionalKeysForTable, P as Prettify, d as ProtectedKeysForTable, g as UniqueColumnConfigData, h as UniqueColumnConfigEntry, i as UniqueColumnConfigOptions, U as UniqueRowConfigData, e as UniqueRowConfigEntry, f as UniqueRowConfigOptions, V as VerifyConfigInput, n as normalizeIndexConfigEntry } from './types-_64SXyva.mjs';
+export { defaultValuesConfig } from './transforms/index.mjs';
+export { ProtectedColumnsConfigData, protectedColumnsConfig } from './configs/index.mjs';
+export { uniqueColumnConfig, uniqueRowConfig } from './plugins/index.mjs';
+export { constructColumnData, constructIndexData, getTableIndexes } from './utils/index.mjs';
+import 'convex/server';
+import 'convex/values';

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { verifyConfig } from './core/index.js';
+export { V as ValidateContext, a as ValidatePlugin, b as ValidatePluginRecord, c as createValidatePlugin, i as isValidatePlugin, r as runValidatePlugins } from './plugin-BjJ7yjrc.js';
+export { D as DefaultValuesConfigData, E as ExtractDefaultValuesConfig, c as ExtractProtectedColumnsConfig, H as HasKey, I as IndexConfigBaseOptions, j as IndexConfigEntry, M as MakeOptional, N as NormalizedIndexConfig, O as OnFailArgs, a as OnFailCallback, b as OptionalKeysForTable, P as Prettify, d as ProtectedKeysForTable, g as UniqueColumnConfigData, h as UniqueColumnConfigEntry, i as UniqueColumnConfigOptions, U as UniqueRowConfigData, e as UniqueRowConfigEntry, f as UniqueRowConfigOptions, V as VerifyConfigInput, n as normalizeIndexConfigEntry } from './types-_64SXyva.js';
+export { defaultValuesConfig } from './transforms/index.js';
+export { ProtectedColumnsConfigData, protectedColumnsConfig } from './configs/index.js';
+export { uniqueColumnConfig, uniqueRowConfig } from './plugins/index.js';
+export { constructColumnData, constructIndexData, getTableIndexes } from './utils/index.js';
+import 'convex/server';
+import 'convex/values';