@skmtc/core 0.0.785 → 0.0.786

package/script/oas/object/Object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../../src/oas/object/Object.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../../src/oas/object/Object.ts"],"names":[],"mappings":"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"}

package/script/oas/object/Object.js

@@ -4,11 +4,109 @@ exports.OasObject = void 0;
 require("../../_dnt.polyfills.js");
 const ts_pattern_1 = require("ts-pattern");
 /**
- * Object representing an object and/or a record in the OpenAPI Specification.
+ * Represents an object schema in the OpenAPI Specification.
  *
- * Objects have fixed, named fields. Records have any number of fields that do not have predefined names.
+ * `OasObject` handles both:
+ * - **Objects**: Types with fixed, named properties (like TypeScript interfaces)
+ * - **Records**: Types with dynamic keys and consistent value types (like TypeScript Record<string, T>)
+ *
+ * This class provides comprehensive support for object validation constraints,
+ * property management, and JSON Schema conversion. It supports nullable types
+ * through generic type parameters and handles complex property relationships.
+ *
+ * ## Key Features
+ *
+ * - **Property Management**: Add/remove properties with automatic required field handling
+ * - **Type Safety**: Generic nullable type support with proper TypeScript inference
+ * - **Validation**: Min/max properties, additional properties, and enum constraints
+ * - **JSON Schema**: Convert to standard JSON Schema format for validation
+ * - **Immutability**: All mutations return new instances (functional style)
+ *
+ * @template Nullable - Whether the object value itself can be null
+ *
+ * @example Basic object schema
+ * ```typescript
+ * import { OasObject } from '@skmtc/core';
+ *
+ * const userObject = new OasObject({
+ *   title: 'User',
+ *   description: 'A user in the system',
+ *   properties: {
+ *     id: new OasString({ title: 'User ID' }),
+ *     name: new OasString({ title: 'Full Name' }),
+ *     email: new OasString({ format: 'email' })
+ *   },
+ *   required: ['id', 'name'],
+ *   additionalProperties: false
+ * });
+ * ```
+ *
+ * @example Dynamic property management
+ * ```typescript
+ * // Start with empty object
+ * let schema = OasObject.empty();
+ *
+ * // Add properties dynamically
+ * schema = schema.addProperty({
+ *   name: 'id',
+ *   schema: new OasString(),
+ *   required: true
+ * });
+ *
+ * schema = schema.addProperty({
+ *   name: 'metadata',
+ *   schema: new OasObject({ additionalProperties: true }),
+ *   required: false
+ * });
+ *
+ * // Remove a property
+ * schema = schema.removeProperty('metadata');
+ * ```
+ *
+ * @example Record-style object (additional properties)
+ * ```typescript
+ * const recordObject = new OasObject({
+ *   title: 'StringMap',
+ *   description: 'A map of string keys to string values',
+ *   additionalProperties: new OasString(), // Any string key -> string value
+ *   minProperties: 1 // At least one property required
+ * });
+ *
+ * // This allows: { [key: string]: string }
+ * ```
+ *
+ * @example Nullable object support
+ * ```typescript
+ * const nullableUser = new OasObject<true>({
+ *   nullable: true,
+ *   properties: {
+ *     name: new OasString()
+ *   },
+ *   default: null // Can have null default when nullable
+ * });
+ *
+ * // This represents: { name: string } | null
+ * ```
  */
 class OasObject {
+    /**
+     * Creates a new OasObject instance.
+     *
+     * @param fields - Object configuration fields
+     *
+     * @example
+     * ```typescript
+     * const userSchema = new OasObject({
+     *   title: 'User',
+     *   properties: {
+     *     id: new OasString({ title: 'ID' }),
+     *     name: new OasString({ title: 'Name' })
+     *   },
+     *   required: ['id'],
+     *   additionalProperties: false
+     * });
+     * ```
+     */
     constructor(fields = {}) {
         /**
          * Object is part the 'schema' set which is used
@@ -161,7 +259,32 @@ class OasObject {
         this.deprecated = fields.deprecated;
         this.enums = fields.enums;
     }
-    /** Creates new empty OasObject */
+    /**
+     * Creates a new empty OasObject with no properties.
+     *
+     * This factory method creates a non-nullable object with empty properties
+     * and required arrays, useful as a starting point for dynamic object building.
+     *
+     * @returns A new empty OasObject instance
+     *
+     * @example
+     * ```typescript
+     * // Start with empty object and build up
+     * let schema = OasObject.empty();
+     *
+     * schema = schema.addProperty({
+     *   name: 'id',
+     *   schema: new OasString(),
+     *   required: true
+     * });
+     *
+     * schema = schema.addProperty({
+     *   name: 'name',
+     *   schema: new OasString(),
+     *   required: true
+     * });
+     * ```
+     */
     static empty() {
         return new OasObject({
             nullable: false,
@@ -172,11 +295,47 @@ class OasObject {
     /**
      * Adds a new property to the object.
      *
-     * @param {AddPropertyArgs} args - The arguments for adding a property.
-     * @param {string} args.name - The name of the property to add.
-     * @param {OasSchema | OasRef<'schema'> | CustomValue | undefined} args.schema - The schema of the property to add.
-     * @param {boolean} args.required - Whether the property is required.
-     * @returns {OasObject} A new OasObject with the added property.
+     * This method returns a new OasObject instance with the added property,
+     * following an immutable pattern. If the property is marked as required,
+     * it will be added to the required array.
+     *
+     * @param args - Property addition arguments
+     * @param args.name - The name of the property to add
+     * @param args.schema - The schema definition for the property
+     * @param args.required - Whether the property should be required (default: false)
+     * @returns A new OasObject with the added property
+     *
+     * @example Adding a simple property
+     * ```typescript
+     * const original = OasObject.empty();
+     * const withName = original.addProperty({
+     *   name: 'username',
+     *   schema: new OasString({ minLength: 3 }),
+     *   required: true
+     * });
+     *
+     * console.log(withName.required); // ['username']
+     * ```
+     *
+     * @example Chaining property additions
+     * ```typescript
+     * const userSchema = OasObject.empty()
+     *   .addProperty({
+     *     name: 'id',
+     *     schema: new OasInteger(),
+     *     required: true
+     *   })
+     *   .addProperty({
+     *     name: 'email',
+     *     schema: new OasString({ format: 'email' }),
+     *     required: true
+     *   })
+     *   .addProperty({
+     *     name: 'age',
+     *     schema: new OasInteger({ minimum: 0 }),
+     *     required: false
+     *   });
+     * ```
      */
     addProperty({ name, schema, required }) {
         if (!schema) {
@@ -198,8 +357,31 @@ class OasObject {
     /**
      * Removes a property from the object.
      *
-     * @param {string} name - The name of the property to remove.
-     * @returns {OasObject} A new OasObject with the removed property.
+     * This method returns a new OasObject instance with the specified property
+     * removed. If the property was required, it will also be removed from the
+     * required array. If the property doesn't exist, returns the same instance.
+     *
+     * @param name - The name of the property to remove
+     * @returns A new OasObject with the property removed, or the same instance if property doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const userSchema = new OasObject({
+     *   properties: {
+     *     id: new OasString(),
+     *     name: new OasString(),
+     *     email: new OasString(),
+     *     temporaryField: new OasString()
+     *   },
+     *   required: ['id', 'name', 'temporaryField']
+     * });
+     *
+     * // Remove temporary field
+     * const cleanedSchema = userSchema.removeProperty('temporaryField');
+     *
+     * console.log(cleanedSchema.required); // ['id', 'name']
+     * console.log('temporaryField' in cleanedSchema.properties); // false
+     * ```
      */
     removeProperty(name) {
         if (!this.properties?.[name]) {
@@ -225,6 +407,43 @@ class OasObject {
     resolveOnce() {
         return this;
     }
+    /**
+     * Converts the OasObject to a standard JSON Schema object.
+     *
+     * This method serializes the object to the JSON Schema format used in
+     * OpenAPI specifications. It handles property conversion, additional
+     * properties rules, and validation constraints.
+     *
+     * @param options - Conversion options for handling references and context
+     * @returns A JSON Schema representation of the object
+     *
+     * @example
+     * ```typescript
+     * const userObject = new OasObject({
+     *   title: 'User',
+     *   properties: {
+     *     id: new OasString(),
+     *     name: new OasString()
+     *   },
+     *   required: ['id'],
+     *   additionalProperties: false
+     * });
+     *
+     * const jsonSchema = userObject.toJsonSchema({ refContext: new Map() });
+     *
+     * console.log(jsonSchema);
+     * // {
+     * //   type: 'object',
+     * //   title: 'User',
+     * //   properties: {
+     * //     id: { type: 'string' },
+     * //     name: { type: 'string' }
+     * //   },
+     * //   required: ['id'],
+     * //   additionalProperties: false
+     * // }
+     * ```
+     */
     toJsonSchema(options) {
         return {
             type: 'object',

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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"}