@quazardous/qdadm 2.16.0 → 2.16.1

package/dist/node/gen/decorators.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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
+ */
+import type { UnifiedEntitySchema } from './schema';
+/**
+ * Field Decorator Configuration
+ *
+ * Per-field overrides that can be applied to schema fields.
+ */
+export interface FieldDecorator {
+    /** Override field visibility */
+    hidden?: boolean;
+    /** Override field label */
+    label?: string;
+    /** Override field read-only state */
+    readOnly?: boolean;
+    /** Override field display order */
+    order?: number;
+}
+/**
+ * Entity Decorator Configuration
+ *
+ * Decorator configuration for a single entity.
+ */
+export interface EntityDecorator {
+    /** Field-level overrides keyed by field name */
+    fields?: Record<string, FieldDecorator>;
+}
+/**
+ * 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 schema - Original entity schema
+ * @param decoratorConfig - Decorator configuration
+ * @returns 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 declare function applyDecorators(schema: UnifiedEntitySchema, decoratorConfig?: EntityDecorator): UnifiedEntitySchema;

package/dist/node/gen/decorators.js

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+const ALLOWED_FIELD_DECORATORS = ['hidden', 'label', 'readOnly', 'order'];
+/**
+ * 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 schema - Original entity schema
+ * @param decoratorConfig - Decorator configuration
+ * @returns 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,
+    };
+}

package/dist/node/gen/generateManagers.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Build-time Manager File Generation
+ *
+ * Generates individual EntityManager files for each entity in the configuration.
+ * This enables better IDE support and static analysis by creating explicit files
+ * rather than relying on runtime factory creation.
+ *
+ * Outputs TypeScript (.ts) files with auto-generated entity interfaces derived
+ * from the field schemas, providing end-to-end type safety.
+ *
+ * @module gen/generateManagers
+ */
+import type { UnifiedEntitySchema, UnifiedFieldSchema, UnifiedFieldType } from './schema';
+import type { EntityDecorator } from './decorators';
+/**
+ * Custom base class for generated managers (#1253).
+ *
+ * The class MUST extend EntityManager, stay generic over the entity type
+ * and pass constructor options through — the generated code does
+ * `class Generated<X>Manager extends <name><XEntity>` and calls
+ * `super({ ...schema options, storage, ...options })`.
+ */
+export interface GenerateManagersBaseClass {
+    /** Import specifier (e.g. '@/managers/SkyEntityManager') */
+    import: string;
+    /** Exported class name (e.g. 'SkyEntityManager') */
+    name: string;
+}
+/**
+ * Entity configuration for generation
+ */
+export interface GenerateManagersEntityConfig {
+    /** Entity schema */
+    schema: UnifiedEntitySchema;
+    /** API endpoint path (e.g., '/users') */
+    endpoint: string;
+    /** Import path for storage (e.g., 'qdadm' or './storage') */
+    storageImport: string;
+    /** Storage class name (e.g., 'ApiStorage') */
+    storageClass: string;
+    /** Additional storage constructor options */
+    storageOptions?: Record<string, unknown>;
+    /** Field decorators to apply */
+    decorators?: EntityDecorator;
+    /** Generate class instead of instance (for extension) */
+    classMode?: boolean;
+    /** Base class for this entity's generated manager (overrides global) */
+    baseClass?: GenerateManagersBaseClass;
+}
+/**
+ * Configuration for generateManagers
+ */
+export interface GenerateManagersConfig {
+    /** Output directory (default: 'src/generated/managers/') */
+    output?: string;
+    /** Generate classes instead of instances (for extension pattern) */
+    classMode?: boolean;
+    /** Base class for all generated managers (default: EntityManager) */
+    baseClass?: GenerateManagersBaseClass;
+    /** Entity configurations keyed by entity name */
+    entities: Record<string, GenerateManagersEntityConfig>;
+}
+/**
+ * Map UnifiedFieldType to TypeScript type string
+ */
+export declare function fieldTypeToTsType(type: UnifiedFieldType, required: boolean): string;
+/**
+ * Generate a TypeScript interface from entity fields
+ */
+export declare function generateEntityInterface(entityName: string, fields: Record<string, UnifiedFieldSchema>, idField: string): string;
+/**
+ * Generate EntityManager files from configuration
+ *
+ * Creates one TypeScript file per entity in the output directory.
+ * Each file exports the entity's interface, schema, and a configured EntityManager instance.
+ *
+ * @param config - Configuration object
+ * @returns List of generated file paths
+ * @throws If config is invalid or file operations fail
+ *
+ * @example
+ * ```ts
+ * import { generateManagers } from '@quazardous/qdadm/gen'
+ *
+ * const generatedFiles = await generateManagers({
+ *   output: 'src/generated/managers/',
+ *   entities: {
+ *     users: {
+ *       schema: usersSchema,
+ *       endpoint: '/api/users',
+ *       storageImport: '@quazardous/qdadm',
+ *       storageClass: 'ApiStorage',
+ *       storageOptions: { client: 'apiClient' },
+ *       decorators: {
+ *         fields: {
+ *           password: { hidden: true }
+ *         }
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * console.log('Generated:', generatedFiles)
+ * // ['src/generated/managers/usersManager.ts']
+ * ```
+ */
+export declare function generateManagers(config: GenerateManagersConfig): Promise<string[]>;

package/dist/node/gen/generateManagers.js

@@ -0,0 +1,338 @@
+/**
+ * Build-time Manager File Generation
+ *
+ * Generates individual EntityManager files for each entity in the configuration.
+ * This enables better IDE support and static analysis by creating explicit files
+ * rather than relying on runtime factory creation.
+ *
+ * Outputs TypeScript (.ts) files with auto-generated entity interfaces derived
+ * from the field schemas, providing end-to-end type safety.
+ *
+ * @module gen/generateManagers
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Default output directory for generated managers
+ */
+const DEFAULT_OUTPUT_DIR = 'src/generated/managers/';
+/**
+ * Convert entity name to PascalCase for class name
+ *
+ * @param name - Entity name (e.g., 'users', 'blog_posts')
+ * @returns PascalCase name (e.g., 'Users', 'BlogPosts')
+ */
+function toPascalCase(name) {
+    return name
+        .split(/[_-]/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+/**
+ * Map UnifiedFieldType to TypeScript type string
+ */
+export function fieldTypeToTsType(type, required) {
+    const tsType = (() => {
+        switch (type) {
+            case 'text':
+            case 'email':
+            case 'url':
+            case 'uuid':
+            case 'date':
+            case 'datetime':
+                return 'string';
+            case 'number':
+                return 'number';
+            case 'boolean':
+                return 'boolean';
+            case 'array':
+                return 'unknown[]';
+            case 'object':
+                return 'Record<string, unknown>';
+            default:
+                // Fallback for types widened beyond UnifiedFieldType at runtime
+                // (e.g. OpenAPI oneOf/discriminator that FieldMapper couldn't classify).
+                // Without this, the IIFE returns undefined and we'd emit the literal
+                // string "undefined" into the generated .ts file.
+                return 'unknown';
+        }
+    })();
+    return required ? tsType : `${tsType} | null`;
+}
+/**
+ * Generate a TypeScript interface from entity fields
+ */
+export function generateEntityInterface(entityName, fields, idField) {
+    const className = toPascalCase(entityName);
+    const lines = [];
+    lines.push(`export interface ${className}Entity extends EntityRecord {`);
+    for (const [fieldName, field] of Object.entries(fields)) {
+        if (field.hidden)
+            continue;
+        // Connectors (e.g. OpenAPIConnector) flatten one level of nested object
+        // properties as dotted keys ("filter.botUuids") for runtime form/column
+        // metadata. The parent object field is already typed as
+        // Record<string, unknown>, and dotted keys are not legal at the top level
+        // of a TS interface body — skip them here.
+        if (fieldName.includes('.'))
+            continue;
+        const isRequired = field.required || fieldName === idField;
+        const tsType = fieldTypeToTsType(field.type, isRequired);
+        const optional = isRequired ? '' : '?';
+        lines.push(`  ${fieldName}${optional}: ${tsType}`);
+    }
+    lines.push('}');
+    return lines.join('\n');
+}
+/**
+ * Serialize a value to JavaScript source code
+ *
+ * @param value - Value to serialize
+ * @param indent - Current indentation level
+ * @returns JavaScript source code
+ */
+function serializeValue(value, indent = 0) {
+    const spaces = '  '.repeat(indent);
+    const innerSpaces = '  '.repeat(indent + 1);
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]';
+        const items = value.map((v) => serializeValue(v, indent + 1));
+        return `[\n${innerSpaces}${items.join(`,\n${innerSpaces}`)}\n${spaces}]`;
+    }
+    if (typeof value === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return '{}';
+        const entries = keys.map((key) => {
+            const safeKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
+            return `${innerSpaces}${safeKey}: ${serializeValue(obj[key], indent + 1)}`;
+        });
+        return `{\n${entries.join(',\n')}\n${spaces}}`;
+    }
+    return String(value);
+}
+// Note: ManagerOptions interface removed - using inline Record<string, unknown> type instead
+/**
+ * Generate the source code for a single entity manager file
+ *
+ * @param entityName - Entity name
+ * @param entityConfig - Entity configuration
+ * @param globalOptions - Global generation options
+ * @returns Generated TypeScript source code
+ */
+function generateManagerSource(entityName, entityConfig, globalOptions = {}) {
+    const { schema, endpoint, storageImport, storageClass, storageOptions = {}, decorators } = entityConfig;
+    const classMode = entityConfig.classMode ?? globalOptions.classMode ?? false;
+    const className = toPascalCase(entityName);
+    // Custom base class (#1253): per-entity wins over global, default EntityManager.
+    const baseClass = entityConfig.baseClass ?? globalOptions.baseClass;
+    const baseName = baseClass?.name ?? 'EntityManager';
+    const baseImport = baseClass
+        ? `import { ${baseClass.name} } from '${baseClass.import}'`
+        : `import { EntityManager } from '@quazardous/qdadm'`;
+    // Build storage options object
+    const fullStorageOptions = {
+        endpoint,
+        ...storageOptions,
+    };
+    // Apply decorators to schema if provided
+    let finalSchema = schema;
+    if (decorators?.fields) {
+        // Create decorated fields inline
+        const decoratedFields = {};
+        for (const [fieldName, fieldSchema] of Object.entries(schema.fields)) {
+            const decorator = decorators.fields[fieldName];
+            if (decorator) {
+                decoratedFields[fieldName] = { ...fieldSchema, ...decorator };
+            }
+            else {
+                decoratedFields[fieldName] = { ...fieldSchema };
+            }
+        }
+        finalSchema = { ...schema, fields: decoratedFields };
+    }
+    // Build EntityManager options
+    const managerOptions = {
+        name: finalSchema.name,
+        idField: finalSchema.idField || 'id',
+        label: finalSchema.label,
+        labelPlural: finalSchema.labelPlural,
+        labelField: finalSchema.labelField,
+        routePrefix: finalSchema.routePrefix,
+        readOnly: finalSchema.readOnly,
+        fields: finalSchema.fields,
+    };
+    // Remove undefined values
+    for (const key of Object.keys(managerOptions)) {
+        if (managerOptions[key] === undefined) {
+            delete managerOptions[key];
+        }
+    }
+    // Generate entity interface
+    const idField = finalSchema.idField || 'id';
+    const entityInterface = generateEntityInterface(entityName, finalSchema.fields, idField);
+    // Class-based template for extension pattern
+    if (classMode) {
+        return `/**
+ * Generated${className}Manager - Auto-generated base class
+ *
+ * Generated by qdadm/gen/generateManagers
+ * DO NOT EDIT MANUALLY - Changes will be overwritten
+ *
+ * Extend this class for custom logic.
+ *
+ * Entity: ${entityName}
+ * Endpoint: ${endpoint}
+ */
+
+${baseImport}
+import type { EntityRecord, EntityManagerOptions } from '@quazardous/qdadm'
+import { ${storageClass} } from '${storageImport}'
+
+${entityInterface}
+
+/**
+ * Generated base manager for ${entityName}
+ *
+ * @extends ${baseName}
+ */
+export class Generated${className}Manager extends ${baseName}<${className}Entity> {
+  constructor(options: Partial<EntityManagerOptions<${className}Entity>> = {}) {
+    super({
+      ...${serializeValue(managerOptions, 2)},
+      storage: new ${storageClass}<${className}Entity>(${serializeValue(fullStorageOptions, 2)}),
+      ...options
+    })
+  }
+}
+`;
+    }
+    // Instance-based template (default)
+    return `/**
+ * ${className}Manager - Auto-generated EntityManager
+ *
+ * Generated by qdadm/gen/generateManagers
+ * DO NOT EDIT MANUALLY - Changes will be overwritten
+ *
+ * Entity: ${entityName}
+ * Endpoint: ${endpoint}
+ */
+
+${baseImport}
+import type { EntityRecord } from '@quazardous/qdadm'
+import { ${storageClass} } from '${storageImport}'
+
+${entityInterface}
+
+/**
+ * Schema definition for ${entityName}
+ */
+export const ${entityName}Schema = ${serializeValue(finalSchema, 0)} as const
+
+/**
+ * Storage options for ${entityName}
+ */
+const storageOptions = ${serializeValue(fullStorageOptions, 0)}
+
+/**
+ * ${className}Manager instance
+ *
+ * Provides CRUD operations for ${entityName} entity.
+ */
+export const ${entityName}Manager = new ${baseName}<${className}Entity>({
+  ...${serializeValue(managerOptions, 0)},
+  storage: new ${storageClass}<${className}Entity>(storageOptions)
+})
+`;
+}
+/**
+ * Generate EntityManager files from configuration
+ *
+ * Creates one TypeScript file per entity in the output directory.
+ * Each file exports the entity's interface, schema, and a configured EntityManager instance.
+ *
+ * @param config - Configuration object
+ * @returns List of generated file paths
+ * @throws If config is invalid or file operations fail
+ *
+ * @example
+ * ```ts
+ * import { generateManagers } from '@quazardous/qdadm/gen'
+ *
+ * const generatedFiles = await generateManagers({
+ *   output: 'src/generated/managers/',
+ *   entities: {
+ *     users: {
+ *       schema: usersSchema,
+ *       endpoint: '/api/users',
+ *       storageImport: '@quazardous/qdadm',
+ *       storageClass: 'ApiStorage',
+ *       storageOptions: { client: 'apiClient' },
+ *       decorators: {
+ *         fields: {
+ *           password: { hidden: true }
+ *         }
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * console.log('Generated:', generatedFiles)
+ * // ['src/generated/managers/usersManager.ts']
+ * ```
+ */
+export async function generateManagers(config) {
+    // Validate config
+    if (!config || typeof config !== 'object') {
+        throw new Error('generateManagers: config is required and must be an object');
+    }
+    if (!config.entities || typeof config.entities !== 'object') {
+        throw new Error('generateManagers: config.entities is required and must be an object');
+    }
+    const outputDir = config.output || DEFAULT_OUTPUT_DIR;
+    const globalOptions = { classMode: config.classMode ?? false, baseClass: config.baseClass };
+    const generatedFiles = [];
+    // Validate each entity config
+    for (const [entityName, entityConfig] of Object.entries(config.entities)) {
+        if (!entityConfig || typeof entityConfig !== 'object') {
+            throw new Error(`generateManagers: entity '${entityName}' config must be an object`);
+        }
+        if (!entityConfig.schema || typeof entityConfig.schema !== 'object') {
+            throw new Error(`generateManagers: entity '${entityName}' requires 'schema' property`);
+        }
+        if (!entityConfig.endpoint || typeof entityConfig.endpoint !== 'string') {
+            throw new Error(`generateManagers: entity '${entityName}' requires 'endpoint' property`);
+        }
+        if (!entityConfig.storageImport || typeof entityConfig.storageImport !== 'string') {
+            throw new Error(`generateManagers: entity '${entityName}' requires 'storageImport' property`);
+        }
+        if (!entityConfig.storageClass || typeof entityConfig.storageClass !== 'string') {
+            throw new Error(`generateManagers: entity '${entityName}' requires 'storageClass' property`);
+        }
+    }
+    // Create output directory if it doesn't exist
+    await mkdir(outputDir, { recursive: true });
+    // Generate files for each entity
+    for (const [entityName, entityConfig] of Object.entries(config.entities)) {
+        const isClassMode = entityConfig.classMode ?? globalOptions.classMode;
+        // Use entity.ts for classMode (matches existing pattern), entityManager.ts for instance mode
+        const fileName = isClassMode ? `${entityName}.ts` : `${entityName}Manager.ts`;
+        const filePath = join(outputDir, fileName);
+        // Generate source code
+        const source = generateManagerSource(entityName, entityConfig, globalOptions);
+        // Write file
+        await writeFile(filePath, source, 'utf-8');
+        generatedFiles.push(filePath);
+    }
+    return generatedFiles;
+}