convex-verify 0.1.0

package/dist/plugin-mHMV2-SG.d.mts

@@ -0,0 +1,141 @@
+import { GenericMutationCtx, SchemaDefinition, GenericSchema } from 'convex/server';
+import { GenericId } from 'convex/values';
+import { a as OnFailCallback } from './types-_64SXyva.mjs';
+
+/**
+ * Context passed to validate plugin functions.
+ *
+ * Provides access to:
+ * - `ctx` - Full Convex mutation context (includes `ctx.db` for queries)
+ * - `tableName` - The table being operated on
+ * - `operation` - 'insert' or 'patch'
+ * - `patchId` - Document ID (only for patch operations)
+ * - `onFail` - Callback to report validation failures before throwing
+ * - `schema` - Optional schema reference (if provided by verifyConfig)
+ */
+type ValidateContext<TN extends string = string> = {
+    /** Full Convex mutation context - use ctx.db for database queries */
+    ctx: Omit<GenericMutationCtx<any>, never>;
+    /** Table name being operated on */
+    tableName: TN;
+    /** Operation type: 'insert' or 'patch' */
+    operation: 'insert' | 'patch';
+    /** Document ID (only available for patch operations) */
+    patchId?: GenericId<any>;
+    /** Callback for validation failures - call before throwing to provide details */
+    onFail?: OnFailCallback<any>;
+    /** Schema reference (if provided to verifyConfig) */
+    schema?: SchemaDefinition<GenericSchema, boolean>;
+};
+/**
+ * A validate plugin that can check data during insert/patch operations.
+ *
+ * Validate plugins:
+ * - Run AFTER transform plugins (like defaultValues)
+ * - Can be async (use await for API calls, db queries, etc.)
+ * - Can throw errors to prevent the operation
+ * - Should return the data unchanged (validation only, no transformation)
+ * - Do NOT affect the TypeScript types of the input data
+ *
+ * @example
+ * ```ts
+ * // Simple sync plugin
+ * const requiredFields = createValidatePlugin(
+ *   'requiredFields',
+ *   { fields: ['title', 'content'] },
+ *   {
+ *     insert: (context, data) => {
+ *       for (const field of config.fields) {
+ *         if (!data[field]) {
+ *           throw new ConvexError({ message: `Missing required field: ${field}` });
+ *         }
+ *       }
+ *       return data;
+ *     },
+ *   }
+ * );
+ *
+ * // Async plugin with database query
+ * const checkOwnership = createValidatePlugin(
+ *   'checkOwnership',
+ *   {},
+ *   {
+ *     patch: async (context, data) => {
+ *       const existing = await context.ctx.db.get(context.patchId);
+ *       if (existing?.ownerId !== getCurrentUserId()) {
+ *         throw new ConvexError({ message: 'Not authorized' });
+ *       }
+ *       return data;
+ *     },
+ *   }
+ * );
+ * ```
+ */
+interface ValidatePlugin<Type extends string = string, Config = unknown> {
+    /** Unique identifier for this plugin */
+    readonly _type: Type;
+    /** Plugin configuration */
+    readonly config: Config;
+    /** Verify functions for insert and/or patch operations */
+    verify: {
+        /**
+         * Validate data for insert operations.
+         * Can be sync or async.
+         *
+         * @param context - Plugin context with ctx, tableName, schema, etc.
+         * @param data - The data to validate (after transforms applied)
+         * @returns The data unchanged (or Promise resolving to data)
+         * @throws ConvexError if validation fails
+         */
+        insert?: (context: ValidateContext, data: any) => Promise<any> | any;
+        /**
+         * Validate data for patch operations.
+         * Can be sync or async.
+         *
+         * @param context - Plugin context with ctx, tableName, patchId, schema, etc.
+         * @param data - The partial data to validate
+         * @returns The data unchanged (or Promise resolving to data)
+         * @throws ConvexError if validation fails
+         */
+        patch?: (context: ValidateContext, data: any) => Promise<any> | any;
+    };
+}
+/**
+ * Type guard to check if something is a ValidatePlugin
+ */
+declare function isValidatePlugin(obj: unknown): obj is ValidatePlugin;
+/**
+ * A collection of validate plugins
+ */
+type ValidatePluginRecord = Record<string, ValidatePlugin>;
+/**
+ * Run all validate plugins for an operation.
+ * Plugins are run in order and each receives the output of the previous.
+ * All plugin verify functions are awaited (supports async plugins).
+ */
+declare function runValidatePlugins(plugins: ValidatePlugin[], context: ValidateContext, data: any): Promise<any>;
+/**
+ * Helper to create a validate plugin with proper typing.
+ *
+ * @param type - Unique identifier for this plugin type
+ * @param config - Plugin configuration data
+ * @param verify - Object with insert and/or patch verify functions
+ * @returns A ValidatePlugin instance
+ *
+ * @example
+ * ```ts
+ * const myPlugin = createValidatePlugin(
+ *   'myPlugin',
+ *   { maxLength: 100 },
+ *   {
+ *     insert: async (context, data) => {
+ *       // Validation logic here
+ *       return data;
+ *     },
+ *   }
+ * );
+ * ```
+ */
+declare function createValidatePlugin<Type extends string, Config>(type: Type, config: Config, verify: ValidatePlugin<Type, Config>['verify']): ValidatePlugin<Type, Config>;
+
+export { type ValidateContext as V, type ValidatePlugin as a, type ValidatePluginRecord as b, createValidatePlugin as c, isValidatePlugin as i, runValidatePlugins as r };

package/dist/plugins/index.d.mts

@@ -0,0 +1,85 @@
+import { SchemaDefinition, GenericSchema, DataModelFromSchemaDefinition } from 'convex/server';
+import { a as ValidatePlugin } from '../plugin-mHMV2-SG.mjs';
+import { U as UniqueRowConfigData, g as UniqueColumnConfigData } from '../types-_64SXyva.mjs';
+export { h as UniqueColumnConfigEntry, i as UniqueColumnConfigOptions, e as UniqueRowConfigEntry, f as UniqueRowConfigOptions } from '../types-_64SXyva.mjs';
+import 'convex/values';
+
+/**
+ * Creates a validate plugin that enforces row uniqueness based on database indexes.
+ *
+ * This plugin checks that the combination of column values defined in your indexes
+ * doesn't already exist in the database before allowing insert/patch operations.
+ *
+ * @param schema - Your Convex schema definition
+ * @param config - Object mapping table names to arrays of index configs
+ * @returns A ValidatePlugin for use with verifyConfig
+ *
+ * @example
+ * ```ts
+ * // Simple shorthand - just index names
+ * const uniqueRow = uniqueRowConfig(schema, {
+ *   posts: ['by_slug'],
+ *   users: ['by_email', 'by_username'],
+ * });
+ *
+ * // With options
+ * const uniqueRow = uniqueRowConfig(schema, {
+ *   posts: [
+ *     { index: 'by_author_slug', identifiers: ['_id', 'authorId'] },
+ *   ],
+ * });
+ *
+ * // Use with verifyConfig
+ * const { insert, patch } = verifyConfig(schema, {
+ *   plugins: [uniqueRow],
+ * });
+ * ```
+ */
+declare const uniqueRowConfig: <S extends SchemaDefinition<GenericSchema, boolean>, DataModel extends DataModelFromSchemaDefinition<S>, const C extends UniqueRowConfigData<DataModel>>(schema: S, config: C) => ValidatePlugin<"uniqueRow", C>;
+
+/**
+ * Creates a validate plugin that enforces column uniqueness using single-column indexes.
+ *
+ * This is useful when you have a column that must be unique across all rows,
+ * like usernames or email addresses.
+ *
+ * The column name is derived from the index name by removing the 'by_' prefix.
+ * For example, 'by_username' checks the 'username' column.
+ *
+ * @param schema - Your Convex schema definition
+ * @param config - Object mapping table names to arrays of index configs
+ * @returns A ValidatePlugin for use with verifyConfig
+ *
+ * @example
+ * ```ts
+ * // Shorthand: just pass index names as strings
+ * const uniqueColumn = uniqueColumnConfig(schema, {
+ *   users: ['by_username', 'by_email'],
+ *   organizations: ['by_slug'],
+ * });
+ *
+ * // Full config: pass objects with options
+ * const uniqueColumn = uniqueColumnConfig(schema, {
+ *   users: [
+ *     { index: 'by_username', identifiers: ['_id', 'userId'] },
+ *     { index: 'by_email', identifiers: ['_id'] },
+ *   ],
+ * });
+ *
+ * // Mix and match
+ * const uniqueColumn = uniqueColumnConfig(schema, {
+ *   users: [
+ *     'by_username',  // shorthand
+ *     { index: 'by_email', identifiers: ['_id', 'clerkId'] },  // full config
+ *   ],
+ * });
+ *
+ * // Use with verifyConfig
+ * const { insert, patch } = verifyConfig(schema, {
+ *   plugins: [uniqueColumn],
+ * });
+ * ```
+ */
+declare const uniqueColumnConfig: <S extends SchemaDefinition<GenericSchema, boolean>, DataModel extends DataModelFromSchemaDefinition<S>, const C extends UniqueColumnConfigData<DataModel>>(_schema: S, config: C) => ValidatePlugin<"uniqueColumn", C>;
+
+export { UniqueColumnConfigData, UniqueRowConfigData, uniqueColumnConfig, uniqueRowConfig };

package/dist/plugins/index.d.ts

@@ -0,0 +1,85 @@
+import { SchemaDefinition, GenericSchema, DataModelFromSchemaDefinition } from 'convex/server';
+import { a as ValidatePlugin } from '../plugin-BjJ7yjrc.js';
+import { U as UniqueRowConfigData, g as UniqueColumnConfigData } from '../types-_64SXyva.js';
+export { h as UniqueColumnConfigEntry, i as UniqueColumnConfigOptions, e as UniqueRowConfigEntry, f as UniqueRowConfigOptions } from '../types-_64SXyva.js';
+import 'convex/values';
+
+/**
+ * Creates a validate plugin that enforces row uniqueness based on database indexes.
+ *
+ * This plugin checks that the combination of column values defined in your indexes
+ * doesn't already exist in the database before allowing insert/patch operations.
+ *
+ * @param schema - Your Convex schema definition
+ * @param config - Object mapping table names to arrays of index configs
+ * @returns A ValidatePlugin for use with verifyConfig
+ *
+ * @example
+ * ```ts
+ * // Simple shorthand - just index names
+ * const uniqueRow = uniqueRowConfig(schema, {
+ *   posts: ['by_slug'],
+ *   users: ['by_email', 'by_username'],
+ * });
+ *
+ * // With options
+ * const uniqueRow = uniqueRowConfig(schema, {
+ *   posts: [
+ *     { index: 'by_author_slug', identifiers: ['_id', 'authorId'] },
+ *   ],
+ * });
+ *
+ * // Use with verifyConfig
+ * const { insert, patch } = verifyConfig(schema, {
+ *   plugins: [uniqueRow],
+ * });
+ * ```
+ */
+declare const uniqueRowConfig: <S extends SchemaDefinition<GenericSchema, boolean>, DataModel extends DataModelFromSchemaDefinition<S>, const C extends UniqueRowConfigData<DataModel>>(schema: S, config: C) => ValidatePlugin<"uniqueRow", C>;
+
+/**
+ * Creates a validate plugin that enforces column uniqueness using single-column indexes.
+ *
+ * This is useful when you have a column that must be unique across all rows,
+ * like usernames or email addresses.
+ *
+ * The column name is derived from the index name by removing the 'by_' prefix.
+ * For example, 'by_username' checks the 'username' column.
+ *
+ * @param schema - Your Convex schema definition
+ * @param config - Object mapping table names to arrays of index configs
+ * @returns A ValidatePlugin for use with verifyConfig
+ *
+ * @example
+ * ```ts
+ * // Shorthand: just pass index names as strings
+ * const uniqueColumn = uniqueColumnConfig(schema, {
+ *   users: ['by_username', 'by_email'],
+ *   organizations: ['by_slug'],
+ * });
+ *
+ * // Full config: pass objects with options
+ * const uniqueColumn = uniqueColumnConfig(schema, {
+ *   users: [
+ *     { index: 'by_username', identifiers: ['_id', 'userId'] },
+ *     { index: 'by_email', identifiers: ['_id'] },
+ *   ],
+ * });
+ *
+ * // Mix and match
+ * const uniqueColumn = uniqueColumnConfig(schema, {
+ *   users: [
+ *     'by_username',  // shorthand
+ *     { index: 'by_email', identifiers: ['_id', 'clerkId'] },  // full config
+ *   ],
+ * });
+ *
+ * // Use with verifyConfig
+ * const { insert, patch } = verifyConfig(schema, {
+ *   plugins: [uniqueColumn],
+ * });
+ * ```
+ */
+declare const uniqueColumnConfig: <S extends SchemaDefinition<GenericSchema, boolean>, DataModel extends DataModelFromSchemaDefinition<S>, const C extends UniqueColumnConfigData<DataModel>>(_schema: S, config: C) => ValidatePlugin<"uniqueColumn", C>;
+
+export { UniqueColumnConfigData, UniqueRowConfigData, uniqueColumnConfig, uniqueRowConfig };

package/dist/plugins/index.js

@@ -0,0 +1,317 @@
+"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/plugins/index.ts
+var plugins_exports = {};
+__export(plugins_exports, {
+  uniqueColumnConfig: () => uniqueColumnConfig,
+  uniqueRowConfig: () => uniqueRowConfig
+});
+module.exports = __toCommonJS(plugins_exports);
+
+// src/plugins/uniqueRowConfig.ts
+var import_values = require("convex/values");
+
+// src/core/plugin.ts
+function createValidatePlugin(type, config, verify) {
+  return {
+    _type: type,
+    config,
+    verify
+  };
+}
+
+// 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
+  };
+}
+
+// src/utils/helpers.ts
+var getTableIndexes = (schema, tableName) => {
+  return schema.tables[tableName][" indexes"]();
+};
+var constructColumnData = (fields, data, {
+  allowNullishValue = false,
+  allOrNothing = true
+}) => {
+  const lengthOfFields = fields.length;
+  const columnData = fields.map((_, index) => {
+    const column = fields?.[index];
+    const value = data?.[column];
+    if (!column || !allowNullishValue && !value) {
+      return;
+    }
+    return {
+      column,
+      value
+    };
+  }).filter((e) => !!e);
+  if (allOrNothing && columnData.length !== lengthOfFields) {
+    console.warn(
+      "The index was NOT supplied with the same amount data as there was fields. This warning only appears when setting `allOrNothing` to `true`.",
+      "`fields: `",
+      fields,
+      "`columnData: `",
+      columnData
+    );
+    return null;
+  }
+  return columnData.length > 0 ? columnData : null;
+};
+var constructIndexData = (schema, tableName, indexConfig) => {
+  if (!indexConfig) {
+    return;
+  }
+  const tableConfig = indexConfig?.[tableName];
+  if (!tableConfig) {
+    return;
+  }
+  return tableConfig.map((entry) => {
+    const normalized = normalizeIndexConfigEntry(entry);
+    const { index, identifiers, ...rest } = normalized;
+    const fields = getTableIndexes(schema, tableName).find(
+      (i) => i.indexDescriptor == index
+    )?.fields;
+    if (!fields) {
+      throw new Error(`Error in 'constructIndexData()'. No fields found for index: [${index}]`);
+    }
+    const identifierMap = new Map(
+      [...identifiers, "_id"].map((i) => [String(i), String(i)])
+    );
+    return {
+      name: index,
+      fields,
+      identifiers: Array.from(identifierMap.values()),
+      ...rest
+    };
+  });
+};
+
+// src/plugins/uniqueRowConfig.ts
+var uniqueRowConfig = (schema, config) => {
+  const uniqueRowError = (message) => {
+    throw new import_values.ConvexError({
+      message,
+      code: "UNIQUE_ROW_VERIFICATION_ERROR"
+    });
+  };
+  const verifyUniqueness = async (context, data, tableName) => {
+    const { ctx, operation, patchId, onFail } = context;
+    const indexesData = constructIndexData(schema, tableName, config);
+    if (!indexesData && !!config[tableName]) {
+      uniqueRowError(`Index data was not found where there should have been.`);
+    }
+    if (!indexesData) {
+      return data;
+    }
+    for (const indexInfo of indexesData) {
+      const { name, fields, identifiers, ...rest } = indexInfo;
+      const _options = rest;
+      if (!fields[0] && !fields[1]) {
+        uniqueRowError(
+          `Error in 'verifyRowUniqueness()'. There must be two columns to test against. If you are attempting to enforce a unique column, use the 'uniqueColumns' config option.`
+        );
+      }
+      const columnData = constructColumnData(fields, data, {});
+      const getExisting = async (cd) => {
+        let existingByIndex = [];
+        if (!cd) {
+          existingByIndex = [];
+        } else {
+          existingByIndex = await ctx.db.query(tableName).withIndex(
+            name,
+            (q) => cd.reduce((query, { column, value }) => query.eq(column, value), q)
+          ).collect();
+        }
+        if (existingByIndex.length > 1) {
+          console.warn(
+            `There was more than one existing result found for index ${name}. Check the following IDs:`,
+            existingByIndex.map((r) => r._id)
+          );
+          console.warn(
+            `It is recommended that you triage the rows listed above since they have data that go against a rule of row uniqueness.`
+          );
+        }
+        return existingByIndex.length > 0 ? existingByIndex[0] : null;
+      };
+      const existing = await getExisting(columnData);
+      if (operation === "insert") {
+        if (!existing) {
+          continue;
+        }
+        onFail?.({
+          uniqueRow: {
+            existingData: existing
+          }
+        });
+        uniqueRowError(
+          `Unable to [${operation}] document. In table [${tableName}], there is an existing row that has the same data combination in the columns: [${fields.join(`, `)}].`
+        );
+      }
+      if (operation === "patch") {
+        if (!patchId) {
+          uniqueRowError(`Unable to patch document without an id.`);
+        }
+        const matchedToExisting = (_existing, _data) => {
+          let idMatchedToExisting = null;
+          if (_existing) {
+            for (const identifier of identifiers) {
+              if (_existing[identifier] && _data[identifier] && _existing[identifier] === _data[identifier] || identifier === "_id" && _existing[identifier] === patchId) {
+                idMatchedToExisting = String(identifier);
+                break;
+              }
+            }
+          }
+          return idMatchedToExisting;
+        };
+        const checkExisting = (_existing, _data) => {
+          const matchedId = matchedToExisting(_existing, _data);
+          if (!_existing) {
+            return;
+          }
+          if (matchedId) {
+            return;
+          } else {
+            onFail?.({
+              uniqueRow: {
+                existingData: _existing
+              }
+            });
+            uniqueRowError(
+              `In '${tableName}' table, there already exists a value match of the columns: [${fields.join(`,`)}].`
+            );
+          }
+        };
+        if (!existing && !columnData && patchId) {
+          const match = await ctx.db.get(patchId);
+          if (!match) {
+            uniqueRowError(`No document found for id ${patchId}`);
+            return data;
+          }
+          const extensiveColumnData = constructColumnData(
+            fields,
+            {
+              ...match,
+              ...data
+            },
+            {}
+          );
+          if (extensiveColumnData) {
+            const extensiveExisting = await getExisting(extensiveColumnData);
+            checkExisting(extensiveExisting, data);
+          } else {
+            uniqueRowError(`Incomplete data when there should have been enough.`);
+          }
+        } else {
+          checkExisting(existing, data);
+        }
+      }
+    }
+    return data;
+  };
+  return createValidatePlugin("uniqueRow", config, {
+    insert: async (context, data) => {
+      return verifyUniqueness(context, data, context.tableName);
+    },
+    patch: async (context, data) => {
+      return verifyUniqueness(context, data, context.tableName);
+    }
+  });
+};
+
+// src/plugins/uniqueColumnConfig.ts
+var import_values2 = require("convex/values");
+var uniqueColumnConfig = (_schema, config) => {
+  const uniqueColumnError = (message) => {
+    throw new import_values2.ConvexError({
+      message,
+      code: "UNIQUE_COLUMN_VERIFICATION_ERROR"
+    });
+  };
+  const verifyUniqueness = async (context, data) => {
+    const { ctx, tableName, patchId, onFail } = context;
+    const tableConfig = config[tableName];
+    if (!tableConfig) {
+      return data;
+    }
+    for (const entry of tableConfig) {
+      const { index, identifiers } = normalizeIndexConfigEntry(
+        entry
+      );
+      const columnName = index.replace("by_", "");
+      const value = data[columnName];
+      if (value === void 0 || value === null) {
+        continue;
+      }
+      const existing = await ctx.db.query(tableName).withIndex(index, (q) => q.eq(columnName, value)).unique();
+      if (!existing) {
+        continue;
+      }
+      let isOwnDocument = false;
+      for (const identifier of identifiers) {
+        if (identifier === "_id" && patchId && existing._id === patchId) {
+          isOwnDocument = true;
+          break;
+        }
+        if (existing[identifier] && data[identifier] && existing[identifier] === data[identifier]) {
+          isOwnDocument = true;
+          break;
+        }
+      }
+      if (isOwnDocument) {
+        continue;
+      }
+      onFail?.({
+        uniqueColumn: {
+          conflictingColumn: columnName,
+          existingData: existing
+        }
+      });
+      uniqueColumnError(
+        `In [${tableName}] table, there already exists value "${value}" in column [${columnName}].`
+      );
+    }
+    return data;
+  };
+  return createValidatePlugin("uniqueColumn", config, {
+    insert: async (context, data) => {
+      return verifyUniqueness(context, data);
+    },
+    patch: async (context, data) => {
+      return verifyUniqueness(context, data);
+    }
+  });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  uniqueColumnConfig,
+  uniqueRowConfig
+});
+//# sourceMappingURL=index.js.map