@carlonicora/nextjs-jsonapi 1.2.0 → 1.3.1

package/scripts/generate-web-module/transformers/relationship-resolver.ts

@@ -0,0 +1,221 @@
+/**
+ * Relationship Resolver
+ *
+ * Resolves JSON relationship definitions to frontend representations
+ * including form fields, imports, and service methods.
+ */
+
+import { JsonRelationshipDefinition } from "../types/json-schema.interface";
+import { FrontendRelationship, RelationshipServiceMethod } from "../types/template-data.interface";
+import { AUTHOR_VARIANT, AUTHOR_ZOD_SCHEMA, ENTITY_ZOD_SCHEMA } from "../types/field-mapping.types";
+import { toCamelCase, toKebabCase, pluralize, toPascalCase } from "./name-transformer";
+
+/**
+ * Resolve a JSON relationship to frontend representation
+ *
+ * @param rel - JSON relationship definition
+ * @returns Frontend relationship representation
+ */
+export function resolveRelationship(rel: JsonRelationshipDefinition): FrontendRelationship {
+  const isAuthor = rel.variant === AUTHOR_VARIANT;
+  const effectiveName = rel.variant || rel.name;
+  const effectiveNameLower = toCamelCase(effectiveName);
+  const modelKebab = toKebabCase(rel.name);
+
+  // Form field ID
+  const formFieldId = effectiveNameLower;
+  const formFieldIdPlural = pluralize(effectiveNameLower);
+
+  // Payload field ID for API calls
+  let payloadFieldId: string;
+  if (rel.single) {
+    payloadFieldId = `${effectiveNameLower}Id`;
+  } else {
+    payloadFieldId = `${toCamelCase(rel.name)}Ids`;
+  }
+
+  // Selector component name
+  let selectorComponent: string;
+  if (rel.single) {
+    selectorComponent = `${rel.name}Selector`;
+  } else {
+    selectorComponent = `${rel.name}MultiSelector`;
+  }
+
+  // Zod schema
+  let zodSchema: string;
+  if (isAuthor) {
+    zodSchema = rel.nullable
+      ? `${AUTHOR_ZOD_SCHEMA}.optional()`
+      : `${AUTHOR_ZOD_SCHEMA}.refine((data) => data.id && data.id.length > 0, { message: t(\`generic.relationships.author.error\`) })`;
+  } else if (rel.single) {
+    zodSchema = rel.nullable
+      ? `${ENTITY_ZOD_SCHEMA}.optional()`
+      : `${ENTITY_ZOD_SCHEMA}.refine((data) => data.id && data.id.length > 0, { message: t(\`generic.relationships.${effectiveNameLower}.error\`) })`;
+  } else {
+    zodSchema = rel.nullable ? `z.array(${ENTITY_ZOD_SCHEMA}).optional()` : `z.array(${ENTITY_ZOD_SCHEMA})`;
+  }
+
+  // Import paths - map directory to web path
+  const webDirectory = mapDirectoryToWebPath(rel.directory);
+  const importPath = `@/features/${webDirectory}/${modelKebab}/components/forms/${selectorComponent}`;
+  const interfaceImportPath = `@/features/${webDirectory}/${modelKebab}/data/${rel.name}Interface`;
+  const serviceImportPath = `@/features/${webDirectory}/${modelKebab}/data/${rel.name}Service`;
+
+  return {
+    name: rel.name,
+    variant: rel.variant,
+    directory: rel.directory,
+    single: rel.single,
+    nullable: rel.nullable,
+    formFieldId,
+    formFieldIdPlural,
+    payloadFieldId,
+    selectorComponent,
+    zodSchema,
+    importPath,
+    interfaceImportPath,
+    serviceImportPath,
+    interfaceName: `${rel.name}Interface`,
+    modelKebab,
+  };
+}
+
+/**
+ * Resolve all relationships from JSON schema
+ *
+ * @param relationships - Array of JSON relationship definitions
+ * @returns Array of frontend relationship representations
+ */
+export function resolveRelationships(relationships: JsonRelationshipDefinition[]): FrontendRelationship[] {
+  return relationships.map(resolveRelationship);
+}
+
+/**
+ * Map directory value to web path
+ * e.g., "features" -> "features", "foundations" -> "foundations"
+ *
+ * @param directory - Directory value from JSON
+ * @returns Web path segment
+ */
+export function mapDirectoryToWebPath(directory: string): string {
+  // The directory value maps directly to the web path
+  return directory;
+}
+
+/**
+ * Generate service method definitions for relationships
+ *
+ * @param relationships - Array of frontend relationships
+ * @returns Array of service method definitions
+ */
+export function generateServiceMethods(relationships: FrontendRelationship[]): RelationshipServiceMethod[] {
+  return relationships.map((rel) => {
+    const effectiveName = rel.variant || rel.name;
+    return {
+      methodName: `findManyBy${toPascalCase(effectiveName)}`,
+      paramName: `${toCamelCase(effectiveName)}Id`,
+      relationshipName: rel.name,
+      relationshipEndpoint: pluralize(toKebabCase(rel.name)),
+    };
+  });
+}
+
+/**
+ * Get unique selector imports needed for the editor
+ *
+ * @param relationships - Array of frontend relationships
+ * @returns Deduplicated array of import statements
+ */
+export function getSelectorImports(relationships: FrontendRelationship[]): string[] {
+  const imports = new Set<string>();
+
+  relationships.forEach((rel) => {
+    // Don't import User selector from same module - it's typically a library import
+    if (rel.name === "User" && rel.variant === AUTHOR_VARIANT) {
+      // User selector is imported from library or user feature
+      imports.add(`import { UserSelector } from "@/features/foundations/user/components/forms/UserSelector";`);
+    } else {
+      imports.add(`import ${rel.selectorComponent} from "${rel.importPath}";`);
+    }
+  });
+
+  return Array.from(imports);
+}
+
+/**
+ * Get form JSX for a relationship field
+ *
+ * @param rel - Frontend relationship
+ * @param moduleName - Module name for i18n keys
+ * @returns JSX code for the relationship selector
+ */
+export function getRelationshipFormJsx(rel: FrontendRelationship, moduleName: string): string {
+  const isRequired = !rel.nullable;
+  const lowerModuleName = moduleName.toLowerCase();
+
+  if (rel.single) {
+    // Single selector
+    if (rel.variant === AUTHOR_VARIANT) {
+      // Author is auto-set, usually not shown in form or read-only
+      return "";
+    }
+    return `<${rel.name}Selector
+  id="${rel.formFieldId}"
+  form={form}
+  label={t(\`generic.relationships.${rel.formFieldId}.label\`)}
+  placeholder={t(\`generic.relationships.${rel.formFieldId}.placeholder\`)}
+  ${isRequired ? "isRequired" : ""}
+/>`;
+  } else {
+    // Multi selector
+    return `<${rel.name}MultiSelector
+  id="${rel.formFieldId}"
+  form={form}
+  label={t(\`types.${pluralize(toKebabCase(rel.name))}\`, { count: 2 })}
+/>`;
+  }
+}
+
+/**
+ * Get default value expression for a relationship in form
+ *
+ * @param rel - Frontend relationship
+ * @param modelVarName - Variable name for the model (e.g., "article")
+ * @returns Expression for default value
+ */
+export function getDefaultValueExpression(rel: FrontendRelationship, modelVarName: string): string {
+  const propertyName = rel.variant ? toCamelCase(rel.variant) : toCamelCase(rel.name);
+  const pluralPropertyName = pluralize(propertyName);
+
+  if (rel.single) {
+    if (rel.variant === AUTHOR_VARIANT) {
+      // Author has special shape with avatar
+      return `${modelVarName}?.${propertyName}
+        ? { id: ${modelVarName}.${propertyName}.id, name: ${modelVarName}.${propertyName}.name, avatar: ${modelVarName}.${propertyName}.avatar }
+        : undefined`;
+    }
+    return `${modelVarName}?.${propertyName}
+        ? { id: ${modelVarName}.${propertyName}.id, name: ${modelVarName}.${propertyName}.name }
+        : undefined`;
+  } else {
+    // Multi-select
+    return `${modelVarName}?.${pluralPropertyName}
+        ? ${modelVarName}.${pluralPropertyName}.map((item) => ({ id: item.id, name: item.name }))
+        : []`;
+  }
+}
+
+/**
+ * Get payload mapping for a relationship
+ *
+ * @param rel - Frontend relationship
+ * @returns Payload field assignment code
+ */
+export function getPayloadMapping(rel: FrontendRelationship): string {
+  if (rel.single) {
+    return `${rel.payloadFieldId}: values.${rel.formFieldId}?.id`;
+  } else {
+    return `${rel.payloadFieldId}: values.${rel.formFieldId} ? values.${rel.formFieldId}.map((item) => item.id) : []`;
+  }
+}

package/scripts/generate-web-module/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "es2020",
+    "outDir": "../../dist/scripts/generate-web-module",
+    "rootDir": ".",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "resolveJsonModule": true
+  },
+  "include": [
+    "./**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/scripts/generate-web-module/types/field-mapping.types.ts

@@ -0,0 +1,141 @@
+/**
+ * Field Mapping Types
+ *
+ * Defines the mapping rules between JSON schema field types
+ * and their TypeScript, Zod, and form component equivalents.
+ */
+
+import { FormComponentType } from "./template-data.interface";
+
+/**
+ * Mapping from JSON type to TypeScript type
+ */
+export const JSON_TO_TS_TYPE: Record<string, string> = {
+  string: "string",
+  number: "number",
+  boolean: "boolean",
+  date: "Date",
+  any: "any",
+};
+
+/**
+ * Mapping from JSON type to Zod schema (base, without modifiers)
+ */
+export const JSON_TO_ZOD_BASE: Record<string, string> = {
+  string: "z.string()",
+  number: "z.number()",
+  boolean: "z.boolean()",
+  date: "z.date()",
+  any: "z.any()",
+};
+
+/**
+ * Special field names that get specific form components
+ */
+export const SPECIAL_FIELD_COMPONENTS: Record<string, FormComponentType> = {
+  content: "BlockNoteEditor",
+  description: "FormTextarea",
+  abstract: "FormTextarea",
+  body: "FormTextarea",
+};
+
+/**
+ * Default form component by type
+ */
+export const TYPE_TO_FORM_COMPONENT: Record<string, FormComponentType> = {
+  string: "FormInput",
+  number: "FormInputNumber",
+  boolean: "Checkbox",
+  date: "DatePicker",
+  any: "FormInput",
+};
+
+/**
+ * Fields that indicate the module extends Content
+ */
+export const CONTENT_INDICATOR_FIELDS = ["name", "tldr", "abstract"];
+
+/**
+ * Standard fields added to all modules
+ */
+export const STANDARD_FIELDS = ["createdAt", "updatedAt"];
+
+/**
+ * Author variant special handling
+ */
+export const AUTHOR_VARIANT = "Author";
+
+/**
+ * Zod schema for author relationships
+ */
+export const AUTHOR_ZOD_SCHEMA = "userObjectSchema";
+
+/**
+ * Zod schema for entity relationships (non-author)
+ */
+export const ENTITY_ZOD_SCHEMA = "entityObjectSchema";
+
+/**
+ * Default icon for new modules
+ */
+export const DEFAULT_MODULE_ICON = "FileTextIcon";
+
+/**
+ * Get TypeScript type for a field
+ */
+export function getTsType(jsonType: string): string {
+  return JSON_TO_TS_TYPE[jsonType] || "any";
+}
+
+/**
+ * Get base Zod schema for a field type
+ */
+export function getZodBase(jsonType: string): string {
+  return JSON_TO_ZOD_BASE[jsonType] || "z.any()";
+}
+
+/**
+ * Get form component for a field
+ */
+export function getFormComponent(fieldName: string, fieldType: string): FormComponentType {
+  // Check for special field names first
+  if (SPECIAL_FIELD_COMPONENTS[fieldName]) {
+    return SPECIAL_FIELD_COMPONENTS[fieldName];
+  }
+  // Fall back to type-based component
+  return TYPE_TO_FORM_COMPONENT[fieldType] || "FormInput";
+}
+
+/**
+ * Check if a field name indicates BlockNoteEditor should be used
+ */
+export function isContentField(fieldName: string): boolean {
+  return fieldName === "content";
+}
+
+/**
+ * Build complete Zod schema for a field
+ */
+export function buildZodSchema(fieldType: string, nullable: boolean, fieldName: string): string {
+  const base = getZodBase(fieldType);
+
+  // Content fields use z.any()
+  if (isContentField(fieldName)) {
+    return "z.any()";
+  }
+
+  // String fields with min(1) for required
+  if (fieldType === "string") {
+    if (nullable) {
+      return `${base}.optional()`;
+    }
+    return `${base}.min(1, { message: t(\`features.\${moduleName}.fields.${fieldName}.error\`) })`;
+  }
+
+  // Other fields with optional modifier
+  if (nullable) {
+    return `${base}.optional()`;
+  }
+
+  return base;
+}

package/scripts/generate-web-module/types/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Types Index
+ *
+ * Re-exports all type definitions for the web module generator.
+ */
+
+export * from "./json-schema.interface";
+export * from "./template-data.interface";
+export * from "./field-mapping.types";

package/scripts/generate-web-module/types/json-schema.interface.ts

@@ -0,0 +1,42 @@
+/**
+ * JSON Schema Interfaces
+ *
+ * Type definitions for the JSON module definition files
+ * located in the /structure folder.
+ * Copied from backend generator - shared schema format.
+ */
+
+/**
+ * Field definition in JSON schema
+ */
+export interface JsonFieldDefinition {
+  name: string;
+  type: string;
+  nullable: boolean;
+}
+
+/**
+ * Relationship definition in JSON schema
+ */
+export interface JsonRelationshipDefinition {
+  name: string;
+  variant?: string;
+  directory: string;
+  single: boolean;
+  relationshipName: string; // Backend-specific, ignored in frontend
+  toNode: boolean; // Backend-specific, ignored in frontend
+  nullable: boolean;
+}
+
+/**
+ * Complete module definition from JSON
+ */
+export interface JsonModuleDefinition {
+  moduleId: string;
+  moduleName: string;
+  endpointName: string;
+  targetDir: string;
+  languages: string[];
+  fields: JsonFieldDefinition[];
+  relationships: JsonRelationshipDefinition[];
+}

package/scripts/generate-web-module/types/template-data.interface.ts

@@ -0,0 +1,164 @@
+/**
+ * Frontend Template Data Interfaces
+ *
+ * Type definitions for the data passed to templates
+ * during frontend module generation.
+ */
+
+/**
+ * Name transformations for different naming conventions
+ */
+export interface NameTransforms {
+  pascalCase: string; // e.g., "Comment"
+  camelCase: string; // e.g., "comment"
+  kebabCase: string; // e.g., "comment"
+  pluralPascal: string; // e.g., "Comments"
+  pluralCamel: string; // e.g., "comments"
+  pluralKebab: string; // e.g., "comments"
+  titleCase: string; // e.g., "Comment" (for labels)
+  pluralTitleCase: string; // e.g., "Comments" (for labels)
+}
+
+/**
+ * Frontend field representation
+ */
+export interface FrontendField {
+  name: string;
+  type: string;
+  tsType: string; // TypeScript type
+  zodSchema: string; // Zod schema code
+  formComponent: FormComponentType;
+  nullable: boolean;
+  isContentField: boolean; // Indicates BlockNoteEditor
+}
+
+/**
+ * Form component types
+ */
+export type FormComponentType = "FormInput" | "FormTextarea" | "BlockNoteEditor" | "Checkbox" | "DatePicker" | "FormInputNumber";
+
+/**
+ * Frontend relationship representation
+ */
+export interface FrontendRelationship {
+  name: string; // e.g., "User"
+  variant?: string; // e.g., "Author"
+  directory: string; // e.g., "foundations"
+  single: boolean;
+  nullable: boolean;
+  // Derived properties
+  formFieldId: string; // e.g., "author" (lowercase variant) or "user"
+  formFieldIdPlural: string; // e.g., "topics" for multi-select
+  payloadFieldId: string; // e.g., "authorId" or "topicIds"
+  selectorComponent: string; // e.g., "UserSelector" or "TopicMultiSelector"
+  zodSchema: string; // e.g., "userObjectSchema" or "z.array(entityObjectSchema)"
+  importPath: string; // Full import path for selector
+  interfaceImportPath: string; // Full import path for interface
+  serviceImportPath: string; // Full import path for service
+  interfaceName: string; // e.g., "UserInterface"
+  modelKebab: string; // e.g., "user"
+}
+
+/**
+ * i18n key structure
+ */
+export interface I18nKeySet {
+  moduleName: string; // e.g., "comment"
+  fields: Record<
+    string,
+    {
+      label: string;
+      placeholder: string;
+      error: string;
+    }
+  >;
+  relationships: Record<
+    string,
+    {
+      label: string;
+      placeholder: string;
+      error: string;
+      list: string;
+    }
+  >;
+  type: {
+    singular: string;
+    plural: string;
+    icuPlural: string; // ICU format plural
+  };
+}
+
+/**
+ * Import statement groups
+ */
+export interface ImportStatements {
+  // Related model/interface imports
+  models: string[];
+  // Selector component imports
+  selectors: string[];
+  // Library imports (from @carlonicora/nextjs-jsonapi)
+  library: string[];
+}
+
+/**
+ * Complete template data passed to all templates
+ */
+export interface FrontendTemplateData {
+  // Name variations
+  names: NameTransforms;
+
+  // Module metadata
+  moduleId: string;
+  endpoint: string;
+  targetDir: "features" | "foundations";
+
+  // Parent class detection
+  extendsContent: boolean;
+
+  // Field mappings
+  fields: FrontendField[];
+
+  // Relationship mappings
+  relationships: FrontendRelationship[];
+
+  // i18n keys
+  i18nKeys: I18nKeySet;
+
+  // Import statements
+  imports: ImportStatements;
+
+  // For table structure
+  tableFieldNames: string[];
+
+  // For service generation
+  relationshipServiceMethods: RelationshipServiceMethod[];
+}
+
+/**
+ * Service method for relationship queries
+ */
+export interface RelationshipServiceMethod {
+  methodName: string; // e.g., "findManyByAuthor"
+  paramName: string; // e.g., "authorId"
+  relationshipName: string; // e.g., "User"
+  relationshipEndpoint: string; // e.g., "users"
+}
+
+/**
+ * Options for the generator
+ */
+export interface GenerateWebModuleOptions {
+  jsonPath: string;
+  dryRun?: boolean;
+  force?: boolean;
+  noRegister?: boolean;
+}
+
+/**
+ * Generated file info
+ */
+export interface GeneratedFile {
+  path: string;
+  content: string;
+  type: "data" | "component" | "context" | "hook" | "module" | "page";
+}