@quazardous/qdadm 1.19.3

package/src/gen/generateManagers.ts

@@ -0,0 +1,398 @@
+/**
+ * Build-time Manager File Generation
+ *
+ * Generates individual EntityManager files for each entity in the configuration.
+ * This enables better IDE support and static analysis by creating explicit files
+ * rather than relying on runtime factory creation.
+ *
+ * Outputs TypeScript (.ts) files with auto-generated entity interfaces derived
+ * from the field schemas, providing end-to-end type safety.
+ *
+ * @module gen/generateManagers
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { UnifiedEntitySchema, UnifiedFieldSchema, UnifiedFieldType } from './schema'
+import type { EntityDecorator } from './decorators'
+
+/**
+ * Default output directory for generated managers
+ */
+const DEFAULT_OUTPUT_DIR = 'src/generated/managers/'
+
+/**
+ * Entity configuration for generation
+ */
+export interface GenerateManagersEntityConfig {
+  /** Entity schema */
+  schema: UnifiedEntitySchema
+  /** API endpoint path (e.g., '/users') */
+  endpoint: string
+  /** Import path for storage (e.g., 'qdadm' or './storage') */
+  storageImport: string
+  /** Storage class name (e.g., 'ApiStorage') */
+  storageClass: string
+  /** Additional storage constructor options */
+  storageOptions?: Record<string, unknown>
+  /** Field decorators to apply */
+  decorators?: EntityDecorator
+  /** Generate class instead of instance (for extension) */
+  classMode?: boolean
+}
+
+/**
+ * Configuration for generateManagers
+ */
+export interface GenerateManagersConfig {
+  /** Output directory (default: 'src/generated/managers/') */
+  output?: string
+  /** Generate classes instead of instances (for extension pattern) */
+  classMode?: boolean
+  /** Entity configurations keyed by entity name */
+  entities: Record<string, GenerateManagersEntityConfig>
+}
+
+/**
+ * Convert entity name to PascalCase for class name
+ *
+ * @param name - Entity name (e.g., 'users', 'blog_posts')
+ * @returns PascalCase name (e.g., 'Users', 'BlogPosts')
+ */
+function toPascalCase(name: string): string {
+  return name
+    .split(/[_-]/)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('')
+}
+
+/**
+ * Map UnifiedFieldType to TypeScript type string
+ */
+export function fieldTypeToTsType(type: UnifiedFieldType, required: boolean): string {
+  const tsType = (() => {
+    switch (type) {
+      case 'text':
+      case 'email':
+      case 'url':
+      case 'uuid':
+      case 'date':
+      case 'datetime':
+        return 'string'
+      case 'number':
+        return 'number'
+      case 'boolean':
+        return 'boolean'
+      case 'array':
+        return 'unknown[]'
+      case 'object':
+        return 'Record<string, unknown>'
+      default:
+        // Fallback for types widened beyond UnifiedFieldType at runtime
+        // (e.g. OpenAPI oneOf/discriminator that FieldMapper couldn't classify).
+        // Without this, the IIFE returns undefined and we'd emit the literal
+        // string "undefined" into the generated .ts file.
+        return 'unknown'
+    }
+  })()
+  return required ? tsType : `${tsType} | null`
+}
+
+/**
+ * Generate a TypeScript interface from entity fields
+ */
+export function generateEntityInterface(
+  entityName: string,
+  fields: Record<string, UnifiedFieldSchema>,
+  idField: string
+): string {
+  const className = toPascalCase(entityName)
+  const lines: string[] = []
+  lines.push(`export interface ${className}Entity extends EntityRecord {`)
+
+  for (const [fieldName, field] of Object.entries(fields)) {
+    if (field.hidden) continue
+    // Connectors (e.g. OpenAPIConnector) flatten one level of nested object
+    // properties as dotted keys ("filter.botUuids") for runtime form/column
+    // metadata. The parent object field is already typed as
+    // Record<string, unknown>, and dotted keys are not legal at the top level
+    // of a TS interface body — skip them here.
+    if (fieldName.includes('.')) continue
+    const isRequired = field.required || fieldName === idField
+    const tsType = fieldTypeToTsType(field.type, isRequired)
+    const optional = isRequired ? '' : '?'
+    lines.push(`  ${fieldName}${optional}: ${tsType}`)
+  }
+
+  lines.push('}')
+  return lines.join('\n')
+}
+
+/**
+ * Serialize a value to JavaScript source code
+ *
+ * @param value - Value to serialize
+ * @param indent - Current indentation level
+ * @returns JavaScript source code
+ */
+function serializeValue(value: unknown, indent: number = 0): string {
+  const spaces = '  '.repeat(indent)
+  const innerSpaces = '  '.repeat(indent + 1)
+
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  if (typeof value === 'string') return JSON.stringify(value)
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]'
+    const items = value.map((v) => serializeValue(v, indent + 1))
+    return `[\n${innerSpaces}${items.join(`,\n${innerSpaces}`)}\n${spaces}]`
+  }
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>
+    const keys = Object.keys(obj)
+    if (keys.length === 0) return '{}'
+    const entries = keys.map((key) => {
+      const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key)
+      return `${innerSpaces}${safeKey}: ${serializeValue(obj[key], indent + 1)}`
+    })
+    return `{\n${entries.join(',\n')}\n${spaces}}`
+  }
+  return String(value)
+}
+
+// Note: ManagerOptions interface removed - using inline Record<string, unknown> type instead
+
+/**
+ * Generate the source code for a single entity manager file
+ *
+ * @param entityName - Entity name
+ * @param entityConfig - Entity configuration
+ * @param globalOptions - Global generation options
+ * @returns Generated TypeScript source code
+ */
+function generateManagerSource(
+  entityName: string,
+  entityConfig: GenerateManagersEntityConfig,
+  globalOptions: { classMode?: boolean } = {}
+): string {
+  const { schema, endpoint, storageImport, storageClass, storageOptions = {}, decorators } = entityConfig
+  const classMode = entityConfig.classMode ?? globalOptions.classMode ?? false
+  const className = toPascalCase(entityName)
+
+  // Build storage options object
+  const fullStorageOptions: Record<string, unknown> = {
+    endpoint,
+    ...storageOptions,
+  }
+
+  // Apply decorators to schema if provided
+  let finalSchema = schema
+  if (decorators?.fields) {
+    // Create decorated fields inline
+    const decoratedFields: Record<string, UnifiedFieldSchema> = {}
+    for (const [fieldName, fieldSchema] of Object.entries(schema.fields)) {
+      const decorator = decorators.fields[fieldName]
+      if (decorator) {
+        decoratedFields[fieldName] = { ...fieldSchema, ...decorator }
+      } else {
+        decoratedFields[fieldName] = { ...fieldSchema }
+      }
+    }
+    finalSchema = { ...schema, fields: decoratedFields }
+  }
+
+  // Build EntityManager options
+  const managerOptions: Record<string, unknown> = {
+    name: finalSchema.name,
+    idField: finalSchema.idField || 'id',
+    label: finalSchema.label,
+    labelPlural: finalSchema.labelPlural,
+    labelField: finalSchema.labelField,
+    routePrefix: finalSchema.routePrefix,
+    readOnly: finalSchema.readOnly,
+    fields: finalSchema.fields,
+  }
+
+  // Remove undefined values
+  for (const key of Object.keys(managerOptions)) {
+    if (managerOptions[key] === undefined) {
+      delete managerOptions[key]
+    }
+  }
+
+  // Generate entity interface
+  const idField = finalSchema.idField || 'id'
+  const entityInterface = generateEntityInterface(entityName, finalSchema.fields, idField)
+
+  // Class-based template for extension pattern
+  if (classMode) {
+    return `/**
+ * Generated${className}Manager - Auto-generated base class
+ *
+ * Generated by qdadm/gen/generateManagers
+ * DO NOT EDIT MANUALLY - Changes will be overwritten
+ *
+ * Extend this class for custom logic.
+ *
+ * Entity: ${entityName}
+ * Endpoint: ${endpoint}
+ */
+
+import { EntityManager } from '@quazardous/qdadm'
+import type { EntityRecord, IStorage } from '@quazardous/qdadm'
+import { ${storageClass} } from '${storageImport}'
+
+${entityInterface}
+
+/**
+ * Generated base manager for ${entityName}
+ *
+ * @extends EntityManager
+ */
+export class Generated${className}Manager extends EntityManager<${className}Entity> {
+  constructor(options: Partial<{ name: string; idField: string; fields: Record<string, unknown>; storage: IStorage<${className}Entity>; [key: string]: unknown }> = {}) {
+    super({
+      ...${serializeValue(managerOptions, 2)},
+      storage: new ${storageClass}<${className}Entity>(${serializeValue(fullStorageOptions, 2)}),
+      ...options
+    })
+  }
+}
+`
+  }
+
+  // Instance-based template (default)
+  return `/**
+ * ${className}Manager - Auto-generated EntityManager
+ *
+ * Generated by qdadm/gen/generateManagers
+ * DO NOT EDIT MANUALLY - Changes will be overwritten
+ *
+ * Entity: ${entityName}
+ * Endpoint: ${endpoint}
+ */
+
+import { EntityManager } from '@quazardous/qdadm'
+import type { EntityRecord } from '@quazardous/qdadm'
+import { ${storageClass} } from '${storageImport}'
+
+${entityInterface}
+
+/**
+ * Schema definition for ${entityName}
+ */
+export const ${entityName}Schema = ${serializeValue(finalSchema, 0)} as const
+
+/**
+ * Storage options for ${entityName}
+ */
+const storageOptions = ${serializeValue(fullStorageOptions, 0)}
+
+/**
+ * ${className}Manager instance
+ *
+ * Provides CRUD operations for ${entityName} entity.
+ */
+export const ${entityName}Manager = new EntityManager<${className}Entity>({
+  ...${serializeValue(managerOptions, 0)},
+  storage: new ${storageClass}<${className}Entity>(storageOptions)
+})
+`
+}
+
+/**
+ * Generate EntityManager files from configuration
+ *
+ * Creates one TypeScript file per entity in the output directory.
+ * Each file exports the entity's interface, schema, and a configured EntityManager instance.
+ *
+ * @param config - Configuration object
+ * @returns List of generated file paths
+ * @throws If config is invalid or file operations fail
+ *
+ * @example
+ * ```ts
+ * import { generateManagers } from '@quazardous/qdadm/gen'
+ *
+ * const generatedFiles = await generateManagers({
+ *   output: 'src/generated/managers/',
+ *   entities: {
+ *     users: {
+ *       schema: usersSchema,
+ *       endpoint: '/api/users',
+ *       storageImport: '@quazardous/qdadm',
+ *       storageClass: 'ApiStorage',
+ *       storageOptions: { client: 'apiClient' },
+ *       decorators: {
+ *         fields: {
+ *           password: { hidden: true }
+ *         }
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * console.log('Generated:', generatedFiles)
+ * // ['src/generated/managers/usersManager.ts']
+ * ```
+ */
+export async function generateManagers(config: GenerateManagersConfig): Promise<string[]> {
+  // Validate config
+  if (!config || typeof config !== 'object') {
+    throw new Error('generateManagers: config is required and must be an object')
+  }
+
+  if (!config.entities || typeof config.entities !== 'object') {
+    throw new Error('generateManagers: config.entities is required and must be an object')
+  }
+
+  const outputDir = config.output || DEFAULT_OUTPUT_DIR
+  const globalOptions = { classMode: config.classMode ?? false }
+  const generatedFiles: string[] = []
+
+  // Validate each entity config
+  for (const [entityName, entityConfig] of Object.entries(config.entities)) {
+    if (!entityConfig || typeof entityConfig !== 'object') {
+      throw new Error(`generateManagers: entity '${entityName}' config must be an object`)
+    }
+
+    if (!entityConfig.schema || typeof entityConfig.schema !== 'object') {
+      throw new Error(`generateManagers: entity '${entityName}' requires 'schema' property`)
+    }
+
+    if (!entityConfig.endpoint || typeof entityConfig.endpoint !== 'string') {
+      throw new Error(`generateManagers: entity '${entityName}' requires 'endpoint' property`)
+    }
+
+    if (!entityConfig.storageImport || typeof entityConfig.storageImport !== 'string') {
+      throw new Error(`generateManagers: entity '${entityName}' requires 'storageImport' property`)
+    }
+
+    if (!entityConfig.storageClass || typeof entityConfig.storageClass !== 'string') {
+      throw new Error(`generateManagers: entity '${entityName}' requires 'storageClass' property`)
+    }
+  }
+
+  // Create output directory if it doesn't exist
+  await mkdir(outputDir, { recursive: true })
+
+  // Generate files for each entity
+  for (const [entityName, entityConfig] of Object.entries(config.entities)) {
+    const isClassMode = entityConfig.classMode ?? globalOptions.classMode
+    // Use entity.ts for classMode (matches existing pattern), entityManager.ts for instance mode
+    const fileName = isClassMode ? `${entityName}.ts` : `${entityName}Manager.ts`
+    const filePath = join(outputDir, fileName)
+
+    // Generate source code
+    const source = generateManagerSource(entityName, entityConfig, globalOptions)
+
+    // Write file
+    await writeFile(filePath, source, 'utf-8')
+
+    generatedFiles.push(filePath)
+  }
+
+  return generatedFiles
+}

package/src/gen/index.ts

@@ -0,0 +1,66 @@
+/**
+ * Gen Module - Code generation utilities
+ *
+ * Provides UnifiedSchema and FieldMapper for generating admin interfaces
+ * from database schemas.
+ *
+ * @module gen
+ */
+
+// T00309: UnifiedSchema types and helpers
+export {
+  UNIFIED_FIELD_TYPES,
+  isValidFieldType,
+  createFieldSchema,
+  createEntitySchema,
+  type UnifiedFieldType,
+  type UnifiedFieldReference,
+  type UnifiedFieldSchema,
+  type UnifiedEntitySchema,
+} from './schema'
+
+// T00310: FieldMapper - JSON Schema to UnifiedFieldSchema type conversion
+export {
+  BASE_TYPE_MAPPINGS,
+  FORMAT_MAPPINGS,
+  getDefaultType,
+  type CustomMappings,
+  type SchemaProperty,
+} from './FieldMapper'
+
+// T00312: BaseConnector - Abstract base for schema connectors
+export {
+  BaseConnector,
+  type ConnectorOptions,
+  type ParseWarning,
+  type ParseResult,
+} from './connectors'
+
+// T00313: ManualConnector - Inline entity/field definitions
+export {
+  ManualConnector,
+  type ManualEntityInput,
+  type ManualFieldInput,
+  type ManualSourceInput,
+} from './connectors'
+
+// OpenAPIConnector - Parse OpenAPI 3.x specifications
+export { OpenAPIConnector, type OpenAPIConnectorOptions, type OperationFilter } from './connectors'
+
+// T00316: StorageProfileFactory - Type definitions for storage profile pattern
+export { type StorageProfileFactory, type StorageProfileOptions } from './StorageProfileFactory'
+
+// T00317: createManagers - Runtime factory for EntityManager creation
+export { createManagers, type CreateManagersConfig, type EntityConfig } from './createManagers'
+
+// T00318: Decorators - Per-entity field customization layer
+export { applyDecorators, type FieldDecorator, type EntityDecorator } from './decorators'
+
+// T00319: generateManagers - Build-time file generation for EntityManagers
+export {
+  generateManagers,
+  fieldTypeToTsType,
+  generateEntityInterface,
+  type GenerateManagersConfig,
+  type GenerateManagersEntityConfig,
+} from './generateManagers'

package/src/gen/schema.ts

@@ -0,0 +1,248 @@
+/**
+ * Unified Schema Types
+ *
+ * Core contracts that abstract differences between OpenAPI, Pydantic, and manual schema sources.
+ * These types provide a common format for entity and field definitions that can be used
+ * by connectors (schema sources) and generators (code output).
+ *
+ * @module gen/schema
+ */
+
+/**
+ * Field Type Enumeration
+ *
+ * Unified field types that abstract source-specific types (OpenAPI string/integer,
+ * Pydantic str/int, etc.) into a common set.
+ */
+export type UnifiedFieldType =
+  | 'text'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'datetime'
+  | 'email'
+  | 'url'
+  | 'uuid'
+  | 'array'
+  | 'object'
+
+/**
+ * Reference Definition
+ *
+ * Describes a relation to another entity for foreign key fields.
+ */
+export interface UnifiedFieldReference {
+  /** Target entity name (e.g., 'users', 'categories') */
+  entity: string
+  /** Field to display as label (e.g., 'name', 'title') */
+  labelField?: string
+}
+
+/**
+ * Unified Field Schema
+ *
+ * Common field definition that abstracts OpenAPI property, Pydantic field, or manual definition.
+ * Connectors transform their source-specific formats into this common shape.
+ *
+ * @example
+ * // Simple text field
+ * const nameField: UnifiedFieldSchema = {
+ *   name: 'name',
+ *   type: 'text',
+ *   label: 'Full Name',
+ *   required: true
+ * }
+ *
+ * @example
+ * // Enum field with options
+ * const statusField: UnifiedFieldSchema = {
+ *   name: 'status',
+ *   type: 'text',
+ *   label: 'Status',
+ *   enum: ['draft', 'published', 'archived'],
+ *   default: 'draft'
+ * }
+ *
+ * @example
+ * // Foreign key with reference
+ * const authorField: UnifiedFieldSchema = {
+ *   name: 'author_id',
+ *   type: 'number',
+ *   label: 'Author',
+ *   reference: {
+ *     entity: 'users',
+ *     labelField: 'username'
+ *   }
+ * }
+ */
+export interface UnifiedFieldSchema {
+  /** Field name (e.g., 'email', 'created_at') */
+  name: string
+  /** Unified field type */
+  type: UnifiedFieldType
+  /** Human-readable label (e.g., 'Email Address') */
+  label?: string
+  /** Whether field is required (default: false) */
+  required?: boolean
+  /** Whether field is read-only (default: false) */
+  readOnly?: boolean
+  /** Whether field should be hidden in UI (default: false) */
+  hidden?: boolean
+  /** Original format hint from source (e.g., 'date-time', 'uri', 'email') */
+  format?: string
+  /** Allowed values for enumeration fields */
+  enum?: string[]
+  /** Default value for the field */
+  default?: unknown
+  /** Relation to another entity */
+  reference?: UnifiedFieldReference
+  /** Project-specific extensions */
+  extensions?: Record<string, unknown>
+  /** Field display order */
+  order?: number
+  /** Additional properties */
+  [key: string]: unknown
+}
+
+/**
+ * Unified Entity Schema
+ *
+ * Common entity definition that abstracts OpenAPI path/schema, Pydantic model, or manual definition.
+ * This is the primary contract between schema sources (connectors) and consumers (generators, runtime).
+ *
+ * @example
+ * // Complete entity schema
+ * const usersSchema: UnifiedEntitySchema = {
+ *   name: 'users',
+ *   endpoint: '/api/users',
+ *   label: 'User',
+ *   labelPlural: 'Users',
+ *   labelField: 'username',
+ *   routePrefix: 'user',
+ *   idField: 'id',
+ *   readOnly: false,
+ *   fields: {
+ *     id: { name: 'id', type: 'number', readOnly: true },
+ *     username: { name: 'username', type: 'text', required: true },
+ *     email: { name: 'email', type: 'email', required: true },
+ *     created_at: { name: 'created_at', type: 'datetime', readOnly: true }
+ *   }
+ * }
+ */
+export interface UnifiedEntitySchema {
+  /** Entity name, typically plural lowercase (e.g., 'users', 'blog_posts') */
+  name: string
+  /** API endpoint path (e.g., '/users', '/api/v1/posts') */
+  endpoint: string
+  /** Human-readable singular label (e.g., 'User', 'Blog Post') */
+  label?: string
+  /** Human-readable plural label (e.g., 'Users', 'Blog Posts') */
+  labelPlural?: string
+  /** Field used as display label (e.g., 'name', 'title') */
+  labelField?: string
+  /** Route prefix for admin UI (e.g., 'user', 'blog-post') */
+  routePrefix?: string
+  /** Primary key field name (default: 'id') */
+  idField?: string
+  /** Whether entity is read-only (no create/update/delete) */
+  readOnly?: boolean
+  /** Field definitions keyed by field name */
+  fields: Record<string, UnifiedFieldSchema>
+  /** Project-specific extensions */
+  extensions?: Record<string, unknown>
+}
+
+/**
+ * Valid field types for UnifiedFieldSchema
+ *
+ * Used for validation and documentation. Maps to common UI input types:
+ * - text: Single-line text input
+ * - number: Numeric input
+ * - boolean: Checkbox/toggle
+ * - date: Date picker (date only)
+ * - datetime: Date-time picker
+ * - email: Email input with validation
+ * - url: URL input with validation
+ * - uuid: UUID text input
+ * - array: Multi-value field (tags, list)
+ * - object: Nested object (JSON editor or subform)
+ */
+export const UNIFIED_FIELD_TYPES = [
+  'text',
+  'number',
+  'boolean',
+  'date',
+  'datetime',
+  'email',
+  'url',
+  'uuid',
+  'array',
+  'object',
+] as const
+
+/**
+ * Check if a type is a valid UnifiedFieldType
+ *
+ * @param type - Type to validate
+ * @returns True if valid
+ *
+ * @example
+ * isValidFieldType('text')     // true
+ * isValidFieldType('string')   // false (OpenAPI type, not unified)
+ */
+export function isValidFieldType(type: string): type is UnifiedFieldType {
+  return (UNIFIED_FIELD_TYPES as readonly string[]).includes(type)
+}
+
+/**
+ * Create a minimal field schema with defaults
+ *
+ * @param name - Field name
+ * @param type - Field type
+ * @param overrides - Additional field properties
+ * @returns Complete field schema
+ *
+ * @example
+ * const field = createFieldSchema('email', 'email', { required: true })
+ * // { name: 'email', type: 'email', required: true }
+ */
+export function createFieldSchema(
+  name: string,
+  type: UnifiedFieldType,
+  overrides: Partial<UnifiedFieldSchema> = {}
+): UnifiedFieldSchema {
+  return {
+    name,
+    type,
+    ...overrides,
+  }
+}
+
+/**
+ * Create a minimal entity schema with defaults
+ *
+ * @param name - Entity name
+ * @param endpoint - API endpoint
+ * @param fields - Field definitions
+ * @param overrides - Additional entity properties
+ * @returns Complete entity schema
+ *
+ * @example
+ * const schema = createEntitySchema('users', '/api/users', {
+ *   id: createFieldSchema('id', 'number', { readOnly: true }),
+ *   name: createFieldSchema('name', 'text', { required: true })
+ * })
+ */
+export function createEntitySchema(
+  name: string,
+  endpoint: string,
+  fields: Record<string, UnifiedFieldSchema>,
+  overrides: Partial<UnifiedEntitySchema> = {}
+): UnifiedEntitySchema {
+  return {
+    name,
+    endpoint,
+    fields,
+    ...overrides,
+  }
+}