qdadm 0.28.0 → 0.29.0

package/src/gen/schema.js

@@ -0,0 +1,221 @@
+/**
+ * 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.
+ *
+ * @typedef {'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'email' | 'url' | 'uuid' | 'array' | 'object'} UnifiedFieldType
+ */
+
+/**
+ * Reference Definition
+ *
+ * Describes a relation to another entity for foreign key fields.
+ *
+ * @typedef {object} UnifiedFieldReference
+ * @property {string} entity - Target entity name (e.g., 'users', 'categories')
+ * @property {string} [labelField] - Field to display as label (e.g., 'name', 'title')
+ */
+
+/**
+ * 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.
+ *
+ * @typedef {object} UnifiedFieldSchema
+ * @property {string} name - Field name (e.g., 'email', 'created_at')
+ * @property {UnifiedFieldType} type - Unified field type
+ * @property {string} [label] - Human-readable label (e.g., 'Email Address')
+ * @property {boolean} [required] - Whether field is required (default: false)
+ * @property {boolean} [readOnly] - Whether field is read-only (default: false)
+ * @property {boolean} [hidden] - Whether field should be hidden in UI (default: false)
+ * @property {string} [format] - Original format hint from source (e.g., 'date-time', 'uri', 'email')
+ * @property {string[]} [enum] - Allowed values for enumeration fields
+ * @property {*} [default] - Default value for the field
+ * @property {UnifiedFieldReference} [reference] - Relation to another entity
+ * @property {Record<string, *>} [extensions] - Project-specific extensions
+ *
+ * @example
+ * // Simple text field
+ * const nameField = {
+ *   name: 'name',
+ *   type: 'text',
+ *   label: 'Full Name',
+ *   required: true
+ * }
+ *
+ * @example
+ * // Enum field with options
+ * const statusField = {
+ *   name: 'status',
+ *   type: 'text',
+ *   label: 'Status',
+ *   enum: ['draft', 'published', 'archived'],
+ *   default: 'draft'
+ * }
+ *
+ * @example
+ * // Foreign key with reference
+ * const authorField = {
+ *   name: 'author_id',
+ *   type: 'number',
+ *   label: 'Author',
+ *   reference: {
+ *     entity: 'users',
+ *     labelField: 'username'
+ *   }
+ * }
+ */
+
+/**
+ * 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).
+ *
+ * @typedef {object} UnifiedEntitySchema
+ * @property {string} name - Entity name, typically plural lowercase (e.g., 'users', 'blog_posts')
+ * @property {string} endpoint - API endpoint path (e.g., '/users', '/api/v1/posts')
+ * @property {string} [label] - Human-readable singular label (e.g., 'User', 'Blog Post')
+ * @property {string} [labelPlural] - Human-readable plural label (e.g., 'Users', 'Blog Posts')
+ * @property {string} [labelField] - Field used as display label (e.g., 'name', 'title')
+ * @property {string} [routePrefix] - Route prefix for admin UI (e.g., 'user', 'blog-post')
+ * @property {string} [idField] - Primary key field name (default: 'id')
+ * @property {boolean} [readOnly] - Whether entity is read-only (no create/update/delete)
+ * @property {Record<string, UnifiedFieldSchema>} fields - Field definitions keyed by field name
+ * @property {Record<string, *>} [extensions] - Project-specific extensions
+ *
+ * @example
+ * // Complete entity schema
+ * const usersSchema = {
+ *   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 }
+ *   }
+ * }
+ *
+ * @example
+ * // Read-only entity (external API)
+ * const countriesSchema = {
+ *   name: 'countries',
+ *   endpoint: 'https://restcountries.com/v3.1/all',
+ *   label: 'Country',
+ *   labelPlural: 'Countries',
+ *   labelField: 'name',
+ *   idField: 'cca3',
+ *   readOnly: true,
+ *   fields: {
+ *     cca3: { name: 'cca3', type: 'text', label: 'Code' },
+ *     name: { name: 'name', type: 'text', label: 'Name' }
+ *   }
+ * }
+ */
+
+/**
+ * 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)
+ *
+ * @type {readonly UnifiedFieldType[]}
+ */
+export const UNIFIED_FIELD_TYPES = Object.freeze([
+  'text',
+  'number',
+  'boolean',
+  'date',
+  'datetime',
+  'email',
+  'url',
+  'uuid',
+  'array',
+  'object'
+])
+
+/**
+ * Check if a type is a valid UnifiedFieldType
+ *
+ * @param {string} type - Type to validate
+ * @returns {type is UnifiedFieldType} - True if valid
+ *
+ * @example
+ * isValidFieldType('text')     // true
+ * isValidFieldType('string')   // false (OpenAPI type, not unified)
+ */
+export function isValidFieldType(type) {
+  return UNIFIED_FIELD_TYPES.includes(type)
+}
+
+/**
+ * Create a minimal field schema with defaults
+ *
+ * @param {string} name - Field name
+ * @param {UnifiedFieldType} type - Field type
+ * @param {Partial<UnifiedFieldSchema>} [overrides] - Additional field properties
+ * @returns {UnifiedFieldSchema} - Complete field schema
+ *
+ * @example
+ * const field = createFieldSchema('email', 'email', { required: true })
+ * // { name: 'email', type: 'email', required: true }
+ */
+export function createFieldSchema(name, type, overrides = {}) {
+  return {
+    name,
+    type,
+    ...overrides
+  }
+}
+
+/**
+ * Create a minimal entity schema with defaults
+ *
+ * @param {string} name - Entity name
+ * @param {string} endpoint - API endpoint
+ * @param {Record<string, UnifiedFieldSchema>} fields - Field definitions
+ * @param {Partial<UnifiedEntitySchema>} [overrides] - Additional entity properties
+ * @returns {UnifiedEntitySchema} - 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, endpoint, fields, overrides = {}) {
+  return {
+    name,
+    endpoint,
+    fields,
+    ...overrides
+  }
+}

package/src/gen/vite-plugin.js

@@ -0,0 +1,105 @@
+/**
+ * Vite Plugin for qdadm EntityManager Generation
+ *
+ * Integrates generateManagers with Vite's build pipeline, triggering
+ * entity manager file generation during the buildStart hook.
+ *
+ * @module gen/vite-plugin
+ */
+
+import { generateManagers } from './generateManagers.js'
+import { pathToFileURL } from 'node:url'
+import { resolve } from 'node:path'
+
+/**
+ * Plugin options for qdadmGen
+ *
+ * @typedef {object} QdadmGenOptions
+ * @property {string} [config] - Path to qdadm config file (default: 'qdadm.config.js')
+ * @property {string} [output] - Override output directory for generated files
+ */
+
+/**
+ * Vite plugin for generating EntityManager files at build time
+ *
+ * Loads the qdadm configuration file and calls generateManagers during
+ * Vite's buildStart hook. Supports both ESM and CommonJS config files.
+ *
+ * @param {QdadmGenOptions} [options={}] - Plugin options
+ * @returns {import('vite').Plugin} Vite plugin object
+ *
+ * @example
+ * // vite.config.js
+ * import { defineConfig } from 'vite'
+ * import { qdadmGen } from 'qdadm/gen/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     qdadmGen({
+ *       config: './qdadm.config.js',
+ *       output: 'src/generated/managers/'
+ *     })
+ *   ]
+ * })
+ *
+ * @example
+ * // qdadm.config.js
+ * export default {
+ *   output: 'src/generated/managers/',
+ *   entities: {
+ *     users: {
+ *       schema: { name: 'users', fields: { id: { type: 'integer' } } },
+ *       endpoint: '/api/users',
+ *       storageImport: 'qdadm',
+ *       storageClass: 'ApiStorage'
+ *     }
+ *   }
+ * }
+ */
+export function qdadmGen(options = {}) {
+  const configPath = options.config || 'qdadm.config.js'
+
+  return {
+    name: 'qdadm-gen',
+
+    async buildStart() {
+      try {
+        // Resolve config path relative to cwd
+        const resolvedConfigPath = resolve(process.cwd(), configPath)
+
+        // Load config file dynamically
+        const configUrl = pathToFileURL(resolvedConfigPath).href
+        const configModule = await import(configUrl)
+        const loadedConfig = configModule.default || configModule
+
+        // Validate loaded config
+        if (!loadedConfig || typeof loadedConfig !== 'object') {
+          throw new Error(`Invalid qdadm config at '${configPath}': must export an object`)
+        }
+
+        if (!loadedConfig.entities) {
+          throw new Error(`Invalid qdadm config at '${configPath}': missing 'entities' property`)
+        }
+
+        // Merge plugin options with config (plugin options take precedence)
+        const mergedConfig = {
+          ...loadedConfig,
+          ...(options.output && { output: options.output })
+        }
+
+        // Generate managers
+        const generatedFiles = await generateManagers(mergedConfig)
+
+        // Log results
+        console.log(`[qdadm-gen] Generated ${generatedFiles.length} manager file(s)`)
+        for (const file of generatedFiles) {
+          console.log(`  - ${file}`)
+        }
+      } catch (error) {
+        // Wrap error with plugin context for clearer messages
+        const message = error instanceof Error ? error.message : String(error)
+        throw new Error(`[qdadm-gen] Failed to generate managers: ${message}`)
+      }
+    }
+  }
+}

package/src/generated/managers/testManager.js

@@ -0,0 +1,45 @@
+/**
+ * TestManager - Auto-generated EntityManager
+ *
+ * Generated by qdadm/gen/generateManagers
+ * DO NOT EDIT MANUALLY - Changes will be overwritten
+ *
+ * Entity: test
+ * Endpoint: /test
+ */
+
+import { EntityManager } from 'qdadm'
+import { ApiStorage } from 'qdadm'
+
+/**
+ * Schema definition for test
+ * @type {import('qdadm/gen').UnifiedEntitySchema}
+ */
+export const testSchema = {
+  name: "test",
+  endpoint: "/test",
+  fields: {}
+}
+
+/**
+ * Storage options for test
+ */
+const storageOptions = {
+  endpoint: "/test"
+}
+
+/**
+ * TestManager instance
+ *
+ * Provides CRUD operations for test entity.
+ *
+ * @type {EntityManager}
+ */
+export const testManager = new EntityManager({
+  ...{
+  name: "test",
+  idField: "id",
+  fields: {}
+},
+  storage: new ApiStorage(storageOptions)
+})