@skmtc/core 0.0.793 → 0.0.794

package/script/typescript/ReactRouterPathParams.d.ts

@@ -2,18 +2,208 @@ import { ContentBase } from '../dsl/ContentBase.js';
 import type { GenerateContext } from '../context/GenerateContext.js';
 import type { OasOperation } from '../oas/operation/Operation.js';
 import type { GeneratorKey } from '../types/GeneratorKeys.js';
+/**
+ * Constructor arguments for {@link ReactRouterPathParams}.
+ */
 type CreateArgs = {
+    /** The generation context for registering imports and handling dependencies */
     context: GenerateContext;
+    /** The generator key identifying this component */
     generatorKey: GeneratorKey;
+    /** The OpenAPI operation containing path parameters */
     operation: OasOperation;
+    /** The destination file path for import registration */
     destinationPath: string;
 };
+/**
+ * Generates React Router path parameter handling code for OpenAPI operations.
+ *
+ * `ReactRouterPathParams` is a specialized content generator that creates the necessary
+ * React code for extracting and validating path parameters from React Router's `useParams`
+ * hook. It automatically generates parameter extraction, assertion logic, and prop passing
+ * code based on OpenAPI operation path parameters.
+ *
+ * This class is essential for generating type-safe React components that need to access
+ * URL path parameters, ensuring runtime validation and proper TypeScript typing. It
+ * integrates with React Router's `useParams` hook and adds runtime assertions using
+ * the `tiny-invariant` library.
+ *
+ * ## Key Features
+ *
+ * - **Automatic Parameter Extraction**: Generates `useParams()` destructuring code
+ * - **Runtime Assertions**: Creates invariant checks for required parameters
+ * - **Prop Passing**: Generates prop spreading syntax for component integration
+ * - **Import Management**: Automatically registers required imports
+ * - **Type Safety**: Ensures parameters are properly validated at runtime
+ *
+ * @example Basic usage with single path parameter
+ * ```typescript
+ * import { ReactRouterPathParams } from '@skmtc/core';
+ *
+ * const operation = new OasOperation({
+ *   path: '/users/{id}',
+ *   method: 'get',
+ *   // ... other operation properties
+ * });
+ *
+ * const pathParams = new ReactRouterPathParams({
+ *   context: generateContext,
+ *   generatorKey: 'react-router-params',
+ *   operation,
+ *   destinationPath: './UserDetail.tsx'
+ * });
+ *
+ * console.log(pathParams.getParams);
+ * // 'const { id } = useParams()'
+ *
+ * console.log(pathParams.assertParams);
+ * // 'invariant(id, 'Expected id to be defined')'
+ *
+ * console.log(pathParams.passProps);
+ * // 'id={id}'
+ * ```
+ *
+ * @example Multiple path parameters
+ * ```typescript
+ * const complexOperation = new OasOperation({
+ *   path: '/organizations/{orgId}/projects/{projectId}/issues/{issueId}',
+ *   method: 'get',
+ *   // ... other properties
+ * });
+ *
+ * const multiParams = new ReactRouterPathParams({
+ *   context: generateContext,
+ *   generatorKey: 'react-router-params',
+ *   operation: complexOperation,
+ *   destinationPath: './IssueDetail.tsx'
+ * });
+ *
+ * console.log(multiParams.getParams);
+ * // 'const { orgId, projectId, issueId } = useParams()'
+ *
+ * console.log(multiParams.assertParams);
+ * // 'invariant(orgId, 'Expected orgId to be defined')
+ * // invariant(projectId, 'Expected projectId to be defined')
+ * // invariant(issueId, 'Expected issueId to be defined')'
+ *
+ * console.log(multiParams.passProps);
+ * // 'orgId={orgId} projectId={projectId} issueId={issueId}'
+ * ```
+ *
+ * @example Generated React component integration
+ * ```typescript
+ * // Generated component might look like:
+ * import { useParams } from 'react-router-dom';
+ * import invariant from 'tiny-invariant';
+ *
+ * function UserDetail() {
+ *   const { id } = useParams();
+ *   invariant(id, 'Expected id to be defined');
+ *
+ *   return <UserDetailView id={id} />;
+ * }
+ * ```
+ *
+ * @example No path parameters (empty generation)
+ * ```typescript
+ * const simpleOperation = new OasOperation({
+ *   path: '/users',
+ *   method: 'get',
+ *   // ... other properties
+ * });
+ *
+ * const emptyParams = new ReactRouterPathParams({
+ *   context: generateContext,
+ *   generatorKey: 'react-router-params',
+ *   operation: simpleOperation,
+ *   destinationPath: './UserList.tsx'
+ * });
+ *
+ * console.log(emptyParams.getParams);    // ''
+ * console.log(emptyParams.assertParams); // ''
+ * console.log(emptyParams.passProps);    // ''
+ * // No imports registered for this case
+ * ```
+ *
+ * @example Integration in component generation
+ * ```typescript
+ * class ReactComponentGenerator {
+ *   generateDetailComponent(operation: OasOperation) {
+ *     const pathParams = new ReactRouterPathParams({
+ *       context: this.context,
+ *       generatorKey: 'react-component',
+ *       operation,
+ *       destinationPath: this.getDestinationPath(operation)
+ *     });
+ *
+ *     if (pathParams.names.length === 0) {
+ *       // Generate simple component without parameters
+ *       return this.generateSimpleComponent(operation);
+ *     }
+ *
+ *     return `
+ * function ${operation.operationId}() {
+ *   ${pathParams.getParams}
+ *   ${pathParams.assertParams}
+ *
+ *   return (
+ *     <DetailView ${pathParams.passProps} />
+ *   );
+ * }`;
+ *   }
+ * }
+ * ```
+ *
+ * @example Custom parameter validation
+ * ```typescript
+ * class CustomReactRouterParams extends ReactRouterPathParams {
+ *   generateCustomAssertions(paramName: string): string {
+ *     return `
+ * invariant(${paramName}, 'Expected ${paramName} to be defined');
+ * invariant(typeof ${paramName} === 'string', '${paramName} must be a string');
+ * invariant(${paramName}.length > 0, '${paramName} cannot be empty');`;
+ *   }
+ * }
+ * ```
+ */
 export declare class ReactRouterPathParams extends ContentBase {
+    /** Generated code for extracting parameters from useParams() */
     getParams: string;
+    /** Generated code for runtime parameter assertions */
     assertParams: string;
+    /** Generated code for passing parameters as component props */
     passProps: string;
+    /** Array of parameter names extracted from the operation path */
     names: string[];
+    /**
+     * Creates a new ReactRouterPathParams instance with generated parameter handling code.
+     *
+     * The constructor analyzes the OpenAPI operation to extract path parameters and
+     * generates the necessary React code for parameter extraction, validation, and
+     * prop passing. It automatically registers required imports when parameters are present.
+     *
+     * @param args - Configuration for React Router parameter generation
+     *
+     * @example
+     * ```typescript
+     * const pathParams = new ReactRouterPathParams({
+     *   context: generateContext,
+     *   generatorKey: 'react-params',
+     *   operation: userDetailOperation, // has path '/users/{id}'
+     *   destinationPath: './UserDetail.tsx'
+     * });
+     * ```
+     */
     constructor({ context, operation, generatorKey, destinationPath }: CreateArgs);
+    /**
+     * Returns an empty string as this class provides code through its properties.
+     *
+     * The ReactRouterPathParams class doesn't generate output through toString(),
+     * instead providing generated code through the `getParams`, `assertParams`,
+     * and `passProps` properties which can be used directly in template generation.
+     *
+     * @returns Empty string
+     */
     toString(): string;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"ReactRouterPathParams.d.ts","sourceRoot":"","sources":["../../src/typescript/ReactRouterPathParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE,eAAe,CAAA;IACxB,YAAY,EAAE,YAAY,CAAA;IAC1B,SAAS,EAAE,YAAY,CAAA;IACvB,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,qBAAa,qBAAsB,SAAQ,WAAW;IACpD,SAAS,EAAE,MAAM,CAAK;IAEtB,YAAY,EAAE,MAAM,CAAK;IAEzB,SAAS,EAAE,MAAM,CAAK;IAEtB,KAAK,EAAE,MAAM,EAAE,CAAA;gBAEH,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,EAAE,UAAU;IAwBpE,QAAQ,IAAI,MAAM;CAG5B"}
+{"version":3,"file":"ReactRouterPathParams.d.ts","sourceRoot":"","sources":["../../src/typescript/ReactRouterPathParams.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D;;GAEG;AACH,KAAK,UAAU,GAAG;IAChB,+EAA+E;IAC/E,OAAO,EAAE,eAAe,CAAA;IACxB,mDAAmD;IACnD,YAAY,EAAE,YAAY,CAAA;IAC1B,uDAAuD;IACvD,SAAS,EAAE,YAAY,CAAA;IACvB,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsJG;AACH,qBAAa,qBAAsB,SAAQ,WAAW;IACpD,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAK;IAEtB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAK;IAEzB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAK;IAEtB,iEAAiE;IACjE,KAAK,EAAE,MAAM,EAAE,CAAA;IAEf;;;;;;;;;;;;;;;;;;OAkBG;gBACS,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,eAAe,EAAE,EAAE,UAAU;IAwB7E;;;;;;;;OAQG;IACM,QAAQ,IAAI,MAAM;CAG5B"}

package/script/typescript/ReactRouterPathParams.js

@@ -2,27 +2,201 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReactRouterPathParams = void 0;
 const ContentBase_js_1 = require("../dsl/ContentBase.js");
+/**
+ * Generates React Router path parameter handling code for OpenAPI operations.
+ *
+ * `ReactRouterPathParams` is a specialized content generator that creates the necessary
+ * React code for extracting and validating path parameters from React Router's `useParams`
+ * hook. It automatically generates parameter extraction, assertion logic, and prop passing
+ * code based on OpenAPI operation path parameters.
+ *
+ * This class is essential for generating type-safe React components that need to access
+ * URL path parameters, ensuring runtime validation and proper TypeScript typing. It
+ * integrates with React Router's `useParams` hook and adds runtime assertions using
+ * the `tiny-invariant` library.
+ *
+ * ## Key Features
+ *
+ * - **Automatic Parameter Extraction**: Generates `useParams()` destructuring code
+ * - **Runtime Assertions**: Creates invariant checks for required parameters
+ * - **Prop Passing**: Generates prop spreading syntax for component integration
+ * - **Import Management**: Automatically registers required imports
+ * - **Type Safety**: Ensures parameters are properly validated at runtime
+ *
+ * @example Basic usage with single path parameter
+ * ```typescript
+ * import { ReactRouterPathParams } from '@skmtc/core';
+ *
+ * const operation = new OasOperation({
+ *   path: '/users/{id}',
+ *   method: 'get',
+ *   // ... other operation properties
+ * });
+ *
+ * const pathParams = new ReactRouterPathParams({
+ *   context: generateContext,
+ *   generatorKey: 'react-router-params',
+ *   operation,
+ *   destinationPath: './UserDetail.tsx'
+ * });
+ *
+ * console.log(pathParams.getParams);
+ * // 'const { id } = useParams()'
+ *
+ * console.log(pathParams.assertParams);
+ * // 'invariant(id, 'Expected id to be defined')'
+ *
+ * console.log(pathParams.passProps);
+ * // 'id={id}'
+ * ```
+ *
+ * @example Multiple path parameters
+ * ```typescript
+ * const complexOperation = new OasOperation({
+ *   path: '/organizations/{orgId}/projects/{projectId}/issues/{issueId}',
+ *   method: 'get',
+ *   // ... other properties
+ * });
+ *
+ * const multiParams = new ReactRouterPathParams({
+ *   context: generateContext,
+ *   generatorKey: 'react-router-params',
+ *   operation: complexOperation,
+ *   destinationPath: './IssueDetail.tsx'
+ * });
+ *
+ * console.log(multiParams.getParams);
+ * // 'const { orgId, projectId, issueId } = useParams()'
+ *
+ * console.log(multiParams.assertParams);
+ * // 'invariant(orgId, 'Expected orgId to be defined')
+ * // invariant(projectId, 'Expected projectId to be defined')
+ * // invariant(issueId, 'Expected issueId to be defined')'
+ *
+ * console.log(multiParams.passProps);
+ * // 'orgId={orgId} projectId={projectId} issueId={issueId}'
+ * ```
+ *
+ * @example Generated React component integration
+ * ```typescript
+ * // Generated component might look like:
+ * import { useParams } from 'react-router-dom';
+ * import invariant from 'tiny-invariant';
+ *
+ * function UserDetail() {
+ *   const { id } = useParams();
+ *   invariant(id, 'Expected id to be defined');
+ *
+ *   return <UserDetailView id={id} />;
+ * }
+ * ```
+ *
+ * @example No path parameters (empty generation)
+ * ```typescript
+ * const simpleOperation = new OasOperation({
+ *   path: '/users',
+ *   method: 'get',
+ *   // ... other properties
+ * });
+ *
+ * const emptyParams = new ReactRouterPathParams({
+ *   context: generateContext,
+ *   generatorKey: 'react-router-params',
+ *   operation: simpleOperation,
+ *   destinationPath: './UserList.tsx'
+ * });
+ *
+ * console.log(emptyParams.getParams);    // ''
+ * console.log(emptyParams.assertParams); // ''
+ * console.log(emptyParams.passProps);    // ''
+ * // No imports registered for this case
+ * ```
+ *
+ * @example Integration in component generation
+ * ```typescript
+ * class ReactComponentGenerator {
+ *   generateDetailComponent(operation: OasOperation) {
+ *     const pathParams = new ReactRouterPathParams({
+ *       context: this.context,
+ *       generatorKey: 'react-component',
+ *       operation,
+ *       destinationPath: this.getDestinationPath(operation)
+ *     });
+ *
+ *     if (pathParams.names.length === 0) {
+ *       // Generate simple component without parameters
+ *       return this.generateSimpleComponent(operation);
+ *     }
+ *
+ *     return `
+ * function ${operation.operationId}() {
+ *   ${pathParams.getParams}
+ *   ${pathParams.assertParams}
+ *
+ *   return (
+ *     <DetailView ${pathParams.passProps} />
+ *   );
+ * }`;
+ *   }
+ * }
+ * ```
+ *
+ * @example Custom parameter validation
+ * ```typescript
+ * class CustomReactRouterParams extends ReactRouterPathParams {
+ *   generateCustomAssertions(paramName: string): string {
+ *     return `
+ * invariant(${paramName}, 'Expected ${paramName} to be defined');
+ * invariant(typeof ${paramName} === 'string', '${paramName} must be a string');
+ * invariant(${paramName}.length > 0, '${paramName} cannot be empty');`;
+ *   }
+ * }
+ * ```
+ */
 class ReactRouterPathParams extends ContentBase_js_1.ContentBase {
+    /**
+     * Creates a new ReactRouterPathParams instance with generated parameter handling code.
+     *
+     * The constructor analyzes the OpenAPI operation to extract path parameters and
+     * generates the necessary React code for parameter extraction, validation, and
+     * prop passing. It automatically registers required imports when parameters are present.
+     *
+     * @param args - Configuration for React Router parameter generation
+     *
+     * @example
+     * ```typescript
+     * const pathParams = new ReactRouterPathParams({
+     *   context: generateContext,
+     *   generatorKey: 'react-params',
+     *   operation: userDetailOperation, // has path '/users/{id}'
+     *   destinationPath: './UserDetail.tsx'
+     * });
+     * ```
+     */
     constructor({ context, operation, generatorKey, destinationPath }) {
         super({ context, generatorKey });
+        /** Generated code for extracting parameters from useParams() */
         Object.defineProperty(this, "getParams", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: ''
         });
+        /** Generated code for runtime parameter assertions */
         Object.defineProperty(this, "assertParams", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: ''
         });
+        /** Generated code for passing parameters as component props */
         Object.defineProperty(this, "passProps", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: ''
         });
+        /** Array of parameter names extracted from the operation path */
         Object.defineProperty(this, "names", {
             enumerable: true,
             configurable: true,
@@ -46,6 +220,15 @@ class ReactRouterPathParams extends ContentBase_js_1.ContentBase {
             });
         }
     }
+    /**
+     * Returns an empty string as this class provides code through its properties.
+     *
+     * The ReactRouterPathParams class doesn't generate output through toString(),
+     * instead providing generated code through the `getParams`, `assertParams`,
+     * and `passProps` properties which can be used directly in template generation.
+     *
+     * @returns Empty string
+     */
     toString() {
         return ``;
     }

package/script/typescript/keyValues.d.ts

@@ -1,3 +1,128 @@
 import type { Stringable } from '../dsl/Stringable.js';
+/**
+ * Converts a properties object into a formatted TypeScript object literal string.
+ *
+ * This utility function takes a record of key-value pairs and generates a properly
+ * formatted TypeScript object literal. It automatically filters out empty values
+ * and handles proper spacing and comma placement. If all properties are empty,
+ * it returns the EMPTY constant instead of an empty object.
+ *
+ * The function is particularly useful for generating TypeScript interface properties,
+ * object type definitions, and literal object expressions in code generation scenarios.
+ *
+ * @param properties - Record of property names to their stringable values
+ * @returns Formatted object literal string or EMPTY if no valid properties
+ *
+ * @example Basic object generation
+ * ```typescript
+ * import { keyValues } from '@skmtc/core';
+ *
+ * const props = {
+ *   name: { toString: () => 'string' },
+ *   age: { toString: () => 'number' },
+ *   email: { toString: () => 'string' }
+ * };
+ *
+ * const result = keyValues(props);
+ * console.log(result);
+ * // {name: string,
+ * // age: number,
+ * // email: string}
+ * ```
+ *
+ * @example With empty values filtered
+ * ```typescript
+ * const propsWithEmpty = {
+ *   name: { toString: () => 'string' },
+ *   description: { toString: () => '' }, // Empty, will be filtered
+ *   age: { toString: () => 'number' },
+ *   notes: { toString: () => 'EMPTY' }   // EMPTY constant, will be filtered
+ * };
+ *
+ * const result = keyValues(propsWithEmpty);
+ * console.log(result);
+ * // {name: string,
+ * // age: number}
+ * ```
+ *
+ * @example All empty properties
+ * ```typescript
+ * const emptyProps = {
+ *   description: { toString: () => '' },
+ *   notes: { toString: () => 'EMPTY' }
+ * };
+ *
+ * const result = keyValues(emptyProps);
+ * console.log(result === EMPTY); // true
+ * ```
+ *
+ * @example TypeScript interface generation
+ * ```typescript
+ * class InterfaceGenerator {
+ *   generateInterface(name: string, properties: Record<string, Stringable>) {
+ *     const propsString = keyValues(properties);
+ *
+ *     if (propsString === EMPTY) {
+ *       return `interface ${name} {}`;
+ *     }
+ *
+ *     return `interface ${name} ${propsString}`;
+ *   }
+ * }
+ *
+ * const generator = new InterfaceGenerator();
+ * const userInterface = generator.generateInterface('User', {
+ *   id: { toString: () => 'string' },
+ *   name: { toString: () => 'string' },
+ *   age: { toString: () => 'number' }
+ * });
+ *
+ * console.log(userInterface);
+ * // interface User {id: string,
+ * // name: string,
+ * // age: number}
+ * ```
+ *
+ * @example Object literal generation
+ * ```typescript
+ * function generateObjectLiteral(values: Record<string, string>) {
+ *   const stringableValues = Object.fromEntries(
+ *     Object.entries(values).map(([k, v]) => [k, { toString: () => `'${v}'` }])
+ *   );
+ *
+ *   const result = keyValues(stringableValues);
+ *   return result === EMPTY ? '{}' : result;
+ * }
+ *
+ * const config = generateObjectLiteral({
+ *   apiUrl: 'https://api.example.com',
+ *   timeout: '5000'
+ * });
+ *
+ * console.log(config);
+ * // {apiUrl: 'https://api.example.com',
+ * // timeout: '5000'}
+ * ```
+ *
+ * @example Conditional property inclusion
+ * ```typescript
+ * class ConditionalGenerator {
+ *   generateObjectType(fields: Array<{name: string, type: string, optional?: boolean}>) {
+ *     const properties: Record<string, Stringable> = {};
+ *
+ *     fields.forEach(field => {
+ *       if (field.type) { // Only include fields with types
+ *         const optionalMarker = field.optional ? '?' : '';
+ *         properties[field.name] = {
+ *           toString: () => `${optionalMarker}: ${field.type}`
+ *         };
+ *       }
+ *     });
+ *
+ *     return keyValues(properties);
+ *   }
+ * }
+ * ```
+ */
 export declare const keyValues: (properties: Record<string, Stringable>) => string;
 //# sourceMappingURL=keyValues.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"keyValues.d.ts","sourceRoot":"","sources":["../../src/typescript/keyValues.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAGtD,eAAO,MAAM,SAAS,GAAI,YAAY,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,KAAG,MAUlE,CAAA"}
+{"version":3,"file":"keyValues.d.ts","sourceRoot":"","sources":["../../src/typescript/keyValues.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4HG;AACH,eAAO,MAAM,SAAS,GAAI,YAAY,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,KAAG,MAUlE,CAAA"}

package/script/typescript/keyValues.js

@@ -2,7 +2,131 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.keyValues = void 0;
 const constants_js_1 = require("../dsl/constants.js");
-// Filter out properties with falsy or EMPTY values and return as joined string
+/**
+ * Converts a properties object into a formatted TypeScript object literal string.
+ *
+ * This utility function takes a record of key-value pairs and generates a properly
+ * formatted TypeScript object literal. It automatically filters out empty values
+ * and handles proper spacing and comma placement. If all properties are empty,
+ * it returns the EMPTY constant instead of an empty object.
+ *
+ * The function is particularly useful for generating TypeScript interface properties,
+ * object type definitions, and literal object expressions in code generation scenarios.
+ *
+ * @param properties - Record of property names to their stringable values
+ * @returns Formatted object literal string or EMPTY if no valid properties
+ *
+ * @example Basic object generation
+ * ```typescript
+ * import { keyValues } from '@skmtc/core';
+ *
+ * const props = {
+ *   name: { toString: () => 'string' },
+ *   age: { toString: () => 'number' },
+ *   email: { toString: () => 'string' }
+ * };
+ *
+ * const result = keyValues(props);
+ * console.log(result);
+ * // {name: string,
+ * // age: number,
+ * // email: string}
+ * ```
+ *
+ * @example With empty values filtered
+ * ```typescript
+ * const propsWithEmpty = {
+ *   name: { toString: () => 'string' },
+ *   description: { toString: () => '' }, // Empty, will be filtered
+ *   age: { toString: () => 'number' },
+ *   notes: { toString: () => 'EMPTY' }   // EMPTY constant, will be filtered
+ * };
+ *
+ * const result = keyValues(propsWithEmpty);
+ * console.log(result);
+ * // {name: string,
+ * // age: number}
+ * ```
+ *
+ * @example All empty properties
+ * ```typescript
+ * const emptyProps = {
+ *   description: { toString: () => '' },
+ *   notes: { toString: () => 'EMPTY' }
+ * };
+ *
+ * const result = keyValues(emptyProps);
+ * console.log(result === EMPTY); // true
+ * ```
+ *
+ * @example TypeScript interface generation
+ * ```typescript
+ * class InterfaceGenerator {
+ *   generateInterface(name: string, properties: Record<string, Stringable>) {
+ *     const propsString = keyValues(properties);
+ *
+ *     if (propsString === EMPTY) {
+ *       return `interface ${name} {}`;
+ *     }
+ *
+ *     return `interface ${name} ${propsString}`;
+ *   }
+ * }
+ *
+ * const generator = new InterfaceGenerator();
+ * const userInterface = generator.generateInterface('User', {
+ *   id: { toString: () => 'string' },
+ *   name: { toString: () => 'string' },
+ *   age: { toString: () => 'number' }
+ * });
+ *
+ * console.log(userInterface);
+ * // interface User {id: string,
+ * // name: string,
+ * // age: number}
+ * ```
+ *
+ * @example Object literal generation
+ * ```typescript
+ * function generateObjectLiteral(values: Record<string, string>) {
+ *   const stringableValues = Object.fromEntries(
+ *     Object.entries(values).map(([k, v]) => [k, { toString: () => `'${v}'` }])
+ *   );
+ *
+ *   const result = keyValues(stringableValues);
+ *   return result === EMPTY ? '{}' : result;
+ * }
+ *
+ * const config = generateObjectLiteral({
+ *   apiUrl: 'https://api.example.com',
+ *   timeout: '5000'
+ * });
+ *
+ * console.log(config);
+ * // {apiUrl: 'https://api.example.com',
+ * // timeout: '5000'}
+ * ```
+ *
+ * @example Conditional property inclusion
+ * ```typescript
+ * class ConditionalGenerator {
+ *   generateObjectType(fields: Array<{name: string, type: string, optional?: boolean}>) {
+ *     const properties: Record<string, Stringable> = {};
+ *
+ *     fields.forEach(field => {
+ *       if (field.type) { // Only include fields with types
+ *         const optionalMarker = field.optional ? '?' : '';
+ *         properties[field.name] = {
+ *           toString: () => `${optionalMarker}: ${field.type}`
+ *         };
+ *       }
+ *     });
+ *
+ *     return keyValues(properties);
+ *   }
+ * }
+ * ```
+ */
 const keyValues = (properties) => {
     const filteredEntries = Object.entries(properties)
         .map(([key, value]) => {