@skmtc/core 0.0.785 → 0.0.787

package/script/types/GeneratorKeys.d.ts

@@ -3,48 +3,384 @@ import type { OasOperation } from '../oas/operation/Operation.js';
 import type { Brand } from './Brand.js';
 import type { RefName } from './RefName.js';
 import { type Method } from './Method.js';
+/**
+ * Template literal type for operation generator keys before branding.
+ * Format: `generatorId|path|method` (e.g., 'api-client|/users|get')
+ */
 export type NakedOperationGeneratorKey = `${string}|${string}|${Method}`;
+/**
+ * Template literal type for model generator keys before branding.
+ * Format: `generatorId|refName` (e.g., 'typescript-models|User')
+ */
 export type NakedModelGeneratorKey = `${string}|${string}`;
+/**
+ * Branded type for operation generator keys.
+ *
+ * Operation generator keys uniquely identify generators that process
+ * OpenAPI operations (HTTP methods on API paths). The key encodes
+ * the generator ID, API path, and HTTP method.
+ */
 export type OperationGeneratorKey = Brand<NakedOperationGeneratorKey, 'OperationGeneratorKey'>;
+/**
+ * Branded type for model generator keys.
+ *
+ * Model generator keys uniquely identify generators that process
+ * OpenAPI schema models. The key encodes the generator ID and
+ * the schema reference name.
+ */
 export type ModelGeneratorKey = Brand<NakedModelGeneratorKey, 'ModelGeneratorKey'>;
+/**
+ * Branded type for generator-only keys.
+ *
+ * Generator-only keys identify generators that don't process specific
+ * operations or models, but generate global artifacts like configuration
+ * files, base classes, or utility modules.
+ */
 export type GeneratorOnlyKey = Brand<string, 'GeneratorOnlyKey'>;
+/**
+ * Union type of all possible generator key types.
+ *
+ * Generator keys serve as unique identifiers for different types of
+ * code generators in the SKMTC system. They enable tracking, caching,
+ * and dependency management between generated artifacts.
+ *
+ * @example
+ * ```typescript
+ * // Operation generator key
+ * const opKey: GeneratorKey = toOperationGeneratorKey({
+ *   generatorId: 'api-client',
+ *   path: '/users/{id}',
+ *   method: 'get'
+ * });
+ *
+ * // Model generator key
+ * const modelKey: GeneratorKey = toModelGeneratorKey({
+ *   generatorId: 'typescript-types',
+ *   refName: 'User'
+ * });
+ *
+ * // Generator-only key
+ * const globalKey: GeneratorKey = toGeneratorOnlyKey({
+ *   generatorId: 'api-config'
+ * });
+ * ```
+ */
 export type GeneratorKey = OperationGeneratorKey | ModelGeneratorKey | GeneratorOnlyKey;
+/**
+ * Arguments for {@link toOperationGeneratorKey}.
+ *
+ * Can specify operation details directly or provide an OasOperation
+ * object from which the path and method will be extracted.
+ */
 type ToOperationGeneratorKeyArgs = {
+    /** Unique identifier for the generator */
     generatorId: string;
+    /** API path (e.g., '/users/{id}') */
     path: string;
+    /** HTTP method */
     method: Method;
 } | {
+    /** Unique identifier for the generator */
     generatorId: string;
+    /** OpenAPI operation object containing path and method */
     operation: OasOperation;
 };
+/**
+ * Creates an operation generator key from generator ID and operation details.
+ *
+ * Operation generator keys uniquely identify generators processing specific
+ * API operations. The key format is: `generatorId|path|method`
+ *
+ * @param args - Operation generator key arguments
+ * @returns A branded OperationGeneratorKey
+ *
+ * @example With explicit path and method
+ * ```typescript
+ * const key = toOperationGeneratorKey({
+ *   generatorId: 'api-client',
+ *   path: '/users/{id}',
+ *   method: 'get'
+ * });
+ * // Result: 'api-client|/users/{id}|get' (branded)
+ * ```
+ *
+ * @example With OasOperation object
+ * ```typescript
+ * const operation = new OasOperation({
+ *   path: '/posts',
+ *   method: 'post',
+ *   // ... other operation details
+ * });
+ *
+ * const key = toOperationGeneratorKey({
+ *   generatorId: 'rest-client',
+ *   operation
+ * });
+ * // Result: 'rest-client|/posts|post' (branded)
+ * ```
+ */
 export declare const toOperationGeneratorKey: ({ generatorId, ...rest }: ToOperationGeneratorKeyArgs) => OperationGeneratorKey;
+/**
+ * Arguments for {@link toModelGeneratorKey}.
+ */
 type ToModelGeneratorKeyArgs = {
+    /** Unique identifier for the generator */
     generatorId: string;
+    /** Reference name of the schema model */
     refName: RefName;
 };
+/**
+ * Creates a model generator key from generator ID and schema reference name.
+ *
+ * Model generator keys uniquely identify generators processing specific
+ * OpenAPI schema models. The key format is: `generatorId|refName`
+ *
+ * @param args - Model generator key arguments
+ * @returns A branded ModelGeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = toModelGeneratorKey({
+ *   generatorId: 'typescript-interfaces',
+ *   refName: 'User'
+ * });
+ * // Result: 'typescript-interfaces|User' (branded)
+ *
+ * const validationKey = toModelGeneratorKey({
+ *   generatorId: 'zod-schemas',
+ *   refName: 'CreateUserRequest'
+ * });
+ * // Result: 'zod-schemas|CreateUserRequest' (branded)
+ * ```
+ */
 export declare const toModelGeneratorKey: ({ generatorId, refName }: ToModelGeneratorKeyArgs) => ModelGeneratorKey;
+/**
+ * Arguments for {@link toGeneratorOnlyKey}.
+ */
 type ToGeneratorOnlyKeyArgs = {
+    /** Unique identifier for the generator */
     generatorId: string;
 };
+/**
+ * Creates a generator-only key for global/utility generators.
+ *
+ * Generator-only keys identify generators that produce artifacts not tied
+ * to specific operations or models, such as configuration files, base classes,
+ * utilities, or documentation.
+ *
+ * @param args - Generator-only key arguments
+ * @returns A branded GeneratorOnlyKey
+ *
+ * @example
+ * ```typescript
+ * const configKey = toGeneratorOnlyKey({
+ *   generatorId: 'api-config'
+ * });
+ * // Result: 'api-config' (branded)
+ *
+ * const utilsKey = toGeneratorOnlyKey({
+ *   generatorId: 'common-utilities'
+ * });
+ * // Result: 'common-utilities' (branded)
+ * ```
+ */
 export declare const toGeneratorOnlyKey: ({ generatorId }: ToGeneratorOnlyKeyArgs) => GeneratorOnlyKey;
+/**
+ * Type guard to check if a value is a valid GeneratorKey.
+ *
+ * This function validates that the argument is one of the three
+ * generator key types: operation, model, or generator-only.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid GeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'api-client|/users|get';
+ *
+ * if (isGeneratorKey(key)) {
+ *   // key is now typed as GeneratorKey
+ *   const generatorId = toGeneratorId(key);
+ *   console.log(generatorId); // 'api-client'
+ * }
+ * ```
+ */
 export declare const isGeneratorKey: (arg: unknown) => arg is GeneratorKey;
+/**
+ * Type guard to check if a value is a valid OperationGeneratorKey.
+ *
+ * Validates that the argument is a string with the correct format:
+ * `generatorId|path|method` where each part is non-empty and method
+ * is a valid HTTP method.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid OperationGeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'api-client|/users/{id}|get';
+ *
+ * if (isOperationGeneratorKey(key)) {
+ *   // key is now typed as OperationGeneratorKey
+ *   const obj = fromGeneratorKey(key);
+ *   console.log(obj.type);        // 'operation'
+ *   console.log(obj.generatorId); // 'api-client'
+ *   console.log(obj.path);        // '/users/{id}'
+ *   console.log(obj.method);      // 'get'
+ * }
+ * ```
+ */
 export declare const isOperationGeneratorKey: (arg: unknown) => arg is OperationGeneratorKey;
+/**
+ * Type guard to check if a value is a valid ModelGeneratorKey.
+ *
+ * Validates that the argument is a string with the correct format:
+ * `generatorId|refName` where both parts are non-empty strings.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid ModelGeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'zod-schemas|User';
+ *
+ * if (isModelGeneratorKey(key)) {
+ *   // key is now typed as ModelGeneratorKey
+ *   const obj = fromGeneratorKey(key);
+ *   console.log(obj.type);        // 'model'
+ *   console.log(obj.generatorId); // 'zod-schemas'
+ *   console.log(obj.refName);     // 'User'
+ * }
+ * ```
+ */
 export declare const isModelGeneratorKey: (arg: unknown) => arg is ModelGeneratorKey;
+/**
+ * Type guard to check if a value is a valid GeneratorOnlyKey.
+ *
+ * Validates that the argument is a non-empty string. Generator-only keys
+ * are simple strings containing just the generator ID.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid GeneratorOnlyKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'api-config';
+ *
+ * if (isGeneratorOnlyKey(key)) {
+ *   // key is now typed as GeneratorOnlyKey
+ *   const obj = fromGeneratorKey(key);
+ *   console.log(obj.type);        // 'generator-only'
+ *   console.log(obj.generatorId); // 'api-config'
+ * }
+ * ```
+ */
 export declare const isGeneratorOnlyKey: (arg: unknown) => arg is GeneratorOnlyKey;
+/**
+ * Extracts the generator ID from any type of GeneratorKey.
+ *
+ * This utility function parses the generator key to extract just the
+ * generator identifier, regardless of the key type. For operation and
+ * model keys, it extracts the first part before the pipe. For generator-only
+ * keys, it returns the entire key since it's just the generator ID.
+ *
+ * @param generatorKey - Any type of generator key
+ * @returns The generator ID string
+ *
+ * @example
+ * ```typescript
+ * const opKey = toOperationGeneratorKey({
+ *   generatorId: 'api-client',
+ *   path: '/users',
+ *   method: 'get'
+ * });
+ * console.log(toGeneratorId(opKey)); // 'api-client'
+ *
+ * const modelKey = toModelGeneratorKey({
+ *   generatorId: 'typescript-types',
+ *   refName: 'User'
+ * });
+ * console.log(toGeneratorId(modelKey)); // 'typescript-types'
+ *
+ * const globalKey = toGeneratorOnlyKey({
+ *   generatorId: 'utilities'
+ * });
+ * console.log(toGeneratorId(globalKey)); // 'utilities'
+ * ```
+ */
 export declare const toGeneratorId: (generatorKey: GeneratorKey) => string;
+/**
+ * Object representation of a parsed GeneratorKey.
+ *
+ * This discriminated union type represents the parsed components of any
+ * generator key, making it easier to work with key data in a structured way.
+ * The `type` field discriminates between the three key types.
+ */
 export type GeneratorKeyObject = {
+    /** Discriminator for operation generator keys */
     type: 'operation';
+    /** Generator identifier */
     generatorId: string;
+    /** API path */
     path: string;
+    /** HTTP method */
     method: Method;
 } | {
+    /** Discriminator for model generator keys */
     type: 'model';
+    /** Generator identifier */
     generatorId: string;
+    /** Schema reference name */
     refName: string;
 } | {
+    /** Discriminator for generator-only keys */
     type: 'generator-only';
+    /** Generator identifier */
     generatorId: string;
 };
+/**
+ * Parses a GeneratorKey into its structured object representation.
+ *
+ * This function decomposes any generator key into a structured object
+ * with discriminated union types, making it easier to work with the
+ * key components in a type-safe manner.
+ *
+ * @param generatorKey - Any type of generator key to parse
+ * @returns Parsed generator key object with discriminated type
+ *
+ * @example Operation key parsing
+ * ```typescript
+ * const opKey = 'api-client|/users/{id}|get' as OperationGeneratorKey;
+ * const parsed = fromGeneratorKey(opKey);
+ *
+ * if (parsed.type === 'operation') {
+ *   console.log(parsed.generatorId); // 'api-client'
+ *   console.log(parsed.path);        // '/users/{id}'
+ *   console.log(parsed.method);      // 'get'
+ * }
+ * ```
+ *
+ * @example Model key parsing
+ * ```typescript
+ * const modelKey = 'zod-schemas|User' as ModelGeneratorKey;
+ * const parsed = fromGeneratorKey(modelKey);
+ *
+ * if (parsed.type === 'model') {
+ *   console.log(parsed.generatorId); // 'zod-schemas'
+ *   console.log(parsed.refName);     // 'User'
+ * }
+ * ```
+ *
+ * @example Generator-only key parsing
+ * ```typescript
+ * const globalKey = 'utilities' as GeneratorOnlyKey;
+ * const parsed = fromGeneratorKey(globalKey);
+ *
+ * if (parsed.type === 'generator-only') {
+ *   console.log(parsed.generatorId); // 'utilities'
+ * }
+ * ```
+ */
 export declare const fromGeneratorKey: (generatorKey: GeneratorKey) => GeneratorKeyObject;
 export {};
 //# sourceMappingURL=GeneratorKeys.d.ts.map

package/script/types/GeneratorKeys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GeneratorKeys.d.ts","sourceRoot":"","sources":["../../src/types/GeneratorKeys.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AACjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,KAAK,MAAM,EAAY,MAAM,aAAa,CAAA;AAEnD,MAAM,MAAM,0BAA0B,GAAG,GAAG,MAAM,IAAI,MAAM,IAAI,MAAM,EAAE,CAAA;AAExE,MAAM,MAAM,sBAAsB,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,CAAA;AAE1D,MAAM,MAAM,qBAAqB,GAAG,KAAK,CACvC,0BAA0B,EAC1B,uBAAuB,CACxB,CAAA;AAED,MAAM,MAAM,iBAAiB,GAAG,KAAK,CACnC,sBAAsB,EACtB,mBAAmB,CACpB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;AAEhE,MAAM,MAAM,YAAY,GACpB,qBAAqB,GACrB,iBAAiB,GACjB,gBAAgB,CAAA;AAEpB,KAAK,2BAA2B,GAC5B;IACE,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf,GACD;IACE,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,YAAY,CAAA;CACxB,CAAA;AAEL,eAAO,MAAM,uBAAuB,GAAI,0BAGrC,2BAA2B,KAAG,qBAMhC,CAAA;AAED,KAAK,uBAAuB,GAAG;IAC7B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,0BAGjC,uBAAuB,KAAG,iBAI5B,CAAA;AAED,KAAK,sBAAsB,GAAG;IAC5B,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,iBAEhC,sBAAsB,KAAG,gBAI3B,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,YAMpD,CAAA;AAED,eAAO,MAAM,uBAAuB,GAClC,KAAK,OAAO,KACX,GAAG,IAAI,qBA0BT,CAAA;AAED,eAAO,MAAM,mBAAmB,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,iBAsBzD,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,gBAMxD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,cAAc,YAAY,KAAG,MAU1D,CAAA;AAED,MAAM,MAAM,kBAAkB,GAC1B;IACE,IAAI,EAAE,WAAW,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf,GACD;IACE,IAAI,EAAE,OAAO,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;CAChB,GACD;IACE,IAAI,EAAE,gBAAgB,CAAA;IACtB,WAAW,EAAE,MAAM,CAAA;CACpB,CAAA;AAEL,eAAO,MAAM,gBAAgB,GAC3B,cAAc,YAAY,KACzB,kBAYF,CAAA"}
+{"version":3,"file":"GeneratorKeys.d.ts","sourceRoot":"","sources":["../../src/types/GeneratorKeys.ts"],"names":[],"mappings":"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"}

package/script/types/GeneratorKeys.js

@@ -3,28 +3,153 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.fromGeneratorKey = exports.toGeneratorId = exports.isGeneratorOnlyKey = exports.isModelGeneratorKey = exports.isOperationGeneratorKey = exports.isGeneratorKey = exports.toGeneratorOnlyKey = exports.toModelGeneratorKey = exports.toOperationGeneratorKey = void 0;
 require("../_dnt.polyfills.js");
 const Method_js_1 = require("./Method.js");
+/**
+ * Creates an operation generator key from generator ID and operation details.
+ *
+ * Operation generator keys uniquely identify generators processing specific
+ * API operations. The key format is: `generatorId|path|method`
+ *
+ * @param args - Operation generator key arguments
+ * @returns A branded OperationGeneratorKey
+ *
+ * @example With explicit path and method
+ * ```typescript
+ * const key = toOperationGeneratorKey({
+ *   generatorId: 'api-client',
+ *   path: '/users/{id}',
+ *   method: 'get'
+ * });
+ * // Result: 'api-client|/users/{id}|get' (branded)
+ * ```
+ *
+ * @example With OasOperation object
+ * ```typescript
+ * const operation = new OasOperation({
+ *   path: '/posts',
+ *   method: 'post',
+ *   // ... other operation details
+ * });
+ *
+ * const key = toOperationGeneratorKey({
+ *   generatorId: 'rest-client',
+ *   operation
+ * });
+ * // Result: 'rest-client|/posts|post' (branded)
+ * ```
+ */
 const toOperationGeneratorKey = ({ generatorId, ...rest }) => {
     const { path, method } = 'operation' in rest ? rest.operation : rest;
     const nakedKey = `${generatorId}|${path}|${method}`;
     return nakedKey;
 };
 exports.toOperationGeneratorKey = toOperationGeneratorKey;
+/**
+ * Creates a model generator key from generator ID and schema reference name.
+ *
+ * Model generator keys uniquely identify generators processing specific
+ * OpenAPI schema models. The key format is: `generatorId|refName`
+ *
+ * @param args - Model generator key arguments
+ * @returns A branded ModelGeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = toModelGeneratorKey({
+ *   generatorId: 'typescript-interfaces',
+ *   refName: 'User'
+ * });
+ * // Result: 'typescript-interfaces|User' (branded)
+ *
+ * const validationKey = toModelGeneratorKey({
+ *   generatorId: 'zod-schemas',
+ *   refName: 'CreateUserRequest'
+ * });
+ * // Result: 'zod-schemas|CreateUserRequest' (branded)
+ * ```
+ */
 const toModelGeneratorKey = ({ generatorId, refName }) => {
     const nakedKey = `${generatorId}|${refName}`;
     return nakedKey;
 };
 exports.toModelGeneratorKey = toModelGeneratorKey;
+/**
+ * Creates a generator-only key for global/utility generators.
+ *
+ * Generator-only keys identify generators that produce artifacts not tied
+ * to specific operations or models, such as configuration files, base classes,
+ * utilities, or documentation.
+ *
+ * @param args - Generator-only key arguments
+ * @returns A branded GeneratorOnlyKey
+ *
+ * @example
+ * ```typescript
+ * const configKey = toGeneratorOnlyKey({
+ *   generatorId: 'api-config'
+ * });
+ * // Result: 'api-config' (branded)
+ *
+ * const utilsKey = toGeneratorOnlyKey({
+ *   generatorId: 'common-utilities'
+ * });
+ * // Result: 'common-utilities' (branded)
+ * ```
+ */
 const toGeneratorOnlyKey = ({ generatorId }) => {
     const nakedKey = `${generatorId}`;
     return nakedKey;
 };
 exports.toGeneratorOnlyKey = toGeneratorOnlyKey;
+/**
+ * Type guard to check if a value is a valid GeneratorKey.
+ *
+ * This function validates that the argument is one of the three
+ * generator key types: operation, model, or generator-only.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid GeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'api-client|/users|get';
+ *
+ * if (isGeneratorKey(key)) {
+ *   // key is now typed as GeneratorKey
+ *   const generatorId = toGeneratorId(key);
+ *   console.log(generatorId); // 'api-client'
+ * }
+ * ```
+ */
 const isGeneratorKey = (arg) => {
     return ((0, exports.isModelGeneratorKey)(arg) ||
         (0, exports.isOperationGeneratorKey)(arg) ||
         (0, exports.isGeneratorOnlyKey)(arg));
 };
 exports.isGeneratorKey = isGeneratorKey;
+/**
+ * Type guard to check if a value is a valid OperationGeneratorKey.
+ *
+ * Validates that the argument is a string with the correct format:
+ * `generatorId|path|method` where each part is non-empty and method
+ * is a valid HTTP method.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid OperationGeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'api-client|/users/{id}|get';
+ *
+ * if (isOperationGeneratorKey(key)) {
+ *   // key is now typed as OperationGeneratorKey
+ *   const obj = fromGeneratorKey(key);
+ *   console.log(obj.type);        // 'operation'
+ *   console.log(obj.generatorId); // 'api-client'
+ *   console.log(obj.path);        // '/users/{id}'
+ *   console.log(obj.method);      // 'get'
+ * }
+ * ```
+ */
 const isOperationGeneratorKey = (arg) => {
     if (typeof arg !== 'string') {
         return false;
@@ -46,6 +171,28 @@ const isOperationGeneratorKey = (arg) => {
     return true;
 };
 exports.isOperationGeneratorKey = isOperationGeneratorKey;
+/**
+ * Type guard to check if a value is a valid ModelGeneratorKey.
+ *
+ * Validates that the argument is a string with the correct format:
+ * `generatorId|refName` where both parts are non-empty strings.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid ModelGeneratorKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'zod-schemas|User';
+ *
+ * if (isModelGeneratorKey(key)) {
+ *   // key is now typed as ModelGeneratorKey
+ *   const obj = fromGeneratorKey(key);
+ *   console.log(obj.type);        // 'model'
+ *   console.log(obj.generatorId); // 'zod-schemas'
+ *   console.log(obj.refName);     // 'User'
+ * }
+ * ```
+ */
 const isModelGeneratorKey = (arg) => {
     if (typeof arg !== 'string') {
         return false;
@@ -64,6 +211,27 @@ const isModelGeneratorKey = (arg) => {
     return true;
 };
 exports.isModelGeneratorKey = isModelGeneratorKey;
+/**
+ * Type guard to check if a value is a valid GeneratorOnlyKey.
+ *
+ * Validates that the argument is a non-empty string. Generator-only keys
+ * are simple strings containing just the generator ID.
+ *
+ * @param arg - Value to check
+ * @returns True if the value is a valid GeneratorOnlyKey
+ *
+ * @example
+ * ```typescript
+ * const key = 'api-config';
+ *
+ * if (isGeneratorOnlyKey(key)) {
+ *   // key is now typed as GeneratorOnlyKey
+ *   const obj = fromGeneratorKey(key);
+ *   console.log(obj.type);        // 'generator-only'
+ *   console.log(obj.generatorId); // 'api-config'
+ * }
+ * ```
+ */
 const isGeneratorOnlyKey = (arg) => {
     if (typeof arg !== 'string') {
         return false;
@@ -71,6 +239,38 @@ const isGeneratorOnlyKey = (arg) => {
     return Boolean(arg.length);
 };
 exports.isGeneratorOnlyKey = isGeneratorOnlyKey;
+/**
+ * Extracts the generator ID from any type of GeneratorKey.
+ *
+ * This utility function parses the generator key to extract just the
+ * generator identifier, regardless of the key type. For operation and
+ * model keys, it extracts the first part before the pipe. For generator-only
+ * keys, it returns the entire key since it's just the generator ID.
+ *
+ * @param generatorKey - Any type of generator key
+ * @returns The generator ID string
+ *
+ * @example
+ * ```typescript
+ * const opKey = toOperationGeneratorKey({
+ *   generatorId: 'api-client',
+ *   path: '/users',
+ *   method: 'get'
+ * });
+ * console.log(toGeneratorId(opKey)); // 'api-client'
+ *
+ * const modelKey = toModelGeneratorKey({
+ *   generatorId: 'typescript-types',
+ *   refName: 'User'
+ * });
+ * console.log(toGeneratorId(modelKey)); // 'typescript-types'
+ *
+ * const globalKey = toGeneratorOnlyKey({
+ *   generatorId: 'utilities'
+ * });
+ * console.log(toGeneratorId(globalKey)); // 'utilities'
+ * ```
+ */
 const toGeneratorId = (generatorKey) => {
     if ((0, exports.isOperationGeneratorKey)(generatorKey)) {
         return generatorKey.split('|')[0];
@@ -81,6 +281,49 @@ const toGeneratorId = (generatorKey) => {
     return generatorKey;
 };
 exports.toGeneratorId = toGeneratorId;
+/**
+ * Parses a GeneratorKey into its structured object representation.
+ *
+ * This function decomposes any generator key into a structured object
+ * with discriminated union types, making it easier to work with the
+ * key components in a type-safe manner.
+ *
+ * @param generatorKey - Any type of generator key to parse
+ * @returns Parsed generator key object with discriminated type
+ *
+ * @example Operation key parsing
+ * ```typescript
+ * const opKey = 'api-client|/users/{id}|get' as OperationGeneratorKey;
+ * const parsed = fromGeneratorKey(opKey);
+ *
+ * if (parsed.type === 'operation') {
+ *   console.log(parsed.generatorId); // 'api-client'
+ *   console.log(parsed.path);        // '/users/{id}'
+ *   console.log(parsed.method);      // 'get'
+ * }
+ * ```
+ *
+ * @example Model key parsing
+ * ```typescript
+ * const modelKey = 'zod-schemas|User' as ModelGeneratorKey;
+ * const parsed = fromGeneratorKey(modelKey);
+ *
+ * if (parsed.type === 'model') {
+ *   console.log(parsed.generatorId); // 'zod-schemas'
+ *   console.log(parsed.refName);     // 'User'
+ * }
+ * ```
+ *
+ * @example Generator-only key parsing
+ * ```typescript
+ * const globalKey = 'utilities' as GeneratorOnlyKey;
+ * const parsed = fromGeneratorKey(globalKey);
+ *
+ * if (parsed.type === 'generator-only') {
+ *   console.log(parsed.generatorId); // 'utilities'
+ * }
+ * ```
+ */
 const fromGeneratorKey = (generatorKey) => {
     if ((0, exports.isOperationGeneratorKey)(generatorKey)) {
         const [generatorId, path, method] = generatorKey.split('|');