@twin.org/tools-core 0.0.3-next.3 → 0.0.3-next.31

package/dist/types/utils/mappedTypeSchemaResolver.d.ts

@@ -0,0 +1,81 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+import * as ts from "typescript";
+import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaContext.js";
+/**
+ * Static mapped-type schema transformation helpers.
+ */
+export declare class MappedTypeSchemaResolver {
+    /**
+     * Resolve mapped type output keys, including remapped key names via `as`.
+     * @param context The generation context.
+     * @param typeNode The mapped type node.
+     * @param mappedKeys The resolved source keys from the mapped type constraint.
+     * @param mappedTypeParameterName The mapped type parameter identifier.
+     * @returns The resolved source-to-output mapped key entries.
+     */
+    static resolveMappedTypePropertyEntries(context: ITypeScriptToSchemaContext, typeNode: ts.MappedTypeNode, mappedKeys: string[], mappedTypeParameterName: string): {
+        sourceKey: string;
+        mappedKey: string;
+    }[] | undefined;
+    /**
+     * Resolve a remapped mapped-type key expression for a concrete source key.
+     * @param context The generation context.
+     * @param nameTypeNode The mapped type name remapping expression node.
+     * @param sourceKey The concrete source key currently being evaluated.
+     * @param mappedTypeParameterName The mapped type parameter identifier.
+     * @returns The remapped key, null when excluded via never, or undefined when unresolved.
+     */
+    static resolveMappedTypeRemappedKey(context: ITypeScriptToSchemaContext, nameTypeNode: ts.TypeNode, sourceKey: string, mappedTypeParameterName: string): string | null | undefined;
+    /**
+     * Evaluate whether a concrete mapped key satisfies an `extends` condition.
+     * @param context The generation context.
+     * @param sourceKey The concrete source key being evaluated.
+     * @param extendsTypeNode The extends condition type node.
+     * @returns True when the key satisfies the condition, false when it does not, otherwise undefined.
+     */
+    static evaluateMappedKeyExtendsCondition(context: ITypeScriptToSchemaContext, sourceKey: string, extendsTypeNode: ts.TypeNode): boolean | undefined;
+    /**
+     * Build a conservative fallback schema for mapped types whose key remapping cannot be resolved.
+     * @param context The generation context.
+     * @param typeNode The mapped type node.
+     * @param mappedKeys The resolved source keys from the mapped type constraint.
+     * @param mappedTypeParameterName The mapped type parameter identifier.
+     * @param sourceObjectSchema The optional source object schema for property lookups.
+     * @returns The fallback mapped type schema.
+     */
+    static buildMappedTypeFallbackSchema(context: ITypeScriptToSchemaContext, typeNode: ts.MappedTypeNode, mappedKeys: string[], mappedTypeParameterName: string, sourceObjectSchema?: IJsonSchema): IJsonSchema;
+    /**
+     * Build fallback additionalProperties for unresolved mapped key remapping.
+     * @param context The generation context.
+     * @param typeNode The mapped type node.
+     * @param mappedKeys The resolved source keys from the mapped type constraint.
+     * @param mappedTypeParameterName The mapped type parameter identifier.
+     * @param sourceObjectSchema The optional source object schema for property lookups.
+     * @returns The fallback additionalProperties schema.
+     */
+    static buildMappedTypeFallbackAdditionalProperties(context: ITypeScriptToSchemaContext, typeNode: ts.MappedTypeNode, mappedKeys: string[], mappedTypeParameterName: string, sourceObjectSchema?: IJsonSchema): IJsonSchema | undefined;
+    /**
+     * Merge mapped property schemas when multiple source keys remap to the same output key.
+     * @param existingSchema The existing schema already assigned to the mapped key.
+     * @param nextSchema The next schema to merge into the mapped key.
+     * @returns The merged schema.
+     */
+    static mergeMappedTypePropertySchemas(existingSchema: IJsonSchema, nextSchema: IJsonSchema): IJsonSchema;
+    /**
+     * Resolve required remapped keys from the source object's required key set.
+     * @param mappedEntries The source-to-output mapped key entries.
+     * @param sourceObjectSchema The source object schema containing required keys.
+     * @returns The required output keys.
+     */
+    static resolveMappedTypeSourceRequiredPropertyKeys(mappedEntries: {
+        sourceKey: string;
+        mappedKey: string;
+    }[], sourceObjectSchema: IJsonSchema): string[] | undefined;
+    /**
+     * Apply TypeScript intrinsic string remapping helpers to a key.
+     * @param intrinsicName The intrinsic helper name.
+     * @param value The input key value.
+     * @returns The remapped key value.
+     */
+    private static applyIntrinsicMappedTypeKeyRemap;
+}

package/dist/types/utils/objectTransformer.d.ts

@@ -0,0 +1,33 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+/**
+ * Applies common object-schema transformations used by the builder.
+ */
+export declare class ObjectTransformer {
+    /**
+     * Resolve a property schema from an object schema by property key.
+     * @param baseSchema The source object schema.
+     * @param propertyKey The property key to resolve.
+     * @returns The resolved property schema.
+     */
+    static resolvePropertySchemaFromObjectSchema(baseSchema: IJsonSchema, propertyKey: string): IJsonSchema | undefined;
+    /**
+     * Remove keys from an object schema.
+     * @param baseSchema The source object schema.
+     * @param omittedKeys The keys to remove.
+     * @returns The transformed object schema.
+     */
+    static omitKeysFromObjectSchema(baseSchema: IJsonSchema, omittedKeys: string[]): IJsonSchema;
+    /**
+     * Keep only keys from an object schema.
+     * @param baseSchema The source object schema.
+     * @param pickedKeys The keys to keep.
+     * @returns The transformed object schema.
+     */
+    static pickKeysFromObjectSchema(baseSchema: IJsonSchema, pickedKeys: string[]): IJsonSchema;
+    /**
+     * Normalize schema description whitespace while preserving intentional line breaks.
+     * @param schema The schema to normalize.
+     * @returns The normalized schema.
+     */
+    static normalizeSchemaDescriptions(schema: IJsonSchema): IJsonSchema;
+}

package/dist/types/utils/regEx.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Utility methods for pattern matching and regex construction.
+ */
+export declare class RegEx {
+    /**
+     * Determine whether a reference mapping pattern matches an external reference.
+     * @param pattern The mapping pattern.
+     * @param packageName The external package name.
+     * @param typeName The imported type name.
+     * @param schemaTitle The derived schema title.
+     * @returns True if matched.
+     */
+    static isReferencePatternMatch(pattern: string, packageName: string, typeName: string, schemaTitle: string): boolean;
+    /**
+     * Apply a reference mapping replacement to the first matching candidate.
+     * @param pattern The mapping pattern.
+     * @param replacement The replacement template.
+     * @param packageName The external package name.
+     * @param typeName The imported type name.
+     * @param schemaTitle The derived schema title.
+     * @returns The replaced value if a candidate matches.
+     */
+    static applyReferencePatternReplacement(pattern: string, replacement: string, packageName: string, typeName: string, schemaTitle: string): string | undefined;
+}

package/dist/types/utils/resolver.d.ts

@@ -0,0 +1,22 @@
+import * as ts from "typescript";
+/**
+ * Resolve TypeScript type declarations from package names.
+ */
+export declare class Resolver {
+    /**
+     * Resolve a type declaration AST from a package and type name.
+     * @param packageName The package to inspect.
+     * @param typeName The type to resolve.
+     * @param containingFilePath An optional source file path to use as the starting point for
+     * package resolution. When provided, TypeScript module resolution walks up from that file's
+     * directory, which allows transitive dependencies installed alongside the source file (e.g.
+     * in a sub-directory node_modules) to be found even when they are not reachable from the
+     * current working directory. The path is normalised to absolute before use;
+     * falls back to process.cwd() when omitted.
+     * @returns The resolved declaration AST.
+     */
+    static resolveTypeDeclarationAst(packageName: string, typeName: string, containingFilePath?: string): {
+        sourceFile: ts.SourceFile;
+        declaration: ts.InterfaceDeclaration | ts.TypeAliasDeclaration;
+    } | undefined;
+}

package/dist/types/utils/templateLiteralPatternBuilder.d.ts

@@ -0,0 +1,12 @@
+import * as ts from "typescript";
+/**
+ * Builds regex patterns for TypeScript template literal types.
+ */
+export declare class TemplateLiteralPatternBuilder {
+    /**
+     * Build a regular-expression pattern for a template literal type.
+     * @param typeNode The template literal type node.
+     * @returns The regex pattern, or undefined if a safe pattern cannot be derived.
+     */
+    static buildTemplateLiteralPattern(typeNode: ts.TemplateLiteralTypeNode): string | undefined;
+}

package/dist/types/utils/typeScriptToSchema.d.ts

@@ -0,0 +1,92 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+import type { ITypeScriptToSchemaOptions } from "../models/ITypeScriptToSchemaOptions.js";
+/**
+ * Class for converting TypeScript types to JSON Schema.
+ */
+export declare class TypeScriptToSchema {
+    /**
+     * Generates a JSON schema from a TypeScript source file or type name.
+     * @param namespace The schema namespace.
+     * @param packageName The package name.
+     * @param schemas The package schema map.
+     * @param sourceFileOrTypeName The source file to process or type name to resolve.
+     * @param options Additional generation options.
+     * @returns The generated JSON schemas indexed by title.
+     */
+    generateSchema(namespace: string, packageName: string, schemas: {
+        [id: string]: {
+            [id: string]: IJsonSchema;
+        };
+    }, sourceFileOrTypeName: string, options?: ITypeScriptToSchemaOptions): Promise<{
+        [id: string]: IJsonSchema;
+    }>;
+    /**
+     * Determine if a diagnostic originates from a specific package.
+     * @param path The schema or source path associated with the diagnostic.
+     * @param fileName The source filename associated with the diagnostic.
+     * @param packageName The package name to check, e.g. jose.
+     * @returns True if the diagnostic originated from the package.
+     */
+    isDiagnosticFromPackage(path: string, fileName: string | undefined, packageName: string): boolean;
+    /**
+     * Rewrite refs to @json-schema embedded local types into the current schema's $defs.
+     * @param context The generation context.
+     * @param schema The root schema to rewrite.
+     * @param rootTitle The title of the root schema.
+     */
+    private inlineEmbeddedSchemas;
+    /**
+     * Traverse a schema tree and move embedded local refs into the root schema's $defs.
+     * @param context The generation context.
+     * @param rootSchema The root schema document being rewritten.
+     * @param currentNode The current schema node.
+     * @param rootTitle The title of the root schema.
+     * @param ancestry Titles currently being expanded to avoid recursion cycles.
+     * @returns True if inline embedding changed this node or a descendant.
+     */
+    private inlineEmbeddedSchemasInNode;
+    /**
+     * Flatten inline-expanded object allOf branches into the containing schema.
+     * @param schema The schema to flatten.
+     */
+    private flattenInlineAllOfBranches;
+    /**
+     * Determine whether an allOf branch can be flattened into its parent after inline embedding.
+     * @param branch The allOf branch.
+     * @returns True if the branch is a plain object schema.
+     */
+    private canFlattenInlineAllOfBranch;
+    /**
+     * Create a clone of an embedded schema suitable for defs or inline expansion.
+     * @param context The generation context.
+     * @param embeddedSchema The source schema.
+     * @param embeddedMode The embedding mode.
+     * @returns The cloned schema.
+     */
+    private createEmbeddedSchemaClone;
+    /**
+     * Replace the contents of a schema node while keeping the same object reference.
+     * @param target The schema node to mutate.
+     * @param replacement The replacement content.
+     */
+    private replaceSchemaNode;
+    /**
+     * Find a generated schema by its canonical id across all loaded packages.
+     * @param context The generation context.
+     * @param schemaId The schema id to locate.
+     * @returns The schema when found.
+     */
+    private findSchemaById;
+    /**
+     * Resolve the local $defs key to use for an embedded schema.
+     * @param schema The embedded schema.
+     * @param schemaId The canonical schema id.
+     * @returns The local definition key.
+     */
+    private getEmbeddedDefinitionKey;
+    /**
+     * Remove $comment fields from a schema tree.
+     * @param schema The schema tree to clean.
+     */
+    private removeSchemaComments;
+}

package/dist/types/utils/utilityTypeSchemaMapper.d.ts

@@ -0,0 +1,141 @@
+import type { IJsonSchema } from "@twin.org/tools-models";
+import * as ts from "typescript";
+import type { ITypeScriptToSchemaContext } from "../models/ITypeScriptToSchemaContext.js";
+/**
+ * Static utility-type schema mapping helpers.
+ */
+export declare class UtilityTypeSchemaMapper {
+    /**
+     * Map `Partial<T>` to an object schema with no required properties.
+     * @param context The generation context.
+     * @param typeNode The `Partial` type reference.
+     * @returns The mapped schema.
+     */
+    static mapPartialUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map `Required<T>` to an object schema with all properties required.
+     * @param context The generation context.
+     * @param typeNode The `Required` type reference.
+     * @returns The mapped schema.
+     */
+    static mapRequiredUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map `Pick<T, K>` to an object schema with selected keys preserved.
+     * @param context The generation context.
+     * @param typeNode The Pick type reference.
+     * @returns The mapped schema.
+     */
+    static mapPickUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map `Omit<T, K>` to an object schema with selected keys removed.
+     * @param context The generation context.
+     * @param typeNode The `Omit` type reference.
+     * @returns The mapped schema.
+     */
+    static mapOmitUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map `Exclude<T, U>` to a schema that removes `U` members from `T`.
+     * @param context The generation context.
+     * @param typeNode The `Exclude` type reference.
+     * @returns The mapped schema.
+     */
+    static mapExcludeUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map `Extract<T, U>` to a schema that keeps `U` members from `T`.
+     * @param context The generation context.
+     * @param typeNode The `Extract` type reference.
+     * @returns The mapped schema.
+     */
+    static mapExtractUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map `NonNullable<T>` by removing `null` and `undefined` branches from `T`.
+     * @param context The generation context.
+     * @param typeNode The `NonNullable` type reference.
+     * @returns The mapped schema.
+     */
+    static mapNonNullableUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map `Record<K, V>` to an object schema with key constraints where possible.
+     * @param context The generation context.
+     * @param typeNode The `Record` type reference.
+     * @returns The mapped schema.
+     */
+    static mapRecordUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map `JsonLdObject` utility types using key-removal and optional key-addition rules.
+     * @param context The generation context.
+     * @param typeNode The `JsonLdObject` utility type reference.
+     * @param options The mapping options for key removal and optional key addition.
+     * @param options.keysToRemove The property keys to remove from the base schema.
+     * @param options.keyToAdd The optional key to add after removal.
+     * @param options.isAddedKeyRequired True when the added key must be required.
+     * @returns The mapped schema.
+     */
+    static mapJsonLdObjectUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode, options: {
+        keysToRemove: string[];
+        keyToAdd?: "id" | "@id" | "type" | "@type" | "@context";
+        isAddedKeyRequired?: boolean;
+    }): IJsonSchema | undefined;
+    /**
+     * Map `ObjectOrArray<T>` to a schema accepting `T` or `T[]`.
+     * @param context The generation context.
+     * @param typeNode The `ObjectOrArray` type reference.
+     * @returns The mapped schema.
+     */
+    static mapObjectOrArrayUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Map `SingleOccurrenceArray<T, U>` to a non-empty array containing exactly one `U`.
+     * @param context The generation context.
+     * @param typeNode The `SingleOccurrenceArray` type reference.
+     * @returns The mapped schema.
+     */
+    static mapSingleOccurrenceArrayUtilityType(context: ITypeScriptToSchemaContext, typeNode: ts.TypeReferenceNode): IJsonSchema | undefined;
+    /**
+     * Determine whether a type node represents null or undefined.
+     * @param typeNode The type node to inspect.
+     * @returns True if the node represents null or undefined; otherwise false.
+     */
+    private static isNullOrUndefinedTypeNode;
+    /**
+     * Extract literal keys from a Record key type argument.
+     * @param keyTypeNode The Record key type argument to inspect.
+     * @returns The extracted literal keys.
+     */
+    private static extractRecordLiteralKeys;
+    /**
+     * Resolve a default schema for JsonLdObject utility key additions when the type argument is omitted.
+     * @param context The generation context.
+     * @param baseSchema The base object schema being transformed.
+     * @param keyToAdd The key to add when no explicit value type argument is provided.
+     * @returns The resolved default schema for the added key.
+     */
+    private static mapJsonLdObjectDefaultSchemaByKey;
+    /**
+     * Resolve default id schema for JsonLdObjectWithId when Id type argument is omitted.
+     * @param baseSchema The base object schema being transformed.
+     * @returns The default id schema.
+     */
+    private static mapJsonLdObjectWithIdDefaultIdSchema;
+    /**
+     * Resolve default type schema for JsonLdObjectWithType when Type argument is omitted.
+     * @param baseSchema The base object schema being transformed.
+     * @returns The default type schema.
+     */
+    private static mapJsonLdObjectWithTypeDefaultTypeSchema;
+    /**
+     * Resolve default context schema for JsonLdObjectWithContext when Context argument is omitted.
+     * @param context The generation context.
+     * @param baseSchema The base object schema being transformed.
+     * @returns The default context schema.
+     */
+    private static mapJsonLdObjectWithContextDefaultContextSchema;
+    /**
+     * Resolve default schema from either of two source keys, with fallback when both are absent.
+     * @param baseSchema The base object schema being transformed.
+     * @param firstKey The first property key to check.
+     * @param secondKey The second property key to check.
+     * @param fallbackSchema The fallback schema when neither key is present.
+     * @returns The resolved schema.
+     */
+    private static mapJsonLdObjectDefaultEitherSchema;
+}