@skmtc/core 0.0.786 → 0.0.788

package/script/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/script/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/script/types/Brand.js

@@ -1,3 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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
+ */
 require("../_dnt.polyfills.js");

package/script/types/RefName.d.ts

@@ -1,4 +1,65 @@
 import "../_dnt.polyfills.js";
 import type { Brand } from './Brand.js';
+/**
+ * Branded type representing a reference name for OpenAPI schemas.
+ *
+ * `RefName` is a branded string type that ensures type safety when working
+ * with schema reference names throughout the SKMTC system. It prevents
+ * accidental mixing of regular strings with schema reference identifiers.
+ *
+ * Reference names typically correspond to keys in the OpenAPI `components.schemas`
+ * section and are used to create cross-references between different parts
+ * of the schema definition.
+ *
+ * @example
+ * ```typescript
+ * import { RefName } from '@skmtc/core';
+ *
+ * // RefName is extracted from OpenAPI schema references
+ * const userRefName: RefName = 'User' as RefName;
+ * const productRefName: RefName = 'Product' as RefName;
+ *
+ * // Used in schema references
+ * const userRef = new OasRef({
+ *   refName: userRefName, // Type-safe reference name
+ *   ref: '#/components/schemas/User'
+ * });
+ * ```
+ *
+ * @example In generator contexts
+ * ```typescript
+ * class ModelGenerator extends ModelBase {
+ *   constructor(args: { refName: RefName; ... }) {
+ *     super(args);
+ *     // this.refName is guaranteed to be a valid schema reference
+ *   }
+ *
+ *   toDefinition(): Definition {
+ *     // RefName ensures we're working with valid schema identifiers
+ *     const schemaName = this.refName; // Type: RefName
+ *     return new Definition({
+ *       identifier: Identifier.createType(schemaName),
+ *       // ...
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Type safety benefits
+ * ```typescript
+ * function processSchema(refName: RefName) {
+ *   // RefName brand ensures this is a valid schema reference
+ *   console.log(`Processing schema: ${refName}`);
+ * }
+ *
+ * const validRef: RefName = 'User' as RefName;
+ * const regularString = 'just a string';
+ *
+ * processSchema(validRef);     // ✅ Works - RefName type
+ * processSchema(regularString); // ❌ TypeScript error - string is not RefName
+ * ```
+ *
+ * @see {@link Brand} for the underlying branding mechanism
+ */
 export type RefName = Brand<string, 'RefName'>;
 //# sourceMappingURL=RefName.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}
+{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}