@twin.org/tools-core 0.0.3-next.15 → 0.0.3-next.17

package/docs/reference/classes/Utility.md

@@ -0,0 +1,164 @@
+# Class: Utility
+
+General-purpose utility methods for working with TypeScript AST nodes.
+
+Enum-related helpers live in TypeScriptEnum.
+Reference-mapping regex helpers live in TypeScriptRegEx.
+
+## Constructors
+
+### Constructor
+
+> **new Utility**(): `Utility`
+
+#### Returns
+
+`Utility`
+
+## Methods
+
+### isTypeNameInput() {#istypenameinput}
+
+> `static` **isTypeNameInput**(`value`): `boolean`
+
+Determine whether an input value is a valid TypeScript type identifier.
+An identifier must start with a letter, underscore, or dollar sign and contain only
+alphanumerics, underscores, or dollar signs thereafter.
+
+#### Parameters
+
+##### value
+
+`string`
+
+The value to inspect.
+
+#### Returns
+
+`boolean`
+
+True if the value looks like a type name.
+
+***
+
+### extractTupleElementType() {#extracttupleelementtype}
+
+> `static` **extractTupleElementType**(`element`): `TypeNode` \| `undefined`
+
+Extract the inner type node from a named or rest tuple element.
+Named tuple members and rest elements both wrap an inner type node; this unwraps them.
+Plain type nodes are returned as-is.
+
+#### Parameters
+
+##### element
+
+`TypeNode`
+
+The tuple element.
+
+#### Returns
+
+`TypeNode` \| `undefined`
+
+The inner type node.
+
+***
+
+### getNodeJsDocDescription() {#getnodejsdocdescription}
+
+> `static` **getNodeJsDocDescription**(`node`): `string` \| `undefined`
+
+Extract the JSDoc description comment for an AST node.
+Only top-level JSDoc block comments are considered; inline tags are ignored.
+
+#### Parameters
+
+##### node
+
+`Node`
+
+The node to inspect.
+
+#### Returns
+
+`string` \| `undefined`
+
+The trimmed description text, or undefined when absent.
+
+***
+
+### getJSDocTagCommentText() {#getjsdoctagcommenttext}
+
+> `static` **getJSDocTagCommentText**(`jsDocTag`): `string` \| `undefined`
+
+Convert a JSDoc tag's comment portion to a plain text string.
+JSDoc tag comments may be plain strings or arrays of link/text parts.
+
+#### Parameters
+
+##### jsDocTag
+
+`JSDocTag`
+
+The JSDoc tag.
+
+#### Returns
+
+`string` \| `undefined`
+
+The comment text, or undefined when absent.
+
+***
+
+### getNodeTags() {#getnodetags}
+
+> `static` **getNodeTags**(`node`, `tagName`): `object`
+
+Read all custom JSDoc tags matching a tag name from a node and convert them to key/value pairs.
+Each matching tag's comment must be in the form "key: value"; entries that do not follow this
+convention are silently skipped.
+
+#### Parameters
+
+##### node
+
+`Node`
+
+The node to inspect.
+
+##### tagName
+
+`string`
+
+The tag name to filter by (e.g., 'json-schema').
+
+#### Returns
+
+`object`
+
+The extracted key/value pairs.
+
+***
+
+### parseTagValue() {#parsetagvalue}
+
+> `static` **parseTagValue**(`value`): `unknown`
+
+Parse a custom JSDoc tag value into JSON-compatible data.
+Values that begin with a JSON token character ({, [, ", true, false, null) or look like a
+number are parsed with JSON.parse.  All other values are returned as plain strings.
+
+#### Parameters
+
+##### value
+
+`string`
+
+The raw value text.
+
+#### Returns
+
+`unknown`
+
+The parsed value.

package/docs/reference/classes/UtilityTypeSchemaMapper.md

@@ -0,0 +1,341 @@
+# Class: UtilityTypeSchemaMapper
+
+Static utility-type schema mapping helpers.
+
+## Constructors
+
+### Constructor
+
+> **new UtilityTypeSchemaMapper**(): `UtilityTypeSchemaMapper`
+
+#### Returns
+
+`UtilityTypeSchemaMapper`
+
+## Methods
+
+### mapPartialUtilityType() {#mappartialutilitytype}
+
+> `static` **mapPartialUtilityType**(`context`, `typeNode`, `resolveUtilityBaseObjectSchema`): `IJsonSchema` \| `undefined`
+
+Map Partial<T> to an object schema with no required properties.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+The generation context.
+
+##### typeNode
+
+`TypeReferenceNode`
+
+The Partial type reference.
+
+##### resolveUtilityBaseObjectSchema
+
+(`context`, `baseTypeNode`) => `IJsonSchema` \| `undefined`
+
+Callback to resolve base object schemas.
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+The mapped schema.
+
+***
+
+### mapRequiredUtilityType() {#maprequiredutilitytype}
+
+> `static` **mapRequiredUtilityType**(`context`, `typeNode`, `resolveUtilityBaseObjectSchema`): `IJsonSchema` \| `undefined`
+
+Map Required<T> to an object schema with all properties required.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+The generation context.
+
+##### typeNode
+
+`TypeReferenceNode`
+
+The Required type reference.
+
+##### resolveUtilityBaseObjectSchema
+
+(`context`, `baseTypeNode`) => `IJsonSchema` \| `undefined`
+
+Callback to resolve base object schemas.
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+The mapped schema.
+
+***
+
+### mapPickUtilityType() {#mappickutilitytype}
+
+> `static` **mapPickUtilityType**(`context`, `typeNode`, `resolveUtilityBaseObjectSchema`, `extractUtilityTypeKeys`): `IJsonSchema` \| `undefined`
+
+Map Pick<T, K> to an object schema with selected keys preserved.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+##### typeNode
+
+`TypeReferenceNode`
+
+##### resolveUtilityBaseObjectSchema
+
+(`context`, `baseTypeNode`) => `IJsonSchema` \| `undefined`
+
+##### extractUtilityTypeKeys
+
+(`context`, `keysNode`) => `string`[]
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+***
+
+### mapOmitUtilityType() {#mapomitutilitytype}
+
+> `static` **mapOmitUtilityType**(`context`, `typeNode`, `resolveUtilityBaseObjectSchema`, `extractUtilityTypeKeys`): `IJsonSchema` \| `undefined`
+
+Map Omit<T, K> to an object schema with selected keys removed.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+##### typeNode
+
+`TypeReferenceNode`
+
+##### resolveUtilityBaseObjectSchema
+
+(`context`, `baseTypeNode`) => `IJsonSchema` \| `undefined`
+
+##### extractUtilityTypeKeys
+
+(`context`, `keysNode`) => `string`[]
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+***
+
+### mapExcludeUtilityType() {#mapexcludeutilitytype}
+
+> `static` **mapExcludeUtilityType**(`context`, `typeNode`, `mapTypeNodeToSchema`): `IJsonSchema` \| `undefined`
+
+Map Exclude<T, U> to a schema that removes U members from T.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+##### typeNode
+
+`TypeReferenceNode`
+
+##### mapTypeNodeToSchema
+
+(`context`, `typeNode`) => `IJsonSchema` \| `undefined`
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+***
+
+### mapExtractUtilityType() {#mapextractutilitytype}
+
+> `static` **mapExtractUtilityType**(`context`, `typeNode`, `mapTypeNodeToSchema`): `IJsonSchema` \| `undefined`
+
+Map Extract<T, U> to a schema that keeps U members from T.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+##### typeNode
+
+`TypeReferenceNode`
+
+##### mapTypeNodeToSchema
+
+(`context`, `typeNode`) => `IJsonSchema` \| `undefined`
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+***
+
+### mapNonNullableUtilityType() {#mapnonnullableutilitytype}
+
+> `static` **mapNonNullableUtilityType**(`context`, `typeNode`, `mapTypeNodeToSchema`): `IJsonSchema` \| `undefined`
+
+Map NonNullable<T> by removing null and undefined branches from T.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+##### typeNode
+
+`TypeReferenceNode`
+
+##### mapTypeNodeToSchema
+
+(`context`, `typeNode`) => `IJsonSchema` \| `undefined`
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+***
+
+### mapRecordUtilityType() {#maprecordutilitytype}
+
+> `static` **mapRecordUtilityType**(`context`, `typeNode`, `mapTypeNodeToSchema`): `IJsonSchema` \| `undefined`
+
+Map Record<K, V> to an object schema with key constraints where possible.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+##### typeNode
+
+`TypeReferenceNode`
+
+##### mapTypeNodeToSchema
+
+(`context`, `typeNode`) => `IJsonSchema` \| `undefined`
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+***
+
+### mapJsonLdObjectUtilityType() {#mapjsonldobjectutilitytype}
+
+> `static` **mapJsonLdObjectUtilityType**(`context`, `typeNode`, `options`, `resolveUtilityBaseObjectSchema`, `mapTypeNodeToSchema`): `IJsonSchema` \| `undefined`
+
+Map JsonLdObject utility types using key-removal and optional key-addition rules.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+##### typeNode
+
+`TypeReferenceNode`
+
+##### options
+
+###### keysToRemove
+
+`string`[]
+
+###### keyToAdd?
+
+`"type"` \| `"id"` \| `"@id"` \| `"@type"` \| `"@context"`
+
+###### isAddedKeyRequired?
+
+`boolean`
+
+##### resolveUtilityBaseObjectSchema
+
+(`context`, `baseTypeNode`) => `IJsonSchema` \| `undefined`
+
+##### mapTypeNodeToSchema
+
+(`context`, `typeNode`) => `IJsonSchema` \| `undefined`
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+***
+
+### mapObjectOrArrayUtilityType() {#mapobjectorarrayutilitytype}
+
+> `static` **mapObjectOrArrayUtilityType**(`context`, `typeNode`, `mapTypeNodeToSchema`): `IJsonSchema` \| `undefined`
+
+Map ObjectOrArray<T> to a schema accepting T or T[].
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+##### typeNode
+
+`TypeReferenceNode`
+
+##### mapTypeNodeToSchema
+
+(`context`, `typeNode`) => `IJsonSchema` \| `undefined`
+
+#### Returns
+
+`IJsonSchema` \| `undefined`
+
+***
+
+### mapSingleOccurrenceArrayUtilityType() {#mapsingleoccurrencearrayutilitytype}
+
+> `static` **mapSingleOccurrenceArrayUtilityType**(`context`, `typeNode`, `mapTypeNodeToSchema`): `IJsonSchema` \| `undefined`
+
+Map SingleOccurrenceArray<T, U> to a non-empty array containing exactly one U.
+
+#### Parameters
+
+##### context
+
+[`ITypeScriptToSchemaContext`](../interfaces/ITypeScriptToSchemaContext.md)
+
+##### typeNode
+
+`TypeReferenceNode`
+
+##### mapTypeNodeToSchema
+
+(`context`, `typeNode`) => `IJsonSchema` \| `undefined`
+
+#### Returns
+
+`IJsonSchema` \| `undefined`

package/docs/reference/index.md

@@ -2,20 +2,26 @@
 
 ## Classes
 
-- [JsonSchemaHelper](classes/JsonSchemaHelper.md)
-- [OpenApiHelper](classes/OpenApiHelper.md)
+- [Constants](classes/Constants.md)
+- [DiagnosticReporter](classes/DiagnosticReporter.md)
+- [DisallowedTypeGuard](classes/DisallowedTypeGuard.md)
+- [Enum](classes/Enum.md)
+- [FileUtils](classes/FileUtils.md)
+- [ImportTypeQuerySchemaResolver](classes/ImportTypeQuerySchemaResolver.md)
+- [IndexSignaturePatternResolver](classes/IndexSignaturePatternResolver.md)
+- [IntersectionSchemaMerger](classes/IntersectionSchemaMerger.md)
+- [JsonSchemaBuilder](classes/JsonSchemaBuilder.md)
+- [MappedTypeSchemaResolver](classes/MappedTypeSchemaResolver.md)
+- [ObjectTransformer](classes/ObjectTransformer.md)
+- [RegEx](classes/RegEx.md)
+- [Resolver](classes/Resolver.md)
+- [TemplateLiteralPatternBuilder](classes/TemplateLiteralPatternBuilder.md)
+- [TypeScriptToSchema](classes/TypeScriptToSchema.md)
+- [Utility](classes/Utility.md)
+- [UtilityTypeSchemaMapper](classes/UtilityTypeSchemaMapper.md)
 
 ## Interfaces
 
-- [IOpenApi](interfaces/IOpenApi.md)
-- [IOpenApiExample](interfaces/IOpenApiExample.md)
-- [IOpenApiHeader](interfaces/IOpenApiHeader.md)
-- [IOpenApiPathMethod](interfaces/IOpenApiPathMethod.md)
-- [IOpenApiResponse](interfaces/IOpenApiResponse.md)
-- [IOpenApiSecurityScheme](interfaces/IOpenApiSecurityScheme.md)
-- [IPackageJson](interfaces/IPackageJson.md)
-
-## Type Aliases
-
-- [IJsonSchema](type-aliases/IJsonSchema.md)
-- [JsonTypeName](type-aliases/JsonTypeName.md)
+- [ITypeScriptToSchemaContext](interfaces/ITypeScriptToSchemaContext.md)
+- [ITypeScriptToSchemaDiagnostics](interfaces/ITypeScriptToSchemaDiagnostics.md)
+- [ITypeScriptToSchemaOptions](interfaces/ITypeScriptToSchemaOptions.md)

package/docs/reference/interfaces/ITypeScriptToSchemaContext.md

@@ -0,0 +1,113 @@
+# Interface: ITypeScriptToSchemaContext
+
+Context for TypeScript to JSON schema generation.
+
+## Properties
+
+### namespace {#namespace}
+
+> **namespace**: `string`
+
+The namespace for generated schema ids.
+
+***
+
+### packageName {#packagename}
+
+> **packageName**: `string`
+
+The package name for generated schema ids.
+
+***
+
+### schemas {#schemas}
+
+> **schemas**: `object`
+
+The schema cache indexed by package and title.
+
+#### Index Signature
+
+\[`id`: `string`\]: `object`
+
+***
+
+### activeSourceFile? {#activesourcefile}
+
+> `optional` **activeSourceFile?**: `SourceFile`
+
+The currently active source file being mapped.
+
+***
+
+### activeEnclosingObjectName? {#activeenclosingobjectname}
+
+> `optional` **activeEnclosingObjectName?**: `string`
+
+The currently active enclosing object (interface/type) being mapped.
+
+***
+
+### activeDisallowedType? {#activedisallowedtype}
+
+> `optional` **activeDisallowedType?**: `object`
+
+The first disallowed type encountered while mapping the active enclosing object.
+
+#### disallowedTypeName
+
+> **disallowedTypeName**: `string`
+
+#### propertyName
+
+> **propertyName**: `string`
+
+#### enclosingObjectName
+
+> **enclosingObjectName**: `string`
+
+***
+
+### resolvingTypeNames? {#resolvingtypenames}
+
+> `optional` **resolvingTypeNames?**: `Set`\<`string`\>
+
+Type names currently being resolved to avoid recursive local-type expansion loops.
+
+***
+
+### resolvingUtilityTypes? {#resolvingutilitytypes}
+
+> `optional` **resolvingUtilityTypes?**: `Set`\<`string`\>
+
+Utility type names currently being processed to avoid infinite recursion cycles
+when encountering complex combinations of indexed access types, keyof, and utility types.
+
+***
+
+### resolvingImportedObjectSchemas? {#resolvingimportedobjectschemas}
+
+> `optional` **resolvingImportedObjectSchemas?**: `Set`\<`string`\>
+
+Imported utility base schemas currently being resolved to avoid recursive re-entry
+while parsing module graphs for utility type application.
+
+***
+
+### typeParameterBindings? {#typeparameterbindings}
+
+> `optional` **typeParameterBindings?**: `object`
+
+Generic type parameter bindings active for the current mapping scope.
+
+#### Index Signature
+
+\[`id`: `string`\]: `TypeNode` \| `null`
+
+***
+
+### options? {#options}
+
+> `optional` **options?**: [`ITypeScriptToSchemaOptions`](ITypeScriptToSchemaOptions.md)
+
+Optional schema generation options.

package/docs/reference/interfaces/ITypeScriptToSchemaDiagnostics.md

@@ -0,0 +1,55 @@
+# Interface: ITypeScriptToSchemaDiagnostics
+
+Diagnostic payload for non-fatal schema generation issues.
+
+## Properties
+
+### code {#code}
+
+> **code**: `string`
+
+Stable diagnostic code identifying the issue type.
+
+***
+
+### properties? {#properties}
+
+> `optional` **properties?**: `object`
+
+Additional structured metadata related to the diagnostic.
+
+#### Index Signature
+
+\[`key`: `string`\]: `unknown`
+
+***
+
+### path {#path}
+
+> **path**: `string`
+
+Schema path where the issue was detected.
+
+***
+
+### fileName? {#filename}
+
+> `optional` **fileName?**: `string`
+
+Source file where the diagnostic originated, if available.
+
+***
+
+### line? {#line}
+
+> `optional` **line?**: `number`
+
+One-based source line number, when available.
+
+***
+
+### column? {#column}
+
+> `optional` **column?**: `number`
+
+One-based source column number, when available.