@skmtc/core 0.0.793 → 0.0.795

package/script/typescript/toPathTemplate.d.ts

@@ -1,2 +1,116 @@
+/**
+ * Converts OpenAPI path parameters into JavaScript template literal syntax.
+ *
+ * This utility function transforms OpenAPI path syntax (using curly braces) into
+ * JavaScript template literal syntax (using ${} expressions). It's essential for
+ * generating URL builders, API client methods, and other dynamic path construction
+ * code where OpenAPI path parameters need to be interpolated at runtime.
+ *
+ * The function supports both simple parameter substitution and qualified parameter
+ * access (when parameters come from an object property).
+ *
+ * @param path - OpenAPI path string with {parameter} syntax
+ * @param queryArg - Optional object name to qualify parameter access
+ * @returns Template literal string with ${} parameter syntax
+ *
+ * @example Basic path parameter conversion
+ * ```typescript
+ * import { toPathTemplate } from '@skmtc/core';
+ *
+ * const template = toPathTemplate('/users/{id}/posts/{postId}');
+ * console.log(template); // '/users/${id}/posts/${postId}'
+ *
+ * // Usage in generated code:
+ * // const url = `/users/${id}/posts/${postId}`;
+ * ```
+ *
+ * @example With query argument qualification
+ * ```typescript
+ * const template = toPathTemplate('/users/{id}/posts/{postId}', 'params');
+ * console.log(template); // '/users/${params.id}/posts/${params.postId}'
+ *
+ * // Usage in generated code:
+ * // function buildUrl(params: {id: string, postId: string}) {
+ * //   return `/users/${params.id}/posts/${params.postId}`;
+ * // }
+ * ```
+ *
+ * @example API client method generation
+ * ```typescript
+ * class ApiClientGenerator {
+ *   generateMethod(path: string, method: string) {
+ *     const template = toPathTemplate(path, 'args');
+ *
+ *     return `
+ * async ${method}(args: PathParams) {
+ *   const url = \`${template}\`;
+ *   return this.request('${method.toUpperCase()}', url);
+ * }`;
+ *   }
+ * }
+ *
+ * const generator = new ApiClientGenerator();
+ * const method = generator.generateMethod('/users/{userId}/profile', 'getProfile');
+ *
+ * console.log(method);
+ * // async getProfile(args: PathParams) {
+ * //   const url = `/users/${args.userId}/profile`;
+ * //   return this.request('GET', url);
+ * // }
+ * ```
+ *
+ * @example URL builder generation
+ * ```typescript
+ * function generateUrlBuilder(endpoints: Array<{name: string, path: string}>) {
+ *   const builders = endpoints.map(endpoint => {
+ *     const template = toPathTemplate(endpoint.path);
+ *
+ *     return `${endpoint.name}: (${extractParams(endpoint.path)}) => \`${template}\``;
+ *   });
+ *
+ *   return `export const urls = {\n  ${builders.join(',\n  ')}\n};`;
+ * }
+ *
+ * const urlBuilder = generateUrlBuilder([
+ *   { name: 'user', path: '/users/{id}' },
+ *   { name: 'userPosts', path: '/users/{id}/posts/{postId}' }
+ * ]);
+ *
+ * // Generates:
+ * // export const urls = {
+ * //   user: (id) => `/users/${id}`,
+ * //   userPosts: (id, postId) => `/users/${id}/posts/${postId}`
+ * // };
+ * ```
+ *
+ * @example React Router integration
+ * ```typescript
+ * function generateRouteComponent(path: string, componentName: string) {
+ *   const template = toPathTemplate(path, 'params');
+ *
+ *   return `
+ * function ${componentName}() {
+ *   const params = useParams();
+ *   const apiUrl = \`/api${template}\`;
+ *
+ *   // Use apiUrl for data fetching
+ *   return <div>Content for {apiUrl}</div>;
+ * }`;
+ * }
+ * ```
+ *
+ * @example Complex nested parameters
+ * ```typescript
+ * const complexPath = '/organizations/{orgId}/projects/{projectId}/issues/{issueId}/comments/{commentId}';
+ *
+ * const simple = toPathTemplate(complexPath);
+ * console.log(simple);
+ * // '/organizations/${orgId}/projects/${projectId}/issues/${issueId}/comments/${commentId}'
+ *
+ * const qualified = toPathTemplate(complexPath, 'pathParams');
+ * console.log(qualified);
+ * // '/organizations/${pathParams.orgId}/projects/${pathParams.projectId}/issues/${pathParams.issueId}/comments/${pathParams.commentId}'
+ * ```
+ */
 export declare const toPathTemplate: (path: string, queryArg?: string) => string;
 //# sourceMappingURL=toPathTemplate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"toPathTemplate.d.ts","sourceRoot":"","sources":["../../src/typescript/toPathTemplate.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,WAAW,MAAM,KAAG,MAKhE,CAAA"}
+{"version":3,"file":"toPathTemplate.d.ts","sourceRoot":"","sources":["../../src/typescript/toPathTemplate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiHG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,WAAW,MAAM,KAAG,MAKhE,CAAA"}

package/script/typescript/toPathTemplate.js

@@ -1,6 +1,120 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toPathTemplate = void 0;
+/**
+ * Converts OpenAPI path parameters into JavaScript template literal syntax.
+ *
+ * This utility function transforms OpenAPI path syntax (using curly braces) into
+ * JavaScript template literal syntax (using ${} expressions). It's essential for
+ * generating URL builders, API client methods, and other dynamic path construction
+ * code where OpenAPI path parameters need to be interpolated at runtime.
+ *
+ * The function supports both simple parameter substitution and qualified parameter
+ * access (when parameters come from an object property).
+ *
+ * @param path - OpenAPI path string with {parameter} syntax
+ * @param queryArg - Optional object name to qualify parameter access
+ * @returns Template literal string with ${} parameter syntax
+ *
+ * @example Basic path parameter conversion
+ * ```typescript
+ * import { toPathTemplate } from '@skmtc/core';
+ *
+ * const template = toPathTemplate('/users/{id}/posts/{postId}');
+ * console.log(template); // '/users/${id}/posts/${postId}'
+ *
+ * // Usage in generated code:
+ * // const url = `/users/${id}/posts/${postId}`;
+ * ```
+ *
+ * @example With query argument qualification
+ * ```typescript
+ * const template = toPathTemplate('/users/{id}/posts/{postId}', 'params');
+ * console.log(template); // '/users/${params.id}/posts/${params.postId}'
+ *
+ * // Usage in generated code:
+ * // function buildUrl(params: {id: string, postId: string}) {
+ * //   return `/users/${params.id}/posts/${params.postId}`;
+ * // }
+ * ```
+ *
+ * @example API client method generation
+ * ```typescript
+ * class ApiClientGenerator {
+ *   generateMethod(path: string, method: string) {
+ *     const template = toPathTemplate(path, 'args');
+ *
+ *     return `
+ * async ${method}(args: PathParams) {
+ *   const url = \`${template}\`;
+ *   return this.request('${method.toUpperCase()}', url);
+ * }`;
+ *   }
+ * }
+ *
+ * const generator = new ApiClientGenerator();
+ * const method = generator.generateMethod('/users/{userId}/profile', 'getProfile');
+ *
+ * console.log(method);
+ * // async getProfile(args: PathParams) {
+ * //   const url = `/users/${args.userId}/profile`;
+ * //   return this.request('GET', url);
+ * // }
+ * ```
+ *
+ * @example URL builder generation
+ * ```typescript
+ * function generateUrlBuilder(endpoints: Array<{name: string, path: string}>) {
+ *   const builders = endpoints.map(endpoint => {
+ *     const template = toPathTemplate(endpoint.path);
+ *
+ *     return `${endpoint.name}: (${extractParams(endpoint.path)}) => \`${template}\``;
+ *   });
+ *
+ *   return `export const urls = {\n  ${builders.join(',\n  ')}\n};`;
+ * }
+ *
+ * const urlBuilder = generateUrlBuilder([
+ *   { name: 'user', path: '/users/{id}' },
+ *   { name: 'userPosts', path: '/users/{id}/posts/{postId}' }
+ * ]);
+ *
+ * // Generates:
+ * // export const urls = {
+ * //   user: (id) => `/users/${id}`,
+ * //   userPosts: (id, postId) => `/users/${id}/posts/${postId}`
+ * // };
+ * ```
+ *
+ * @example React Router integration
+ * ```typescript
+ * function generateRouteComponent(path: string, componentName: string) {
+ *   const template = toPathTemplate(path, 'params');
+ *
+ *   return `
+ * function ${componentName}() {
+ *   const params = useParams();
+ *   const apiUrl = \`/api${template}\`;
+ *
+ *   // Use apiUrl for data fetching
+ *   return <div>Content for {apiUrl}</div>;
+ * }`;
+ * }
+ * ```
+ *
+ * @example Complex nested parameters
+ * ```typescript
+ * const complexPath = '/organizations/{orgId}/projects/{projectId}/issues/{issueId}/comments/{commentId}';
+ *
+ * const simple = toPathTemplate(complexPath);
+ * console.log(simple);
+ * // '/organizations/${orgId}/projects/${projectId}/issues/${issueId}/comments/${commentId}'
+ *
+ * const qualified = toPathTemplate(complexPath, 'pathParams');
+ * console.log(qualified);
+ * // '/organizations/${pathParams.orgId}/projects/${pathParams.projectId}/issues/${pathParams.issueId}/comments/${pathParams.commentId}'
+ * ```
+ */
 const toPathTemplate = (path, queryArg) => {
     return `${path.replaceAll(/{([^}]*)}/g, queryArg ? '${' + queryArg + '.$1}' : '${$1}')}`;
 };