qdadm 0.28.0 → 0.29.0

package/src/gen/connectors/__fixtures__/sample-openapi.json

@@ -0,0 +1,311 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Sample API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/api/users": {
+      "get": {
+        "summary": "List users",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/User"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "summary": "Create user",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateUserRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/User"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/users/{id}": {
+      "get": {
+        "summary": "Get user by ID",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/User"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/posts": {
+      "get": {
+        "summary": "List posts",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Post"
+                      }
+                    },
+                    "pagination": {
+                      "type": "object",
+                      "properties": {
+                        "page": { "type": "integer" },
+                        "total": { "type": "integer" }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/posts/{id}": {
+      "get": {
+        "summary": "Get post by ID",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/Post"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/categories": {
+      "get": {
+        "summary": "List categories",
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Category"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/internal/metrics": {
+      "get": {
+        "summary": "Internal metrics",
+        "tags": ["internal"],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "required": ["email"],
+        "properties": {
+          "id": {
+            "type": "integer",
+            "readOnly": true,
+            "description": "User ID"
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "description": "Email address"
+          },
+          "name": {
+            "type": "string",
+            "description": "Full name"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "readOnly": true,
+            "description": "Creation date"
+          },
+          "website": {
+            "type": "string",
+            "format": "uri",
+            "description": "Personal website"
+          },
+          "uuid": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique identifier"
+          },
+          "active": {
+            "type": "boolean",
+            "default": true,
+            "description": "Is active"
+          },
+          "role": {
+            "type": "string",
+            "enum": ["admin", "user", "guest"],
+            "default": "user",
+            "description": "User role"
+          },
+          "tags": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "User tags"
+          },
+          "metadata": {
+            "type": "object",
+            "description": "Extra metadata"
+          },
+          "profile": {
+            "type": "object",
+            "properties": {
+              "bio": { "type": "string" },
+              "avatar": { "type": "string", "format": "uri" }
+            }
+          }
+        }
+      },
+      "CreateUserRequest": {
+        "type": "object",
+        "required": ["email", "name"],
+        "properties": {
+          "email": {
+            "type": "string",
+            "format": "email"
+          },
+          "name": {
+            "type": "string"
+          },
+          "password": {
+            "type": "string",
+            "format": "password"
+          }
+        }
+      },
+      "Post": {
+        "type": "object",
+        "required": ["title"],
+        "properties": {
+          "id": {
+            "type": "integer",
+            "readOnly": true
+          },
+          "title": {
+            "type": "string",
+            "description": "Post title"
+          },
+          "content": {
+            "type": "string"
+          },
+          "author_id": {
+            "type": "integer",
+            "description": "Author reference"
+          },
+          "published_at": {
+            "type": "string",
+            "format": "date"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["draft", "published", "archived"],
+            "default": "draft"
+          }
+        }
+      },
+      "Category": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "readOnly": true
+          },
+          "name": {
+            "type": "string"
+          },
+          "slug": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/src/gen/connectors/index.js

@@ -0,0 +1,11 @@
+/**
+ * Schema Connectors
+ *
+ * Pluggable connectors that parse various schema sources into UnifiedEntitySchema format.
+ *
+ * @module gen/connectors
+ */
+
+export { BaseConnector } from './BaseConnector.js'
+export { ManualConnector } from './ManualConnector.js'
+export { OpenAPIConnector } from './OpenAPIConnector.js'

package/src/gen/createManagers.js

@@ -0,0 +1,224 @@
+/**
+ * Runtime Factory for EntityManager Creation
+ *
+ * Creates EntityManager instances on-the-fly from configuration.
+ * This is the core factory function that wires schemas, storage profiles,
+ * and decorators together at runtime.
+ *
+ * @module gen/createManagers
+ */
+
+import { EntityManager } from '../entity/EntityManager.js'
+import { applyDecorators } from './decorators.js'
+
+/**
+ * Entity configuration in the config.entities map
+ *
+ * @typedef {object} EntityConfig
+ * @property {string} schema - Schema source name (key in config.schemas)
+ * @property {string} storage - Storage profile name (key in config.storages)
+ * @property {string} endpoint - API endpoint path (e.g., '/users')
+ * @property {import('./StorageProfileFactory.js').StorageProfileOptions} [options] - Per-entity storage options
+ */
+
+/**
+ * Configuration for createManagers factory
+ *
+ * @typedef {object} CreateManagersConfig
+ * @property {Record<string, import('./schema.js').UnifiedEntitySchema[]>} schemas - Schema sources (connector results) keyed by name
+ * @property {Record<string, import('./StorageProfileFactory.js').StorageProfileFactory>} storages - Storage profile factories keyed by name
+ * @property {Record<string, EntityConfig>} entities - Entity configurations keyed by entity name
+ * @property {Record<string, object>} [decorators] - Per-entity decorators (fields, labels, permissions)
+ */
+
+/**
+ * Validate config structure early with clear error messages
+ *
+ * @param {CreateManagersConfig} config - Configuration to validate
+ * @throws {Error} - If config is invalid
+ * @private
+ */
+function validateConfig(config) {
+  if (!config || typeof config !== 'object') {
+    throw new Error('createManagers: config is required and must be an object')
+  }
+
+  if (!config.schemas || typeof config.schemas !== 'object') {
+    throw new Error('createManagers: config.schemas is required and must be an object')
+  }
+
+  if (!config.storages || typeof config.storages !== 'object') {
+    throw new Error('createManagers: config.storages is required and must be an object')
+  }
+
+  if (!config.entities || typeof config.entities !== 'object') {
+    throw new Error('createManagers: config.entities is required and must be an object')
+  }
+
+  // Validate each entity config
+  for (const [entityName, entityConfig] of Object.entries(config.entities)) {
+    if (!entityConfig || typeof entityConfig !== 'object') {
+      throw new Error(`createManagers: entity '${entityName}' config must be an object`)
+    }
+
+    if (!entityConfig.schema || typeof entityConfig.schema !== 'string') {
+      throw new Error(`createManagers: entity '${entityName}' requires 'schema' property`)
+    }
+
+    if (!entityConfig.storage || typeof entityConfig.storage !== 'string') {
+      throw new Error(`createManagers: entity '${entityName}' requires 'storage' property`)
+    }
+
+    if (!entityConfig.endpoint || typeof entityConfig.endpoint !== 'string') {
+      throw new Error(`createManagers: entity '${entityName}' requires 'endpoint' property`)
+    }
+
+    // Validate references exist
+    if (!(entityConfig.schema in config.schemas)) {
+      throw new Error(`createManagers: entity '${entityName}' references unknown schema '${entityConfig.schema}'`)
+    }
+
+    if (!(entityConfig.storage in config.storages)) {
+      throw new Error(`createManagers: entity '${entityName}' references unknown storage '${entityConfig.storage}'`)
+    }
+  }
+}
+
+/**
+ * Find schema for entity from connector result
+ *
+ * Connector results are arrays of UnifiedEntitySchema. This finds the schema
+ * matching the entity name, or uses the first schema if none matches.
+ *
+ * @param {import('./schema.js').UnifiedEntitySchema[]} schemas - Connector result (array of schemas)
+ * @param {string} entityName - Entity name to find
+ * @param {string} schemaSourceName - Schema source name for error messages
+ * @returns {import('./schema.js').UnifiedEntitySchema} - Found schema
+ * @throws {Error} - If schema not found
+ * @private
+ */
+function findSchemaForEntity(schemas, entityName, schemaSourceName) {
+  if (!Array.isArray(schemas)) {
+    throw new Error(`createManagers: schema source '${schemaSourceName}' must be an array of UnifiedEntitySchema`)
+  }
+
+  if (schemas.length === 0) {
+    throw new Error(`createManagers: schema source '${schemaSourceName}' is empty`)
+  }
+
+  // Find by entity name
+  const schema = schemas.find(s => s.name === entityName)
+  if (schema) {
+    return schema
+  }
+
+  // If only one schema in source, use it (common for single-entity sources)
+  if (schemas.length === 1) {
+    return schemas[0]
+  }
+
+  // Multiple schemas but none match
+  const available = schemas.map(s => s.name).join(', ')
+  throw new Error(`createManagers: entity '${entityName}' not found in schema source '${schemaSourceName}'. Available: ${available}`)
+}
+
+/**
+ * Create EntityManager instances from configuration
+ *
+ * This is the runtime factory that wires schemas, storage profiles, and
+ * decorators together at runtime without code generation.
+ *
+ * @param {CreateManagersConfig} config - Configuration object
+ * @returns {Map<string, EntityManager>} - Map of entity name to EntityManager instance
+ * @throws {Error} - If config is invalid or references missing schemas/storages
+ *
+ * @example
+ * import { createManagers } from 'qdadm/gen'
+ * import { ManualConnector } from 'qdadm/gen'
+ * import { ApiStorage } from 'qdadm'
+ * import axios from 'axios'
+ *
+ * // Define schemas using connectors
+ * const connector = new ManualConnector()
+ * const schemas = connector.parse([
+ *   {
+ *     name: 'users',
+ *     endpoint: '/users',
+ *     fields: {
+ *       id: { name: 'id', type: 'number', readOnly: true },
+ *       email: { name: 'email', type: 'email', required: true }
+ *     }
+ *   }
+ * ])
+ *
+ * // Define storage profile factory
+ * const apiClient = axios.create({ baseURL: 'https://api.example.com' })
+ * const apiProfile = (endpoint, options) => new ApiStorage({
+ *   endpoint,
+ *   client: apiClient,
+ *   ...options
+ * })
+ *
+ * // Create managers
+ * const managers = createManagers({
+ *   schemas: { api: schemas },
+ *   storages: { jsonplaceholder: apiProfile },
+ *   entities: {
+ *     users: { schema: 'api', storage: 'jsonplaceholder', endpoint: '/users' }
+ *   },
+ *   decorators: {
+ *     users: { fields: { email: { hidden: true } } }
+ *   }
+ * })
+ *
+ * const usersManager = managers.get('users')
+ * const users = await usersManager.list()
+ */
+export function createManagers(config) {
+  // Validate config structure early
+  validateConfig(config)
+
+  /** @type {Map<string, EntityManager>} */
+  const managers = new Map()
+
+  // Process each entity configuration
+  for (const [entityName, entityConfig] of Object.entries(config.entities)) {
+    // 1. Get schema from connector result
+    const schemaSource = config.schemas[entityConfig.schema]
+    let schema = findSchemaForEntity(schemaSource, entityName, entityConfig.schema)
+
+    // 2. Apply decorators if defined
+    const decorator = config.decorators?.[entityName]
+    schema = applyDecorators(schema, decorator)
+
+    // 3. Get storage factory and create storage instance
+    const storageFactory = config.storages[entityConfig.storage]
+    if (typeof storageFactory !== 'function') {
+      throw new Error(`createManagers: storage '${entityConfig.storage}' must be a factory function`)
+    }
+
+    const storageOptions = {
+      entity: entityName,
+      ...entityConfig.options
+    }
+    const storage = storageFactory(entityConfig.endpoint, storageOptions)
+
+    // 4. Create EntityManager with schema + storage
+    const manager = new EntityManager({
+      name: schema.name,
+      storage,
+      idField: schema.idField || 'id',
+      label: schema.label,
+      labelPlural: schema.labelPlural,
+      labelField: schema.labelField,
+      routePrefix: schema.routePrefix,
+      readOnly: schema.readOnly,
+      fields: schema.fields
+    })
+
+    // 5. Store in result Map
+    managers.set(entityName, manager)
+  }
+
+  return managers
+}

package/src/gen/decorators.js

@@ -0,0 +1,129 @@
+/**
+ * Decorators Layer
+ *
+ * Applies per-entity field customizations to UnifiedEntitySchema.
+ * Decorators allow overriding field properties (hidden, label, readonly, order)
+ * without modifying the base schema from connectors.
+ *
+ * @module gen/decorators
+ */
+
+/**
+ * Allowed decorator properties for field overrides.
+ * Unknown properties will trigger a console warning.
+ *
+ * @type {readonly string[]}
+ */
+const ALLOWED_FIELD_DECORATORS = Object.freeze([
+  'hidden',
+  'label',
+  'readOnly',
+  'order'
+])
+
+/**
+ * Field Decorator Configuration
+ *
+ * Per-field overrides that can be applied to schema fields.
+ *
+ * @typedef {object} FieldDecorator
+ * @property {boolean} [hidden] - Override field visibility
+ * @property {string} [label] - Override field label
+ * @property {boolean} [readOnly] - Override field read-only state
+ * @property {number} [order] - Override field display order
+ */
+
+/**
+ * Entity Decorator Configuration
+ *
+ * Decorator configuration for a single entity.
+ *
+ * @typedef {object} EntityDecorator
+ * @property {Record<string, FieldDecorator>} [fields] - Field-level overrides keyed by field name
+ */
+
+/**
+ * Apply decorators to a UnifiedEntitySchema
+ *
+ * Takes a schema and decorator configuration, returns a new schema with
+ * decorator properties merged onto matching fields. Original schema is
+ * not mutated.
+ *
+ * @param {import('./schema.js').UnifiedEntitySchema} schema - Original entity schema
+ * @param {EntityDecorator} [decoratorConfig] - Decorator configuration
+ * @returns {import('./schema.js').UnifiedEntitySchema} New schema with decorators applied
+ *
+ * @example
+ * // Hide email field and rename created_at
+ * const decorated = applyDecorators(usersSchema, {
+ *   fields: {
+ *     email: { hidden: true },
+ *     created_at: { label: 'Member Since', readOnly: true }
+ *   }
+ * })
+ *
+ * @example
+ * // Set field display order
+ * const ordered = applyDecorators(postsSchema, {
+ *   fields: {
+ *     title: { order: 1 },
+ *     body: { order: 2 },
+ *     author_id: { order: 3 }
+ *   }
+ * })
+ */
+export function applyDecorators(schema, decoratorConfig) {
+  // No decorators - return schema as-is (still immutable reference)
+  if (!decoratorConfig || !decoratorConfig.fields) {
+    return schema
+  }
+
+  const { fields: fieldDecorators } = decoratorConfig
+
+  // Build new fields object with decorators applied
+  const decoratedFields = {}
+
+  for (const [fieldName, fieldSchema] of Object.entries(schema.fields)) {
+    const decorator = fieldDecorators[fieldName]
+
+    if (!decorator) {
+      // No decorator for this field - copy as-is
+      decoratedFields[fieldName] = { ...fieldSchema }
+      continue
+    }
+
+    // Validate decorator properties
+    for (const key of Object.keys(decorator)) {
+      if (!ALLOWED_FIELD_DECORATORS.includes(key)) {
+        console.warn(
+          `[qdadm] Unknown decorator property "${key}" for field "${fieldName}" in entity "${schema.name}". Allowed: ${ALLOWED_FIELD_DECORATORS.join(', ')}`
+        )
+      }
+    }
+
+    // Merge decorator properties onto field (only allowed properties)
+    const decoratedField = { ...fieldSchema }
+    for (const key of ALLOWED_FIELD_DECORATORS) {
+      if (key in decorator) {
+        decoratedField[key] = decorator[key]
+      }
+    }
+
+    decoratedFields[fieldName] = decoratedField
+  }
+
+  // Warn about decorators for non-existent fields
+  for (const fieldName of Object.keys(fieldDecorators)) {
+    if (!(fieldName in schema.fields)) {
+      console.warn(
+        `[qdadm] Decorator defined for unknown field "${fieldName}" in entity "${schema.name}". Available fields: ${Object.keys(schema.fields).join(', ')}`
+      )
+    }
+  }
+
+  // Return new schema with decorated fields
+  return {
+    ...schema,
+    fields: decoratedFields
+  }
+}