qdadm 0.28.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -25,7 +25,9 @@
     "./module": "./src/module/index.js",
     "./utils": "./src/utils/index.js",
     "./styles": "./src/styles/index.scss",
-    "./styles/breakpoints": "./src/styles/_breakpoints.scss"
+    "./styles/breakpoints": "./src/styles/_breakpoints.scss",
+    "./gen": "./src/gen/index.js",
+    "./gen/vite-plugin": "./src/gen/vite-plugin.js"
   },
   "files": [
     "src",

package/src/gen/FieldMapper.js

@@ -0,0 +1,116 @@
+/**
+ * Field Type Mapper
+ *
+ * Maps JSON Schema types and formats to UnifiedFieldSchema types.
+ * Extracted from Skybot and Faketual to eliminate duplication.
+ *
+ * Mapping priority:
+ * 1. Enum detection (schema.enum present -> 'select')
+ * 2. Custom mappings (user-provided)
+ * 3. Format-specific mappings (e.g., string + format:email -> email)
+ * 4. Base type mappings (e.g., string -> text)
+ *
+ * @module gen/FieldMapper
+ */
+
+/**
+ * Base type mappings: JSON Schema type -> UnifiedFieldSchema type
+ *
+ * @type {Readonly<Record<string, import('./schema.js').UnifiedFieldType>>}
+ */
+export const BASE_TYPE_MAPPINGS = Object.freeze({
+  string: 'text',
+  integer: 'number',
+  number: 'number',
+  boolean: 'boolean',
+  array: 'array',
+  object: 'object'
+})
+
+/**
+ * Format-specific mappings: JSON Schema format -> UnifiedFieldSchema type
+ *
+ * These take precedence over base type mappings when a format is specified.
+ *
+ * @type {Readonly<Record<string, import('./schema.js').UnifiedFieldType>>}
+ */
+export const FORMAT_MAPPINGS = Object.freeze({
+  email: 'email',
+  'date-time': 'datetime',
+  date: 'date',
+  uri: 'url',
+  url: 'url',
+  uuid: 'uuid',
+  password: 'text'
+})
+
+/**
+ * Custom mappings override structure
+ *
+ * @typedef {object} CustomMappings
+ * @property {Record<string, string>} [types] - Custom type mappings { jsonSchemaType: unifiedType }
+ * @property {Record<string, string>} [formats] - Custom format mappings { jsonSchemaFormat: unifiedType }
+ */
+
+/**
+ * Minimal JSON Schema property definition for type detection
+ *
+ * @typedef {object} SchemaProperty
+ * @property {string} [type] - JSON Schema type (string, integer, number, boolean, array, object)
+ * @property {string} [format] - JSON Schema format (email, date-time, uuid, etc.)
+ * @property {Array<*>} [enum] - Enumeration values
+ */
+
+/**
+ * Get the UnifiedFieldSchema type for a JSON Schema property
+ *
+ * @param {SchemaProperty} schema - JSON Schema property definition
+ * @param {CustomMappings} [customMappings] - Optional custom type/format mappings
+ * @returns {import('./schema.js').UnifiedFieldType | 'select'} - Unified field type
+ *
+ * @example
+ * // Basic type mapping
+ * getDefaultType({ type: 'string' })           // 'text'
+ * getDefaultType({ type: 'integer' })          // 'number'
+ *
+ * @example
+ * // Format takes precedence
+ * getDefaultType({ type: 'string', format: 'email' })  // 'email'
+ * getDefaultType({ type: 'string', format: 'uuid' })   // 'uuid'
+ *
+ * @example
+ * // Enum detection
+ * getDefaultType({ type: 'string', enum: ['a', 'b'] }) // 'select'
+ *
+ * @example
+ * // Custom mappings
+ * getDefaultType({ type: 'string', format: 'phone' }, {
+ *   formats: { phone: 'text' }
+ * })  // 'text'
+ */
+export function getDefaultType(schema, customMappings = {}) {
+  const { type, format } = schema || {}
+
+  // Check for enum pattern first (returns 'select')
+  if (Array.isArray(schema?.enum) && schema.enum.length > 0) {
+    return 'select'
+  }
+
+  // Check custom format mapping
+  if (format && customMappings.formats?.[format]) {
+    return customMappings.formats[format]
+  }
+
+  // Check default format mapping
+  if (format && FORMAT_MAPPINGS[format]) {
+    return FORMAT_MAPPINGS[format]
+  }
+
+  // Check custom type mapping
+  if (type && customMappings.types?.[type]) {
+    return customMappings.types[type]
+  }
+
+  // Fall back to base type mapping, default to 'text'
+  return BASE_TYPE_MAPPINGS[type] || 'text'
+}

package/src/gen/StorageProfileFactory.js

@@ -0,0 +1,109 @@
+/**
+ * Storage Profile Factory Pattern
+ *
+ * A storage profile factory is a function that creates storage instances for a given endpoint.
+ * This pattern enables DRY backend configuration by centralizing storage creation logic
+ * (API client, base URL, headers, error handling) in one place.
+ *
+ * Instead of configuring each entity's storage individually, you define a profile factory
+ * once and pass it to createManagers(), which calls it with each entity's endpoint.
+ *
+ * @module gen/StorageProfileFactory
+ */
+
+/**
+ * Storage Profile Factory Options
+ *
+ * Per-entity options passed when creating storage from a profile factory.
+ * Allows overriding profile defaults for specific entities.
+ *
+ * @typedef {object} StorageProfileOptions
+ * @property {string} [entity] - Entity name (e.g., 'users', 'posts')
+ * @property {object} [client] - Override the profile's HTTP client for this entity
+ * @property {object} [headers] - Additional headers for this entity
+ * @property {boolean} [readOnly] - Force read-only mode (no create/update/delete)
+ * @property {Record<string, *>} [extensions] - Custom per-entity options
+ */
+
+/**
+ * Storage Profile Factory
+ *
+ * A function that creates storage instances for a given endpoint.
+ * The factory encapsulates common storage configuration (API client, auth, base URL)
+ * and creates properly-configured storage adapters for each entity.
+ *
+ * @callback StorageProfileFactory
+ * @param {string} endpoint - Entity endpoint path (e.g., '/users', '/api/v1/posts')
+ * @param {StorageProfileOptions} [options] - Per-entity options to override profile defaults
+ * @returns {import('../entity/storage/IStorage.js').IStorage} Storage instance
+ *
+ * @example Basic factory using ApiStorage
+ * import axios from 'axios'
+ * import { ApiStorage } from 'qdadm'
+ *
+ * // Define profile factory with shared configuration
+ * const apiProfile = (endpoint, options = {}) => {
+ *   return new ApiStorage({
+ *     endpoint,
+ *     client: axios.create({
+ *       baseURL: 'https://api.example.com',
+ *       headers: { 'Authorization': `Bearer ${getToken()}` }
+ *     }),
+ *     ...options
+ *   })
+ * }
+ *
+ * // Use with createManagers (T00317)
+ * const managers = createManagers(schemas, {
+ *   storageProfile: apiProfile
+ * })
+ *
+ * @example Factory with dynamic client resolution
+ * // For Vue/inject pattern - client resolved at call time
+ * const lazyApiProfile = (endpoint, options = {}) => {
+ *   return new ApiStorage({
+ *     endpoint,
+ *     getClient: () => inject('apiClient'),
+ *     ...options
+ *   })
+ * }
+ *
+ * @example Factory for local development
+ * import { MemoryStorage } from 'qdadm'
+ *
+ * const memoryProfile = (endpoint, options = {}) => {
+ *   const entity = options.entity || endpoint.replace(/^\//, '')
+ *   return new MemoryStorage({
+ *     initialData: mockData[entity] || []
+ *   })
+ * }
+ *
+ * @example Factory with per-entity overrides
+ * const hybridProfile = (endpoint, options = {}) => {
+ *   // Some entities use SDK, others use REST
+ *   if (options.useSdk) {
+ *     return new SdkStorage({
+ *       sdk: options.sdk,
+ *       collection: options.entity
+ *     })
+ *   }
+ *   return new ApiStorage({
+ *     endpoint,
+ *     client: defaultClient
+ *   })
+ * }
+ *
+ * @example Factory with environment-based switching
+ * const envAwareProfile = (endpoint, options = {}) => {
+ *   if (import.meta.env.MODE === 'development') {
+ *     return new MockApiStorage({ endpoint })
+ *   }
+ *   return new ApiStorage({
+ *     endpoint,
+ *     client: productionClient
+ *   })
+ * }
+ */
+
+// Type-only module - no runtime exports
+// Types are available via JSDoc when importing this module

package/src/gen/connectors/BaseConnector.js

@@ -0,0 +1,142 @@
+/**
+ * Base Connector Interface
+ *
+ * Abstract base class for schema connectors. Connectors parse various sources
+ * (OpenAPI specs, manual definitions, etc.) into UnifiedEntitySchema format.
+ *
+ * Subclasses must implement the `parse(source)` method with source-specific logic.
+ *
+ * @module gen/connectors/BaseConnector
+ */
+
+/**
+ * Connector options for customizing parsing behavior
+ *
+ * @typedef {object} ConnectorOptions
+ * @property {string} [name] - Connector instance name for debugging
+ * @property {boolean} [strict] - Throw on validation errors instead of warning (default: false)
+ * @property {Record<string, *>} [extensions] - Custom extension data passed to output schemas
+ */
+
+/**
+ * Parse result with parsed schemas and any encountered issues
+ *
+ * @typedef {object} ParseResult
+ * @property {import('../schema.js').UnifiedEntitySchema[]} schemas - Parsed entity schemas
+ * @property {ParseWarning[]} warnings - Non-fatal issues encountered during parsing
+ */
+
+/**
+ * Warning encountered during parsing
+ *
+ * @typedef {object} ParseWarning
+ * @property {string} path - Location in source where issue occurred
+ * @property {string} message - Description of the issue
+ * @property {string} [code] - Warning code for programmatic handling
+ */
+
+/**
+ * Base connector class for parsing schema sources into UnifiedEntitySchema format.
+ *
+ * @abstract
+ * @example
+ * // Extending BaseConnector
+ * class ManualConnector extends BaseConnector {
+ *   parse(source) {
+ *     // Parse inline definitions
+ *     return source.entities.map(e => this.transformEntity(e))
+ *   }
+ * }
+ *
+ * @example
+ * // Using a connector
+ * const connector = new ManualConnector({ strict: true })
+ * const schemas = connector.parse(manualDefinitions)
+ */
+export class BaseConnector {
+  /**
+   * Create a new connector instance
+   *
+   * @param {ConnectorOptions} [options={}] - Connector configuration options
+   */
+  constructor(options = {}) {
+    if (new.target === BaseConnector) {
+      throw new Error('BaseConnector is abstract and cannot be instantiated directly')
+    }
+
+    /** @type {string} */
+    this.name = options.name || this.constructor.name
+
+    /** @type {boolean} */
+    this.strict = options.strict ?? false
+
+    /** @type {Record<string, *>} */
+    this.extensions = options.extensions || {}
+  }
+
+  /**
+   * Parse a schema source into UnifiedEntitySchema format.
+   *
+   * This method must be implemented by subclasses to handle source-specific
+   * parsing logic. The source parameter format depends on the connector type:
+   * - ManualConnector: Object with entity/field definitions
+   * - OpenAPIConnector: OpenAPI 3.x specification object
+   *
+   * @abstract
+   * @param {*} source - Source data to parse (format depends on connector type)
+   * @returns {import('../schema.js').UnifiedEntitySchema[]} - Parsed entity schemas
+   * @throws {Error} - If parsing fails (in strict mode) or source is invalid
+   *
+   * @example
+   * // ManualConnector source format
+   * connector.parse({
+   *   entities: [
+   *     { name: 'users', endpoint: '/api/users', fields: { ... } }
+   *   ]
+   * })
+   *
+   * @example
+   * // OpenAPIConnector source format
+   * connector.parse({
+   *   openapi: '3.0.0',
+   *   paths: { '/api/users': { ... } },
+   *   components: { schemas: { ... } }
+   * })
+   */
+  parse(source) {
+    throw new Error(`${this.name}.parse() must be implemented by subclass`)
+  }
+
+  /**
+   * Parse with detailed result including warnings
+   *
+   * Alternative to `parse()` that returns warnings along with schemas.
+   * Useful when you want to handle non-fatal issues without strict mode.
+   *
+   * Default implementation wraps `parse()` with empty warnings array.
+   * Subclasses can override for more detailed reporting.
+   *
+   * @param {*} source - Source data to parse
+   * @returns {ParseResult} - Schemas and any warnings encountered
+   */
+  parseWithWarnings(source) {
+    return {
+      schemas: this.parse(source),
+      warnings: []
+    }
+  }
+
+  /**
+   * Validate connector is properly configured before parsing
+   *
+   * Override in subclasses to add custom validation.
+   *
+   * @returns {boolean} - True if connector is valid
+   * @throws {Error} - If connector configuration is invalid
+   */
+  validate() {
+    return true
+  }
+}
+
+export default BaseConnector