@skmtc/core 0.0.792 → 0.0.793

package/script/helpers/isEmpty.js

@@ -1,6 +1,68 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isEmpty = void 0;
+/**
+ * Checks whether a record/object is empty (has no enumerable properties).
+ *
+ * This utility function determines if an object contains any enumerable properties
+ * by checking the length of its keys array. It's commonly used throughout the
+ * SKMTC codebase to validate whether generated objects, configurations, or
+ * other data structures contain meaningful content.
+ *
+ * @param value - The record/object to check for emptiness
+ * @returns `true` if the object has no enumerable properties, `false` otherwise
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { isEmpty } from '@skmtc/core';
+ *
+ * console.log(isEmpty({})); // true
+ * console.log(isEmpty({ name: 'John' })); // false
+ * console.log(isEmpty({ a: undefined })); // false (undefined is still a property)
+ * ```
+ *
+ * @example In conditional logic
+ * ```typescript
+ * const userPreferences = loadUserPreferences();
+ *
+ * if (isEmpty(userPreferences)) {
+ *   // Apply default settings
+ *   applyDefaults();
+ * } else {
+ *   // Use user's custom settings
+ *   applyUserSettings(userPreferences);
+ * }
+ * ```
+ *
+ * @example Filtering collections
+ * ```typescript
+ * const configurations = [
+ *   { api: 'v1', settings: {} },
+ *   { api: 'v2', settings: { timeout: 5000 } },
+ *   { api: 'v3', settings: {} }
+ * ];
+ *
+ * const validConfigs = configurations.filter(config => !isEmpty(config.settings));
+ * console.log(validConfigs); // [{ api: 'v2', settings: { timeout: 5000 } }]
+ * ```
+ *
+ * @example Code generation usage
+ * ```typescript
+ * class Generator {
+ *   generateInterface(properties: Record<string, string>) {
+ *     if (isEmpty(properties)) {
+ *       return 'interface EmptyInterface {}';
+ *     }
+ *
+ *     const props = Object.entries(properties)
+ *       .map(([name, type]) => `  ${name}: ${type};`)
+ *       .join('\n');
+ *
+ *     return `interface GeneratedInterface {\n${props}\n}`;
+ *   }
+ * }
+ * ```
+ */
 require("../_dnt.polyfills.js");
 const isEmpty = (value) => {
     return Object.keys(value).length === 0;

package/script/helpers/isImported.d.ts

@@ -1,2 +1,82 @@
+/**
+ * Determines whether two file paths represent different locations (import required).
+ *
+ * This utility function normalizes two file paths and compares them to determine
+ * if they represent different files. It's used throughout the SKMTC system to
+ * decide when import statements are needed - if two paths are different, an
+ * import is required to access symbols from one file in another.
+ *
+ * The function handles path normalization to ensure consistent comparisons
+ * across different operating systems and path formats (handling './' vs absolute
+ * paths, different separators, etc.).
+ *
+ * @param pathOne - The first file path to compare
+ * @param pathTwo - The second file path to compare
+ * @returns `true` if the paths are different (import needed), `false` if they're the same file
+ *
+ * @example Basic path comparison
+ * ```typescript
+ * import { isImported } from '@skmtc/core';
+ *
+ * // Same file, no import needed
+ * console.log(isImported('./src/user.ts', './src/user.ts')); // false
+ *
+ * // Different files, import needed
+ * console.log(isImported('./src/user.ts', './src/product.ts')); // true
+ * ```
+ *
+ * @example Path normalization handling
+ * ```typescript
+ * // These all represent the same file after normalization
+ * console.log(isImported('./src/user.ts', 'src/user.ts')); // false
+ * console.log(isImported('src/./user.ts', 'src/user.ts')); // false
+ * console.log(isImported('src/models/../user.ts', 'src/user.ts')); // false
+ * ```
+ *
+ * @example Usage in import decision logic
+ * ```typescript
+ * class FileGenerator {
+ *   addImportIfNeeded(
+ *     sourceFile: string,
+ *     targetFile: string,
+ *     importName: string
+ *   ) {
+ *     if (isImported(sourceFile, targetFile)) {
+ *       // Files are different, add import
+ *       this.addImport(sourceFile, targetFile, importName);
+ *       console.log(`Added import: ${importName} from ${targetFile}`);
+ *     } else {
+ *       // Same file, no import needed
+ *       console.log(`No import needed - same file: ${sourceFile}`);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Cross-platform path handling
+ * ```typescript
+ * // Works consistently across platforms
+ * const windowsPath = 'src\\models\\user.ts';
+ * const unixPath = 'src/models/user.ts';
+ *
+ * console.log(isImported(windowsPath, unixPath)); // false (same file)
+ * ```
+ *
+ * @example In generator context
+ * ```typescript
+ * class ModelGenerator {
+ *   generateModel(modelPath: string, referencePath: string) {
+ *     const definition = this.createModelDefinition();
+ *
+ *     if (isImported(modelPath, referencePath)) {
+ *       // Need to import the referenced model
+ *       definition.addImport(referencePath, 'ReferencedModel');
+ *     }
+ *
+ *     return definition;
+ *   }
+ * }
+ * ```
+ */
 export declare const isImported: (pathOne: string, pathTwo: string) => boolean;
 //# sourceMappingURL=isImported.d.ts.map

package/script/helpers/isImported.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"isImported.d.ts","sourceRoot":"","sources":["../../src/helpers/isImported.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,KAAG,OAE7D,CAAA"}
+{"version":3,"file":"isImported.d.ts","sourceRoot":"","sources":["../../src/helpers/isImported.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,SAAS,MAAM,KAAG,OAE7D,CAAA"}

package/script/helpers/isImported.js

@@ -2,6 +2,86 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isImported = void 0;
 const normalize_js_1 = require("../deps/jsr.io/@std/path/1.1.2/normalize.js");
+/**
+ * Determines whether two file paths represent different locations (import required).
+ *
+ * This utility function normalizes two file paths and compares them to determine
+ * if they represent different files. It's used throughout the SKMTC system to
+ * decide when import statements are needed - if two paths are different, an
+ * import is required to access symbols from one file in another.
+ *
+ * The function handles path normalization to ensure consistent comparisons
+ * across different operating systems and path formats (handling './' vs absolute
+ * paths, different separators, etc.).
+ *
+ * @param pathOne - The first file path to compare
+ * @param pathTwo - The second file path to compare
+ * @returns `true` if the paths are different (import needed), `false` if they're the same file
+ *
+ * @example Basic path comparison
+ * ```typescript
+ * import { isImported } from '@skmtc/core';
+ *
+ * // Same file, no import needed
+ * console.log(isImported('./src/user.ts', './src/user.ts')); // false
+ *
+ * // Different files, import needed
+ * console.log(isImported('./src/user.ts', './src/product.ts')); // true
+ * ```
+ *
+ * @example Path normalization handling
+ * ```typescript
+ * // These all represent the same file after normalization
+ * console.log(isImported('./src/user.ts', 'src/user.ts')); // false
+ * console.log(isImported('src/./user.ts', 'src/user.ts')); // false
+ * console.log(isImported('src/models/../user.ts', 'src/user.ts')); // false
+ * ```
+ *
+ * @example Usage in import decision logic
+ * ```typescript
+ * class FileGenerator {
+ *   addImportIfNeeded(
+ *     sourceFile: string,
+ *     targetFile: string,
+ *     importName: string
+ *   ) {
+ *     if (isImported(sourceFile, targetFile)) {
+ *       // Files are different, add import
+ *       this.addImport(sourceFile, targetFile, importName);
+ *       console.log(`Added import: ${importName} from ${targetFile}`);
+ *     } else {
+ *       // Same file, no import needed
+ *       console.log(`No import needed - same file: ${sourceFile}`);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Cross-platform path handling
+ * ```typescript
+ * // Works consistently across platforms
+ * const windowsPath = 'src\\models\\user.ts';
+ * const unixPath = 'src/models/user.ts';
+ *
+ * console.log(isImported(windowsPath, unixPath)); // false (same file)
+ * ```
+ *
+ * @example In generator context
+ * ```typescript
+ * class ModelGenerator {
+ *   generateModel(modelPath: string, referencePath: string) {
+ *     const definition = this.createModelDefinition();
+ *
+ *     if (isImported(modelPath, referencePath)) {
+ *       // Need to import the referenced model
+ *       definition.addImport(referencePath, 'ReferencedModel');
+ *     }
+ *
+ *     return definition;
+ *   }
+ * }
+ * ```
+ */
 const isImported = (pathOne, pathTwo) => {
     return (0, normalize_js_1.normalize)(pathOne) !== (0, normalize_js_1.normalize)(pathTwo);
 };

package/script/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/script/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/script/helpers/parseModuleName.js

@@ -1,6 +1,159 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseModuleName = void 0;
+/**
+ * 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}`;
+ *   }
+ * }
+ * ```
+ */
 const parseModuleName = (moduleName) => {
     const result = {
         scheme: null,