convex-cms 0.0.1 → 0.0.3

package/src/component/lib/slugUniqueness.ts

@@ -1,333 +0,0 @@
-/**
- * Slug Uniqueness Utilities
- *
- * Provides functions for checking slug uniqueness within content type scope
- * and generating unique slugs with incremental suffixes when conflicts exist.
- */
-
-import {
-	generateSlug,
-	generateUniqueSlug,
-	isValidSlug,
-} from "./slugGenerator.js";
-
-/**
- * Options for slug uniqueness checking
- */
-export interface SlugUniquenessOptions {
-	/** Maximum number of suffix attempts before falling back to timestamp (default: 100) */
-	maxAttempts?: number;
-	/** Separator character used in slugs (default: '-') */
-	separator?: string;
-	/** ID of the current entry to exclude from uniqueness check (for updates) */
-	excludeEntryId?: string;
-}
-
-/**
- * Result of a slug uniqueness check
- */
-export interface SlugCheckResult {
-	/** Whether the slug is unique */
-	isUnique: boolean;
-	/** The existing entry ID that has this slug (if not unique) */
-	existingEntryId?: string;
-	/** Suggested alternative slug if not unique */
-	suggestedSlug?: string;
-}
-
-/**
- * Entry data structure for uniqueness checking
- */
-export interface SlugEntry {
-	/** The entry's unique identifier */
-	_id: string;
-	/** The entry's slug */
-	slug: string;
-	/** Soft delete timestamp (null/undefined if not deleted) */
-	deletedAt?: number | null;
-}
-
-/**
- * Function type for querying existing entries by slug within a content type
- */
-export type SlugQueryFn = (slug: string) => Promise<SlugEntry | null>;
-
-/**
- * Function type for querying all entries with a slug prefix within a content type
- * Used for finding the next available suffix number
- */
-export type SlugPrefixQueryFn = (slugPrefix: string) => Promise<SlugEntry[]>;
-
-/**
- * Checks if a slug is unique within a content type scope.
- *
- * @param slug - The slug to check
- * @param queryFn - Function that queries the database for entries with the given slug
- * @param options - Configuration options
- * @returns Result indicating uniqueness and suggestions
- *
- * @example
- * ```typescript
- * // In a Convex mutation
- * const queryFn = async (slug: string) => {
- *   return await ctx.db
- *     .query("contentEntries")
- *     .withIndex("by_content_type_and_slug", (q) =>
- *       q.eq("contentTypeId", contentTypeId).eq("slug", slug)
- *     )
- *     .filter((q) => q.eq(q.field("deletedAt"), undefined))
- *     .first();
- * };
- *
- * const result = await checkSlugUniqueness("my-post", queryFn);
- * if (!result.isUnique) {
- *   console.log(`Slug conflict with entry ${result.existingEntryId}`);
- *   console.log(`Suggested alternative: ${result.suggestedSlug}`);
- * }
- * ```
- */
-export async function checkSlugUniqueness(
-	slug: string,
-	queryFn: SlugQueryFn,
-	options: SlugUniquenessOptions = {},
-): Promise<SlugCheckResult> {
-	const { excludeEntryId } = options;
-
-	// Validate the slug format
-	if (!isValidSlug(slug, options.separator)) {
-		return {
-			isUnique: false,
-			suggestedSlug: generateSlug(slug, { separator: options.separator }),
-		};
-	}
-
-	// Query for existing entry with this slug
-	const existingEntry = await queryFn(slug);
-
-	// Check if the slug is available
-	if (!existingEntry) {
-		return { isUnique: true };
-	}
-
-	// If we're updating an entry, exclude it from the check
-	if (excludeEntryId && existingEntry._id === excludeEntryId) {
-		return { isUnique: true };
-	}
-
-	// Slug is taken - generate a suggestion
-	const isUniqueFn = async (candidateSlug: string): Promise<boolean> => {
-		const entry = await queryFn(candidateSlug);
-		if (!entry) return true;
-		if (excludeEntryId && entry._id === excludeEntryId) return true;
-		return false;
-	};
-
-	const suggestedSlug = await generateUniqueSlug(
-		slug,
-		isUniqueFn,
-		options.maxAttempts,
-	);
-
-	return {
-		isUnique: false,
-		existingEntryId: existingEntry._id,
-		suggestedSlug,
-	};
-}
-
-/**
- * Ensures a slug is unique by generating incremental suffixes if needed.
- * This is the main function to use when creating or updating content entries.
- *
- * @param baseSlug - The desired slug (or title to generate slug from)
- * @param queryFn - Function that queries the database for entries with a given slug
- * @param options - Configuration options
- * @returns A unique slug (either the original or with a numeric suffix)
- *
- * @example
- * ```typescript
- * // In a Convex mutation for creating a new entry
- * const queryFn = async (slug: string) => {
- *   return await ctx.db
- *     .query("contentEntries")
- *     .withIndex("by_content_type_and_slug", (q) =>
- *       q.eq("contentTypeId", contentTypeId).eq("slug", slug)
- *     )
- *     .filter((q) => q.eq(q.field("deletedAt"), undefined))
- *     .first();
- * };
- *
- * const uniqueSlug = await ensureUniqueSlug("my-post", queryFn);
- * // Returns "my-post" if unique, or "my-post-1", "my-post-2", etc.
- * ```
- */
-export async function ensureUniqueSlug(
-	baseSlug: string,
-	queryFn: SlugQueryFn,
-	options: SlugUniquenessOptions = {},
-): Promise<string> {
-	const { excludeEntryId, maxAttempts = 100 } = options;
-
-	// Validate and normalize the base slug
-	let slug = baseSlug;
-	if (!isValidSlug(slug, options.separator)) {
-		slug = generateSlug(slug, { separator: options.separator });
-	}
-
-	// If slug is empty after normalization, use a fallback
-	if (!slug) {
-		slug = "untitled";
-	}
-
-	// Check if the base slug is available
-	const isUniqueFn = async (candidateSlug: string): Promise<boolean> => {
-		const entry = await queryFn(candidateSlug);
-		if (!entry) return true;
-		if (excludeEntryId && entry._id === excludeEntryId) return true;
-		return false;
-	};
-
-	return generateUniqueSlug(slug, isUniqueFn, maxAttempts);
-}
-
-/**
- * Finds the next available slug suffix by analyzing existing slugs.
- * This is useful when you want to pre-compute the next suffix without
- * iterating through each number.
- *
- * @param baseSlug - The base slug to find the next suffix for
- * @param prefixQueryFn - Function that returns all entries with slugs starting with the base
- * @param options - Configuration options
- * @returns The next available slug with the appropriate suffix
- *
- * @example
- * ```typescript
- * // If entries exist with slugs: "post", "post-1", "post-2", "post-5"
- * const nextSlug = await findNextAvailableSlug("post", queryPrefixFn);
- * // Returns "post-3" (fills the gap)
- * ```
- */
-export async function findNextAvailableSlug(
-	baseSlug: string,
-	prefixQueryFn: SlugPrefixQueryFn,
-	options: SlugUniquenessOptions = {},
-): Promise<string> {
-	const { excludeEntryId, separator = "-" } = options;
-
-	// Validate the base slug
-	let slug = baseSlug;
-	if (!isValidSlug(slug, separator)) {
-		slug = generateSlug(slug, { separator });
-	}
-
-	if (!slug) {
-		slug = "untitled";
-	}
-
-	// Get all entries with this prefix
-	const existingEntries = await prefixQueryFn(slug);
-
-	// Filter out the excluded entry and soft-deleted entries
-	const activeEntries = existingEntries.filter((entry) => {
-		if (excludeEntryId && entry._id === excludeEntryId) return false;
-		if (entry.deletedAt) return false;
-		return true;
-	});
-
-	// If no entries exist with this slug, the base is available
-	const hasSlugsToCheck = activeEntries.some((entry) => {
-		return entry.slug === slug || entry.slug.startsWith(`${slug}${separator}`);
-	});
-
-	if (!hasSlugsToCheck) {
-		return slug;
-	}
-
-	// Check if base slug itself is taken
-	const baseIsTaken = activeEntries.some((entry) => entry.slug === slug);
-	if (!baseIsTaken) {
-		return slug;
-	}
-
-	// Extract existing suffix numbers
-	const suffixPattern = new RegExp(
-		`^${escapeRegex(slug)}${escapeRegex(separator)}(\\d+)$`,
-	);
-	const usedNumbers = new Set<number>();
-
-	for (const entry of activeEntries) {
-		const match = entry.slug.match(suffixPattern);
-		if (match) {
-			usedNumbers.add(parseInt(match[1], 10));
-		}
-	}
-
-	// Find the smallest available number
-	let nextNumber = 1;
-	while (usedNumbers.has(nextNumber)) {
-		nextNumber++;
-	}
-
-	return `${slug}${separator}${nextNumber}`;
-}
-
-/**
- * Escapes special regex characters in a string
- */
-function escapeRegex(str: string): string {
-	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-/**
- * Validates a slug and returns validation errors if any.
- *
- * @param slug - The slug to validate
- * @param separator - The separator character (default: '-')
- * @returns Array of validation error messages (empty if valid)
- */
-export function validateSlugFormat(
-	slug: string,
-	separator: string = "-",
-): string[] {
-	const errors: string[] = [];
-
-	if (!slug || typeof slug !== "string") {
-		errors.push("Slug is required");
-		return errors;
-	}
-
-	if (slug.length === 0) {
-		errors.push("Slug cannot be empty");
-		return errors;
-	}
-
-	if (slug.length > 100) {
-		errors.push("Slug must be 100 characters or less");
-	}
-
-	if (slug !== slug.toLowerCase()) {
-		errors.push("Slug must be lowercase");
-	}
-
-	if (slug.startsWith(separator)) {
-		errors.push(`Slug cannot start with '${separator}'`);
-	}
-
-	if (slug.endsWith(separator)) {
-		errors.push(`Slug cannot end with '${separator}'`);
-	}
-
-	const doubleSeparatorRegex = new RegExp(`${escapeRegex(separator)}{2,}`);
-	if (doubleSeparatorRegex.test(slug)) {
-		errors.push(`Slug cannot contain consecutive '${separator}' characters`);
-	}
-
-	const invalidCharsRegex = new RegExp(`[^a-z0-9${escapeRegex(separator)}]`);
-	if (invalidCharsRegex.test(slug)) {
-		errors.push(
-			"Slug can only contain lowercase letters, numbers, and hyphens",
-		);
-	}
-
-	return errors;
-}

package/src/component/lib/softDelete.ts

@@ -1,44 +0,0 @@
-/**
- * Soft-delete utilities for CMS documents.
- *
- * Provides type-safe helpers for working with documents that use
- * the soft-delete pattern (deletedAt timestamp).
- */
-
-export interface SoftDeletable {
-  deletedAt?: number;
-}
-
-export function isDeleted<T extends SoftDeletable>(doc: T): boolean {
-  return doc.deletedAt !== undefined;
-}
-
-export function isActive<T extends SoftDeletable>(doc: T): boolean {
-  return doc.deletedAt === undefined;
-}
-
-export function filterActive<T extends SoftDeletable>(docs: T[]): T[] {
-  return docs.filter(isActive);
-}
-
-export function filterDeleted<T extends SoftDeletable>(docs: T[]): T[] {
-  return docs.filter(isDeleted);
-}
-
-export function requireNotDeleted<T extends SoftDeletable>(
-  doc: T,
-  errorFactory: () => Error
-): asserts doc is T & { deletedAt: undefined } {
-  if (isDeleted(doc)) {
-    throw errorFactory();
-  }
-}
-
-export function requireDeleted<T extends SoftDeletable>(
-  doc: T,
-  errorFactory: () => Error
-): void {
-  if (!isDeleted(doc)) {
-    throw errorFactory();
-  }
-}