convex-cms 0.0.1

package/src/component/lib/referenceResolver.ts

@@ -0,0 +1,430 @@
+/**
+ * Reference Resolution Utilities
+ *
+ * Provides functions for resolving and populating content references.
+ * These utilities help with fetching referenced content entries and
+ * validating reference constraints.
+ */
+
+import { Id } from "../_generated/dataModel.js";
+import { isDeleted } from "./softDelete.js";
+import { QueryCtx } from "../_generated/server.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * A single reference value (content entry ID as string)
+ */
+export type SingleReference = string;
+
+/**
+ * Multiple reference values (array of content entry IDs)
+ */
+export type MultipleReferences = string[];
+
+/**
+ * Reference field value - either single or multiple based on field configuration
+ */
+export type ReferenceValue = SingleReference | MultipleReferences;
+
+/**
+ * A resolved reference with the full content entry data
+ */
+export interface ResolvedReference {
+	/** The content entry ID */
+	id: string;
+	/** The content type name */
+	contentTypeName: string;
+	/** The content type display name */
+	contentTypeDisplayName: string;
+	/** The entry's slug */
+	slug: string;
+	/** The entry's status (supports custom workflow states) */
+	status: string;
+	/** The entry's data (field values) */
+	data: Record<string, unknown>;
+	/** Whether the entry exists and is not deleted */
+	exists: boolean;
+}
+
+/**
+ * Options for resolving references
+ */
+export interface ResolveOptions {
+	/** Include soft-deleted entries (default: false) */
+	includeDeleted?: boolean;
+	/** Only return published entries (default: false) */
+	publishedOnly?: boolean;
+	/** Specific fields to include from the entry data (default: all) */
+	fields?: string[];
+}
+
+/**
+ * Result of a reference resolution operation
+ */
+export interface ResolveResult {
+	/** Successfully resolved references */
+	resolved: ResolvedReference[];
+	/** IDs that could not be resolved (not found or deleted) */
+	unresolved: string[];
+}
+
+// =============================================================================
+// Core Resolution Functions
+// =============================================================================
+
+/**
+ * Resolve a single reference to its full content entry.
+ *
+ * @param ctx - Convex query context
+ * @param referenceId - The content entry ID to resolve
+ * @param options - Resolution options
+ * @returns The resolved reference or null if not found
+ *
+ * @example
+ * ```typescript
+ * // In a query handler:
+ * const author = await resolveReference(ctx, entry.data.authorId);
+ * if (author) {
+ *   console.log("Author:", author.data.name);
+ * }
+ * ```
+ */
+export async function resolveReference(
+	ctx: QueryCtx,
+	referenceId: string,
+	options: ResolveOptions = {},
+): Promise<ResolvedReference | null> {
+	const { includeDeleted = false, publishedOnly = false } = options;
+
+	try {
+		// Get the content entry
+		const entry = await ctx.db.get(referenceId as Id<"contentEntries">);
+
+		if (!entry) {
+			return null;
+		}
+
+		// Check soft-delete status
+		if (!includeDeleted && isDeleted(entry)) {
+			return null;
+		}
+
+		// Check published status
+		if (publishedOnly && entry.status !== "published") {
+			return null;
+		}
+
+		// Get the content type for this entry
+		const contentType = await ctx.db.get(entry.contentTypeId);
+
+		if (!contentType || isDeleted(contentType)) {
+			return null;
+		}
+
+		// Filter fields if specified
+		let data = entry.data as Record<string, unknown>;
+		if (options.fields && options.fields.length > 0) {
+			const filteredData: Record<string, unknown> = {};
+			for (const field of options.fields) {
+				if (field in data) {
+					filteredData[field] = data[field];
+				}
+			}
+			data = filteredData;
+		}
+
+		return {
+			id: referenceId,
+			contentTypeName: contentType.name,
+			contentTypeDisplayName: contentType.displayName,
+			slug: entry.slug,
+			status: entry.status,
+			data,
+			exists: true,
+		};
+	} catch {
+		// Invalid ID format or other error
+		return null;
+	}
+}
+
+/**
+ * Resolve multiple references to their full content entries.
+ *
+ * @param ctx - Convex query context
+ * @param referenceIds - Array of content entry IDs to resolve
+ * @param options - Resolution options
+ * @returns Result with resolved references and unresolved IDs
+ *
+ * @example
+ * ```typescript
+ * // In a query handler:
+ * const result = await resolveReferences(ctx, entry.data.relatedPostIds, {
+ *   publishedOnly: true,
+ * });
+ *
+ * console.log("Found:", result.resolved.length);
+ * console.log("Missing:", result.unresolved);
+ * ```
+ */
+export async function resolveReferences(
+	ctx: QueryCtx,
+	referenceIds: string[],
+	options: ResolveOptions = {},
+): Promise<ResolveResult> {
+	const resolved: ResolvedReference[] = [];
+	const unresolved: string[] = [];
+
+	// Resolve each reference in parallel for efficiency
+	const promises = referenceIds.map(async (id) => {
+		const result = await resolveReference(ctx, id, options);
+		return { id, result };
+	});
+
+	const results = await Promise.all(promises);
+
+	for (const { id, result } of results) {
+		if (result) {
+			resolved.push(result);
+		} else {
+			unresolved.push(id);
+		}
+	}
+
+	return { resolved, unresolved };
+}
+
+/**
+ * Check if a reference ID points to a valid, existing content entry.
+ *
+ * @param ctx - Convex query context
+ * @param referenceId - The content entry ID to check
+ * @param allowedContentTypes - Optional array of allowed content type names
+ * @returns Object with validity status and optional error message
+ *
+ * @example
+ * ```typescript
+ * // Validate a reference before saving:
+ * const check = await isValidReference(ctx, authorId, ["user"]);
+ * if (!check.valid) {
+ *   throw new Error(check.error);
+ * }
+ * ```
+ */
+export async function isValidReference(
+	ctx: QueryCtx,
+	referenceId: string,
+	allowedContentTypes?: string[],
+): Promise<{ valid: boolean; error?: string }> {
+	try {
+		// Get the content entry
+		const entry = await ctx.db.get(referenceId as Id<"contentEntries">);
+
+		if (!entry) {
+			return { valid: false, error: `Content entry not found: ${referenceId}` };
+		}
+
+		// Check soft-delete status
+		if (isDeleted(entry)) {
+			return {
+				valid: false,
+				error: `Content entry has been deleted: ${referenceId}`,
+			};
+		}
+
+		// If content type constraints specified, check them
+		if (allowedContentTypes && allowedContentTypes.length > 0) {
+			const contentType = await ctx.db.get(entry.contentTypeId);
+
+			if (!contentType) {
+				return {
+					valid: false,
+					error: `Content type not found for entry: ${referenceId}`,
+				};
+			}
+
+			if (!allowedContentTypes.includes(contentType.name)) {
+				return {
+					valid: false,
+					error: `Expected content type: ${allowedContentTypes.join(
+						" or ",
+					)}. Got: ${contentType.name}`,
+				};
+			}
+		}
+
+		return { valid: true };
+	} catch {
+		return {
+			valid: false,
+			error: `Invalid reference ID format: ${referenceId}`,
+		};
+	}
+}
+
+/**
+ * Validate all references in a content entry's data.
+ *
+ * Iterates through all reference fields and validates that each reference
+ * points to a valid, existing content entry of the allowed type.
+ *
+ * @param ctx - Convex query context
+ * @param data - The content entry data containing reference fields
+ * @param fields - Array of field definitions (to identify reference fields)
+ * @returns Object with overall validity and array of errors
+ *
+ * @example
+ * ```typescript
+ * // Validate all references before creating/updating an entry:
+ * const validation = await validateAllReferences(ctx, data, contentType.fields);
+ * if (!validation.valid) {
+ *   throw new Error(validation.errors.join(", "));
+ * }
+ * ```
+ */
+export async function validateAllReferences(
+	ctx: QueryCtx,
+	data: Record<string, unknown>,
+	fields: Array<{
+		name: string;
+		type: string;
+		options?: {
+			allowedContentTypes?: string[];
+			multiple?: boolean;
+		};
+	}>,
+): Promise<{ valid: boolean; errors: string[] }> {
+	const errors: string[] = [];
+
+	// Find all reference fields
+	const referenceFields = fields.filter((f) => f.type === "reference");
+
+	for (const field of referenceFields) {
+		const value = data[field.name];
+
+		if (value === null || value === undefined) {
+			continue; // Skip empty values (required validation is separate)
+		}
+
+		const allowedTypes = field.options?.allowedContentTypes;
+		const multiple = field.options?.multiple ?? false;
+
+		if (multiple) {
+			// Validate array of references
+			if (!Array.isArray(value)) {
+				errors.push(`${field.name}: Expected array of references`);
+				continue;
+			}
+
+			for (const refId of value) {
+				if (typeof refId !== "string") {
+					errors.push(`${field.name}: Invalid reference ID type`);
+					continue;
+				}
+
+				const check = await isValidReference(ctx, refId, allowedTypes);
+				if (!check.valid) {
+					errors.push(`${field.name}: ${check.error}`);
+				}
+			}
+		} else {
+			// Validate single reference
+			if (typeof value !== "string") {
+				errors.push(`${field.name}: Expected string reference ID`);
+				continue;
+			}
+
+			const check = await isValidReference(ctx, value, allowedTypes);
+			if (!check.valid) {
+				errors.push(`${field.name}: ${check.error}`);
+			}
+		}
+	}
+
+	return {
+		valid: errors.length === 0,
+		errors,
+	};
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Extract all reference IDs from a content entry's data.
+ *
+ * @param data - The content entry data
+ * @param fields - Array of field definitions
+ * @returns Array of all reference IDs found in the data
+ */
+export function extractReferenceIds(
+	data: Record<string, unknown>,
+	fields: Array<{
+		name: string;
+		type: string;
+		options?: { multiple?: boolean };
+	}>,
+): string[] {
+	const ids: string[] = [];
+
+	const referenceFields = fields.filter((f) => f.type === "reference");
+
+	for (const field of referenceFields) {
+		const value = data[field.name];
+
+		if (value === null || value === undefined) {
+			continue;
+		}
+
+		const multiple = field.options?.multiple ?? false;
+
+		if (multiple && Array.isArray(value)) {
+			for (const id of value) {
+				if (typeof id === "string") {
+					ids.push(id);
+				}
+			}
+		} else if (typeof value === "string") {
+			ids.push(value);
+		}
+	}
+
+	return ids;
+}
+
+/**
+ * Get the content type name for a content entry ID.
+ *
+ * This is a helper function for the `validateReferenceContentType` function
+ * in the validation module.
+ *
+ * @param ctx - Convex query context
+ * @param entryId - The content entry ID
+ * @returns The content type name or null if not found
+ */
+export async function getContentTypeName(
+	ctx: QueryCtx,
+	entryId: string,
+): Promise<string | null> {
+	try {
+		const entry = await ctx.db.get(entryId as Id<"contentEntries">);
+
+		if (!entry || isDeleted(entry)) {
+			return null;
+		}
+
+		const contentType = await ctx.db.get(entry.contentTypeId);
+
+		if (!contentType || isDeleted(contentType)) {
+			return null;
+		}
+
+		return contentType.name;
+	} catch {
+		return null;
+	}
+}

package/src/component/lib/slugGenerator.ts

@@ -0,0 +1,262 @@
+/**
+ * Slug Generator Utility
+ *
+ * Generates URL-friendly slugs from content titles.
+ * Handles special characters, unicode, and ensures slug format consistency.
+ */
+
+/**
+ * Options for slug generation
+ */
+export interface SlugOptions {
+  /** Maximum length of the generated slug (default: 100) */
+  maxLength?: number;
+  /** Separator character to use (default: '-') */
+  separator?: string;
+  /** Whether to lowercase the slug (default: true) */
+  lowercase?: boolean;
+  /** Custom replacements for specific characters */
+  customReplacements?: Record<string, string>;
+}
+
+/**
+ * Default character replacements for common special characters and unicode
+ */
+const DEFAULT_REPLACEMENTS: Record<string, string> = {
+  // German
+  ä: "ae",
+  ö: "oe",
+  ü: "ue",
+  ß: "ss",
+  Ä: "ae",
+  Ö: "oe",
+  Ü: "ue",
+  // French
+  à: "a",
+  â: "a",
+  ç: "c",
+  é: "e",
+  è: "e",
+  ê: "e",
+  ë: "e",
+  î: "i",
+  ï: "i",
+  ô: "o",
+  ù: "u",
+  û: "u",
+  ÿ: "y",
+  œ: "oe",
+  æ: "ae",
+  // Spanish
+  ñ: "n",
+  Ñ: "n",
+  // Polish
+  ą: "a",
+  Ą: "a",
+  ć: "c",
+  Ć: "c",
+  ę: "e",
+  Ę: "e",
+  ł: "l",
+  Ł: "l",
+  ń: "n",
+  Ń: "n",
+  ó: "o",
+  Ó: "o",
+  ś: "s",
+  Ś: "s",
+  ź: "z",
+  Ź: "z",
+  ż: "z",
+  Ż: "z",
+  // Nordic
+  å: "a",
+  Å: "a",
+  ø: "o",
+  Ø: "o",
+  // Other common
+  ð: "d",
+  þ: "th",
+  // Symbols
+  "&": "and",
+  "@": "at",
+  "#": "hash",
+  "%": "percent",
+  "+": "plus",
+  "=": "equals",
+  // Punctuation to remove (replaced with empty string to prevent separator)
+  "'": "",
+  "\u2018": "", // left single quote '
+  "\u2019": "", // right single quote '
+  "\u201C": "", // left double quote "
+  "\u201D": "", // right double quote "
+};
+
+/**
+ * Generates a URL-friendly slug from a given title string.
+ *
+ * @param title - The input string to convert to a slug
+ * @param options - Optional configuration for slug generation
+ * @returns A URL-friendly slug string
+ *
+ * @example
+ * ```typescript
+ * generateSlug("Hello World!") // "hello-world"
+ * generateSlug("Café & Restaurant") // "cafe-and-restaurant"
+ * generateSlug("日本語タイトル") // "ri-ben-yu-taitoru"
+ * generateSlug("  Multiple   Spaces  ") // "multiple-spaces"
+ * ```
+ */
+export function generateSlug(title: string, options: SlugOptions = {}): string {
+  const {
+    maxLength = 100,
+    separator = "-",
+    lowercase = true,
+    customReplacements = {},
+  } = options;
+
+  if (!title || typeof title !== "string") {
+    return "";
+  }
+
+  // Merge custom replacements with defaults (custom takes precedence)
+  const replacements = { ...DEFAULT_REPLACEMENTS, ...customReplacements };
+
+  let slug = title.trim();
+
+  // Apply character replacements
+  for (const [char, replacement] of Object.entries(replacements)) {
+    slug = slug.split(char).join(replacement);
+  }
+
+  // Normalize unicode to decomposed form, then remove combining diacritical marks
+  slug = slug.normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+
+  // Convert to lowercase if requested
+  if (lowercase) {
+    slug = slug.toLowerCase();
+  }
+
+  // Replace any non-alphanumeric characters (except separator) with separator
+  // This regex keeps letters (including unicode letters after normalization), numbers
+  const separatorRegex = new RegExp(`[^a-z0-9${escapeRegex(separator)}]`, "gi");
+  slug = slug.replace(separatorRegex, separator);
+
+  // Collapse multiple consecutive separators into one
+  const multipleSeparatorRegex = new RegExp(`${escapeRegex(separator)}+`, "g");
+  slug = slug.replace(multipleSeparatorRegex, separator);
+
+  // Remove leading and trailing separators
+  const trimSeparatorRegex = new RegExp(
+    `^${escapeRegex(separator)}|${escapeRegex(separator)}$`,
+    "g"
+  );
+  slug = slug.replace(trimSeparatorRegex, "");
+
+  // Truncate to max length, but don't cut words in the middle
+  if (slug.length > maxLength) {
+    slug = truncateSlug(slug, maxLength, separator);
+  }
+
+  return slug;
+}
+
+/**
+ * Escapes special regex characters in a string
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Truncates a slug to a maximum length without cutting words
+ */
+function truncateSlug(
+  slug: string,
+  maxLength: number,
+  separator: string
+): string {
+  if (slug.length <= maxLength) {
+    return slug;
+  }
+
+  // Find the last separator before the max length
+  const truncated = slug.substring(0, maxLength);
+  const lastSeparatorIndex = truncated.lastIndexOf(separator);
+
+  if (lastSeparatorIndex > 0) {
+    return truncated.substring(0, lastSeparatorIndex);
+  }
+
+  // If no separator found, just truncate at maxLength
+  return truncated;
+}
+
+/**
+ * Validates if a string is a valid slug format
+ *
+ * @param slug - The string to validate
+ * @param separator - The separator character (default: '-')
+ * @returns True if the string is a valid slug
+ *
+ * @example
+ * ```typescript
+ * isValidSlug("hello-world") // true
+ * isValidSlug("Hello World") // false
+ * isValidSlug("hello--world") // false
+ * isValidSlug("-hello-world") // false
+ * ```
+ */
+export function isValidSlug(slug: string, separator: string = "-"): boolean {
+  if (!slug || typeof slug !== "string") {
+    return false;
+  }
+
+  // Must be lowercase alphanumeric with single separators
+  const validSlugRegex = new RegExp(
+    `^[a-z0-9]+(?:${escapeRegex(separator)}[a-z0-9]+)*$`
+  );
+
+  return validSlugRegex.test(slug);
+}
+
+/**
+ * Generates a unique slug by appending a numeric suffix if needed.
+ * This is a helper that can be used with a uniqueness check function.
+ *
+ * @param baseSlug - The base slug to make unique
+ * @param isUnique - Async function that checks if a slug is unique
+ * @param maxAttempts - Maximum number of suffix attempts (default: 100)
+ * @returns A unique slug
+ *
+ * @example
+ * ```typescript
+ * const checkUnique = async (slug: string) => {
+ *   return !(await db.query("entries").withSlug(slug).first());
+ * };
+ * const uniqueSlug = await generateUniqueSlug("hello-world", checkUnique);
+ * // Returns "hello-world" if unique, or "hello-world-1", "hello-world-2", etc.
+ * ```
+ */
+export async function generateUniqueSlug(
+  baseSlug: string,
+  isUnique: (slug: string) => Promise<boolean>,
+  maxAttempts: number = 100
+): Promise<string> {
+  // Check if base slug is already unique
+  if (await isUnique(baseSlug)) {
+    return baseSlug;
+  }
+
+  // Try appending numeric suffixes
+  for (let i = 1; i <= maxAttempts; i++) {
+    const candidateSlug = `${baseSlug}-${i}`;
+    if (await isUnique(candidateSlug)) {
+      return candidateSlug;
+    }
+  }
+
+  // Fallback: append timestamp if all numeric suffixes are taken
+  const timestamp = Date.now().toString(36);
+  return `${baseSlug}-${timestamp}`;
+}