@skmtc/core 0.0.794 → 0.0.796

package/script/typescript/FunctionParameter.d.ts

@@ -1,35 +1,348 @@
 import type { TypeSystemObject, TypeSystemValue, TypeSystemVoid } from '../types/TypeSystem.js';
 import type { Definition } from '../dsl/Definition.js';
 import { List } from './List.js';
+/**
+ * Constructor arguments for {@link FunctionParameter}.
+ */
 type FunctionParameterArgs = {
+    /** Optional parameter name (if undefined and destructure is true, uses destructured syntax) */
     name?: string;
+    /** The type definition for the parameter */
     typeDefinition: Definition<TypeSystemObject | TypeSystemVoid>;
+    /** Whether to use destructured parameter syntax */
     destructure?: boolean;
+    /** Whether the parameter is required (affects optional marker) */
     required?: boolean;
+    /** Whether to skip empty properties in destructured parameters */
     skipEmpty?: boolean;
 };
+/**
+ * Union type representing the different parameter configurations.
+ */
 type ParameterProperties = VoidParameter | DestructuredParameter | RegularParameter;
+/**
+ * Represents a void parameter (no parameters).
+ */
 type VoidParameter = {
     type: 'void';
 };
+/**
+ * Represents a destructured object parameter.
+ */
 type DestructuredParameter = {
     type: 'destructured';
     typeDefinition: Definition<TypeSystemObject>;
     required: true;
 };
+/**
+ * Represents a regular named parameter.
+ */
 type RegularParameter = {
     type: 'regular';
     name: string;
     typeDefinition: Definition<TypeSystemValue>;
     required: boolean;
 };
+/**
+ * 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 declare class FunctionParameter {
+    /** The internal parameter configuration determining how the parameter is generated */
     properties: ParameterProperties;
+    /** Whether to skip empty properties in destructured parameters */
     skipEmpty?: boolean;
+    /**
+     * 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: FunctionParameterArgs);
+    /**
+     * 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: string): boolean;
+    /**
+     * 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(): List;
+    /**
+     * 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(): string;
+    /**
+     * 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(): string;
 }
 export {};

package/script/typescript/FunctionParameter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FunctionParameter.d.ts","sourceRoot":"","sources":["../../src/typescript/FunctionParameter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAwB,MAAM,WAAW,CAAA;AAItD,KAAK,qBAAqB,GAAG;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,cAAc,EAAE,UAAU,CAAC,gBAAgB,GAAG,cAAc,CAAC,CAAA;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,mBAAmB,GAAG,aAAa,GAAG,qBAAqB,GAAG,gBAAgB,CAAA;AAEnF,KAAK,aAAa,GAAG;IACnB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,qBAAqB,GAAG;IAC3B,IAAI,EAAE,cAAc,CAAA;IACpB,cAAc,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAC5C,QAAQ,EAAE,IAAI,CAAA;CACf,CAAA;AAED,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,UAAU,CAAC,eAAe,CAAC,CAAA;IAC3C,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED,qBAAa,iBAAiB;IAC5B,UAAU,EAAE,mBAAmB,CAAA;IAC/B,SAAS,CAAC,EAAE,OAAO,CAAA;gBAEP,IAAI,EAAE,qBAAqB;IA2BvC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAalC,cAAc,IAAI,IAAI;IAUtB,SAAS,IAAI,MAAM;IAUnB,QAAQ,IAAI,MAAM;CAoBnB"}
+{"version":3,"file":"FunctionParameter.d.ts","sourceRoot":"","sources":["../../src/typescript/FunctionParameter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAwB,MAAM,WAAW,CAAA;AAItD;;GAEG;AACH,KAAK,qBAAqB,GAAG;IAC3B,+FAA+F;IAC/F,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,cAAc,EAAE,UAAU,CAAC,gBAAgB,GAAG,cAAc,CAAC,CAAA;IAC7D,mDAAmD;IACnD,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,KAAK,mBAAmB,GAAG,aAAa,GAAG,qBAAqB,GAAG,gBAAgB,CAAA;AAEnF;;GAEG;AACH,KAAK,aAAa,GAAG;IACnB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;GAEG;AACH,KAAK,qBAAqB,GAAG;IAC3B,IAAI,EAAE,cAAc,CAAA;IACpB,cAAc,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAA;IAC5C,QAAQ,EAAE,IAAI,CAAA;CACf,CAAA;AAED;;GAEG;AACH,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc,EAAE,UAAU,CAAC,eAAe,CAAC,CAAA;IAC3C,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkJG;AACH,qBAAa,iBAAiB;IAC5B,sFAAsF;IACtF,UAAU,EAAE,mBAAmB,CAAA;IAE/B,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;;;;;;;;;;;;;;;;;OAmBG;gBACS,IAAI,EAAE,qBAAqB;IA2BvC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAalC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,cAAc,IAAI,IAAI;IAUtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,SAAS,IAAI,MAAM;IAUnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,QAAQ,IAAI,MAAM;CAoBnB"}