@skmtc/core 0.0.785 → 0.0.787

package/esm/oas/string/String.d.ts

@@ -2,21 +2,108 @@ import "../../_dnt.polyfills.js";
 import type { OasRef } from '../ref/Ref.js';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Constructor fields for {@link OasString}.
+ *
+ * @template Nullable - Whether the string value can be null
+ */
 export type StringFields<Nullable extends boolean | undefined> = {
+    /** A short summary of the string schema */
     title?: string;
+    /** A description of the string schema */
     description?: string;
+    /** String format (e.g., 'email', 'date-time', 'uri') */
     format?: string;
+    /** Default value for the string */
     default?: Nullable extends true ? string | null | undefined : string | undefined;
+    /** Regular expression pattern for validation */
     pattern?: string;
+    /** Array of allowed enum values */
     enums?: Nullable extends true ? (string | null)[] | undefined : string[] | undefined;
+    /** Maximum length constraint */
     maxLength?: number;
+    /** Minimum length constraint */
     minLength?: number;
+    /** Whether the string value can be null */
     nullable?: Nullable;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
+    /** Example value for the string */
     example?: Nullable extends true ? string | null | undefined : string | undefined;
 };
 /**
- * Object representing a string in the OpenAPI Specification.
+ * Represents a string schema in the OpenAPI Specification.
+ *
+ * `OasString` handles string type definitions with comprehensive validation
+ * constraints including format validation, length limits, pattern matching,
+ * and enum restrictions. It supports nullable types and provides JSON Schema
+ * conversion for validation purposes.
+ *
+ * This class is used throughout the OAS processing pipeline to represent
+ * string fields in API schemas, parameters, and request/response bodies.
+ *
+ * ## Key Features
+ *
+ * - **Format Validation**: Support for standard formats (email, date-time, uri, etc.)
+ * - **Length Constraints**: Minimum and maximum length validation
+ * - **Pattern Matching**: Regular expression validation
+ * - **Enum Values**: Restricted sets of allowed values
+ * - **Nullable Support**: Type-safe nullable string handling
+ * - **JSON Schema**: Conversion to standard JSON Schema format
+ *
+ * @template Nullable - Whether the string value can be null
+ *
+ * @example Basic string schema
+ * ```typescript
+ * import { OasString } from '@skmtc/core';
+ *
+ * const basicString = new OasString({
+ *   title: 'User Name',
+ *   description: 'The full name of the user',
+ *   minLength: 1,
+ *   maxLength: 100
+ * });
+ * ```
+ *
+ * @example Email format validation
+ * ```typescript
+ * const emailString = new OasString({
+ *   title: 'Email Address',
+ *   description: 'Valid email address',
+ *   format: 'email',
+ *   example: 'user@example.com'
+ * });
+ * ```
+ *
+ * @example Enum with allowed values
+ * ```typescript
+ * const statusString = new OasString({
+ *   title: 'Status',
+ *   description: 'Current status of the item',
+ *   enums: ['pending', 'approved', 'rejected'],
+ *   default: 'pending'
+ * });
+ * ```
+ *
+ * @example Pattern validation
+ * ```typescript
+ * const phoneString = new OasString({
+ *   title: 'Phone Number',
+ *   description: 'US phone number format',
+ *   pattern: '^\\+?1?[2-9]\\d{2}[2-9]\\d{2}\\d{4}$',
+ *   example: '+15551234567'
+ * });
+ * ```
+ *
+ * @example Nullable string
+ * ```typescript
+ * const nullableString = new OasString<true>({
+ *   title: 'Optional Note',
+ *   description: 'Optional note that can be null',
+ *   nullable: true,
+ *   default: null
+ * });
+ * ```
  */
 export declare class OasString<Nullable extends boolean | undefined = boolean | undefined> {
     /**
@@ -68,6 +155,21 @@ export declare class OasString<Nullable extends boolean | undefined = boolean |
      * The default value of the string.
      */
     default: Nullable extends true ? string | null | undefined : string | undefined;
+    /**
+     * Creates a new OasString instance.
+     *
+     * @param fields - String schema configuration fields
+     *
+     * @example
+     * ```typescript
+     * const userIdString = new OasString({
+     *   title: 'User ID',
+     *   description: 'Unique identifier for user',
+     *   format: 'uuid',
+     *   example: '123e4567-e89b-12d3-a456-426614174000'
+     * });
+     * ```
+     */
     constructor(fields?: StringFields<Nullable>);
     isRef(): this is OasRef<'schema'>;
     resolve(): OasString<Nullable>;

package/esm/oas/string/String.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"String.d.ts","sourceRoot":"","sources":["../../../src/oas/string/String.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,YAAY,CAAC,QAAQ,SAAS,OAAO,GAAG,SAAS,IAAI;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;IAChF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAAA;IACpF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,OAAO,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;CACjF,CAAA;AAED;;GAEG;AACH,qBAAa,SAAS,CAAC,QAAQ,SAAS,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS;IAC/E;;;OAGG;IACH,OAAO,EAAG,QAAQ,CAAS;IAC3B;;OAEG;IACH,IAAI,EAAG,QAAQ,CAAS;IACxB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B;;OAEG;IACH,KAAK,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAAA;IACnF;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B;;OAEG;IACH,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC9B,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACpD,gCAAgC;IAChC,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;IAC/E;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B;;OAEG;IACH,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAA;gBAEnE,MAAM,GAAE,YAAY,CAAC,QAAQ,CAAM;IAc/C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,OAAO,IAAI,SAAS,CAAC,QAAQ,CAAC;IAI9B,WAAW,IAAI,SAAS,CAAC,QAAQ,CAAC;IAKlC,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC,oBAAoB;CAe5E"}
+{"version":3,"file":"String.d.ts","sourceRoot":"","sources":["../../../src/oas/string/String.ts"],"names":[],"mappings":"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"}

package/esm/oas/string/String.js

@@ -1,8 +1,94 @@
 import "../../_dnt.polyfills.js";
 /**
- * Object representing a string in the OpenAPI Specification.
+ * Represents a string schema in the OpenAPI Specification.
+ *
+ * `OasString` handles string type definitions with comprehensive validation
+ * constraints including format validation, length limits, pattern matching,
+ * and enum restrictions. It supports nullable types and provides JSON Schema
+ * conversion for validation purposes.
+ *
+ * This class is used throughout the OAS processing pipeline to represent
+ * string fields in API schemas, parameters, and request/response bodies.
+ *
+ * ## Key Features
+ *
+ * - **Format Validation**: Support for standard formats (email, date-time, uri, etc.)
+ * - **Length Constraints**: Minimum and maximum length validation
+ * - **Pattern Matching**: Regular expression validation
+ * - **Enum Values**: Restricted sets of allowed values
+ * - **Nullable Support**: Type-safe nullable string handling
+ * - **JSON Schema**: Conversion to standard JSON Schema format
+ *
+ * @template Nullable - Whether the string value can be null
+ *
+ * @example Basic string schema
+ * ```typescript
+ * import { OasString } from '@skmtc/core';
+ *
+ * const basicString = new OasString({
+ *   title: 'User Name',
+ *   description: 'The full name of the user',
+ *   minLength: 1,
+ *   maxLength: 100
+ * });
+ * ```
+ *
+ * @example Email format validation
+ * ```typescript
+ * const emailString = new OasString({
+ *   title: 'Email Address',
+ *   description: 'Valid email address',
+ *   format: 'email',
+ *   example: 'user@example.com'
+ * });
+ * ```
+ *
+ * @example Enum with allowed values
+ * ```typescript
+ * const statusString = new OasString({
+ *   title: 'Status',
+ *   description: 'Current status of the item',
+ *   enums: ['pending', 'approved', 'rejected'],
+ *   default: 'pending'
+ * });
+ * ```
+ *
+ * @example Pattern validation
+ * ```typescript
+ * const phoneString = new OasString({
+ *   title: 'Phone Number',
+ *   description: 'US phone number format',
+ *   pattern: '^\\+?1?[2-9]\\d{2}[2-9]\\d{2}\\d{4}$',
+ *   example: '+15551234567'
+ * });
+ * ```
+ *
+ * @example Nullable string
+ * ```typescript
+ * const nullableString = new OasString<true>({
+ *   title: 'Optional Note',
+ *   description: 'Optional note that can be null',
+ *   nullable: true,
+ *   default: null
+ * });
+ * ```
  */
 export class OasString {
+    /**
+     * Creates a new OasString instance.
+     *
+     * @param fields - String schema configuration fields
+     *
+     * @example
+     * ```typescript
+     * const userIdString = new OasString({
+     *   title: 'User ID',
+     *   description: 'Unique identifier for user',
+     *   format: 'uuid',
+     *   example: '123e4567-e89b-12d3-a456-426614174000'
+     * });
+     * ```
+     */
     constructor(fields = {}) {
         /**
          * Object is part the 'schema' set which is used

package/esm/types/Brand.d.ts

@@ -1,5 +1,79 @@
+/**
+ * Unique symbol used for branding types.
+ *
+ * This symbol is used internally by the {@link Brand} type to create
+ * unique branded types that are structurally identical but nominally
+ * distinct from their base types.
+ *
+ * @internal
+ */
 import "../_dnt.polyfills.js";
 declare const brand: unique symbol;
+/**
+ * Creates a branded type from a base type.
+ *
+ * Brand types (also known as nominal types or opaque types) are TypeScript
+ * types that are structurally identical to their base type but are treated
+ * as distinct types by the type system. This prevents accidental mixing of
+ * values that should be kept separate.
+ *
+ * The SKMTC system uses branded types extensively to ensure type safety
+ * when working with identifiers, keys, and other string-based values that
+ * have specific semantic meaning.
+ *
+ * @template T - The base type to brand
+ * @template TBrand - The brand identifier (usually a string literal)
+ *
+ * @example Basic branded type usage
+ * ```typescript
+ * import { Brand } from '@skmtc/core';
+ *
+ * type UserId = Brand<string, 'UserId'>;
+ * type ProductId = Brand<string, 'ProductId'>;
+ *
+ * const userId: UserId = 'user-123' as UserId;
+ * const productId: ProductId = 'prod-456' as ProductId;
+ *
+ * function getUser(id: UserId) {
+ *   // Function expects a UserId, not just any string
+ *   return `User with ID: ${id}`;
+ * }
+ *
+ * getUser(userId);    // ✅ Works - correct type
+ * getUser(productId); // ❌ TypeScript error - ProductId is not UserId
+ * getUser('user-789'); // ❌ TypeScript error - string is not UserId
+ * ```
+ *
+ * @example SKMTC branded types
+ * ```typescript
+ * // RefName ensures schema reference safety
+ * type RefName = Brand<string, 'RefName'>;
+ * const schemaRef: RefName = 'User' as RefName;
+ *
+ * // GeneratorKey ensures generator identification safety
+ * type OperationGeneratorKey = Brand<string, 'OperationGeneratorKey'>;
+ * const opKey: OperationGeneratorKey = 'api-client|/users|get' as OperationGeneratorKey;
+ * ```
+ *
+ * @example Runtime behavior
+ * ```typescript
+ * type EmailAddress = Brand<string, 'EmailAddress'>;
+ *
+ * const email: EmailAddress = 'user@example.com' as EmailAddress;
+ *
+ * // At runtime, branded types are just their base type
+ * console.log(typeof email); // 'string'
+ * console.log(email);        // 'user@example.com'
+ *
+ * // But TypeScript enforces the brand at compile time
+ * function sendEmail(to: EmailAddress) {
+ *   // Implementation
+ * }
+ *
+ * sendEmail(email);               // ✅ Works
+ * sendEmail('test@example.com');  // ❌ Error - needs EmailAddress brand
+ * ```
+ */
 export type Brand<T, TBrand> = T & {
     [brand]: TBrand;
 };

package/esm/types/Brand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Brand.d.ts","sourceRoot":"","sources":["../../src/types/Brand.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,CAAC,MAAM,KAAK,EAAE,OAAO,MAAM,CAAA;AAElC,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,GAAG;IAAE,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA"}
+{"version":3,"file":"Brand.d.ts","sourceRoot":"","sources":["../../src/types/Brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,sBAAsB,CAAC;AAE9B,OAAO,CAAC,MAAM,KAAK,EAAE,OAAO,MAAM,CAAA;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,GAAG;IAAE,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA"}

package/esm/types/Brand.js

@@ -1 +1,10 @@
+/**
+ * Unique symbol used for branding types.
+ *
+ * This symbol is used internally by the {@link Brand} type to create
+ * unique branded types that are structurally identical but nominally
+ * distinct from their base types.
+ *
+ * @internal
+ */
 import "../_dnt.polyfills.js";