@common-stack/server-core 7.2.1-alpha.31 → 7.2.1-alpha.32

package/lib/moleculer-generation/typedMoleculerService.d.ts

@@ -0,0 +1,491 @@
+/**
+ * @file typed-moleculer-service.ts
+ * @description Provides type-safe base class for Moleculer services with ENFORCED
+ * compile-time verification AND automatic action generation from service methods.
+ */
+import type { ServiceSchema } from 'moleculer';
+import { type ExcludedServiceMethods } from './serviceGenerationUtils';
+/**
+ * Exclude base service CRUD methods and lifecycle methods
+ * @deprecated Use ExcludedServiceMethods from serviceGenerationUtils instead
+ */
+type ExcludedMethods = ExcludedServiceMethods;
+/**
+ * Extract all method names from a service interface (excluding base methods)
+ */
+export type ServiceMethods<T> = {
+    [K in keyof T]: T[K] extends Function ? (K extends ExcludedMethods ? never : K) : never;
+}[keyof T];
+/**
+ * Required actions type - forces all service methods to have actions
+ */
+export type RequiredServiceActions<TService> = {
+    [K in ServiceMethods<TService>]: {
+        params?: Record<string, unknown>;
+        handler: (...args: unknown[]) => unknown;
+    };
+};
+/**
+ * Service schema with REQUIRED typed actions - TypeScript will error if any are missing
+ */
+export interface EnforcedServiceSchema<TService> extends Omit<ServiceSchema, 'actions'> {
+    name: string;
+    actions: RequiredServiceActions<TService> & Record<string, unknown>;
+}
+/**
+ * ADVANCED AUTO-GENERATED configuration with full control
+ * Params are inferred from TypeScript function signatures with optional fine-grained control
+ */
+export type AutoInferredActionConfig<TService> = {
+    /**
+     * Optional: Override param schemas for specific methods
+     * Use this when you need custom Moleculer validation beyond the default 'object' type
+     *
+     * @example
+     * ```typescript
+     * paramOverrides: {
+     *   findAccountById: { id: 'string' },  // Override inferred 'object' with 'string'
+     *   getUsers: { where: { type: 'object', optional: true } }  // Add optional flag
+     * }
+     * ```
+     */
+    paramOverrides?: Partial<{
+        [K in ServiceMethods<TService>]: Record<string, unknown>;
+    }>;
+    /**
+     * Optional: Only include specific methods (whitelist approach)
+     * If specified, ONLY these methods will be auto-generated
+     * Takes precedence over exclude
+     *
+     * @example
+     * ```typescript
+     * include: ['findAccountById', 'createAccount', 'updateAccount']
+     * ```
+     */
+    include?: Array<ServiceMethods<TService>>;
+    /**
+     * Optional: Exclude specific methods from auto-generation (blacklist approach)
+     * Ignored if 'include' is specified
+     *
+     * @example
+     * ```typescript
+     * exclude: ['deleteAccount', 'internalMethod']
+     * ```
+     */
+    exclude?: Array<ServiceMethods<TService>>;
+    /**
+     * Optional: Map action names to different method names
+     * Use this when your Moleculer action name differs from the service method name
+     *
+     * @example
+     * ```typescript
+     * actionToMethodMap: {
+     *   'accounts.find': 'findAccountById',
+     *   'accounts.create': 'createAccount'
+     * }
+     * ```
+     */
+    actionToMethodMap?: Record<string, string>;
+    /**
+     * Optional: Add custom Moleculer action properties for specific methods
+     * Allows setting visibility, caching, rate limiting, etc.
+     *
+     * @example
+     * ```typescript
+     * actionConfig: {
+     *   findAccountById: {
+     *     cache: true,
+     *     visibility: 'public'
+     *   },
+     *   deleteAccount: {
+     *     visibility: 'protected'
+     *   }
+     * }
+     * ```
+     */
+    actionConfig?: Partial<{
+        [K in ServiceMethods<TService>]: {
+            cache?: boolean | object;
+            visibility?: 'public' | 'protected' | 'private';
+            [key: string]: unknown;
+        };
+    }>;
+};
+/**
+ * ADVANCED AUTO-GENERATED: Generate actions with full control over inclusion, exclusion, and overrides.
+ * Params are inferred from TypeScript function signatures with optional fine-grained control.
+ *
+ * @param service - The service instance to wrap
+ * @param config - Advanced configuration for fine-grained control
+ * @returns Actions object with handlers for selected service methods
+ *
+ * @example
+ * ```typescript
+ * // Basic: Auto-generate all methods
+ * const actions = generateAutoInferredServiceActions<IAccountService>(accountService);
+ *
+ * // Advanced: Include only specific methods
+ * const actions = generateAutoInferredServiceActions<IAccountService>(accountService, {
+ *   include: ['findAccountById', 'createAccount', 'updateAccount']
+ * });
+ *
+ * // Advanced: Exclude specific methods
+ * const actions = generateAutoInferredServiceActions<IAccountService>(accountService, {
+ *   exclude: ['deleteAccount', 'internalMethod']
+ * });
+ *
+ * // Advanced: Override param schemas for specific methods
+ * const actions = generateAutoInferredServiceActions<IAccountService>(accountService, {
+ *   paramOverrides: {
+ *     findAccountById: { id: 'string' },
+ *     getUsers: { where: { type: 'object', optional: true } }
+ *   }
+ * });
+ *
+ * // Advanced: Add custom action configuration
+ * const actions = generateAutoInferredServiceActions<IAccountService>(accountService, {
+ *   actionConfig: {
+ *     findAccountById: { cache: true, visibility: 'public' },
+ *     deleteAccount: { visibility: 'protected' }
+ *   }
+ * });
+ *
+ * // Advanced: Combine multiple options
+ * const actions = generateAutoInferredServiceActions<IAccountService>(accountService, {
+ *   include: ['findAccountById', 'createAccount'],
+ *   paramOverrides: {
+ *     findAccountById: { id: 'string' }
+ *   },
+ *   actionConfig: {
+ *     findAccountById: { cache: true }
+ *   }
+ * });
+ * ```
+ */
+export declare function generateAutoInferredServiceActions<TService>(service: TService, config?: AutoInferredActionConfig<TService>): Record<string, {
+    params?: Record<string, unknown>;
+    handler: (ctx: unknown) => unknown;
+}>;
+/**
+ * Generate both actions AND events from a service instance
+ * - Actions: Generated from regular service methods
+ * - Events: Generated from methods marked with @MoleculerEventHandler decorator
+ *
+ * @param service - The service instance to wrap
+ * @param config - Configuration for actions and events
+ * @returns Object with both actions and events
+ *
+ * @example
+ * ```typescript
+ * // Service with decorator
+ * class OrganizationService {
+ *     // Regular method becomes action
+ *     async createOrganization(org: Org): Promise<Org> { }
+ *
+ *     // Decorated method becomes event handler
+ *     @MoleculerEventHandler(UserBroadcasterAction.OnUserCreated)
+ *     async onUserCreated(event: UserEvent): Promise<void> { }
+ * }
+ *
+ * // Generate both
+ * const { actions, events } = generateServiceActionsAndEvents(service);
+ * ```
+ */
+export declare function generateServiceActionsAndEvents<TService>(service: TService, config?: AutoInferredActionConfig<TService>): {
+    actions: Record<string, {
+        params?: Record<string, unknown>;
+        handler: (ctx: unknown) => unknown;
+        [key: string]: unknown;
+    }>;
+    events: Record<string, {
+        handler: (ctx: unknown) => unknown;
+        group?: string;
+    }>;
+};
+export interface AutoActionConfig {
+    /**
+     * Custom parameter validation schema for specific actions
+     * Key is the action/method name, value is Moleculer params schema
+     */
+    params?: Record<string, Record<string, unknown>>;
+    /**
+     * Actions to exclude from auto-generation (use manual handlers instead)
+     */
+    exclude?: string[];
+    /**
+     * Action name mappings (if action name differs from method name)
+     * Key is the action name, value is the method name
+     */
+    actionToMethodMap?: Record<string, string>;
+}
+/**
+ * Type-safe configuration that REQUIRES params for ALL service methods
+ * TypeScript will show compile error if any method is missing from params
+ */
+export type TypeSafeActionConfig<TService> = {
+    /**
+     * REQUIRED: Parameter validation schema for ALL service methods
+     * TypeScript will error if any method is missing
+     */
+    params: {
+        [K in ServiceMethods<TService>]: Record<string, unknown>;
+    };
+    /**
+     * Optional: Actions to exclude from auto-generation
+     */
+    exclude?: string[];
+    /**
+     * Optional: Action name mappings
+     */
+    actionToMethodMap?: Record<string, string>;
+};
+/**
+ * Automatically generate Moleculer actions from a service instance.
+ *
+ * This eliminates the need to write repetitive action handlers - just pass your service
+ * and it will create handlers that forward all calls automatically.
+ *
+ * @param service - The service instance to wrap
+ * @param config - Optional configuration for customizing actions
+ * @returns Actions object with handlers for all service methods
+ *
+ * @example
+ * ```typescript
+ * const actions = generateServiceActions(accountService, {
+ *   params: {
+ *     findAccountById: { id: 'string' },
+ *     createAccount: { account: 'object' }
+ *   },
+ *   exclude: ['get', 'getAll'] // Handle these manually
+ * });
+ * ```
+ */
+export declare function generateServiceActions<TService extends Record<string, unknown>>(service: TService, config?: AutoActionConfig): Record<string, {
+    params?: Record<string, unknown>;
+    handler: (ctx: unknown) => unknown;
+}>;
+/**
+ * TYPE-SAFE version: Generate Moleculer actions with COMPILE-TIME verification.
+ * TypeScript will error if any service method is missing from params.
+ *
+ * @param service - The service instance to wrap
+ * @param config - Type-safe configuration requiring ALL methods to have params
+ * @returns Actions object with handlers for all service methods
+ *
+ * @example
+ * ```typescript
+ * const actions = generateTypeSafeServiceActions<IAccountService>(accountService, {
+ *   params: {
+ *     // TypeScript enforces ALL IAccountService methods are here!
+ *     findAccountById: { id: 'string' },
+ *     createAccount: { account: 'object' },
+ *     // ... if you forget any method, TypeScript will error
+ *   }
+ * });
+ * ```
+ */
+export declare function generateTypeSafeServiceActions<TService>(service: TService, config: TypeSafeActionConfig<TService>): Record<string, {
+    params?: Record<string, unknown>;
+    handler: (ctx: unknown) => unknown;
+}>;
+/**
+ * Verify that all service methods have param validation defined.
+ * Throws an error if any methods are missing params.
+ *
+ * Use this in development to ensure you haven't forgotten any param schemas.
+ *
+ * @param service - The service instance
+ * @param config - The config used for generateServiceActions
+ * @throws Error if any methods are missing param validation
+ *
+ * @example
+ * ```typescript
+ * const config = { params: { ... }, exclude: [...] };
+ * verifyAllParamsDefined(accountService, config); // Throws if params missing
+ * const actions = generateServiceActions(accountService, config);
+ * ```
+ */
+export declare function verifyAllParamsDefined<TService extends Record<string, unknown>>(service: TService, config?: AutoActionConfig): void;
+/**
+ * Type-safe Moleculer Service base class with ENFORCED action verification.
+ *
+ * @deprecated Use generateServiceActionsAndEvents() or generateAutoInferredServiceActions() instead
+ * This class requires importing Moleculer Service which causes build issues.
+ *
+ * Usage with auto-generated actions:
+ * ```typescript
+ * export class AccountMoleculerService extends Service {
+ *     constructor(broker: ServiceBroker, { container }: { container: Container }) {
+ *         super(broker);
+ *         const accountService = container.get<IAccountService>(SERVER_TYPES.IAccountService);
+ *
+ *         // Automatically generate ALL actions from the service!
+ *         const autoActions = generateAutoInferredServiceActions(accountService);
+ *
+ *         this.parseServiceSchema({
+ *             name: MoleculerServiceName.AccountUser,
+ *             actions: autoActions,
+ *         });
+ *     }
+ * }
+ * ```
+ */
+/**
+ * Placeholder for TypedMoleculerService for backward compatibility
+ * @deprecated Use generateServiceActionsAndEvents() instead
+ */
+export type TypedMoleculerService<TService> = unknown;
+/**
+ * Helper type for explicit verification - use in const to get better error messages
+ */
+export type VerifyAllActionsImplemented<TService> = {
+    [K in ServiceMethods<TService>]: true;
+};
+/**
+ * Typed action handler with parameter and return type safety
+ */
+export interface TypedActionHandler<TParams = unknown, TReturn = unknown> {
+    params?: Record<string, unknown>;
+    handler: (ctx: {
+        params: TParams;
+    }) => TReturn | Promise<TReturn>;
+}
+/**
+ * Helper to create a typed action handler
+ */
+export declare function createTypedAction<TParams, TReturn>(action: TypedActionHandler<TParams, TReturn>): TypedActionHandler<TParams, TReturn>;
+/**
+ * Service schema type with better action type hints
+ */
+export interface TypedServiceSchema extends ServiceSchema {
+    actions?: Record<string, TypedActionHandler>;
+}
+/**
+ * Extend Moleculer namespace with action generation utilities
+ */
+declare module './moleculerEventHandler' {
+    namespace Moleculer {
+        /**
+         * ADVANCED AUTO-GENERATED configuration with full control
+         */
+        type AutoInferredActionConfig<TService> = {
+            paramOverrides?: Partial<{
+                [K in ServiceMethods<TService>]: Record<string, unknown>;
+            }>;
+            include?: Array<ServiceMethods<TService>>;
+            exclude?: Array<ServiceMethods<TService>>;
+            actionToMethodMap?: Record<string, string>;
+            actionConfig?: Partial<{
+                [K in ServiceMethods<TService>]: {
+                    cache?: boolean | object;
+                    visibility?: 'public' | 'protected' | 'private';
+                    [key: string]: unknown;
+                };
+            }>;
+        };
+        /**
+         * Generate actions with full control over inclusion, exclusion, and overrides.
+         * Params are inferred from TypeScript function signatures.
+         */
+        function generateAutoInferredActions<TService>(service: TService, config?: AutoInferredActionConfig<TService>): Record<string, {
+            params?: Record<string, unknown>;
+            handler: (ctx: unknown) => unknown;
+        }>;
+        /**
+         * Generate both actions AND events from a service instance
+         */
+        function generateActionsAndEvents<TService>(service: TService, config?: AutoInferredActionConfig<TService>): {
+            actions: Record<string, {
+                params?: Record<string, unknown>;
+                handler: (ctx: unknown) => unknown;
+                [key: string]: unknown;
+            }>;
+            events: Record<string, {
+                handler: (ctx: unknown) => unknown;
+                group?: string;
+            }>;
+        };
+        /**
+         * DEBUG UTILITY: Extract parameter information for all service methods
+         * Returns detailed information about parameters, schemas, and configurations
+         */
+        function debugServiceParams<TService>(service: TService, config?: AutoInferredActionConfig<TService>): Record<string, {
+            methodName: string;
+            paramNames: string[];
+            functionSignature: string;
+            inferredSchema: Record<string, unknown> | undefined;
+            overrideSchema: Record<string, unknown> | undefined;
+            isExcluded: boolean;
+            isEventHandler: boolean;
+        }>;
+        /**
+         * DEBUG UTILITY: Pretty print service parameter information to console
+         * Useful for understanding auto-generation and identifying methods needing overrides
+         */
+        function printServiceParams<TService>(service: TService, config?: AutoInferredActionConfig<TService>, options?: {
+            onlyMissingOverrides?: boolean;
+            onlyIncluded?: boolean;
+            showExcluded?: boolean;
+        }): void;
+    }
+}
+/**
+ * DEBUG UTILITY: Dumps parameter information for all service methods
+ *
+ * This function extracts and logs parameter names, types, and inferred schemas
+ * for debugging auto-generation issues. Use during development to understand
+ * what the auto-generation sees and optimize paramOverrides.
+ *
+ * @param service - The service instance to analyze
+ * @param config - Optional configuration to see what would be generated
+ * @returns Object with detailed parameter information for each method
+ *
+ * @example
+ * ```typescript
+ * // In development/debug mode
+ * const paramInfo = Moleculer.debugServiceParams(accountService);
+ * console.log(JSON.stringify(paramInfo, null, 2));
+ *
+ * // With config to see filtered results
+ * const paramInfo = Moleculer.debugServiceParams(accountService, {
+ *   exclude: ['dispose', 'createUserToken']
+ * });
+ * ```
+ */
+export declare function debugServiceParams<TService>(service: TService, config?: AutoInferredActionConfig<TService>): Record<string, {
+    methodName: string;
+    paramNames: string[];
+    functionSignature: string;
+    inferredSchema: Record<string, unknown> | undefined;
+    overrideSchema: Record<string, unknown> | undefined;
+    isExcluded: boolean;
+    isEventHandler: boolean;
+}>;
+/**
+ * DEBUG UTILITY: Pretty prints service parameter information to console
+ *
+ * Formats and logs the output of debugServiceParams() in a readable way.
+ * Shows which methods need paramOverrides and what types are inferred.
+ *
+ * @param service - The service instance to analyze
+ * @param config - Optional configuration
+ * @param options - Display options
+ *
+ * @example
+ * ```typescript
+ * // Print all methods
+ * Moleculer.printServiceParams(accountService);
+ *
+ * // Print only methods without overrides
+ * Moleculer.printServiceParams(accountService, config, { onlyMissingOverrides: true });
+ *
+ * // Print only included methods
+ * Moleculer.printServiceParams(accountService, config, { onlyIncluded: true });
+ * ```
+ */
+export declare function printServiceParams<TService>(service: TService, config?: AutoInferredActionConfig<TService>, options?: {
+    onlyMissingOverrides?: boolean;
+    onlyIncluded?: boolean;
+    showExcluded?: boolean;
+}): void;
+export {};