@skmtc/core 0.0.791 → 0.0.793

package/script/helpers/collateExamples.d.ts

@@ -1,10 +1,160 @@
 import "../_dnt.polyfills.js";
 import type { OasRef } from '../oas/ref/Ref.js';
 import type { OasSchema } from '../oas/schema/Schema.js';
+/**
+ * Arguments for collating examples from OpenAPI schemas.
+ */
 type CollatedExampleArgs = {
+    /** The OpenAPI schema or reference to extract examples from */
     objectSchema: OasSchema | OasRef<'schema'> | undefined;
+    /** Current recursion depth (used to prevent infinite loops) */
     depth: number;
 };
+/**
+ * Recursively collates and builds example values from OpenAPI schemas.
+ *
+ * This function traverses OpenAPI schema structures and generates comprehensive
+ * example values based on the schema definitions and any explicit examples provided.
+ * It handles complex nested structures including objects, arrays, unions, and
+ * references while preventing infinite recursion through depth limiting.
+ *
+ * The function prioritizes explicit examples when available and falls back to
+ * generating examples from nested schemas. It's particularly useful for creating
+ * realistic test data, API documentation examples, and mock responses.
+ *
+ * @param args - Configuration for example collation
+ * @param args.objectSchema - The schema to extract examples from
+ * @param args.depth - Current recursion depth (prevents infinite loops)
+ * @returns Collated example value matching the schema structure, or undefined if no examples
+ *
+ * @throws {Error} When recursion depth exceeds 15 levels (prevents stack overflow)
+ *
+ * @example Basic schema examples
+ * ```typescript
+ * import { collateExamples } from '@skmtc/core';
+ *
+ * // String schema with example
+ * const stringSchema = new OasString({ example: 'john.doe@example.com' });
+ * const example = collateExamples({ objectSchema: stringSchema, depth: 0 });
+ * console.log(example); // 'john.doe@example.com'
+ *
+ * // Number schema with example
+ * const numberSchema = new OasNumber({ example: 42 });
+ * const numExample = collateExamples({ objectSchema: numberSchema, depth: 0 });
+ * console.log(numExample); // 42
+ * ```
+ *
+ * @example Object schema examples
+ * ```typescript
+ * // Object schema with nested properties
+ * const userSchema = new OasObject({
+ *   properties: {
+ *     id: new OasInteger({ example: 123 }),
+ *     name: new OasString({ example: 'John Doe' }),
+ *     email: new OasString({ example: 'john@example.com' }),
+ *     age: new OasInteger({ example: 30 })
+ *   }
+ * });
+ *
+ * const userExample = collateExamples({ objectSchema: userSchema, depth: 0 });
+ * console.log(userExample);
+ * // {
+ * //   id: 123,
+ * //   name: 'John Doe',
+ * //   email: 'john@example.com',
+ * //   age: 30
+ * // }
+ * ```
+ *
+ * @example Array schema examples
+ * ```typescript
+ * // Array of objects
+ * const usersArraySchema = new OasArray({
+ *   items: new OasObject({
+ *     properties: {
+ *       id: new OasInteger({ example: 1 }),
+ *       name: new OasString({ example: 'Jane Smith' })
+ *     }
+ *   })
+ * });
+ *
+ * const arrayExample = collateExamples({ objectSchema: usersArraySchema, depth: 0 });
+ * console.log(arrayExample);
+ * // [
+ * //   {
+ * //     id: 1,
+ * //     name: 'Jane Smith'
+ * //   }
+ * // ]
+ * ```
+ *
+ * @example Union schema examples
+ * ```typescript
+ * // Union of string and number
+ * const unionSchema = new OasUnion({
+ *   members: [
+ *     new OasString({ example: 'text-value' }),
+ *     new OasNumber({ example: 99 })
+ *   ]
+ * });
+ *
+ * const unionExample = collateExamples({ objectSchema: unionSchema, depth: 0 });
+ * console.log(unionExample); // 'text-value' (first member with example)
+ * ```
+ *
+ * @example Reference resolution
+ * ```typescript
+ * // Schema with reference to another schema
+ * const addressRef = new OasRef({
+ *   $ref: '#/components/schemas/Address',
+ *   resolve: () => new OasObject({
+ *     properties: {
+ *       street: new OasString({ example: '123 Main St' }),
+ *       city: new OasString({ example: 'Springfield' })
+ *     }
+ *   })
+ * });
+ *
+ * const refExample = collateExamples({ objectSchema: addressRef, depth: 0 });
+ * console.log(refExample);
+ * // {
+ * //   street: '123 Main St',
+ * //   city: 'Springfield'
+ * // }
+ * ```
+ *
+ * @example Depth limiting and error handling
+ * ```typescript
+ * // Deep nesting detection
+ * try {
+ *   const deepExample = collateExamples({ objectSchema: someSchema, depth: 16 });
+ * } catch (error) {
+ *   console.error('Depth limit exceeded:', error.message); // 'Depth limit reached'
+ * }
+ *
+ * // Handling missing schemas
+ * const emptyExample = collateExamples({ objectSchema: undefined, depth: 0 });
+ * console.log(emptyExample); // undefined
+ * ```
+ *
+ * @example Using in API documentation generation
+ * ```typescript
+ * class ApiDocGenerator {
+ *   generateExampleResponse(responseSchema: OasSchema) {
+ *     const example = collateExamples({ objectSchema: responseSchema, depth: 0 });
+ *
+ *     if (example) {
+ *       return {
+ *         description: 'Example response',
+ *         value: example
+ *       };
+ *     }
+ *
+ *     return { description: 'No example available' };
+ *   }
+ * }
+ * ```
+ */
 export declare const collateExamples: ({ objectSchema, depth }: CollatedExampleArgs) => unknown;
 export {};
 //# sourceMappingURL=collateExamples.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"collateExamples.d.ts","sourceRoot":"","sources":["../../src/helpers/collateExamples.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAIxD,KAAK,mBAAmB,GAAG;IACzB,YAAY,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACtD,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,eAAO,MAAM,eAAe,GAAI,yBAAyB,mBAAmB,KAAG,OAwE9E,CAAA"}
+{"version":3,"file":"collateExamples.d.ts","sourceRoot":"","sources":["../../src/helpers/collateExamples.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAIxD;;GAEG;AACH,KAAK,mBAAmB,GAAG;IACzB,+DAA+D;IAC/D,YAAY,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACtD,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgJG;AACH,eAAO,MAAM,eAAe,GAAI,yBAAyB,mBAAmB,KAAG,OAwE9E,CAAA"}

package/script/helpers/collateExamples.js

@@ -4,6 +4,151 @@ exports.collateExamples = void 0;
 require("../_dnt.polyfills.js");
 const ts_pattern_1 = require("ts-pattern");
 const isEmpty_js_1 = require("./isEmpty.js");
+/**
+ * Recursively collates and builds example values from OpenAPI schemas.
+ *
+ * This function traverses OpenAPI schema structures and generates comprehensive
+ * example values based on the schema definitions and any explicit examples provided.
+ * It handles complex nested structures including objects, arrays, unions, and
+ * references while preventing infinite recursion through depth limiting.
+ *
+ * The function prioritizes explicit examples when available and falls back to
+ * generating examples from nested schemas. It's particularly useful for creating
+ * realistic test data, API documentation examples, and mock responses.
+ *
+ * @param args - Configuration for example collation
+ * @param args.objectSchema - The schema to extract examples from
+ * @param args.depth - Current recursion depth (prevents infinite loops)
+ * @returns Collated example value matching the schema structure, or undefined if no examples
+ *
+ * @throws {Error} When recursion depth exceeds 15 levels (prevents stack overflow)
+ *
+ * @example Basic schema examples
+ * ```typescript
+ * import { collateExamples } from '@skmtc/core';
+ *
+ * // String schema with example
+ * const stringSchema = new OasString({ example: 'john.doe@example.com' });
+ * const example = collateExamples({ objectSchema: stringSchema, depth: 0 });
+ * console.log(example); // 'john.doe@example.com'
+ *
+ * // Number schema with example
+ * const numberSchema = new OasNumber({ example: 42 });
+ * const numExample = collateExamples({ objectSchema: numberSchema, depth: 0 });
+ * console.log(numExample); // 42
+ * ```
+ *
+ * @example Object schema examples
+ * ```typescript
+ * // Object schema with nested properties
+ * const userSchema = new OasObject({
+ *   properties: {
+ *     id: new OasInteger({ example: 123 }),
+ *     name: new OasString({ example: 'John Doe' }),
+ *     email: new OasString({ example: 'john@example.com' }),
+ *     age: new OasInteger({ example: 30 })
+ *   }
+ * });
+ *
+ * const userExample = collateExamples({ objectSchema: userSchema, depth: 0 });
+ * console.log(userExample);
+ * // {
+ * //   id: 123,
+ * //   name: 'John Doe',
+ * //   email: 'john@example.com',
+ * //   age: 30
+ * // }
+ * ```
+ *
+ * @example Array schema examples
+ * ```typescript
+ * // Array of objects
+ * const usersArraySchema = new OasArray({
+ *   items: new OasObject({
+ *     properties: {
+ *       id: new OasInteger({ example: 1 }),
+ *       name: new OasString({ example: 'Jane Smith' })
+ *     }
+ *   })
+ * });
+ *
+ * const arrayExample = collateExamples({ objectSchema: usersArraySchema, depth: 0 });
+ * console.log(arrayExample);
+ * // [
+ * //   {
+ * //     id: 1,
+ * //     name: 'Jane Smith'
+ * //   }
+ * // ]
+ * ```
+ *
+ * @example Union schema examples
+ * ```typescript
+ * // Union of string and number
+ * const unionSchema = new OasUnion({
+ *   members: [
+ *     new OasString({ example: 'text-value' }),
+ *     new OasNumber({ example: 99 })
+ *   ]
+ * });
+ *
+ * const unionExample = collateExamples({ objectSchema: unionSchema, depth: 0 });
+ * console.log(unionExample); // 'text-value' (first member with example)
+ * ```
+ *
+ * @example Reference resolution
+ * ```typescript
+ * // Schema with reference to another schema
+ * const addressRef = new OasRef({
+ *   $ref: '#/components/schemas/Address',
+ *   resolve: () => new OasObject({
+ *     properties: {
+ *       street: new OasString({ example: '123 Main St' }),
+ *       city: new OasString({ example: 'Springfield' })
+ *     }
+ *   })
+ * });
+ *
+ * const refExample = collateExamples({ objectSchema: addressRef, depth: 0 });
+ * console.log(refExample);
+ * // {
+ * //   street: '123 Main St',
+ * //   city: 'Springfield'
+ * // }
+ * ```
+ *
+ * @example Depth limiting and error handling
+ * ```typescript
+ * // Deep nesting detection
+ * try {
+ *   const deepExample = collateExamples({ objectSchema: someSchema, depth: 16 });
+ * } catch (error) {
+ *   console.error('Depth limit exceeded:', error.message); // 'Depth limit reached'
+ * }
+ *
+ * // Handling missing schemas
+ * const emptyExample = collateExamples({ objectSchema: undefined, depth: 0 });
+ * console.log(emptyExample); // undefined
+ * ```
+ *
+ * @example Using in API documentation generation
+ * ```typescript
+ * class ApiDocGenerator {
+ *   generateExampleResponse(responseSchema: OasSchema) {
+ *     const example = collateExamples({ objectSchema: responseSchema, depth: 0 });
+ *
+ *     if (example) {
+ *       return {
+ *         description: 'Example response',
+ *         value: example
+ *       };
+ *     }
+ *
+ *     return { description: 'No example available' };
+ *   }
+ * }
+ * ```
+ */
 const collateExamples = ({ objectSchema, depth }) => {
     if (!objectSchema) {
         return undefined;

package/script/helpers/formatNumber.d.ts

@@ -1,3 +1,98 @@
+/**
+ * Formats a number using locale-specific formatting without decimal places.
+ *
+ * This utility function formats numbers according to locale conventions,
+ * adding thousand separators and other locale-specific number formatting
+ * while ensuring the output contains no fractional digits. It's useful
+ * for displaying counts, statistics, or other whole numbers in a
+ * human-readable format.
+ *
+ * @param value - The number to format
+ * @param locales - The locale(s) to use for formatting (defaults to 'en-US')
+ * @returns The formatted number as a string with locale-appropriate thousand separators
+ *
+ * @example Basic formatting with default locale (en-US)
+ * ```typescript
+ * import { formatNumber } from '@skmtc/core';
+ *
+ * console.log(formatNumber(1234));     // '1,234'
+ * console.log(formatNumber(1234567));  // '1,234,567'
+ * console.log(formatNumber(42));       // '42'
+ * console.log(formatNumber(0));        // '0'
+ * ```
+ *
+ * @example Formatting with different locales
+ * ```typescript
+ * const bigNumber = 1234567;
+ *
+ * console.log(formatNumber(bigNumber, 'en-US')); // '1,234,567'
+ * console.log(formatNumber(bigNumber, 'de-DE')); // '1.234.567'
+ * console.log(formatNumber(bigNumber, 'fr-FR')); // '1 234 567'
+ * console.log(formatNumber(bigNumber, 'en-IN')); // '12,34,567'
+ * ```
+ *
+ * @example Formatting decimal numbers (fractional part removed)
+ * ```typescript
+ * // The function always rounds to whole numbers
+ * console.log(formatNumber(1234.56));    // '1,235' (rounded)
+ * console.log(formatNumber(999.99));     // '1,000' (rounded)
+ * console.log(formatNumber(1000.1));     // '1,000' (rounded)
+ * console.log(formatNumber(1000.0));     // '1,000'
+ * ```
+ *
+ * @example Usage in reporting and statistics
+ * ```typescript
+ * class StatsReporter {
+ *   generateReport(stats: {
+ *     totalFiles: number;
+ *     linesGenerated: number;
+ *     errors: number;
+ *   }) {
+ *     return `
+ * Generation Report:
+ * - Files generated: ${formatNumber(stats.totalFiles)}
+ * - Lines of code: ${formatNumber(stats.linesGenerated)}
+ * - Errors encountered: ${formatNumber(stats.errors)}
+ *     `.trim();
+ *   }
+ * }
+ *
+ * const reporter = new StatsReporter();
+ * const report = reporter.generateReport({
+ *   totalFiles: 1234,
+ *   linesGenerated: 567890,
+ *   errors: 5
+ * });
+ *
+ * console.log(report);
+ * // Generation Report:
+ * // - Files generated: 1,234
+ * // - Lines of code: 567,890
+ * // - Errors encountered: 5
+ * ```
+ *
+ * @example International number formatting
+ * ```typescript
+ * const count = 50000;
+ *
+ * // Different regions format numbers differently
+ * const formats = [
+ *   { locale: 'en-US', label: 'US English' },
+ *   { locale: 'de-DE', label: 'German' },
+ *   { locale: 'fr-FR', label: 'French' },
+ *   { locale: 'ja-JP', label: 'Japanese' }
+ * ];
+ *
+ * formats.forEach(({ locale, label }) => {
+ *   console.log(`${label}: ${formatNumber(count, locale)}`);
+ * });
+ *
+ * // US English: 50,000
+ * // German: 50.000
+ * // French: 50 000
+ * // Japanese: 50,000
+ * ```
+ */
 import "../_dnt.polyfills.js";
 export declare const formatNumber: (value: number, locales?: Intl.LocalesArgument) => string;
 //# sourceMappingURL=formatNumber.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"formatNumber.d.ts","sourceRoot":"","sources":["../../src/helpers/formatNumber.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,EAAE,UAAS,IAAI,CAAC,eAAyB,KAAG,MAKrF,CAAA"}
+{"version":3,"file":"formatNumber.d.ts","sourceRoot":"","sources":["../../src/helpers/formatNumber.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,OAAO,sBAAsB,CAAC;AAE9B,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,EAAE,UAAS,IAAI,CAAC,eAAyB,KAAG,MAKrF,CAAA"}

package/script/helpers/formatNumber.js

@@ -1,6 +1,101 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatNumber = void 0;
+/**
+ * Formats a number using locale-specific formatting without decimal places.
+ *
+ * This utility function formats numbers according to locale conventions,
+ * adding thousand separators and other locale-specific number formatting
+ * while ensuring the output contains no fractional digits. It's useful
+ * for displaying counts, statistics, or other whole numbers in a
+ * human-readable format.
+ *
+ * @param value - The number to format
+ * @param locales - The locale(s) to use for formatting (defaults to 'en-US')
+ * @returns The formatted number as a string with locale-appropriate thousand separators
+ *
+ * @example Basic formatting with default locale (en-US)
+ * ```typescript
+ * import { formatNumber } from '@skmtc/core';
+ *
+ * console.log(formatNumber(1234));     // '1,234'
+ * console.log(formatNumber(1234567));  // '1,234,567'
+ * console.log(formatNumber(42));       // '42'
+ * console.log(formatNumber(0));        // '0'
+ * ```
+ *
+ * @example Formatting with different locales
+ * ```typescript
+ * const bigNumber = 1234567;
+ *
+ * console.log(formatNumber(bigNumber, 'en-US')); // '1,234,567'
+ * console.log(formatNumber(bigNumber, 'de-DE')); // '1.234.567'
+ * console.log(formatNumber(bigNumber, 'fr-FR')); // '1 234 567'
+ * console.log(formatNumber(bigNumber, 'en-IN')); // '12,34,567'
+ * ```
+ *
+ * @example Formatting decimal numbers (fractional part removed)
+ * ```typescript
+ * // The function always rounds to whole numbers
+ * console.log(formatNumber(1234.56));    // '1,235' (rounded)
+ * console.log(formatNumber(999.99));     // '1,000' (rounded)
+ * console.log(formatNumber(1000.1));     // '1,000' (rounded)
+ * console.log(formatNumber(1000.0));     // '1,000'
+ * ```
+ *
+ * @example Usage in reporting and statistics
+ * ```typescript
+ * class StatsReporter {
+ *   generateReport(stats: {
+ *     totalFiles: number;
+ *     linesGenerated: number;
+ *     errors: number;
+ *   }) {
+ *     return `
+ * Generation Report:
+ * - Files generated: ${formatNumber(stats.totalFiles)}
+ * - Lines of code: ${formatNumber(stats.linesGenerated)}
+ * - Errors encountered: ${formatNumber(stats.errors)}
+ *     `.trim();
+ *   }
+ * }
+ *
+ * const reporter = new StatsReporter();
+ * const report = reporter.generateReport({
+ *   totalFiles: 1234,
+ *   linesGenerated: 567890,
+ *   errors: 5
+ * });
+ *
+ * console.log(report);
+ * // Generation Report:
+ * // - Files generated: 1,234
+ * // - Lines of code: 567,890
+ * // - Errors encountered: 5
+ * ```
+ *
+ * @example International number formatting
+ * ```typescript
+ * const count = 50000;
+ *
+ * // Different regions format numbers differently
+ * const formats = [
+ *   { locale: 'en-US', label: 'US English' },
+ *   { locale: 'de-DE', label: 'German' },
+ *   { locale: 'fr-FR', label: 'French' },
+ *   { locale: 'ja-JP', label: 'Japanese' }
+ * ];
+ *
+ * formats.forEach(({ locale, label }) => {
+ *   console.log(`${label}: ${formatNumber(count, locale)}`);
+ * });
+ *
+ * // US English: 50,000
+ * // German: 50.000
+ * // French: 50 000
+ * // Japanese: 50,000
+ * ```
+ */
 require("../_dnt.polyfills.js");
 const formatNumber = (value, locales = 'en-US') => {
     return value.toLocaleString(locales, {