convex-cms 0.0.2 → 0.0.3

package/src/component/lib/referenceResolver.ts

@@ -1,430 +0,0 @@
-/**
- * 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

@@ -1,262 +0,0 @@
-/**
- * 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}`;
-}