@quazardous/qdadm 1.19.3

package/src/entity/storage/factory.ts

@@ -0,0 +1,209 @@
+/**
+ * Storage Factory/Resolver Pattern
+ *
+ * Enables declarative storage configuration with auto-resolution.
+ */
+
+import { IStorage } from './IStorage'
+import { ApiStorage } from './ApiStorage'
+import { LocalStorage } from './LocalStorage'
+import { MemoryStorage } from './MemoryStorage'
+import { MockApiStorage } from './MockApiStorage'
+import { SdkStorage } from './SdkStorage'
+import type { EntityRecord } from '../../types'
+
+/**
+ * Storage class type
+ */
+type StorageClass = typeof IStorage
+
+/**
+ * Storage type registry - maps type names to storage classes
+ */
+export const storageTypes: Record<string, StorageClass> = {
+  api: ApiStorage as unknown as StorageClass,
+  local: LocalStorage as unknown as StorageClass,
+  memory: MemoryStorage as unknown as StorageClass,
+  mock: MockApiStorage as unknown as StorageClass,
+  sdk: SdkStorage as unknown as StorageClass,
+}
+
+/**
+ * Parsed storage pattern result
+ */
+export interface ParsedStoragePattern {
+  type: string
+  endpoint?: string
+  key?: string
+  entityName?: string
+  [key: string]: unknown
+}
+
+/**
+ * Storage configuration object
+ */
+export interface StorageConfig {
+  type?: string
+  endpoint?: string
+  key?: string
+  entityName?: string
+  initialData?: unknown[]
+  [key: string]: unknown
+}
+
+/**
+ * Storage resolver function type
+ */
+export type StorageResolver = <T extends EntityRecord = EntityRecord>(
+  config: StorageConfig,
+  entityName: string
+) => IStorage<T>
+
+/**
+ * Parse string pattern 'type:endpoint' into config object
+ */
+export function parseStoragePattern(pattern: string): ParsedStoragePattern | null {
+  if (typeof pattern !== 'string') return null
+
+  // Pattern: 'type:value'
+  const match = pattern.match(/^(\w+):(.+)$/)
+  if (match && match[1] && match[2]) {
+    const type = match[1]
+    const value = match[2]
+    // For local/mock, value is key/name; for api/sdk, value is endpoint
+    if (type === 'local' || type === 'memory') {
+      return { type, key: value }
+    }
+    if (type === 'mock') {
+      return { type, entityName: value }
+    }
+    return { type, endpoint: value }
+  }
+
+  // Plain string starting with '/' → assume API endpoint
+  if (pattern.startsWith('/')) {
+    return { type: 'api', endpoint: pattern }
+  }
+
+  return null
+}
+
+/**
+ * Default storage resolver - creates storage instance from config
+ */
+export function defaultStorageResolver<T extends EntityRecord = EntityRecord>(
+  config: StorageConfig,
+  entityName: string
+): IStorage<T> {
+  const { type, ...rest } = config
+
+  if (!type) {
+    throw new Error('Storage config must have a type property')
+  }
+
+  const StorageClass = storageTypes[type]
+  if (!StorageClass) {
+    throw new Error(
+      `Unknown storage type: "${type}". Available: ${Object.keys(storageTypes).join(', ')}`
+    )
+  }
+
+  // Add entityName to config if not present (useful for mock/memory)
+  const resolvedConfig = { ...rest }
+  if (!resolvedConfig.entityName && !resolvedConfig.key) {
+    if (type === 'local' || type === 'memory') {
+      resolvedConfig.key = entityName
+    } else if (type === 'mock') {
+      resolvedConfig.entityName = entityName
+    }
+  }
+
+  // @ts-expect-error - StorageClass constructor accepts options object
+  return new StorageClass(resolvedConfig) as IStorage<T>
+}
+
+/**
+ * Duck-typed storage interface for detection
+ */
+interface DuckTypedStorage {
+  list: (...args: unknown[]) => Promise<unknown>
+  get: (...args: unknown[]) => Promise<unknown>
+}
+
+/**
+ * Storage factory - normalizes input and delegates to resolver
+ *
+ * Handles:
+ * - IStorage instance → return directly
+ * - String pattern 'type:endpoint' → parse and resolve
+ * - Plain string '/endpoint' → treat as API endpoint
+ * - Config object → normalize and resolve
+ */
+export function storageFactory<T extends EntityRecord = EntityRecord>(
+  config: IStorage<T> | string | StorageConfig,
+  entityName: string,
+  resolver: StorageResolver = defaultStorageResolver
+): IStorage<T> {
+  // Already a Storage instance → return directly
+  if (config instanceof IStorage) {
+    return config
+  }
+
+  // Also check for duck-typed storage (has list method and isn't a class)
+  if (
+    config &&
+    typeof config === 'object' &&
+    typeof (config as unknown as DuckTypedStorage).list === 'function' &&
+    typeof (config as unknown as DuckTypedStorage).get === 'function'
+  ) {
+    return config as unknown as IStorage<T>
+  }
+
+  // String pattern → parse
+  if (typeof config === 'string') {
+    const parsed = parseStoragePattern(config)
+    if (!parsed) {
+      throw new Error(`Invalid storage pattern: "${config}". Use 'type:value' or '/api/endpoint'`)
+    }
+    return resolver(parsed, entityName)
+  }
+
+  // Config object → normalize
+  if (config && typeof config === 'object') {
+    let normalizedConfig = config as StorageConfig
+    // If no type, infer from properties
+    if (!normalizedConfig.type) {
+      if (normalizedConfig.endpoint) {
+        normalizedConfig = { type: 'api', ...normalizedConfig }
+      } else if (normalizedConfig.key) {
+        normalizedConfig = { type: 'local', ...normalizedConfig }
+      } else if (normalizedConfig.initialData) {
+        normalizedConfig = { type: 'mock', ...normalizedConfig }
+      } else {
+        throw new Error(
+          `Cannot infer storage type from config: ${JSON.stringify(config)}. Add 'type' property.`
+        )
+      }
+    }
+    return resolver(normalizedConfig, entityName)
+  }
+
+  throw new Error(
+    `Invalid storage config: ${typeof config}. Expected string, object, or Storage instance.`
+  )
+}
+
+/**
+ * Create a custom storage factory with overridden resolver
+ */
+export function createStorageFactory(
+  customResolver: StorageResolver
+): <T extends EntityRecord = EntityRecord>(
+  config: IStorage<T> | string | StorageConfig,
+  entityName: string
+) => IStorage<T> {
+  return <T extends EntityRecord = EntityRecord>(
+    config: IStorage<T> | string | StorageConfig,
+    entityName: string
+  ) => storageFactory(config, entityName, customResolver)
+}

package/src/entity/storage/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Storage Adapters
+ *
+ * Boilerplate implementations for common storage backends.
+ * EntityManagers can use these or implement their own storage.
+ */
+
+import type { StorageCapabilities } from '../../types'
+
+/**
+ * Default capabilities for storages that don't declare their own.
+ * All capabilities default to false for safe degradation.
+ */
+export const DEFAULT_STORAGE_CAPABILITIES: StorageCapabilities = {
+  supportsTotal: false,
+  supportsFilters: false,
+  supportsPagination: false,
+  supportsCaching: false,
+}
+
+/**
+ * Read capabilities from a storage instance.
+ * Accesses static `capabilities` property via constructor with fallback to defaults.
+ *
+ * @example
+ * const caps = getStorageCapabilities(myStorage)
+ * if (caps.supportsTotal) {
+ *   // Storage provides accurate total count
+ * }
+ */
+export function getStorageCapabilities(
+  storage: { constructor?: { capabilities?: Partial<StorageCapabilities> } } | null | undefined
+): StorageCapabilities {
+  const declared = storage?.constructor?.capabilities || {}
+  return {
+    ...DEFAULT_STORAGE_CAPABILITIES,
+    ...declared,
+  }
+}
+
+// Base class
+export { IStorage } from './IStorage'
+
+// Factory/Resolver
+export {
+  storageFactory,
+  defaultStorageResolver,
+  createStorageFactory,
+  parseStoragePattern,
+  storageTypes,
+} from './factory'
+export type { ParsedStoragePattern, StorageConfig, StorageResolver } from './factory'
+
+// Storage adapters
+export { ApiStorage, createApiStorage } from './ApiStorage'
+export type { HttpClient, RoutingContext, ApiStorageOptions } from './ApiStorage'
+
+export { LocalStorage, createLocalStorage } from './LocalStorage'
+export type { LocalStorageOptions } from './LocalStorage'
+
+export { MemoryStorage, createMemoryStorage, StorageError } from './MemoryStorage'
+export type { MemoryStorageOptions } from './MemoryStorage'
+
+export { MockApiStorage, createMockApiStorage } from './MockApiStorage'
+export type { MockApiStorageOptions } from './MockApiStorage'
+
+export { SdkStorage, createSdkStorage } from './SdkStorage'
+export type {
+  SdkInstance,
+  SdkMethodConfig,
+  SdkMethodTransforms,
+  SdkResponseFormat,
+  SdkMethods,
+  SdkStorageOptions,
+} from './SdkStorage'

package/src/gen/FieldMapper.ts

@@ -0,0 +1,122 @@
+/**
+ * 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
+ */
+
+import type { UnifiedFieldType } from './schema'
+
+/**
+ * Base type mappings: JSON Schema type -> UnifiedFieldSchema type
+ */
+export const BASE_TYPE_MAPPINGS: Readonly<Record<string, UnifiedFieldType>> = 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.
+ */
+export const FORMAT_MAPPINGS: Readonly<Record<string, UnifiedFieldType>> = Object.freeze({
+  email: 'email',
+  'date-time': 'datetime',
+  date: 'date',
+  uri: 'url',
+  url: 'url',
+  uuid: 'uuid',
+  password: 'text',
+})
+
+/**
+ * Custom mappings override structure
+ */
+export interface CustomMappings {
+  /** Custom type mappings { jsonSchemaType: unifiedType } */
+  types?: Record<string, string>
+  /** Custom format mappings { jsonSchemaFormat: unifiedType } */
+  formats?: Record<string, string>
+}
+
+/**
+ * Minimal JSON Schema property definition for type detection
+ */
+export interface SchemaProperty {
+  /** JSON Schema type (string, integer, number, boolean, array, object) */
+  type?: string
+  /** JSON Schema format (email, date-time, uuid, etc.) */
+  format?: string
+  /** Enumeration values */
+  enum?: unknown[]
+}
+
+/**
+ * Get the UnifiedFieldSchema type for a JSON Schema property
+ *
+ * @param schema - JSON Schema property definition
+ * @param customMappings - Optional custom type/format mappings
+ * @returns 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: SchemaProperty | null | undefined,
+  customMappings: CustomMappings = {}
+): UnifiedFieldType | 'select' {
+  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] as UnifiedFieldType
+  }
+
+  // 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] as UnifiedFieldType
+  }
+
+  // Fall back to base type mapping, default to 'text'
+  return (type && BASE_TYPE_MAPPINGS[type]) || 'text'
+}

package/src/gen/StorageProfileFactory.ts

@@ -0,0 +1,93 @@
+/**
+ * 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
+ */
+
+import type { IStorage } from '../entity/storage/IStorage'
+import type { EntityRecord } from '../types'
+
+/**
+ * Storage Profile Factory Options
+ *
+ * Per-entity options passed when creating storage from a profile factory.
+ * Allows overriding profile defaults for specific entities.
+ */
+export interface StorageProfileOptions {
+  /** Entity name (e.g., 'users', 'posts') */
+  entity?: string
+  /** Override the profile's HTTP client for this entity */
+  client?: unknown
+  /** Additional headers for this entity */
+  headers?: Record<string, string>
+  /** Force read-only mode (no create/update/delete) */
+  readOnly?: boolean
+  /** Custom per-entity options */
+  extensions?: Record<string, unknown>
+}
+
+/**
+ * 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.
+ *
+ * @example Basic factory using ApiStorage
+ * ```ts
+ * import axios from 'axios'
+ * import { ApiStorage } from '@quazardous/qdadm'
+ *
+ * // Define profile factory with shared configuration
+ * const apiProfile: StorageProfileFactory = (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
+ * ```ts
+ * // For Vue/inject pattern - client resolved at call time
+ * const lazyApiProfile: StorageProfileFactory = (endpoint, options = {}) => {
+ *   return new ApiStorage({
+ *     endpoint,
+ *     getClient: () => inject('apiClient'),
+ *     ...options
+ *   })
+ * }
+ * ```
+ *
+ * @example Factory for local development
+ * ```ts
+ * import { MemoryStorage } from '@quazardous/qdadm'
+ *
+ * const memoryProfile: StorageProfileFactory = (endpoint, options = {}) => {
+ *   const entity = options.entity || endpoint.replace(/^\//, '')
+ *   return new MemoryStorage({
+ *     initialData: mockData[entity] || []
+ *   })
+ * }
+ * ```
+ */
+export type StorageProfileFactory = (
+  endpoint: string,
+  options?: StorageProfileOptions
+) => IStorage<EntityRecord>

package/src/gen/connectors/BaseConnector.ts

@@ -0,0 +1,150 @@
+/**
+ * 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
+ */
+
+import type { UnifiedEntitySchema } from '../schema'
+
+/**
+ * Connector options for customizing parsing behavior
+ */
+export interface ConnectorOptions {
+  /** Connector instance name for debugging */
+  name?: string
+  /** Throw on validation errors instead of warning (default: false) */
+  strict?: boolean
+  /** Custom extension data passed to output schemas */
+  extensions?: Record<string, unknown>
+}
+
+/**
+ * Warning encountered during parsing
+ */
+export interface ParseWarning {
+  /** Location in source where issue occurred */
+  path: string
+  /** Description of the issue */
+  message: string
+  /** Warning code for programmatic handling */
+  code?: string
+}
+
+/**
+ * Parse result with parsed schemas and any encountered issues
+ */
+export interface ParseResult {
+  /** Parsed entity schemas */
+  schemas: UnifiedEntitySchema[]
+  /** Non-fatal issues encountered during parsing */
+  warnings: ParseWarning[]
+}
+
+/**
+ * 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 abstract class BaseConnector {
+  /** Connector instance name */
+  name: string
+
+  /** Whether to throw on validation errors */
+  strict: boolean
+
+  /** Custom extension data */
+  extensions: Record<string, unknown>
+
+  /**
+   * Create a new connector instance
+   *
+   * @param options - Connector configuration options
+   */
+  constructor(options: ConnectorOptions = {}) {
+    this.name = options.name || this.constructor.name
+    this.strict = options.strict ?? false
+    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 Parsed entity schemas
+   * @throws 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: { ... } }
+   * })
+   */
+  abstract parse(source: unknown): UnifiedEntitySchema[]
+
+  /**
+   * 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 Schemas and any warnings encountered
+   */
+  parseWithWarnings(source: unknown): ParseResult {
+    return {
+      schemas: this.parse(source),
+      warnings: [],
+    }
+  }
+
+  /**
+   * Validate connector is properly configured before parsing
+   *
+   * Override in subclasses to add custom validation.
+   *
+   * @returns True if connector is valid
+   * @throws If connector configuration is invalid
+   */
+  validate(): boolean {
+    return true
+  }
+}
+
+export default BaseConnector