@skmtc/core 0.0.791 → 0.0.793

package/esm/helpers/naming.js

@@ -1,22 +1,86 @@
 import { camelCase } from 'lodash-es';
 import { match } from 'ts-pattern';
+/**
+ * Determines the endpoint type based on HTTP method.
+ *
+ * @param operation - The OpenAPI operation to analyze
+ * @returns 'query' for GET operations, 'mutation' for all others
+ *
+ * @example
+ * ```typescript
+ * const getOp = new OasOperation({ method: 'get', path: '/users' });
+ * console.log(toEndpointType(getOp)); // 'query'
+ *
+ * const postOp = new OasOperation({ method: 'post', path: '/users' });
+ * console.log(toEndpointType(postOp)); // 'mutation'
+ * ```
+ */
 export const toEndpointType = (operation) => {
     return operation.method === 'get' ? 'query' : 'mutation';
 };
-/** generates endpoint name in the `camelCase{method}Api{path}` format */
+/**
+ * Generates endpoint name in the `camelCase{method}Api{path}` format.
+ *
+ * @param operation - The OpenAPI operation
+ * @returns Camel-cased endpoint name
+ *
+ * @example
+ * ```typescript
+ * const op = new OasOperation({ method: 'post', path: '/users/{id}/profile' });
+ * console.log(toEndpointName(op)); // 'createApiUsersIdProfile'
+ * ```
+ */
 export const toEndpointName = (operation) => {
     const { path, method } = operation;
     const verb = toMethodVerb(method);
     return camelCase(`${verb}Api${path}`);
 };
+/**
+ * Generates response type name for an operation.
+ *
+ * @param operation - The OpenAPI operation
+ * @returns Response type name with 'Response' suffix
+ *
+ * @example
+ * ```typescript
+ * const op = new OasOperation({ method: 'get', path: '/users' });
+ * console.log(toResponseName(op)); // 'getApiUsersResponse'
+ * ```
+ */
 export const toResponseName = (operation) => {
     const operationName = toEndpointName(operation);
     return `${operationName}Response`;
 };
+/**
+ * Generates arguments type name for an operation.
+ *
+ * @param operation - The OpenAPI operation
+ * @returns Arguments type name with 'Args' suffix
+ *
+ * @example
+ * ```typescript
+ * const op = new OasOperation({ method: 'put', path: '/users/{id}' });
+ * console.log(toArgsName(op)); // 'updateApiUsersIdArgs'
+ * ```
+ */
 export const toArgsName = (operation) => {
     const operationName = toEndpointName(operation);
     return `${operationName}Args`;
 };
+/**
+ * Converts HTTP method to a descriptive verb.
+ *
+ * @param method - HTTP method
+ * @returns Descriptive verb for the method
+ *
+ * @example
+ * ```typescript
+ * console.log(toMethodVerb('post')); // 'Create'
+ * console.log(toMethodVerb('put'));  // 'Update'
+ * console.log(toMethodVerb('get'));  // 'get'
+ * console.log(toMethodVerb('delete')); // 'delete'
+ * ```
+ */
 export const toMethodVerb = (method) => {
     return match(method)
         .with('post', () => 'Create')

package/esm/helpers/parseModuleName.d.ts

@@ -1,8 +1,183 @@
+/**
+ * Represents the parsed components of a module name.
+ *
+ * This type breaks down a module name into its constituent parts,
+ * supporting various formats used in different package managers
+ * and registries (npm, JSR, Deno, etc.).
+ *
+ * @example
+ * ```typescript
+ * // For 'jsr:@std/path@1.0.0'
+ * const parsed: ParsedModuleName = {
+ *   scheme: 'jsr',
+ *   scopeName: '@std',
+ *   packageName: 'path',
+ *   version: '1.0.0'
+ * };
+ * ```
+ */
 export type ParsedModuleName = {
+    /** The module scheme (e.g., 'npm', 'jsr', 'https') */
     scheme: string | null;
+    /** The scope name for scoped packages (e.g., '@std', '@company') */
     scopeName: string | null;
+    /** The package name (the main identifier) */
     packageName: string;
+    /** The version specifier (e.g., '1.0.0', '^2.3.4') */
     version: string | null;
 };
+/**
+ * Parses a module name string into its component parts.
+ *
+ * This utility function decomposes module names from various formats into
+ * structured components, handling schemes, scopes, versions, and package names.
+ * It supports formats used by npm, JSR, Deno, and other package managers.
+ *
+ * The parser handles complex module name patterns including:
+ * - Scheme prefixes (jsr:, npm:, https:)
+ * - Scoped packages (@scope/package)
+ * - Version specifiers (@version)
+ * - Combinations of the above
+ *
+ * @param moduleName - The module name string to parse
+ * @returns Parsed components of the module name
+ *
+ * @example Basic package names
+ * ```typescript
+ * import { parseModuleName } from '@skmtc/core';
+ *
+ * // Simple package name
+ * const simple = parseModuleName('lodash');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: null,
+ * //   packageName: 'lodash',
+ * //   version: null
+ * // }
+ *
+ * // Package with version
+ * const versioned = parseModuleName('lodash@4.17.21');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: null,
+ * //   packageName: 'lodash',
+ * //   version: '4.17.21'
+ * // }
+ * ```
+ *
+ * @example Scoped packages
+ * ```typescript
+ * // Scoped package
+ * const scoped = parseModuleName('@company/utils');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: '@company',
+ * //   packageName: 'utils',
+ * //   version: null
+ * // }
+ *
+ * // Scoped package with version
+ * const scopedVersioned = parseModuleName('@company/utils@2.0.0');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: '@company',
+ * //   packageName: 'utils',
+ * //   version: '2.0.0'
+ * // }
+ * ```
+ *
+ * @example Scheme-prefixed modules
+ * ```typescript
+ * // JSR module
+ * const jsrModule = parseModuleName('jsr:@std/path@1.0.0');
+ * // {
+ * //   scheme: 'jsr',
+ * //   scopeName: '@std',
+ * //   packageName: 'path',
+ * //   version: '1.0.0'
+ * // }
+ *
+ * // npm module with scheme
+ * const npmModule = parseModuleName('npm:lodash@^4.17.0');
+ * // {
+ * //   scheme: 'npm',
+ * //   scopeName: null,
+ * //   packageName: 'lodash',
+ * //   version: '^4.17.0'
+ * // }
+ *
+ * // HTTPS module
+ * const httpsModule = parseModuleName('https:example.com/package@v1.2.3');
+ * // {
+ * //   scheme: 'https',
+ * //   scopeName: null,
+ * //   packageName: 'example.com/package',
+ * //   version: 'v1.2.3'
+ * // }
+ * ```
+ *
+ * @example Complex parsing scenarios
+ * ```typescript
+ * // Multiple levels in package name
+ * const nested = parseModuleName('npm:@babel/plugin-transform-runtime@^7.0.0');
+ * // {
+ * //   scheme: 'npm',
+ * //   scopeName: '@babel',
+ * //   packageName: 'plugin-transform-runtime',
+ * //   version: '^7.0.0'
+ * // }
+ *
+ * // Version ranges and pre-release versions
+ * const prerelease = parseModuleName('jsr:@deno/std@1.0.0-rc.1');
+ * // {
+ * //   scheme: 'jsr',
+ * //   scopeName: '@deno',
+ * //   packageName: 'std',
+ * //   version: '1.0.0-rc.1'
+ * // }
+ * ```
+ *
+ * @example Usage in dependency management
+ * ```typescript
+ * class DependencyManager {
+ *   processDependency(moduleSpec: string) {
+ *     const parsed = parseModuleName(moduleSpec);
+ *
+ *     console.log(`Processing ${parsed.packageName}`);
+ *
+ *     if (parsed.scheme) {
+ *       console.log(`Using ${parsed.scheme} registry`);
+ *     }
+ *
+ *     if (parsed.scopeName) {
+ *       console.log(`Scoped package: ${parsed.scopeName}/${parsed.packageName}`);
+ *     }
+ *
+ *     if (parsed.version) {
+ *       console.log(`Version constraint: ${parsed.version}`);
+ *     }
+ *
+ *     return this.resolvePackage(parsed);
+ *   }
+ * }
+ * ```
+ *
+ * @example Building module URLs
+ * ```typescript
+ * function buildModuleUrl(moduleSpec: string): string {
+ *   const parsed = parseModuleName(moduleSpec);
+ *
+ *   switch (parsed.scheme) {
+ *     case 'jsr':
+ *       return `https://jsr.io/${parsed.scopeName}/${parsed.packageName}`;
+ *     case 'npm':
+ *       const scope = parsed.scopeName ? `${parsed.scopeName}/` : '';
+ *       return `https://npmjs.com/package/${scope}${parsed.packageName}`;
+ *     default:
+ *       return `https://deno.land/x/${parsed.packageName}`;
+ *   }
+ * }
+ * ```
+ */
 export declare const parseModuleName: (moduleName: string) => ParsedModuleName;
 //# sourceMappingURL=parseModuleName.d.ts.map

package/esm/helpers/parseModuleName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parseModuleName.d.ts","sourceRoot":"","sources":["../../src/helpers/parseModuleName.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,YAAY,MAAM,KAAG,gBAgCpD,CAAA"}
+{"version":3,"file":"parseModuleName.d.ts","sourceRoot":"","sources":["../../src/helpers/parseModuleName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,sDAAsD;IACtD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,oEAAoE;IACpE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAA;IACnB,sDAAsD;IACtD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwJG;AACH,eAAO,MAAM,eAAe,GAAI,YAAY,MAAM,KAAG,gBAgCpD,CAAA"}

package/esm/helpers/parseModuleName.js

@@ -1,3 +1,156 @@
+/**
+ * Parses a module name string into its component parts.
+ *
+ * This utility function decomposes module names from various formats into
+ * structured components, handling schemes, scopes, versions, and package names.
+ * It supports formats used by npm, JSR, Deno, and other package managers.
+ *
+ * The parser handles complex module name patterns including:
+ * - Scheme prefixes (jsr:, npm:, https:)
+ * - Scoped packages (@scope/package)
+ * - Version specifiers (@version)
+ * - Combinations of the above
+ *
+ * @param moduleName - The module name string to parse
+ * @returns Parsed components of the module name
+ *
+ * @example Basic package names
+ * ```typescript
+ * import { parseModuleName } from '@skmtc/core';
+ *
+ * // Simple package name
+ * const simple = parseModuleName('lodash');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: null,
+ * //   packageName: 'lodash',
+ * //   version: null
+ * // }
+ *
+ * // Package with version
+ * const versioned = parseModuleName('lodash@4.17.21');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: null,
+ * //   packageName: 'lodash',
+ * //   version: '4.17.21'
+ * // }
+ * ```
+ *
+ * @example Scoped packages
+ * ```typescript
+ * // Scoped package
+ * const scoped = parseModuleName('@company/utils');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: '@company',
+ * //   packageName: 'utils',
+ * //   version: null
+ * // }
+ *
+ * // Scoped package with version
+ * const scopedVersioned = parseModuleName('@company/utils@2.0.0');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: '@company',
+ * //   packageName: 'utils',
+ * //   version: '2.0.0'
+ * // }
+ * ```
+ *
+ * @example Scheme-prefixed modules
+ * ```typescript
+ * // JSR module
+ * const jsrModule = parseModuleName('jsr:@std/path@1.0.0');
+ * // {
+ * //   scheme: 'jsr',
+ * //   scopeName: '@std',
+ * //   packageName: 'path',
+ * //   version: '1.0.0'
+ * // }
+ *
+ * // npm module with scheme
+ * const npmModule = parseModuleName('npm:lodash@^4.17.0');
+ * // {
+ * //   scheme: 'npm',
+ * //   scopeName: null,
+ * //   packageName: 'lodash',
+ * //   version: '^4.17.0'
+ * // }
+ *
+ * // HTTPS module
+ * const httpsModule = parseModuleName('https:example.com/package@v1.2.3');
+ * // {
+ * //   scheme: 'https',
+ * //   scopeName: null,
+ * //   packageName: 'example.com/package',
+ * //   version: 'v1.2.3'
+ * // }
+ * ```
+ *
+ * @example Complex parsing scenarios
+ * ```typescript
+ * // Multiple levels in package name
+ * const nested = parseModuleName('npm:@babel/plugin-transform-runtime@^7.0.0');
+ * // {
+ * //   scheme: 'npm',
+ * //   scopeName: '@babel',
+ * //   packageName: 'plugin-transform-runtime',
+ * //   version: '^7.0.0'
+ * // }
+ *
+ * // Version ranges and pre-release versions
+ * const prerelease = parseModuleName('jsr:@deno/std@1.0.0-rc.1');
+ * // {
+ * //   scheme: 'jsr',
+ * //   scopeName: '@deno',
+ * //   packageName: 'std',
+ * //   version: '1.0.0-rc.1'
+ * // }
+ * ```
+ *
+ * @example Usage in dependency management
+ * ```typescript
+ * class DependencyManager {
+ *   processDependency(moduleSpec: string) {
+ *     const parsed = parseModuleName(moduleSpec);
+ *
+ *     console.log(`Processing ${parsed.packageName}`);
+ *
+ *     if (parsed.scheme) {
+ *       console.log(`Using ${parsed.scheme} registry`);
+ *     }
+ *
+ *     if (parsed.scopeName) {
+ *       console.log(`Scoped package: ${parsed.scopeName}/${parsed.packageName}`);
+ *     }
+ *
+ *     if (parsed.version) {
+ *       console.log(`Version constraint: ${parsed.version}`);
+ *     }
+ *
+ *     return this.resolvePackage(parsed);
+ *   }
+ * }
+ * ```
+ *
+ * @example Building module URLs
+ * ```typescript
+ * function buildModuleUrl(moduleSpec: string): string {
+ *   const parsed = parseModuleName(moduleSpec);
+ *
+ *   switch (parsed.scheme) {
+ *     case 'jsr':
+ *       return `https://jsr.io/${parsed.scopeName}/${parsed.packageName}`;
+ *     case 'npm':
+ *       const scope = parsed.scopeName ? `${parsed.scopeName}/` : '';
+ *       return `https://npmjs.com/package/${scope}${parsed.packageName}`;
+ *     default:
+ *       return `https://deno.land/x/${parsed.packageName}`;
+ *   }
+ * }
+ * ```
+ */
 export const parseModuleName = (moduleName) => {
     const result = {
         scheme: null,

package/esm/helpers/toResolvedArtifactPath.d.ts

@@ -1,8 +1,153 @@
 import "../_dnt.polyfills.js";
+/**
+ * Arguments for resolving artifact file paths.
+ */
 type ToResolvedArtifactPathArgs = {
+    /** The base directory path for resolving relative paths */
     basePath: string | undefined;
+    /** The destination path for the artifact file */
     destinationPath: string;
 };
+/**
+ * Resolves artifact destination paths relative to a base directory.
+ *
+ * This utility function combines a base path with a destination path to create
+ * the final resolved file path for generated artifacts. It handles special path
+ * prefixes (like '@/') and provides sensible defaults when no base path is specified.
+ *
+ * The function is used throughout the rendering pipeline to determine the final
+ * file system locations for generated code artifacts, ensuring consistent path
+ * resolution across different operating systems and deployment scenarios.
+ *
+ * @param args - Path resolution configuration
+ * @param args.basePath - Base directory path (defaults to './' if undefined)
+ * @param args.destinationPath - Destination path for the artifact
+ * @returns The resolved absolute or relative path for the artifact
+ *
+ * @example Basic path resolution
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core';
+ *
+ * // With explicit base path
+ * const resolved1 = toResolvedArtifactPath({
+ *   basePath: './src/generated',
+ *   destinationPath: 'models/User.ts'
+ * });
+ * console.log(resolved1); // './src/generated/models/User.ts'
+ *
+ * // With undefined base path (uses default)
+ * const resolved2 = toResolvedArtifactPath({
+ *   basePath: undefined,
+ *   destinationPath: 'types.ts'
+ * });
+ * console.log(resolved2); // './types.ts'
+ * ```
+ *
+ * @example Special path prefix handling
+ * ```typescript
+ * // '@/' prefix gets stripped and resolved relative to base
+ * const resolved = toResolvedArtifactPath({
+ *   basePath: './output',
+ *   destinationPath: '@/api/models.ts'
+ * });
+ * console.log(resolved); // './output/api/models.ts'
+ *
+ * // Regular paths work normally
+ * const normal = toResolvedArtifactPath({
+ *   basePath: './build',
+ *   destinationPath: 'components/Button.tsx'
+ * });
+ * console.log(normal); // './build/components/Button.tsx'
+ * ```
+ *
+ * @example Cross-platform path resolution
+ * ```typescript
+ * // Works consistently across platforms
+ * const windowsPath = toResolvedArtifactPath({
+ *   basePath: 'C:\\projects\\app\\dist',
+ *   destinationPath: 'utils/helpers.js'
+ * });
+ *
+ * const unixPath = toResolvedArtifactPath({
+ *   basePath: '/home/user/projects/app/dist',
+ *   destinationPath: 'utils/helpers.js'
+ * });
+ * ```
+ *
+ * @example Usage in file generation
+ * ```typescript
+ * class ArtifactWriter {
+ *   writeArtifact(
+ *     content: string,
+ *     destination: string,
+ *     baseDir?: string
+ *   ) {
+ *     const resolvedPath = toResolvedArtifactPath({
+ *       basePath: baseDir,
+ *       destinationPath: destination
+ *     });
+ *
+ *     console.log(`Writing to: ${resolvedPath}`);
+ *     return Deno.writeTextFile(resolvedPath, content);
+ *   }
+ * }
+ *
+ * const writer = new ArtifactWriter();
+ * await writer.writeArtifact(
+ *   'export const greeting = "Hello";',
+ *   '@/constants.ts',
+ *   './src/generated'
+ * );
+ * // Writes to: ./src/generated/constants.ts
+ * ```
+ *
+ * @example Integration with rendering pipeline
+ * ```typescript
+ * class FileRenderer {
+ *   renderFiles(
+ *     files: Map<string, File>,
+ *     outputDir: string
+ *   ): Record<string, string> {
+ *     const artifacts: Record<string, string> = {};
+ *
+ *     for (const [destPath, file] of files) {
+ *       const resolvedPath = toResolvedArtifactPath({
+ *         basePath: outputDir,
+ *         destinationPath: destPath
+ *       });
+ *
+ *       artifacts[resolvedPath] = file.toString();
+ *     }
+ *
+ *     return artifacts;
+ *   }
+ * }
+ * ```
+ *
+ * @example Dynamic base path resolution
+ * ```typescript
+ * function resolveForEnvironment(
+ *   destination: string,
+ *   env: 'development' | 'production'
+ * ): string {
+ *   const basePaths = {
+ *     development: './dev-output',
+ *     production: './dist'
+ *   };
+ *
+ *   return toResolvedArtifactPath({
+ *     basePath: basePaths[env],
+ *     destinationPath: destination
+ *   });
+ * }
+ *
+ * const devPath = resolveForEnvironment('api.ts', 'development');
+ * const prodPath = resolveForEnvironment('api.ts', 'production');
+ *
+ * console.log(devPath);  // './dev-output/api.ts'
+ * console.log(prodPath); // './dist/api.ts'
+ * ```
+ */
 export declare const toResolvedArtifactPath: ({ basePath, destinationPath }: ToResolvedArtifactPathArgs) => string;
 export {};
 //# sourceMappingURL=toResolvedArtifactPath.d.ts.map

package/esm/helpers/toResolvedArtifactPath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toResolvedArtifactPath.d.ts","sourceRoot":"","sources":["../../src/helpers/toResolvedArtifactPath.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B,KAAK,0BAA0B,GAAG;IAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,+BAGpC,0BAA0B,KAAG,MAE/B,CAAA"}
+{"version":3,"file":"toResolvedArtifactPath.d.ts","sourceRoot":"","sources":["../../src/helpers/toResolvedArtifactPath.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAG9B;;GAEG;AACH,KAAK,0BAA0B,GAAG;IAChC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2IG;AACH,eAAO,MAAM,sBAAsB,GAAI,+BAGpC,0BAA0B,KAAG,MAE/B,CAAA"}