@skmtc/core 0.0.793 → 0.0.795

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]) => {

package/script/typescript/toPathParams.d.ts

@@ -1,2 +1,181 @@
+/**
+ * Converts OpenAPI path parameters to React Router path parameter syntax.
+ *
+ * This utility function transforms OpenAPI path syntax (using curly braces) into
+ * React Router path parameter syntax (using colon prefix). It's essential for
+ * generating React Router route definitions and other routing configurations
+ * that need to match URL parameters.
+ *
+ * The function performs a simple but crucial transformation that enables
+ * OpenAPI-defined paths to be used directly in React Router route definitions,
+ * maintaining the same parameter names while adapting the syntax.
+ *
+ * @param path - OpenAPI path string with {parameter} syntax
+ * @returns React Router path string with :parameter syntax
+ *
+ * @example Basic path parameter conversion
+ * ```typescript
+ * import { toPathParams } from '@skmtc/core';
+ *
+ * const routePath = toPathParams('/users/{id}/posts/{postId}');
+ * console.log(routePath); // '/users/:id/posts/:postId'
+ * ```
+ *
+ * @example React Router route generation
+ * ```typescript
+ * import { Routes, Route } from 'react-router-dom';
+ *
+ * const apiPaths = [
+ *   '/users/{id}',
+ *   '/users/{id}/posts/{postId}',
+ *   '/organizations/{orgId}/members/{userId}'
+ * ];
+ *
+ * const routePaths = apiPaths.map(toPathParams);
+ * // [
+ * //   '/users/:id',
+ * //   '/users/:id/posts/:postId',
+ * //   '/organizations/:orgId/members/:userId'
+ * // ]
+ *
+ * function App() {
+ *   return (
+ *     <Routes>
+ *       {routePaths.map(path => (
+ *         <Route key={path} path={path} element={<DetailView />} />
+ *       ))}
+ *     </Routes>
+ *   );
+ * }
+ * ```
+ *
+ * @example Express.js route generation
+ * ```typescript
+ * import express from 'express';
+ *
+ * class RouteGenerator {
+ *   generateExpressRoutes(openApiPaths: string[]) {
+ *     const router = express.Router();
+ *
+ *     openApiPaths.forEach(path => {
+ *       const expressPath = toPathParams(path);
+ *
+ *       router.get(expressPath, (req, res) => {
+ *         // Handler logic using req.params
+ *         res.json({ path: expressPath, params: req.params });
+ *       });
+ *     });
+ *
+ *     return router;
+ *   }
+ * }
+ *
+ * const generator = new RouteGenerator();
+ * const router = generator.generateExpressRoutes([
+ *   '/api/users/{userId}',
+ *   '/api/users/{userId}/orders/{orderId}'
+ * ]);
+ * // Generates routes for:
+ * // '/api/users/:userId'
+ * // '/api/users/:userId/orders/:orderId'
+ * ```
+ *
+ * @example Route configuration generation
+ * ```typescript
+ * interface RouteConfig {
+ *   path: string;
+ *   component: string;
+ *   exact?: boolean;
+ * }
+ *
+ * function generateRouteConfigs(apiEndpoints: Array<{path: string, component: string}>): RouteConfig[] {
+ *   return apiEndpoints.map(endpoint => ({
+ *     path: toPathParams(endpoint.path),
+ *     component: endpoint.component,
+ *     exact: true
+ *   }));
+ * }
+ *
+ * const routeConfigs = generateRouteConfigs([
+ *   { path: '/users/{id}', component: 'UserDetail' },
+ *   { path: '/users/{id}/settings', component: 'UserSettings' },
+ *   { path: '/projects/{projectId}/tasks/{taskId}', component: 'TaskDetail' }
+ * ]);
+ *
+ * console.log(routeConfigs);
+ * // [
+ * //   { path: '/users/:id', component: 'UserDetail', exact: true },
+ * //   { path: '/users/:id/settings', component: 'UserSettings', exact: true },
+ * //   { path: '/projects/:projectId/tasks/:taskId', component: 'TaskDetail', exact: true }
+ * // ]
+ * ```
+ *
+ * @example Next.js dynamic route generation
+ * ```typescript
+ * class NextJsRouteGenerator {
+ *   generateFileStructure(openApiPaths: string[]) {
+ *     return openApiPaths.map(path => {
+ *       // Convert to Next.js file-based routing syntax
+ *       const routerPath = toPathParams(path);
+ *       const fileName = routerPath
+ *         .replace(/:/g, '[') // :id becomes [id
+ *         .replace(/\/\[([^\]]+)/g, '/[$1]') // [id becomes [id]
+ *         .replace(/^\//,'') // Remove leading slash
+ *         + '.tsx';
+ *
+ *       return {
+ *         originalPath: path,
+ *         routerPath,
+ *         fileName
+ *       };
+ *     });
+ *   }
+ * }
+ *
+ * const generator = new NextJsRouteGenerator();
+ * const structure = generator.generateFileStructure([
+ *   '/users/{id}',
+ *   '/posts/{slug}/comments/{commentId}'
+ * ]);
+ *
+ * console.log(structure);
+ * // [
+ * //   {
+ * //     originalPath: '/users/{id}',
+ * //     routerPath: '/users/:id',
+ * //     fileName: 'users/[id].tsx'
+ * //   },
+ * //   {
+ * //     originalPath: '/posts/{slug}/comments/{commentId}',
+ * //     routerPath: '/posts/:slug/comments/:commentId',
+ * //     fileName: 'posts/[slug]/comments/[commentId].tsx'
+ * //   }
+ * // ]
+ * ```
+ *
+ * @example Integration with path matching
+ * ```typescript
+ * import { matchPath } from 'react-router-dom';
+ *
+ * class PathMatcher {
+ *   createMatcher(openApiPath: string) {
+ *     const routerPath = toPathParams(openApiPath);
+ *
+ *     return (pathname: string) => {
+ *       return matchPath(
+ *         { path: routerPath, exact: true },
+ *         pathname
+ *       );
+ *     };
+ *   }
+ * }
+ *
+ * const matcher = new PathMatcher();
+ * const userMatcher = matcher.createMatcher('/users/{id}');
+ *
+ * const match = userMatcher('/users/123');
+ * console.log(match?.params); // { id: '123' }
+ * ```
+ */
 export declare const toPathParams: (path: string) => string;
 //# sourceMappingURL=toPathParams.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"toPathParams.d.ts","sourceRoot":"","sources":["../../src/typescript/toPathParams.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAE3C,CAAA"}
+{"version":3,"file":"toPathParams.d.ts","sourceRoot":"","sources":["../../src/typescript/toPathParams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkLG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAE3C,CAAA"}

package/script/typescript/toPathParams.js

@@ -1,6 +1,185 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toPathParams = void 0;
+/**
+ * Converts OpenAPI path parameters to React Router path parameter syntax.
+ *
+ * This utility function transforms OpenAPI path syntax (using curly braces) into
+ * React Router path parameter syntax (using colon prefix). It's essential for
+ * generating React Router route definitions and other routing configurations
+ * that need to match URL parameters.
+ *
+ * The function performs a simple but crucial transformation that enables
+ * OpenAPI-defined paths to be used directly in React Router route definitions,
+ * maintaining the same parameter names while adapting the syntax.
+ *
+ * @param path - OpenAPI path string with {parameter} syntax
+ * @returns React Router path string with :parameter syntax
+ *
+ * @example Basic path parameter conversion
+ * ```typescript
+ * import { toPathParams } from '@skmtc/core';
+ *
+ * const routePath = toPathParams('/users/{id}/posts/{postId}');
+ * console.log(routePath); // '/users/:id/posts/:postId'
+ * ```
+ *
+ * @example React Router route generation
+ * ```typescript
+ * import { Routes, Route } from 'react-router-dom';
+ *
+ * const apiPaths = [
+ *   '/users/{id}',
+ *   '/users/{id}/posts/{postId}',
+ *   '/organizations/{orgId}/members/{userId}'
+ * ];
+ *
+ * const routePaths = apiPaths.map(toPathParams);
+ * // [
+ * //   '/users/:id',
+ * //   '/users/:id/posts/:postId',
+ * //   '/organizations/:orgId/members/:userId'
+ * // ]
+ *
+ * function App() {
+ *   return (
+ *     <Routes>
+ *       {routePaths.map(path => (
+ *         <Route key={path} path={path} element={<DetailView />} />
+ *       ))}
+ *     </Routes>
+ *   );
+ * }
+ * ```
+ *
+ * @example Express.js route generation
+ * ```typescript
+ * import express from 'express';
+ *
+ * class RouteGenerator {
+ *   generateExpressRoutes(openApiPaths: string[]) {
+ *     const router = express.Router();
+ *
+ *     openApiPaths.forEach(path => {
+ *       const expressPath = toPathParams(path);
+ *
+ *       router.get(expressPath, (req, res) => {
+ *         // Handler logic using req.params
+ *         res.json({ path: expressPath, params: req.params });
+ *       });
+ *     });
+ *
+ *     return router;
+ *   }
+ * }
+ *
+ * const generator = new RouteGenerator();
+ * const router = generator.generateExpressRoutes([
+ *   '/api/users/{userId}',
+ *   '/api/users/{userId}/orders/{orderId}'
+ * ]);
+ * // Generates routes for:
+ * // '/api/users/:userId'
+ * // '/api/users/:userId/orders/:orderId'
+ * ```
+ *
+ * @example Route configuration generation
+ * ```typescript
+ * interface RouteConfig {
+ *   path: string;
+ *   component: string;
+ *   exact?: boolean;
+ * }
+ *
+ * function generateRouteConfigs(apiEndpoints: Array<{path: string, component: string}>): RouteConfig[] {
+ *   return apiEndpoints.map(endpoint => ({
+ *     path: toPathParams(endpoint.path),
+ *     component: endpoint.component,
+ *     exact: true
+ *   }));
+ * }
+ *
+ * const routeConfigs = generateRouteConfigs([
+ *   { path: '/users/{id}', component: 'UserDetail' },
+ *   { path: '/users/{id}/settings', component: 'UserSettings' },
+ *   { path: '/projects/{projectId}/tasks/{taskId}', component: 'TaskDetail' }
+ * ]);
+ *
+ * console.log(routeConfigs);
+ * // [
+ * //   { path: '/users/:id', component: 'UserDetail', exact: true },
+ * //   { path: '/users/:id/settings', component: 'UserSettings', exact: true },
+ * //   { path: '/projects/:projectId/tasks/:taskId', component: 'TaskDetail', exact: true }
+ * // ]
+ * ```
+ *
+ * @example Next.js dynamic route generation
+ * ```typescript
+ * class NextJsRouteGenerator {
+ *   generateFileStructure(openApiPaths: string[]) {
+ *     return openApiPaths.map(path => {
+ *       // Convert to Next.js file-based routing syntax
+ *       const routerPath = toPathParams(path);
+ *       const fileName = routerPath
+ *         .replace(/:/g, '[') // :id becomes [id
+ *         .replace(/\/\[([^\]]+)/g, '/[$1]') // [id becomes [id]
+ *         .replace(/^\//,'') // Remove leading slash
+ *         + '.tsx';
+ *
+ *       return {
+ *         originalPath: path,
+ *         routerPath,
+ *         fileName
+ *       };
+ *     });
+ *   }
+ * }
+ *
+ * const generator = new NextJsRouteGenerator();
+ * const structure = generator.generateFileStructure([
+ *   '/users/{id}',
+ *   '/posts/{slug}/comments/{commentId}'
+ * ]);
+ *
+ * console.log(structure);
+ * // [
+ * //   {
+ * //     originalPath: '/users/{id}',
+ * //     routerPath: '/users/:id',
+ * //     fileName: 'users/[id].tsx'
+ * //   },
+ * //   {
+ * //     originalPath: '/posts/{slug}/comments/{commentId}',
+ * //     routerPath: '/posts/:slug/comments/:commentId',
+ * //     fileName: 'posts/[slug]/comments/[commentId].tsx'
+ * //   }
+ * // ]
+ * ```
+ *
+ * @example Integration with path matching
+ * ```typescript
+ * import { matchPath } from 'react-router-dom';
+ *
+ * class PathMatcher {
+ *   createMatcher(openApiPath: string) {
+ *     const routerPath = toPathParams(openApiPath);
+ *
+ *     return (pathname: string) => {
+ *       return matchPath(
+ *         { path: routerPath, exact: true },
+ *         pathname
+ *       );
+ *     };
+ *   }
+ * }
+ *
+ * const matcher = new PathMatcher();
+ * const userMatcher = matcher.createMatcher('/users/{id}');
+ *
+ * const match = userMatcher('/users/123');
+ * console.log(match?.params); // { id: '123' }
+ * ```
+ */
 const toPathParams = (path) => {
     return `${path.replaceAll(/{([^}]*)}/g, ':$1')}`;
 };