convex-cms 0.0.2 → 0.0.3

package/src/client/schema/defineContentType.ts

@@ -1,501 +0,0 @@
-/**
- * Content Type Schema Definition
- *
- * The `defineContentType` function creates type-safe content type definitions
- * using Convex validators. Types are automatically inferred via Convex's
- * native `Infer<typeof validator>` pattern.
- *
- * @example
- * ```typescript
- * import { v } from "convex/values";
- * import { defineContentType } from "@convex-cms/core";
- *
- * export const blogPost = defineContentType({
- *   name: "blog_post",
- *   validator: v.object({
- *     title: v.string(),
- *     slug: v.string(),
- *     content: v.string(),
- *     author: v.id("contentEntries"),
- *     category: v.optional(v.union(v.literal("tech"), v.literal("news"))),
- *     publishedAt: v.optional(v.number()),
- *   }),
- *   meta: {
- *     displayName: "Blog Post",
- *     titleField: "title",
- *     slugField: "slug",
- *     fields: {
- *       title: { label: "Title", maxLength: 200 },
- *       content: { label: "Content", renderAs: "richText", searchable: true },
- *       author: { label: "Author", renderAs: "reference" },
- *       category: { label: "Category", renderAs: "select" },
- *     },
- *   },
- * });
- * ```
- */
-
-import type { Validator } from "convex/values";
-import type {
-  ContentTypeConfig,
-  ContentTypeDefinition,
-  ContentTypeMeta,
-  FieldMeta,
-} from "./types.js";
-
-// =============================================================================
-// Content Type Name Validation
-// =============================================================================
-
-/**
- * Pattern for valid content type names.
- * - Lowercase letters, numbers, and underscores only
- * - Must start with a letter
- * - 1-50 characters
- */
-const CONTENT_TYPE_NAME_PATTERN = /^[a-z][a-z0-9_]{0,49}$/;
-
-/**
- * Validates a content type name.
- *
- * @param name - The name to validate
- * @throws Error if the name is invalid
- */
-function validateContentTypeName(name: string): void {
-  if (!name) {
-    throw new Error("Content type name is required");
-  }
-
-  if (!CONTENT_TYPE_NAME_PATTERN.test(name)) {
-    throw new Error(
-      `Invalid content type name "${name}". ` +
-        "Names must start with a lowercase letter and contain only " +
-        "lowercase letters, numbers, and underscores (1-50 characters)."
-    );
-  }
-}
-
-// =============================================================================
-// Define Content Type
-// =============================================================================
-
-/**
- * Creates a type-safe content type definition.
- *
- * This function accepts a Convex validator and CMS metadata, returning a
- * definition object that can be used for:
- * 1. **Type inference**: `Infer<typeof definition.validator>` gives the data type
- * 2. **Runtime validation**: The validator is used to validate content at runtime
- * 3. **Admin UI configuration**: Metadata provides display hints and field labels
- *
- * ## Why Convex Validators?
- *
- * Using Convex validators directly (instead of custom schema builders) provides:
- * - **Native type inference** via `Infer<typeof>` - no custom type machinery
- * - **Familiarity** - same validators used in Convex functions
- * - **Full power** - supports unions, literals, nested objects, arrays, IDs
- * - **Maintenance-free** - types are maintained by Convex
- *
- * ## Example: Basic Blog Post
- *
- * ```typescript
- * import { v, Infer } from "convex/values";
- * import { defineContentType } from "@convex-cms/core";
- *
- * export const blogPost = defineContentType({
- *   name: "blog_post",
- *   validator: v.object({
- *     title: v.string(),
- *     content: v.string(),
- *     publishedAt: v.optional(v.number()),
- *   }),
- *   meta: {
- *     displayName: "Blog Post",
- *     titleField: "title",
- *   },
- * });
- *
- * // Type is automatically inferred
- * type BlogPostData = Infer<typeof blogPost.validator>;
- * // { title: string; content: string; publishedAt?: number }
- * ```
- *
- * ## Example: Product with Variants
- *
- * ```typescript
- * export const product = defineContentType({
- *   name: "product",
- *   validator: v.object({
- *     name: v.string(),
- *     price: v.number(),
- *     description: v.optional(v.string()),
- *     variants: v.array(v.object({
- *       sku: v.string(),
- *       name: v.string(),
- *       price: v.number(),
- *       attributes: v.record(v.string(), v.string()),
- *     })),
- *     seo: v.optional(v.object({
- *       title: v.string(),
- *       description: v.string(),
- *       keywords: v.array(v.string()),
- *     })),
- *   }),
- *   meta: {
- *     displayName: "Product",
- *     titleField: "name",
- *     fields: {
- *       name: { label: "Product Name", searchable: true },
- *       price: { label: "Base Price" },
- *       variants: { label: "Variants", renderAs: "json" },
- *       seo: { label: "SEO Settings", renderAs: "json" },
- *     },
- *   },
- * });
- * ```
- *
- * @param config - The content type configuration
- * @returns A frozen content type definition object
- *
- * @typeParam TName - The literal string type of the content type name
- * @typeParam TValidator - The Convex validator type
- */
-export function defineContentType<
-  const TName extends string,
-  TValidator extends Validator<Record<string, unknown>, "required", string>
->(
-  config: ContentTypeConfig<TValidator> & { name: TName }
-): ContentTypeDefinition<TName, TValidator> {
-  // Validate the content type name at definition time
-  validateContentTypeName(config.name);
-
-  // Create the definition object
-  const definition: ContentTypeDefinition<TName, TValidator> = {
-    name: config.name,
-    validator: config.validator,
-    meta: config.meta as ContentTypeMeta,
-    _type: "content_type_definition",
-  };
-
-  // Freeze to prevent accidental mutation
-  return Object.freeze(definition);
-}
-
-// =============================================================================
-// Schema Collection Utilities
-// =============================================================================
-
-/**
- * Creates a content schema from multiple content type definitions.
- *
- * This is a convenience function that validates the schema and provides
- * runtime utilities for working with multiple content types.
- *
- * @example
- * ```typescript
- * import { createContentSchema } from "@convex-cms/core";
- *
- * export const contentSchema = createContentSchema({
- *   blogPost,
- *   author,
- *   product,
- * });
- *
- * // Get a specific definition
- * const blogDef = contentSchema.getDefinition("blog_post");
- *
- * // List all content type names
- * const names = contentSchema.getContentTypeNames();
- * // ["blog_post", "author", "product"]
- * ```
- *
- * @param definitions - An object containing content type definitions
- * @returns A schema object with utility methods
- */
-export function createContentSchema<
-  T extends Record<string, ContentTypeDefinition>
->(definitions: T): ContentSchemaInstance<T> {
-  // Build a map of name -> definition for quick lookup
-  const byName = new Map<string, ContentTypeDefinition>();
-  const names: string[] = [];
-
-  for (const [_key, def] of Object.entries(definitions)) {
-    if (byName.has(def.name)) {
-      throw new Error(
-        `Duplicate content type name "${def.name}" in schema. ` +
-          `Content type names must be unique.`
-      );
-    }
-    byName.set(def.name, def);
-    names.push(def.name);
-  }
-
-  return Object.freeze({
-    definitions,
-
-    getDefinition(name: string): ContentTypeDefinition | undefined {
-      return byName.get(name);
-    },
-
-    getContentTypeNames(): string[] {
-      return [...names];
-    },
-
-    hasContentType(name: string): boolean {
-      return byName.has(name);
-    },
-
-    getDefinitionByKey<K extends keyof T>(key: K): T[K] {
-      return definitions[key];
-    },
-  });
-}
-
-/**
- * A content schema instance with utility methods.
- */
-export interface ContentSchemaInstance<
-  T extends Record<string, ContentTypeDefinition>
-> {
-  /**
-   * The raw definitions object.
-   */
-  readonly definitions: T;
-
-  /**
-   * Get a content type definition by its name.
-   *
-   * @param name - The content type name (e.g., "blog_post")
-   * @returns The definition or undefined if not found
-   */
-  getDefinition(name: string): ContentTypeDefinition | undefined;
-
-  /**
-   * Get all content type names in the schema.
-   *
-   * @returns Array of content type names
-   */
-  getContentTypeNames(): string[];
-
-  /**
-   * Check if a content type exists in the schema.
-   *
-   * @param name - The content type name to check
-   * @returns true if the content type exists
-   */
-  hasContentType(name: string): boolean;
-
-  /**
-   * Get a content type definition by its key in the definitions object.
-   *
-   * @param key - The key used in the definitions object
-   * @returns The definition
-   */
-  getDefinitionByKey<K extends keyof T>(key: K): T[K];
-}
-
-// =============================================================================
-// Schema to Field Definitions Converter
-// =============================================================================
-
-/**
- * Field definition format expected by the CMS database.
- * This is the format stored in contentTypes.fields.
- */
-export interface DatabaseFieldDefinition {
-  name: string;
-  label: string;
-  type: string;
-  required: boolean;
-  searchable?: boolean;
-  localized?: boolean;
-  description?: string;
-  defaultValue?: unknown;
-  options?: Record<string, unknown>;
-}
-
-/**
- * Converts a content type definition to the database field format.
- *
- * This bridges the gap between the code-defined schema and the
- * database format used by the CMS component.
- *
- * @param definition - The content type definition
- * @returns An array of field definitions for the database
- *
- * @example
- * ```typescript
- * const fields = toFieldDefinitions(blogPost);
- * // [
- * //   { name: "title", label: "Title", type: "text", required: true, ... },
- * //   { name: "content", label: "Content", type: "richText", required: true, ... },
- * // ]
- * ```
- */
-export function toFieldDefinitions(
-  definition: ContentTypeDefinition
-): DatabaseFieldDefinition[] {
-  // Extract field information from the validator
-  // This requires introspecting the validator structure
-  const validatorFields = extractValidatorFields(definition.validator);
-  const fieldMeta = definition.meta.fields || {};
-
-  return validatorFields.map((field) => {
-    const meta = fieldMeta[field.name as keyof typeof fieldMeta] || {};
-
-    return {
-      name: field.name,
-      label: meta.label || field.name,
-      type: meta.renderAs || inferFieldType(field.validatorType),
-      required: field.required,
-      searchable: meta.searchable,
-      localized: meta.localized,
-      description: meta.description,
-      options: buildFieldOptions(field, meta),
-    };
-  });
-}
-
-/**
- * Field information extracted from a validator.
- */
-interface ExtractedField {
-  name: string;
-  validatorType: string;
-  required: boolean;
-  innerValidator?: unknown;
-}
-
-/**
- * Extract field information from a Convex object validator.
- *
- * @internal
- */
-function extractValidatorFields(
-  validator: Validator<Record<string, unknown>, "required", string>
-): ExtractedField[] {
-  const fields: ExtractedField[] = [];
-
-  // Convex validators have internal structure we can introspect
-  // The validator has a `fields` property for object validators
-  const validatorAny = validator as unknown as {
-    fieldPaths?: Record<string, unknown>;
-    type?: string;
-    kind?: string;
-    fields?: Record<
-      string,
-      { fieldPath: string; validator: { isOptional?: string; type?: string; kind?: string } }
-    >;
-  };
-
-  // Try to access the validator's internal field definitions
-  if (validatorAny.fields) {
-    for (const [name, fieldInfo] of Object.entries(validatorAny.fields)) {
-      const innerValidator = fieldInfo.validator;
-      const isOptional = innerValidator?.isOptional === "optional";
-
-      fields.push({
-        name,
-        validatorType: innerValidator?.type || innerValidator?.kind || "unknown",
-        required: !isOptional,
-        innerValidator,
-      });
-    }
-  }
-
-  return fields;
-}
-
-/**
- * Infer a CMS field type from a Convex validator type.
- *
- * @internal
- */
-function inferFieldType(validatorType: string): string {
-  const typeMap: Record<string, string> = {
-    string: "text",
-    number: "number",
-    boolean: "boolean",
-    id: "reference",
-    array: "json",
-    object: "json",
-    union: "select",
-    literal: "select",
-    bytes: "media",
-  };
-
-  return typeMap[validatorType] || "text";
-}
-
-/**
- * Build field options from extracted field info and metadata.
- *
- * This function maps all FieldMeta options to the database field options format.
- * The options object is stored in contentTypes.fields[].options and is used
- * for validation and UI rendering.
- *
- * @internal
- */
-function buildFieldOptions(
-  field: ExtractedField,
-  meta: FieldMeta
-): Record<string, unknown> | undefined {
-  const options: Record<string, unknown> = {};
-
-  // ==========================================================================
-  // Text Field Options
-  // ==========================================================================
-  if (meta.minLength !== undefined) options.minLength = meta.minLength;
-  if (meta.maxLength !== undefined) options.maxLength = meta.maxLength;
-  if (meta.pattern !== undefined) options.pattern = meta.pattern;
-  // Note: patternMessage and multiline are UI hints, not stored in component schema
-  // They could be stored in a separate UI hints field if needed
-
-  // ==========================================================================
-  // Number Field Options
-  // ==========================================================================
-  if (meta.min !== undefined) options.min = meta.min;
-  if (meta.max !== undefined) options.max = meta.max;
-  if (meta.step !== undefined) options.step = meta.step;
-  if (meta.precision !== undefined) options.precision = meta.precision;
-  // Note: prefix/suffix are UI hints, not stored in component schema
-
-  // ==========================================================================
-  // Reference Field Options
-  // ==========================================================================
-  if (meta.allowedContentTypes !== undefined) options.allowedContentTypes = meta.allowedContentTypes;
-  if (meta.multiple !== undefined) options.multiple = meta.multiple;
-  if (meta.minItems !== undefined) options.minItems = meta.minItems;
-  // Note: maxItems maps to minItems in the component (for validation purposes)
-  // The component schema has minItems but not maxItems - we'll add it anyway
-  // for forward compatibility
-
-  // ==========================================================================
-  // Media Field Options
-  // ==========================================================================
-  if (meta.allowedMimeTypes !== undefined) options.allowedMimeTypes = meta.allowedMimeTypes;
-  if (meta.maxFileSize !== undefined) options.maxFileSize = meta.maxFileSize;
-
-  // ==========================================================================
-  // Select/MultiSelect Field Options
-  // ==========================================================================
-  if (meta.options !== undefined) options.options = meta.options;
-  // Note: minSelections/maxSelections could be mapped to minItems/maxItems
-
-  // ==========================================================================
-  // Rich Text Field Options
-  // ==========================================================================
-  if (meta.allowedBlocks !== undefined) options.allowedBlocks = meta.allowedBlocks;
-  if (meta.allowedMarks !== undefined) options.allowedMarks = meta.allowedMarks;
-
-  // ==========================================================================
-  // Taxonomy Field Options (tags/category)
-  // ==========================================================================
-  if (meta.taxonomyId !== undefined) options.taxonomyId = meta.taxonomyId;
-  if (meta.allowCreate !== undefined) options.allowCreate = meta.allowCreate;
-  if (meta.maxTags !== undefined) options.maxTags = meta.maxTags;
-  if (meta.minTags !== undefined) options.minTags = meta.minTags;
-  if (meta.allowMultiple !== undefined) options.allowMultiple = meta.allowMultiple;
-
-  return Object.keys(options).length > 0 ? options : undefined;
-}

package/src/client/schema/index.ts

@@ -1,169 +0,0 @@
-/**
- * Code-Only Schema System
- *
- * This module provides type-safe content type definitions using Convex validators.
- * Types are automatically inferred via Convex's native `Infer<typeof validator>` pattern.
- *
- * ## Quick Start
- *
- * ```typescript
- * import { v, Infer } from "convex/values";
- * import { defineContentType, InferContentType } from "@convex-cms/core";
- *
- * // Define a content type with a Convex validator
- * export const blogPost = defineContentType({
- *   name: "blog_post",
- *   validator: v.object({
- *     title: v.string(),
- *     content: v.string(),
- *     publishedAt: v.optional(v.number()),
- *   }),
- *   meta: {
- *     displayName: "Blog Post",
- *     titleField: "title",
- *   },
- * });
- *
- * // Type is automatically inferred
- * type BlogPostData = InferContentType<typeof blogPost>;
- * // { title: string; content: string; publishedAt?: number }
- * ```
- *
- * ## Creating a Schema
- *
- * ```typescript
- * import { createContentSchema, InferSchema } from "@convex-cms/core";
- *
- * // Combine multiple content types into a schema
- * export const contentSchema = createContentSchema({
- *   blogPost,
- *   author,
- *   product,
- * });
- *
- * // Infer all types at once
- * export type ContentTypes = InferSchema<typeof contentSchema.definitions>;
- * // {
- * //   blog_post: { title: string; content: string; ... };
- * //   author: { name: string; bio?: string; ... };
- * //   product: { name: string; price: number; ... };
- * // }
- * ```
- *
- * ## Using with CMS Client
- *
- * ```typescript
- * import { createCmsClient } from "@convex-cms/core";
- * import { components } from "./_generated/api";
- * import { contentSchema } from "./schema";
- *
- * // Create a schema-aware CMS client
- * export const cms = createCmsClient(components.convexCms, {
- *   schema: contentSchema,
- *   // ... other options
- * });
- *
- * // Now get() returns typed data
- * const post = await cms.contentEntries.get<"blog_post">(ctx, id);
- * post.data.title    // ✅ string - fully typed
- * post.data.typo     // ❌ Error: Property 'typo' does not exist
- * ```
- *
- * @module
- */
-
-// =============================================================================
-// Core Functions
-// =============================================================================
-
-export { defineContentType, createContentSchema, toFieldDefinitions } from "./defineContentType.js";
-
-// =============================================================================
-// Types
-// =============================================================================
-
-// Core definition types
-export type {
-  ContentTypeConfig,
-  ContentTypeDefinition,
-  ContentTypeMeta,
-  FieldMeta,
-  FieldRenderAs,
-} from "./types.js";
-
-// Type inference utilities
-export type {
-  InferContentType,
-  InferSchema,
-  ContentSchema,
-  SchemaContentTypeNames,
-  SchemaContentType,
-  ContentTypeFieldNames,
-} from "./types.js";
-
-// Schema instance type
-export type { ContentSchemaInstance, DatabaseFieldDefinition } from "./defineContentType.js";
-
-// Runtime utilities
-export { isContentTypeDefinition } from "./types.js";
-
-// =============================================================================
-// Typed Client Factory
-// =============================================================================
-
-export { createTypedCmsClient, TypedContentEntriesApiImpl } from "./typedClient.js";
-
-// =============================================================================
-// Schema Drift Detection
-// =============================================================================
-
-export {
-  detectSchemaDrift,
-  formatDriftReport,
-  hasErrors,
-  filterReportByContentTypes,
-} from "./schemaDrift.js";
-
-export type {
-  DriftSeverity,
-  DriftType,
-  DriftIssue,
-  DriftSummary,
-  SchemaDriftReport,
-  DetectDriftOptions,
-} from "./schemaDrift.js";
-
-// =============================================================================
-// Type Code Generation
-// =============================================================================
-
-export {
-  generateTypesFromDatabase,
-  generateTypesFromDefinitions,
-  validateGeneratedCode,
-} from "./codegen.js";
-
-export type {
-  CodegenOptions,
-  CodegenResult,
-} from "./codegen.js";
-
-// =============================================================================
-// Typed Client Types
-// =============================================================================
-
-// Typed content entry types
-export type {
-  TypedContentEntry,
-  TypedPaginationResult,
-  TypedContentEntriesApi,
-  TypedCreateEntryOptions,
-  TypedUpdateEntryOptions,
-  TypedListEntriesOptions,
-  SchemaDataType,
-  ValidContentTypeName,
-  HasContentType,
-  GetContentTypeDefinition,
-  TypedCmsClientConfig,
-  TypedCmsClient,
-} from "./typedClient.js";