@twin.org/tools-core 0.0.3-next.9 → 0.0.4-next.1

package/docs/reference/classes/UtilityTypeSchemaMapper.md

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

package/docs/reference/index.md

@@ -2,20 +2,34 @@
 
 ## 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)
+- [JsDoc](classes/JsDoc.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)
+- [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)
+- [ITypeScriptToSchemaContext](interfaces/ITypeScriptToSchemaContext.md)
+- [ITypeScriptToSchemaDiagnostics](interfaces/ITypeScriptToSchemaDiagnostics.md)
+- [ITypeScriptToSchemaOptions](interfaces/ITypeScriptToSchemaOptions.md)
 
 ## Type Aliases
 
-- [IJsonSchema](type-aliases/IJsonSchema.md)
-- [JsonTypeName](type-aliases/JsonTypeName.md)
+- [EmbeddedSchemaMode](type-aliases/EmbeddedSchemaMode.md)
+
+## Variables
+
+- [EmbeddedSchemaMode](variables/EmbeddedSchemaMode.md)

package/docs/reference/interfaces/ITypeScriptToSchemaContext.md

@@ -0,0 +1,125 @@
+# 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`
+
+***
+
+### embeddedSchemaModes? {#embeddedschemamodes}
+
+> `optional` **embeddedSchemaModes?**: `object`
+
+Schema ids marked with
+
+#### Index Signature
+
+\[`id`: `string`\]: [`EmbeddedSchemaMode`](../type-aliases/EmbeddedSchemaMode.md)
+
+***
+
+### 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.

package/docs/reference/interfaces/ITypeScriptToSchemaOptions.md

@@ -0,0 +1,44 @@
+# Interface: ITypeScriptToSchemaOptions
+
+Options for TypeScript to JSON schema generation.
+
+## Properties
+
+### externalReferences? {#externalreferences}
+
+> `optional` **externalReferences?**: `object`
+
+Mapping of package ids, type ids, wildcard patterns, or regex patterns to schema id prefixes
+or replacement templates for referenced schemas.
+
+#### Index Signature
+
+\[`id`: `string`\]: `string`
+
+***
+
+### onDiagnostic? {#ondiagnostic}
+
+> `optional` **onDiagnostic?**: (`diagnostic`) => `void`
+
+Optional diagnostic callback for non-fatal generation issues.
+
+#### Parameters
+
+##### diagnostic
+
+[`ITypeScriptToSchemaDiagnostics`](ITypeScriptToSchemaDiagnostics.md)
+
+The diagnostic details for the generation issue.
+
+#### Returns
+
+`void`
+
+***
+
+### suppressPackageWarnings? {#suppresspackagewarnings}
+
+> `optional` **suppressPackageWarnings?**: `string`[]
+
+Package names where diagnostics should be suppressed, e.g. jose.

package/docs/reference/type-aliases/EmbeddedSchemaMode.md

@@ -0,0 +1,5 @@
+# Type Alias: EmbeddedSchemaMode
+
+> **EmbeddedSchemaMode** = *typeof* [`EmbeddedSchemaMode`](../variables/EmbeddedSchemaMode.md)\[keyof *typeof* [`EmbeddedSchemaMode`](../variables/EmbeddedSchemaMode.md)\]
+
+The embedded schema mode value type.

package/docs/reference/variables/EmbeddedSchemaMode.md

@@ -0,0 +1,19 @@
+# Variable: EmbeddedSchemaMode
+
+> `const` **EmbeddedSchemaMode**: `object`
+
+The available embedded schema modes.
+
+## Type Declaration
+
+### Defs {#defs}
+
+> `readonly` **Defs**: `"defs"` = `"defs"`
+
+Referenced schemas are added to the "defs" section of the root schema.
+
+### Inline {#inline}
+
+> `readonly` **Inline**: `"inline"` = `"inline"`
+
+Referenced schemas are inlined into the referencing schema.

package/locales/en.json

@@ -1,3 +1,34 @@
 {
-	"error": {}
+	"error": {
+		"jsonSchemaBuilder": {
+			"invalidJsonSchemaTagKey": "Ignoring invalid @json-schema tag key \"{rawKey}\". Mapped key \"{schemaKey}\" is not supported by JSON Schema.",
+			"constraintOnIncompatibleType": "The @json-schema \"{schemaKey}\" constraint requires type \"{requiredType}\" but the type is \"{schemaType}\".",
+			"invalidFormatValue": "The @json-schema \"format\" value \"{formatValue}\" is not a recognised JSON Schema format. Valid values are: {validFormats}.",
+			"missingTypeReferenceSchema": "Unable to resolve type \"{typeName}\"{importSource} required as base type for utility type. Ensure the type is in the configured packages list or its external package exports TypeScript source files that can be parsed via the AST."
+		}
+	},
+	"jsonSchemaBuilder": {
+		"diagnostic": {
+			"symbolValuedProperty": "Skipping symbol-typed property \"{propertyName}\".",
+			"symbolKeyedMember": "Skipping symbol-keyed member \"{memberName}\".",
+			"unsupportedComputedPropertyName": "Skipping unsupported computed property name \"{propertyName}\".",
+			"functionTypedProperty": "Skipping function-typed property \"{propertyName}\".",
+			"unsupportedIndexSignature": "Skipping index signature with unsupported key type \"{keyType}\".",
+			"unresolvedKeyofOperand": "Could not resolve keyof operand \"{operand}\".",
+			"unmappedTypeNode": "Unsupported TypeScript type node kind \"{kind}\"; the type will be omitted.",
+			"unresolvedMappedTypeRemap": "Could not resolve mapped type key remap for \"{typeName}\"; falling back to additionalProperties.",
+			"unsupportedImportTypeForm": "Skipping unsupported import type form \"{argument}\".",
+			"unresolvedImportTypeQualifier": "Could not resolve import type qualifier for \"{argument}\".",
+			"unresolvedTypeQueryTarget": "Could not resolve type query target \"{target}\".",
+			"unsupportedInferredExpressionKind": "Skipping unsupported inferred expression kind \"{kind}\".",
+			"unsupportedInferredObjectComputedKey": "Skipping inferred object property with unsupported computed key \"{propertyName}\".",
+			"unsupportedInferredObjectSpread": "Skipping inferred object spread expression \"{expression}\".",
+			"unsupportedInferredObjectMemberKind": "Skipping inferred object member kind \"{kind}\".",
+			"unsupportedInferredTupleElement": "Skipping unsupported inferred tuple element kind \"{kind}\".",
+			"unsupportedTemplateLiteralSpan": "Could not derive a regex pattern for template literal type \"{type}\"; falling back to string.",
+			"unsupportedTypeElementMember": "Skipping unsupported type member kind \"{kind}\".",
+			"unsupportedUtilityType": "Skipping unsupported utility type \"{utilityType}\".",
+			"excludedEnclosingObjectDisallowedType": "Excluding enclosing object \"{enclosingObjectName}\" because property \"{propertyName}\" uses disallowed type \"{disallowedTypeName}\"."
+		}
+	}
 }

package/package.json

@@ -1,10 +1,10 @@
 {
 	"name": "@twin.org/tools-core",
-	"version": "0.0.3-next.9",
-	"description": "Shared components for the tools",
+	"version": "0.0.4-next.1",
+	"description": "Shared utilities and models for tooling packages",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/twinfoundation/tools.git",
+		"url": "git+https://github.com/iotaledger/twin-tools.git",
 		"directory": "packages/tools-core"
 	},
 	"author": "martyn.janes@iota.org",
@@ -16,7 +16,8 @@
 	"dependencies": {
 		"@twin.org/core": "next",
 		"@twin.org/nameof": "next",
-		"ajv": "8.17.1"
+		"@twin.org/tools-models": "0.0.4-next.1",
+		"glob": "13.0.6"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",
@@ -46,7 +47,7 @@
 		"utilities"
 	],
 	"bugs": {
-		"url": "git+https://github.com/twinfoundation/tools/issues"
+		"url": "git+https://github.com/iotaledger/twin-tools/issues"
 	},
 	"homepage": "https://twindev.org"
 }