@skmtc/core 0.0.793 → 0.0.795

package/esm/typescript/FunctionParameter.js

@@ -3,14 +3,183 @@ import { camelCase } from 'lodash-es';
 import { match, P } from 'ts-pattern';
 import { List } from './List.js';
 import { isEmpty } from '../helpers/isEmpty.js';
+/**
+ * Generates TypeScript function parameters with advanced handling for different parameter patterns.
+ *
+ * `FunctionParameter` is a sophisticated utility for generating TypeScript function parameter
+ * syntax that handles multiple parameter patterns including named parameters, destructured
+ * object parameters, and void parameters. It provides intelligent type handling and can
+ * generate both the parameter declaration and the parameter usage patterns.
+ *
+ * This class is essential for generating type-safe function signatures in API clients,
+ * utility functions, and other generated code where parameters need to be handled
+ * consistently and safely.
+ *
+ * ## Supported Parameter Patterns
+ *
+ * - **Named Parameters**: Traditional `paramName: Type` syntax
+ * - **Destructured Parameters**: `{ prop1, prop2 }: ObjectType` syntax
+ * - **Void Parameters**: No parameters when dealing with void types
+ * - **Optional Parameters**: Automatic handling of optional parameter markers
+ * - **Empty Filtering**: Option to skip empty properties in destructured objects
+ *
+ * @example Named parameter generation
+ * ```typescript
+ * import { FunctionParameter, Definition, Identifier } from '@skmtc/core';
+ *
+ * const userIdParam = new FunctionParameter({
+ *   name: 'userId',
+ *   typeDefinition: new Definition({
+ *     context: generateContext,
+ *     identifier: Identifier.createType('string'),
+ *     value: { type: 'string' }
+ *   }),
+ *   required: true
+ * });
+ *
+ * console.log(userIdParam.toString()); // 'userId: string'
+ * console.log(userIdParam.toInbound()); // 'userId'
+ * ```
+ *
+ * @example Destructured parameter generation
+ * ```typescript
+ * const destructuredParam = new FunctionParameter({
+ *   typeDefinition: new Definition({
+ *     context: generateContext,
+ *     identifier: Identifier.createType('UserParams'),
+ *     value: {
+ *       type: 'object',
+ *       objectProperties: {
+ *         properties: {
+ *           name: { type: 'string' },
+ *           email: { type: 'string' },
+ *           age: { type: 'number' }
+ *         }
+ *       }
+ *     }
+ *   }),
+ *   destructure: true,
+ *   required: true
+ * });
+ *
+ * console.log(destructuredParam.toString());
+ * // '{ name, email, age }: UserParams'
+ *
+ * console.log(destructuredParam.toInbound());
+ * // '{ name, email, age }'
+ * ```
+ *
+ * @example Optional parameter handling
+ * ```typescript
+ * const optionalParam = new FunctionParameter({
+ *   name: 'options',
+ *   typeDefinition: optionsTypeDefinition,
+ *   required: false
+ * });
+ *
+ * console.log(optionalParam.toString()); // 'options?: OptionsType'
+ * ```
+ *
+ * @example Void parameter handling
+ * ```typescript
+ * const voidParam = new FunctionParameter({
+ *   typeDefinition: new Definition({
+ *     context: generateContext,
+ *     identifier: Identifier.createType('void'),
+ *     value: { type: 'void' }
+ *   })
+ * });
+ *
+ * console.log(voidParam.toString()); // ''
+ * console.log(voidParam.toInbound()); // ''
+ * ```
+ *
+ * @example Property checking
+ * ```typescript
+ * const objectParam = new FunctionParameter({
+ *   typeDefinition: userTypeDefinition,
+ *   destructure: true,
+ *   required: true
+ * });
+ *
+ * if (objectParam.hasProperty('email')) {
+ *   // Handle email property access
+ *   console.log('Parameter includes email property');
+ * }
+ *
+ * const propertyList = objectParam.toPropertyList();
+ * console.log(propertyList.toString()); // 'name, email, age'
+ * ```
+ *
+ * @example API method generation with parameters
+ * ```typescript
+ * class ApiMethodGenerator {
+ *   generateMethod(
+ *     methodName: string,
+ *     pathParams?: FunctionParameter,
+ *     bodyParam?: FunctionParameter
+ *   ) {
+ *     const parameters = [pathParams, bodyParam]
+ *       .filter(p => p && p.toString())
+ *       .map(p => p!.toString())
+ *       .join(', ');
+ *
+ *     const pathInbound = pathParams?.toInbound() || '';
+ *     const bodyInbound = bodyParam?.toInbound() || '';
+ *
+ *     return `
+ * async ${methodName}(${parameters}) {
+ *   const path = this.buildPath(${pathInbound});
+ *   return this.request('POST', path, ${bodyInbound});
+ * }`;
+ *   }
+ * }
+ * ```
+ *
+ * @example Empty property filtering
+ * ```typescript
+ * const filteredParam = new FunctionParameter({
+ *   typeDefinition: sparseObjectDefinition,
+ *   destructure: true,
+ *   required: true,
+ *   skipEmpty: true // Skip properties with empty types
+ * });
+ *
+ * // Only non-empty properties will be included in destructuring
+ * console.log(filteredParam.toString());
+ * // '{ validProp1, validProp2 }: FilteredType' (empty props omitted)
+ * ```
+ */
 export class FunctionParameter {
+    /**
+     * Creates a new FunctionParameter instance with the specified configuration.
+     *
+     * The constructor analyzes the provided type definition and configuration options
+     * to determine the appropriate parameter pattern (void, regular, or destructured).
+     * It handles the complex logic of parameter type determination and validation.
+     *
+     * @param args - Configuration options for the function parameter
+     *
+     * @throws {Error} When the parameter configuration is invalid
+     *
+     * @example
+     * ```typescript
+     * const param = new FunctionParameter({
+     *   name: 'userData',
+     *   typeDefinition: userTypeDefinition,
+     *   required: true
+     * });
+     * ```
+     */
     constructor(args) {
+        /** The internal parameter configuration determining how the parameter is generated */
         Object.defineProperty(this, "properties", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether to skip empty properties in destructured parameters */
         Object.defineProperty(this, "skipEmpty", {
             enumerable: true,
             configurable: true,
@@ -39,6 +208,34 @@ export class FunctionParameter {
             this.properties = { type: 'void' };
         }
     }
+    /**
+     * Checks if the parameter has a specific property (for object-based parameters).
+     *
+     * This method determines whether a given property name exists within the parameter's
+     * type structure. It's useful for conditional code generation based on available
+     * properties and only returns true for object-based parameters (regular object
+     * parameters or destructured parameters).
+     *
+     * @param name - The property name to check for
+     * @returns True if the property exists in the parameter's type structure
+     *
+     * @example
+     * ```typescript
+     * const userParam = new FunctionParameter({
+     *   typeDefinition: userTypeDefinition, // has properties: name, email, age
+     *   destructure: true,
+     *   required: true
+     * });
+     *
+     * if (userParam.hasProperty('email')) {
+     *   console.log('Parameter includes email property');
+     * }
+     *
+     * if (userParam.hasProperty('nonexistent')) {
+     *   // This won't execute
+     * }
+     * ```
+     */
     hasProperty(name) {
         return match(this.properties)
             .with({ type: 'void' }, () => false)
@@ -51,6 +248,37 @@ export class FunctionParameter {
         })
             .exhaustive();
     }
+    /**
+     * Generates a List of property names from the parameter.
+     *
+     * This method extracts property names from object-based parameters and returns
+     * them as a List instance. For regular parameters, it returns the parameter name,
+     * for destructured parameters it returns all object properties, and for void
+     * parameters it returns an empty list.
+     *
+     * @returns List containing the relevant property or parameter names
+     *
+     * @example
+     * ```typescript
+     * const destructuredParam = new FunctionParameter({
+     *   typeDefinition: userTypeDefinition, // has properties: name, email, age
+     *   destructure: true,
+     *   required: true
+     * });
+     *
+     * const propertyList = destructuredParam.toPropertyList();
+     * console.log(propertyList.toString()); // 'name, email, age'
+     *
+     * const regularParam = new FunctionParameter({
+     *   name: 'userData',
+     *   typeDefinition: userTypeDefinition,
+     *   required: true
+     * });
+     *
+     * const regularList = regularParam.toPropertyList();
+     * console.log(regularList.toString()); // 'userData'
+     * ```
+     */
     toPropertyList() {
         return match(this.properties)
             .with({ type: 'void' }, () => List.toEmpty())
@@ -60,6 +288,35 @@ export class FunctionParameter {
         })
             .exhaustive();
     }
+    /**
+     * Generates the inbound parameter syntax for function calls.
+     *
+     * This method produces the syntax used when calling a function with this parameter.
+     * For regular parameters, it returns the parameter name. For destructured parameters,
+     * it returns the destructured object syntax. For void parameters, it returns an
+     * empty string.
+     *
+     * @returns The inbound parameter syntax string
+     *
+     * @example
+     * ```typescript
+     * const regularParam = new FunctionParameter({
+     *   name: 'userId',
+     *   typeDefinition: stringTypeDefinition,
+     *   required: true
+     * });
+     *
+     * console.log(regularParam.toInbound()); // 'userId'
+     *
+     * const destructuredParam = new FunctionParameter({
+     *   typeDefinition: userTypeDefinition,
+     *   destructure: true,
+     *   required: true
+     * });
+     *
+     * console.log(destructuredParam.toInbound()); // '{ name, email, age }'
+     * ```
+     */
     toInbound() {
         return match(this.properties)
             .with({ type: 'void' }, () => '')
@@ -69,6 +326,42 @@ export class FunctionParameter {
         })
             .exhaustive();
     }
+    /**
+     * Generates the complete function parameter declaration syntax.
+     *
+     * This method produces the full parameter declaration that appears in a function
+     * signature, including the parameter name, type annotation, and optional markers.
+     * It handles all parameter patterns supported by the class.
+     *
+     * @returns The complete parameter declaration string
+     *
+     * @example
+     * ```typescript
+     * const requiredParam = new FunctionParameter({
+     *   name: 'userId',
+     *   typeDefinition: stringTypeDefinition,
+     *   required: true
+     * });
+     *
+     * console.log(requiredParam.toString()); // 'userId: string'
+     *
+     * const optionalParam = new FunctionParameter({
+     *   name: 'options',
+     *   typeDefinition: optionsTypeDefinition,
+     *   required: false
+     * });
+     *
+     * console.log(optionalParam.toString()); // 'options?: OptionsType'
+     *
+     * const destructuredParam = new FunctionParameter({
+     *   typeDefinition: userTypeDefinition,
+     *   destructure: true,
+     *   required: true
+     * });
+     *
+     * console.log(destructuredParam.toString()); // '{ name, email, age }: UserType'
+     * ```
+     */
     toString() {
         return match(this.properties)
             .with({ type: 'void' }, () => '')
@@ -86,6 +379,41 @@ export class FunctionParameter {
             .exhaustive();
     }
 }
+/**
+ * Generates destructured object parameter syntax from a type definition.
+ *
+ * This helper function creates the destructured parameter syntax for object types,
+ * handling property name validation and optional camelCase conversion for invalid
+ * JavaScript identifiers. It integrates with the List system to produce properly
+ * formatted destructured parameter lists.
+ *
+ * @param typeDefinition - The object type definition to destructure
+ * @param options - Options for controlling the destructuring behavior
+ * @param options.skipEmpty - Whether to skip empty properties
+ * @returns List instance representing the destructured parameter structure
+ *
+ * @example
+ * ```typescript
+ * const objectDef = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createType('ApiParams'),
+ *   value: {
+ *     type: 'object',
+ *     objectProperties: {
+ *       properties: {
+ *         'user-id': { type: 'string' },
+ *         'valid_name': { type: 'string' },
+ *         'api-key': { type: 'string' }
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * const result = toDestructured(objectDef);
+ * console.log(result.toString());
+ * // "{ 'user-id': userId, valid_name, 'api-key': apiKey }"
+ * ```
+ */
 const toDestructured = (typeDefinition, { skipEmpty } = {}) => {
     return List.fromKeys(typeDefinition.value.objectProperties?.properties).toObject(key => {
         return isIdentifierName(key) ? key : List.toKeyValue(key, camelCase(key));

package/esm/typescript/PathParams.d.ts

@@ -2,18 +2,216 @@ import type { GenerateContext } from '../context/GenerateContext.js';
 import { Definition } from '../dsl/Definition.js';
 import type { TypeSystemObject } from '../types/TypeSystem.js';
 import { FunctionParameter } from './FunctionParameter.js';
+/**
+ * Constructor arguments for {@link PathParams}.
+ */
 type ConstructorArgs = {
+    /** The generation context for registering types and handling imports */
     context: GenerateContext;
+    /** Optional argument name for the parameter (if undefined, uses destructuring) */
     argName?: string;
+    /** Name of the TypeScript type to generate */
     typeName: string;
+    /** The type system object defining the parameter structure */
     typeValue: TypeSystemObject;
+    /** OpenAPI path template with parameter placeholders */
     pathTemplate: string;
 };
+/**
+ * Manages path parameter type definitions and function parameters for API endpoints.
+ *
+ * `PathParams` is a utility class that combines type generation, function parameter
+ * handling, and path templating for OpenAPI path parameters. It creates TypeScript
+ * type definitions for path parameters and generates the corresponding function
+ * parameters that can be used in API client methods.
+ *
+ * This class is essential for generating type-safe API clients where path parameters
+ * are properly typed and validated at compile time. It handles both destructured
+ * parameters (when no argument name is provided) and named parameters.
+ *
+ * ## Key Features
+ *
+ * - **Type Definition Generation**: Creates TypeScript types for path parameters
+ * - **Function Parameter Integration**: Generates properly typed function parameters
+ * - **Path Template Processing**: Converts OpenAPI paths to template literals
+ * - **Destructuring Support**: Handles both named and destructured parameter patterns
+ * - **Context Integration**: Fully integrated with the SKMTC generation pipeline
+ *
+ * @example Basic path parameters with destructuring
+ * ```typescript
+ * import { PathParams } from '@skmtc/core';
+ *
+ * const pathParams = new PathParams({
+ *   context: generateContext,
+ *   typeName: 'GetUserParams',
+ *   typeValue: {
+ *     type: 'object',
+ *     objectProperties: {
+ *       properties: {
+ *         id: { type: 'string' },
+ *         format: { type: 'string' }
+ *       }
+ *     }
+ *   },
+ *   pathTemplate: '/users/{id}'
+ * });
+ *
+ * console.log(pathParams.path); // '/users/${id}'
+ * ```
+ *
+ * @example Named parameter usage
+ * ```typescript
+ * const namedPathParams = new PathParams({
+ *   context: generateContext,
+ *   argName: 'params',
+ *   typeName: 'UserPathParams',
+ *   typeValue: {
+ *     type: 'object',
+ *     objectProperties: {
+ *       properties: {
+ *         userId: { type: 'string' },
+ *         projectId: { type: 'string' }
+ *       }
+ *     }
+ *   },
+ *   pathTemplate: '/users/{userId}/projects/{projectId}'
+ * });
+ *
+ * console.log(pathParams.path); // '/users/${params.userId}/projects/${params.projectId}'
+ * ```
+ *
+ * @example API client method generation
+ * ```typescript
+ * class ApiMethodGenerator {
+ *   generateGetMethod(operationPath: string, parameters: any) {
+ *     const pathParams = new PathParams({
+ *       context: this.context,
+ *       argName: 'pathParams',
+ *       typeName: 'PathParameters',
+ *       typeValue: parameters,
+ *       pathTemplate: operationPath
+ *     });
+ *
+ *     return `
+ * async getData(${pathParams.parameter.toString()}) {
+ *   const url = \`${pathParams.path}\`;
+ *   return this.client.get(url);
+ * }`;
+ *   }
+ * }
+ *
+ * // Generates:
+ * // async getData(pathParams: PathParameters) {
+ * //   const url = `/users/${pathParams.userId}/projects/${pathParams.projectId}`;
+ * //   return this.client.get(url);
+ * // }
+ * ```
+ *
+ * @example With destructured parameters
+ * ```typescript
+ * const destructuredParams = new PathParams({
+ *   context: generateContext,
+ *   // No argName provided, so uses destructuring
+ *   typeName: 'OrderParams',
+ *   typeValue: {
+ *     type: 'object',
+ *     objectProperties: {
+ *       properties: {
+ *         orderId: { type: 'string' },
+ *         customerId: { type: 'string' }
+ *       }
+ *     }
+ *   },
+ *   pathTemplate: '/customers/{customerId}/orders/{orderId}'
+ * });
+ *
+ * // Function parameter will be: { orderId, customerId }: OrderParams
+ * // Path template will be: '/customers/${customerId}/orders/${orderId}'
+ * ```
+ *
+ * @example Complex nested path parameters
+ * ```typescript
+ * const complexPathParams = new PathParams({
+ *   context: generateContext,
+ *   argName: 'pathData',
+ *   typeName: 'ComplexPathParams',
+ *   typeValue: {
+ *     type: 'object',
+ *     objectProperties: {
+ *       properties: {
+ *         orgId: { type: 'string' },
+ *         projectId: { type: 'string' },
+ *         issueId: { type: 'number' },
+ *         commentId: { type: 'string' }
+ *       }
+ *     }
+ *   },
+ *   pathTemplate: '/orgs/{orgId}/projects/{projectId}/issues/{issueId}/comments/{commentId}'
+ * });
+ *
+ * // Generates path: '/orgs/${pathData.orgId}/projects/${pathData.projectId}/issues/${pathData.issueId}/comments/${pathData.commentId}'
+ * ```
+ *
+ * @example Integration with operation generation
+ * ```typescript
+ * class OperationGenerator {
+ *   generateOperation(operation: OasOperation) {
+ *     const pathParameters = this.extractPathParameters(operation);
+ *
+ *     if (pathParameters.length > 0) {
+ *       const pathParams = new PathParams({
+ *         context: this.context,
+ *         typeName: `${operation.operationId}PathParams`,
+ *         typeValue: this.buildParametersType(pathParameters),
+ *         pathTemplate: operation.path
+ *       });
+ *
+ *       return this.generateMethodWithPathParams(operation, pathParams);
+ *     }
+ *
+ *     return this.generateSimpleMethod(operation);
+ *   }
+ * }
+ * ```
+ */
 export declare class PathParams {
+    /** The generation context used for type registration and imports */
     context: GenerateContext;
+    /** The TypeScript type definition for the path parameters */
     typeDefinition: Definition<TypeSystemObject>;
+    /** The function parameter representation for method signatures */
     parameter: FunctionParameter;
+    /** The processed path template with parameter substitutions */
     path: string;
+    /**
+     * Creates a new PathParams instance with type definitions and path processing.
+     *
+     * The constructor sets up the complete parameter handling pipeline:
+     * 1. Creates a TypeScript type definition for the parameters
+     * 2. Generates a function parameter (either named or destructured)
+     * 3. Processes the path template for runtime interpolation
+     *
+     * @param args - Configuration for path parameter generation
+     *
+     * @example
+     * ```typescript
+     * const pathParams = new PathParams({
+     *   context: generateContext,
+     *   argName: 'params',
+     *   typeName: 'UserPathParams',
+     *   typeValue: {
+     *     type: 'object',
+     *     objectProperties: {
+     *       properties: {
+     *         id: { type: 'string' },
+     *         format: { type: 'string' }
+     *       }
+     *     }
+     *   },
+     *   pathTemplate: '/users/{id}/profile'
+     * });
+     * ```
+     */
     constructor({ context, argName, typeName, typeValue, pathTemplate }: ConstructorArgs);
 }
 export {};

package/esm/typescript/PathParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathParams.d.ts","sourceRoot":"","sources":["../../src/typescript/PathParams.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAG1D,KAAK,eAAe,GAAG;IACrB,OAAO,EAAE,eAAe,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,gBAAgB,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,qBAAa,UAAU;IACrB,OAAO,EAAE,eAAe,CAAA;IACxB,cAAc,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAC5C,SAAS,EAAE,iBAAiB,CAAA;IAC5B,IAAI,EAAE,MAAM,CAAA;gBAEA,EACV,OAAO,EACP,OAAO,EACP,QAAQ,EACR,SAAS,EACT,YAAY,EACb,EAAE,eAAe;CAwBnB"}
+{"version":3,"file":"PathParams.d.ts","sourceRoot":"","sources":["../../src/typescript/PathParams.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAG1D;;GAEG;AACH,KAAK,eAAe,GAAG;IACrB,wEAAwE;IACxE,OAAO,EAAE,eAAe,CAAA;IACxB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,SAAS,EAAE,gBAAgB,CAAA;IAC3B,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4JG;AACH,qBAAa,UAAU;IACrB,oEAAoE;IACpE,OAAO,EAAE,eAAe,CAAA;IAExB,6DAA6D;IAC7D,cAAc,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAE5C,kEAAkE;IAClE,SAAS,EAAE,iBAAiB,CAAA;IAE5B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;gBACS,EACV,OAAO,EACP,OAAO,EACP,QAAQ,EACR,SAAS,EACT,YAAY,EACb,EAAE,eAAe;CAwBnB"}