qdadm 0.27.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)
+})

package/src/index.js

@@ -35,6 +35,9 @@ export * from './zones/index.js'
 // Hooks
 export * from './hooks/index.js'
 
+// Deferred (async service loading)
+export * from './deferred/index.js'
+
 // Core (extension helpers)
 export * from './core/index.js'
 

package/src/kernel/EventRouter.js

@@ -0,0 +1,264 @@
+/**
+ * EventRouter - Declarative signal routing
+ *
+ * Routes one signal to multiple targets (signals or callbacks).
+ * Configured at Kernel level to keep components simple.
+ *
+ * Usage:
+ * ```js
+ * const router = new EventRouter({
+ *   signals,      // SignalBus instance
+ *   orchestrator, // Orchestrator instance (optional, for callbacks)
+ *   routes: {
+ *     'auth:impersonate': [
+ *       'cache:entity:invalidate:loans',     // string = emit signal
+ *       { signal: 'notify', transform: (p) => ({ msg: p.user }) },  // object = transform
+ *       (payload, ctx) => { ... }            // function = callback
+ *     ]
+ *   }
+ * })
+ * ```
+ */
+
+/**
+ * Detect cycles in route graph using DFS
+ *
+ * @param {object} routes - Route configuration
+ * @returns {string[]|null} - Cycle path if found, null otherwise
+ */
+function detectCycles(routes) {
+  // Build adjacency list (only signal targets, not callbacks)
+  const graph = new Map()
+
+  for (const [source, targets] of Object.entries(routes)) {
+    const signalTargets = []
+    for (const target of targets) {
+      if (typeof target === 'string') {
+        signalTargets.push(target)
+      } else if (target && typeof target === 'object' && target.signal) {
+        signalTargets.push(target.signal)
+      }
+      // Functions don't create edges in the graph
+    }
+    graph.set(source, signalTargets)
+  }
+
+  // DFS cycle detection
+  const visited = new Set()
+  const recursionStack = new Set()
+  const path = []
+
+  function dfs(node) {
+    visited.add(node)
+    recursionStack.add(node)
+    path.push(node)
+
+    const neighbors = graph.get(node) || []
+    for (const neighbor of neighbors) {
+      if (!visited.has(neighbor)) {
+        const cycle = dfs(neighbor)
+        if (cycle) return cycle
+      } else if (recursionStack.has(neighbor)) {
+        // Found cycle - return path from neighbor to current
+        const cycleStart = path.indexOf(neighbor)
+        return [...path.slice(cycleStart), neighbor]
+      }
+    }
+
+    path.pop()
+    recursionStack.delete(node)
+    return null
+  }
+
+  // Check all nodes
+  for (const node of graph.keys()) {
+    if (!visited.has(node)) {
+      const cycle = dfs(node)
+      if (cycle) return cycle
+    }
+  }
+
+  return null
+}
+
+export class EventRouter {
+  /**
+   * @param {object} options
+   * @param {SignalBus} options.signals - SignalBus instance
+   * @param {Orchestrator} [options.orchestrator] - Orchestrator (for callback context)
+   * @param {object} options.routes - Route configuration
+   * @param {boolean} [options.debug=false] - Enable debug logging
+   */
+  constructor(options = {}) {
+    const { signals, orchestrator = null, routes = {}, debug = false } = options
+
+    if (!signals) {
+      throw new Error('[EventRouter] signals is required')
+    }
+
+    this._signals = signals
+    this._orchestrator = orchestrator
+    this._routes = routes
+    this._debug = debug
+    this._cleanups = []
+
+    // Validate and setup
+    this._validateRoutes()
+    this._setupListeners()
+  }
+
+  /**
+   * Validate routes configuration and check for cycles
+   * @private
+   */
+  _validateRoutes() {
+    // Check for cycles
+    const cycle = detectCycles(this._routes)
+    if (cycle) {
+      throw new Error(
+        `[EventRouter] Cycle detected: ${cycle.join(' -> ')}`
+      )
+    }
+
+    // Validate each route
+    for (const [source, targets] of Object.entries(this._routes)) {
+      if (!Array.isArray(targets)) {
+        throw new Error(
+          `[EventRouter] Route "${source}" must be an array of targets`
+        )
+      }
+
+      for (let i = 0; i < targets.length; i++) {
+        const target = targets[i]
+        const isString = typeof target === 'string'
+        const isFunction = typeof target === 'function'
+        const isObject = target && typeof target === 'object' && target.signal
+
+        if (!isString && !isFunction && !isObject) {
+          throw new Error(
+            `[EventRouter] Invalid target at "${source}"[${i}]: must be string, function, or { signal, transform? }`
+          )
+        }
+      }
+    }
+  }
+
+  /**
+   * Setup signal listeners for all routes
+   * @private
+   */
+  _setupListeners() {
+    for (const [source, targets] of Object.entries(this._routes)) {
+      const cleanup = this._signals.on(source, (payload) => {
+        this._handleRoute(source, payload, targets)
+      })
+      this._cleanups.push(cleanup)
+    }
+
+    if (this._debug) {
+      console.debug(`[EventRouter] Registered ${Object.keys(this._routes).length} routes`)
+    }
+  }
+
+  /**
+   * Handle a routed signal
+   * @private
+   */
+  _handleRoute(source, payload, targets) {
+    if (this._debug) {
+      console.debug(`[EventRouter] ${source} -> ${targets.length} targets`)
+    }
+
+    const context = {
+      signals: this._signals,
+      orchestrator: this._orchestrator
+    }
+
+    for (const target of targets) {
+      try {
+        if (typeof target === 'string') {
+          // String: emit signal with same payload
+          this._signals.emit(target, payload)
+          if (this._debug) {
+            console.debug(`[EventRouter]   -> ${target} (forward)`)
+          }
+        } else if (typeof target === 'function') {
+          // Function: call callback
+          target(payload, context)
+          if (this._debug) {
+            console.debug(`[EventRouter]   -> callback()`)
+          }
+        } else if (target && target.signal) {
+          // Object: emit signal with transformed payload
+          const transformedPayload = target.transform
+            ? target.transform(payload)
+            : payload
+          this._signals.emit(target.signal, transformedPayload)
+          if (this._debug) {
+            console.debug(`[EventRouter]   -> ${target.signal} (transform)`)
+          }
+        }
+      } catch (error) {
+        console.error(`[EventRouter] Error handling ${source} -> ${JSON.stringify(target)}:`, error)
+      }
+    }
+  }
+
+  /**
+   * Add a route dynamically
+   *
+   * @param {string} source - Source signal
+   * @param {Array} targets - Target array
+   */
+  addRoute(source, targets) {
+    if (this._routes[source]) {
+      throw new Error(`[EventRouter] Route "${source}" already exists`)
+    }
+
+    // Validate new route doesn't create cycle
+    const testRoutes = { ...this._routes, [source]: targets }
+    const cycle = detectCycles(testRoutes)
+    if (cycle) {
+      throw new Error(`[EventRouter] Adding route would create cycle: ${cycle.join(' -> ')}`)
+    }
+
+    this._routes[source] = targets
+
+    // Setup listener
+    const cleanup = this._signals.on(source, (payload) => {
+      this._handleRoute(source, payload, targets)
+    })
+    this._cleanups.push(cleanup)
+  }
+
+  /**
+   * Get all registered routes
+   * @returns {object}
+   */
+  getRoutes() {
+    return { ...this._routes }
+  }
+
+  /**
+   * Dispose the router, cleaning up all listeners
+   */
+  dispose() {
+    for (const cleanup of this._cleanups) {
+      if (typeof cleanup === 'function') {
+        cleanup()
+      }
+    }
+    this._cleanups = []
+    this._routes = {}
+  }
+}
+
+/**
+ * Factory function for creating EventRouter
+ *
+ * @param {object} options
+ * @returns {EventRouter}
+ */
+export function createEventRouter(options) {
+  return new EventRouter(options)
+}