@skmtc/core 0.0.787 → 0.0.789

package/esm/dsl/JsonFile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"JsonFile.d.ts","sourceRoot":"","sources":["../../src/dsl/JsonFile.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,CAAA;AAED,qBAAa,QAAQ;IACnB,QAAQ,EAAE,MAAM,CAAS;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;gBAEpB,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,YAAY;IAK3C,QAAQ,IAAI,MAAM;CAGnB"}
+{"version":3,"file":"JsonFile.d.ts","sourceRoot":"","sources":["../../src/dsl/JsonFile.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,KAAK,YAAY,GAAG;IAClB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+GG;AACH,qBAAa,QAAQ;IACnB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAS;IAEzB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;IAEZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEhC;;;;;;;;;;;;;;;;;;OAkBG;gBACS,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,YAAY;IAK3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/esm/dsl/JsonFile.js

@@ -1,17 +1,151 @@
+/**
+ * Represents a JSON file in the SKMTC DSL system.
+ *
+ * The `JsonFile` class is used to generate JSON files as part of the code generation
+ * process. It provides a simple interface for creating configuration files, manifests,
+ * package.json files, and other JSON-based artifacts with proper formatting.
+ *
+ * ## Key Features
+ *
+ * - **JSON Formatting**: Automatically formats JSON with 2-space indentation
+ * - **Type Safety**: Accepts any valid JSON-serializable content structure
+ * - **Path Management**: Associates content with specific file paths
+ * - **String Conversion**: Easy integration with file writing systems
+ *
+ * @example Basic JSON file creation
+ * ```typescript
+ * import { JsonFile } from '@skmtc/core';
+ *
+ * const packageJson = new JsonFile({
+ *   path: './package.json',
+ *   content: {
+ *     name: 'my-api-client',
+ *     version: '1.0.0',
+ *     type: 'module',
+ *     main: './index.js',
+ *     dependencies: {
+ *       'axios': '^1.0.0'
+ *     }
+ *   }
+ * });
+ *
+ * const jsonContent = packageJson.toString();
+ * console.log(jsonContent);
+ * // {
+ * //   "name": "my-api-client",
+ * //   "version": "1.0.0",
+ * //   "type": "module",
+ * //   "main": "./index.js",
+ * //   "dependencies": {
+ * //     "axios": "^1.0.0"
+ * //   }
+ * // }
+ * ```
+ *
+ * @example Configuration file generation
+ * ```typescript
+ * const configFile = new JsonFile({
+ *   path: './src/config/api.json',
+ *   content: {
+ *     baseUrl: 'https://api.example.com',
+ *     timeout: 5000,
+ *     retryAttempts: 3,
+ *     endpoints: {
+ *       users: '/users',
+ *       products: '/products',
+ *       orders: '/orders'
+ *     }
+ *   }
+ * });
+ *
+ * // Write to file system
+ * await Deno.writeTextFile(configFile.path, configFile.toString());
+ * ```
+ *
+ * @example OpenAPI specification output
+ * ```typescript
+ * const openApiFile = new JsonFile({
+ *   path: './dist/openapi.json',
+ *   content: {
+ *     openapi: '3.0.0',
+ *     info: {
+ *       title: 'My API',
+ *       version: '1.0.0'
+ *     },
+ *     paths: {
+ *       '/users': {
+ *         get: {
+ *           summary: 'List users',
+ *           responses: {
+ *             '200': {
+ *               description: 'Success'
+ *             }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example Using with generator registration
+ * ```typescript
+ * class MyGenerator extends ContentBase {
+ *   generate() {
+ *     const manifestFile = new JsonFile({
+ *       path: './generated/manifest.json',
+ *       content: {
+ *         generatedAt: new Date().toISOString(),
+ *         version: '1.0.0',
+ *         files: [
+ *           './models/User.ts',
+ *           './models/Product.ts'
+ *         ]
+ *       }
+ *     });
+ *
+ *     // Register with the generation context
+ *     this.register({ jsonFile: manifestFile });
+ *   }
+ * }
+ * ```
+ */
 export class JsonFile {
+    /**
+     * Creates a new JsonFile instance.
+     *
+     * @param args - JSON file configuration
+     * @param args.path - The output path for this JSON file
+     * @param args.content - The JSON content to write
+     *
+     * @example
+     * ```typescript
+     * const configFile = new JsonFile({
+     *   path: './config/settings.json',
+     *   content: {
+     *     theme: 'dark',
+     *     language: 'en',
+     *     features: ['auth', 'notifications']
+     *   }
+     * });
+     * ```
+     */
     constructor({ path, content }) {
+        /** The file type, always 'json' for JSON files */
         Object.defineProperty(this, "fileType", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: 'json'
         });
+        /** The file path for this generated JSON file */
         Object.defineProperty(this, "path", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The JSON content to write to the file */
         Object.defineProperty(this, "content", {
             enumerable: true,
             configurable: true,
@@ -21,6 +155,29 @@ export class JsonFile {
         this.path = path;
         this.content = content;
     }
+    /**
+     * Converts the JSON content to a formatted string.
+     *
+     * This method serializes the content object to JSON with 2-space indentation
+     * for readable output. The resulting string is suitable for writing directly
+     * to a file or including in the generation pipeline.
+     *
+     * @returns The formatted JSON content as a string
+     *
+     * @example
+     * ```typescript
+     * const file = new JsonFile({
+     *   path: './data.json',
+     *   content: { name: 'test', value: 42 }
+     * });
+     *
+     * console.log(file.toString());
+     * // {
+     * //   "name": "test",
+     * //   "value": 42
+     * // }
+     * ```
+     */
     toString() {
         return JSON.stringify(this.content, null, 2);
     }

package/esm/helpers/refFns.d.ts

@@ -2,11 +2,171 @@ import "../_dnt.polyfills.js";
 import type { RefName } from '../types/RefName.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import type { ReferenceObject } from '../oas/_merge-all-of/types.js';
+/**
+ * Extracts a reference name from an OpenAPI $ref string.
+ *
+ * This function parses JSON Pointer references (like '#/components/schemas/User')
+ * and extracts the final component as a branded RefName type. It's used throughout
+ * the SKMTC system to convert string references into type-safe reference names.
+ *
+ * @param $ref - The OpenAPI reference string (e.g., '#/components/schemas/User')
+ * @returns The extracted reference name as a branded RefName type
+ *
+ * @throws {Error} When the reference string is invalid or empty
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { toRefName } from '@skmtc/core/helpers';
+ *
+ * const refName = toRefName('#/components/schemas/User');
+ * console.log(refName); // 'User' (typed as RefName)
+ *
+ * const responseRef = toRefName('#/components/responses/ErrorResponse');
+ * console.log(responseRef); // 'ErrorResponse' (typed as RefName)
+ * ```
+ *
+ * @example Error cases
+ * ```typescript
+ * // These will throw errors:
+ * toRefName('invalid/ref/'); // Error: 'Invalid reference'
+ * toRefName('#/components/schemas/'); // Error: 'Invalid reference'
+ * ```
+ *
+ * @example Integration with OAS processing
+ * ```typescript
+ * class SchemaProcessor {
+ *   processReference(ref: string) {
+ *     const refName = toRefName(ref);
+ *     const schema = this.document.components.schemas[refName];
+ *     return this.processSchema(schema, refName);
+ *   }
+ * }
+ * ```
+ */
 export declare const toRefName: ($ref: string) => RefName;
+/**
+ * Type representing an object with a $ref property.
+ */
 type Ref = {
+    /** The OpenAPI reference string */
     $ref: string;
 };
+/**
+ * Type guard function to check if a value is an OpenAPI reference object.
+ *
+ * This function performs runtime type checking to determine if an unknown value
+ * is an OpenAPI Reference Object (contains a $ref property with a string value).
+ * It's essential for safely handling mixed schema/reference data during processing.
+ *
+ * @param value - The value to check for reference properties
+ * @returns True if the value is a reference object, false otherwise
+ *
+ * @example Basic type checking
+ * ```typescript
+ * import { isRef } from '@skmtc/core/helpers';
+ *
+ * const schemaOrRef: unknown = { $ref: '#/components/schemas/User' };
+ *
+ * if (isRef(schemaOrRef)) {
+ *   // TypeScript now knows schemaOrRef has a $ref property
+ *   console.log(schemaOrRef.$ref); // Safe to access
+ *   const refName = toRefName(schemaOrRef.$ref);
+ * } else {
+ *   // Handle as actual schema object
+ *   console.log('Direct schema object');
+ * }
+ * ```
+ *
+ * @example Processing mixed data
+ * ```typescript
+ * function processSchemaOrRef(data: unknown) {
+ *   if (isRef(data)) {
+ *     // Handle reference
+ *     return resolveReference(data.$ref);
+ *   } else {
+ *     // Handle direct schema
+ *     return processSchema(data as SchemaObject);
+ *   }
+ * }
+ * ```
+ *
+ * @example Array processing
+ * ```typescript
+ * const mixedArray: unknown[] = [
+ *   { type: 'string' },
+ *   { $ref: '#/components/schemas/User' },
+ *   { type: 'number' }
+ * ];
+ *
+ * const references = mixedArray.filter(isRef);
+ * const schemas = mixedArray.filter(item => !isRef(item));
+ * ```
+ */
 export declare const isRef: (value: unknown) => value is Ref;
+/**
+ * Creates a reference resolver function for an OpenAPI document.
+ *
+ * This higher-order function returns a resolver that can dereference OpenAPI
+ * JSON Pointer references within the context of a specific document. It handles
+ * nested references by recursively resolving reference chains until it reaches
+ * an actual schema object.
+ *
+ * The resolver is particularly useful during schema processing where you need
+ * to follow reference chains to get the actual schema definitions.
+ *
+ * @param oasDocument - The OpenAPI document containing the schemas to resolve against
+ * @returns A function that resolves reference objects to schema objects
+ *
+ * @throws {Error} When a reference cannot be resolved or points to a non-existent schema
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { toGetRef } from '@skmtc/core/helpers';
+ *
+ * const resolver = toGetRef(openApiDocument);
+ *
+ * const userSchema = resolver({ $ref: '#/components/schemas/User' });
+ * console.log(userSchema.type); // 'object'
+ * console.log(userSchema.properties); // User properties
+ * ```
+ *
+ * @example Resolving nested references
+ * ```typescript
+ * // If User references Address, and Address references Country
+ * const resolver = toGetRef(document);
+ *
+ * // This will follow the chain: User -> Address -> Country
+ * const resolvedSchema = resolver({ $ref: '#/components/schemas/User' });
+ * // Returns the final resolved schema object
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * const resolver = toGetRef(document);
+ *
+ * try {
+ *   const schema = resolver({ $ref: '#/components/schemas/NonExistent' });
+ * } catch (error) {
+ *   console.error('Reference resolution failed:', error.message);
+ *   // Error: Invalid reference: #/components/schemas/NonExistent
+ * }
+ * ```
+ *
+ * @example Integration with schema processing
+ * ```typescript
+ * class SchemaProcessor {
+ *   private resolver = toGetRef(this.document);
+ *
+ *   processProperty(property: SchemaObject | ReferenceObject) {
+ *     if (isRef(property)) {
+ *       const resolved = this.resolver(property);
+ *       return this.processSchema(resolved);
+ *     }
+ *     return this.processSchema(property);
+ *   }
+ * }
+ * ```
+ */
 export declare const toGetRef: (oasDocument: OpenAPIV3.Document) => ({ $ref }: ReferenceObject) => OpenAPIV3.SchemaObject;
 export {};
 //# sourceMappingURL=refFns.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"refFns.d.ts","sourceRoot":"","sources":["../../src/helpers/refFns.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAEpE,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,OASxC,CAAA;AAED,KAAK,GAAG,GAAG;IACT,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,eAAO,MAAM,KAAK,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,GAM/C,CAAA;AAED,eAAO,MAAM,QAAQ,GAClB,aAAa,SAAS,CAAC,QAAQ,MAC/B,UAAU,eAAe,KAAG,SAAS,CAAC,YActC,CAAA"}
+{"version":3,"file":"refFns.d.ts","sourceRoot":"","sources":["../../src/helpers/refFns.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,OASxC,CAAA;AAED;;GAEG;AACH,KAAK,GAAG,GAAG;IACT,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,GAM/C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,eAAO,MAAM,QAAQ,GAClB,aAAa,SAAS,CAAC,QAAQ,MAC/B,UAAU,eAAe,KAAG,SAAS,CAAC,YActC,CAAA"}

package/esm/helpers/refFns.js

@@ -1,4 +1,45 @@
 import "../_dnt.polyfills.js";
+/**
+ * Extracts a reference name from an OpenAPI $ref string.
+ *
+ * This function parses JSON Pointer references (like '#/components/schemas/User')
+ * and extracts the final component as a branded RefName type. It's used throughout
+ * the SKMTC system to convert string references into type-safe reference names.
+ *
+ * @param $ref - The OpenAPI reference string (e.g., '#/components/schemas/User')
+ * @returns The extracted reference name as a branded RefName type
+ *
+ * @throws {Error} When the reference string is invalid or empty
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { toRefName } from '@skmtc/core/helpers';
+ *
+ * const refName = toRefName('#/components/schemas/User');
+ * console.log(refName); // 'User' (typed as RefName)
+ *
+ * const responseRef = toRefName('#/components/responses/ErrorResponse');
+ * console.log(responseRef); // 'ErrorResponse' (typed as RefName)
+ * ```
+ *
+ * @example Error cases
+ * ```typescript
+ * // These will throw errors:
+ * toRefName('invalid/ref/'); // Error: 'Invalid reference'
+ * toRefName('#/components/schemas/'); // Error: 'Invalid reference'
+ * ```
+ *
+ * @example Integration with OAS processing
+ * ```typescript
+ * class SchemaProcessor {
+ *   processReference(ref: string) {
+ *     const refName = toRefName(ref);
+ *     const schema = this.document.components.schemas[refName];
+ *     return this.processSchema(schema, refName);
+ *   }
+ * }
+ * ```
+ */
 export const toRefName = ($ref) => {
     // TODO: Add validation here to ensure reference exists
     const refName = $ref.split('/').slice(-1)[0];
@@ -7,6 +48,57 @@ export const toRefName = ($ref) => {
     }
     return refName;
 };
+/**
+ * Type guard function to check if a value is an OpenAPI reference object.
+ *
+ * This function performs runtime type checking to determine if an unknown value
+ * is an OpenAPI Reference Object (contains a $ref property with a string value).
+ * It's essential for safely handling mixed schema/reference data during processing.
+ *
+ * @param value - The value to check for reference properties
+ * @returns True if the value is a reference object, false otherwise
+ *
+ * @example Basic type checking
+ * ```typescript
+ * import { isRef } from '@skmtc/core/helpers';
+ *
+ * const schemaOrRef: unknown = { $ref: '#/components/schemas/User' };
+ *
+ * if (isRef(schemaOrRef)) {
+ *   // TypeScript now knows schemaOrRef has a $ref property
+ *   console.log(schemaOrRef.$ref); // Safe to access
+ *   const refName = toRefName(schemaOrRef.$ref);
+ * } else {
+ *   // Handle as actual schema object
+ *   console.log('Direct schema object');
+ * }
+ * ```
+ *
+ * @example Processing mixed data
+ * ```typescript
+ * function processSchemaOrRef(data: unknown) {
+ *   if (isRef(data)) {
+ *     // Handle reference
+ *     return resolveReference(data.$ref);
+ *   } else {
+ *     // Handle direct schema
+ *     return processSchema(data as SchemaObject);
+ *   }
+ * }
+ * ```
+ *
+ * @example Array processing
+ * ```typescript
+ * const mixedArray: unknown[] = [
+ *   { type: 'string' },
+ *   { $ref: '#/components/schemas/User' },
+ *   { type: 'number' }
+ * ];
+ *
+ * const references = mixedArray.filter(isRef);
+ * const schemas = mixedArray.filter(item => !isRef(item));
+ * ```
+ */
 export const isRef = (value) => {
     if (value && typeof value === 'object' && '$ref' in value && typeof value.$ref === 'string') {
         return true;
@@ -15,6 +107,70 @@ export const isRef = (value) => {
         return false;
     }
 };
+/**
+ * Creates a reference resolver function for an OpenAPI document.
+ *
+ * This higher-order function returns a resolver that can dereference OpenAPI
+ * JSON Pointer references within the context of a specific document. It handles
+ * nested references by recursively resolving reference chains until it reaches
+ * an actual schema object.
+ *
+ * The resolver is particularly useful during schema processing where you need
+ * to follow reference chains to get the actual schema definitions.
+ *
+ * @param oasDocument - The OpenAPI document containing the schemas to resolve against
+ * @returns A function that resolves reference objects to schema objects
+ *
+ * @throws {Error} When a reference cannot be resolved or points to a non-existent schema
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { toGetRef } from '@skmtc/core/helpers';
+ *
+ * const resolver = toGetRef(openApiDocument);
+ *
+ * const userSchema = resolver({ $ref: '#/components/schemas/User' });
+ * console.log(userSchema.type); // 'object'
+ * console.log(userSchema.properties); // User properties
+ * ```
+ *
+ * @example Resolving nested references
+ * ```typescript
+ * // If User references Address, and Address references Country
+ * const resolver = toGetRef(document);
+ *
+ * // This will follow the chain: User -> Address -> Country
+ * const resolvedSchema = resolver({ $ref: '#/components/schemas/User' });
+ * // Returns the final resolved schema object
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * const resolver = toGetRef(document);
+ *
+ * try {
+ *   const schema = resolver({ $ref: '#/components/schemas/NonExistent' });
+ * } catch (error) {
+ *   console.error('Reference resolution failed:', error.message);
+ *   // Error: Invalid reference: #/components/schemas/NonExistent
+ * }
+ * ```
+ *
+ * @example Integration with schema processing
+ * ```typescript
+ * class SchemaProcessor {
+ *   private resolver = toGetRef(this.document);
+ *
+ *   processProperty(property: SchemaObject | ReferenceObject) {
+ *     if (isRef(property)) {
+ *       const resolved = this.resolver(property);
+ *       return this.processSchema(resolved);
+ *     }
+ *     return this.processSchema(property);
+ *   }
+ * }
+ * ```
+ */
 export const toGetRef = (oasDocument) => ({ $ref }) => {
     const refName = toRefName($ref);
     const item = oasDocument.components?.schemas?.[refName];