@elliots/typical 0.1.10 → 0.2.0

package/dist/src/transformer.d.ts

@@ -1,204 +1,39 @@
-import ts from "typescript";
-import { TypicalConfig } from "./config.js";
-import { TransformResult } from "./source-map.js";
-export type { TransformResult } from "./source-map.js";
-export interface TransformContext {
-    ts: typeof ts;
-    factory: ts.NodeFactory;
-    context: ts.TransformationContext;
-    sourceFile: ts.SourceFile;
+/**
+ * TypicalTransformer - Thin wrapper around the Go compiler.
+ *
+ * The Go compiler (compiler) handles all TypeScript analysis
+ * and validation code generation. This class just manages the lifecycle
+ * and communication with the Go process.
+ */
+import { type RawSourceMap } from '@elliots/typical-compiler';
+import type { TypicalConfig } from './config.js';
+export interface TransformResult {
+    code: string;
+    map: RawSourceMap | null;
 }
 export declare class TypicalTransformer {
     config: TypicalConfig;
-    private program;
-    private ts;
-    private compiledPatterns;
-    private typeValidators;
-    private typeStringifiers;
-    private typeParsers;
-    constructor(config?: TypicalConfig, program?: ts.Program, tsInstance?: typeof ts);
+    private compiler;
+    private projectHandle;
+    private initPromise;
+    private configFile;
+    constructor(config?: TypicalConfig, configFile?: string);
     /**
-     * Create a new TypeScript program with transformed source code.
-     * This is needed so typia can resolve types from our generated typia.createAssert<T>() calls.
+     * Ensure the Go compiler is started and project is loaded.
+     * Uses lazy initialization - only starts on first transform.
      */
-    private createTypiaProgram;
+    private ensureInitialized;
     /**
-     * Write intermediate file for debugging purposes.
-     * Creates a .typical.ts file showing the code after typical's transformations
-     * but before typia processes it.
-     */
-    private writeIntermediateFile;
-    /**
-     * Format typia diagnostic errors into readable error messages.
-     */
-    private formatTypiaErrors;
-    /**
-     * Check for untransformed typia calls and throw an error if found.
-     * This is a fallback in case typia silently fails without reporting a diagnostic.
-     */
-    private checkUntransformedTypiaCalls;
-    createSourceFile(fileName: string, content: string): ts.SourceFile;
-    /**
-     * Transform options for controlling source map generation.
-     */
-    transform(sourceFile: ts.SourceFile | string, mode: "basic" | "typia" | "js", options?: {
-        sourceMap?: boolean;
-        skippedTypes?: Set<string>;
-    }): TransformResult;
-    /**
-     * Legacy transform method that returns just the code string.
-     * @deprecated Use transform() with options.sourceMap instead
-     */
-    transformCode(sourceFile: ts.SourceFile | string, mode: "basic" | "typia" | "js", skippedTypes?: Set<string>): string;
-    /**
-     * Apply typia transformation in a separate ts.transform() context.
-     * This avoids mixing program contexts and eliminates the need for import recreation.
-     * Returns either the transformed code, or a retry signal with the failed type.
-     * Source map markers in the code are preserved through the typia transformation.
-     */
-    private applyTypiaTransform;
-    /**
-     * Get a transformer that only applies typical's transformations (no typia).
-     * @param skippedTypes Set of type strings to skip validation for (used for retry after typia errors)
-     */
-    private getTypicalOnlyTransformer;
-    /**
-     * Get a combined transformer for use with ts-patch/ttsc.
-     * This is used by the TSC plugin where we need a single transformer factory.
-     *
-     * Note: Even for ts-patch, we need to create a new program with the transformed
-     * source so typia can resolve the types from our generated typia.createAssert<T>() calls.
-     */
-    getTransformer(withTypia: boolean): ts.TransformerFactory<ts.SourceFile>;
-    /**
-     * Transform JSON.stringify or JSON.parse calls to use typia's validated versions.
-     * Returns the transformed node if applicable, or undefined to indicate no transformation.
-     */
-    private transformJSONCall;
-    /**
-     * Check if a type should be skipped (failed in typia on previous attempt).
-     */
-    private shouldSkipType;
-    /**
-     * Create an AST visitor function for transforming a source file.
-     * The visitor handles JSON calls, type casts, and function declarations.
-     */
-    private createVisitor;
-    /**
-     * Transform a single source file with TypeScript AST
-     */
-    private transformSourceFile;
-    /**
-     * Add @L line markers to nodes that have original source positions.
-     * This preserves identity mappings for original code, so lines from the source
-     * file map back to themselves rather than inheriting from generated code markers.
-     *
-     * We need to add markers to every node that will be printed on its own line,
-     * including nested members of interfaces, classes, etc.
-     */
-    private addLineMarkersToStatements;
-    shouldTransformFile(fileName: string): boolean;
-    /**
-     * Get pre-compiled ignore patterns, caching them for performance.
-     */
-    private getCompiledPatterns;
-    /**
-     * Check if a TypeNode represents a type that shouldn't be validated.
-     * This includes:
-     * - any/unknown (intentional escape hatches)
-     * - Type parameters (generics like T)
-     * - Constructor types (new (...args: any[]) => T)
-     * - Function types ((...args) => T)
-     */
-    private isAnyOrUnknownType;
-    /**
-     * Check if a type contains any unvalidatable parts (type parameters, constructor types, etc.)
-     * This recursively checks intersection and union types.
-     */
-    private containsUnvalidatableType;
-    /**
-     * Check if a Type has any or unknown flags, or is a type parameter or function/constructor.
-     */
-    private isAnyOrUnknownTypeFlags;
-    /**
-     * Check if a type name matches any of the ignoreTypes patterns.
-     * Supports wildcards: "React.*" matches "React.FormEvent", "React.ChangeEvent", etc.
-     * Also handles union types: "Document | Element" is ignored if "Document" or "Element" is in ignoreTypes.
-     */
-    private isIgnoredType;
-    /**
-     * Check if a single type (not a union) should be ignored.
-     * Checks both the type name and its base classes.
-     * Uses Set-based cycle detection to handle recursive type hierarchies.
-     * @param patterns Pre-compiled RegExp patterns
-     * @param visited Set of type IDs already visited (for cycle detection)
-     */
-    private isIgnoredSingleType;
-    /**
-     * Check if a single type name matches any pre-compiled ignore pattern.
-     * @param patterns Pre-compiled RegExp patterns
-     */
-    private matchesIgnorePatternCompiled;
-    /**
-     * Find untransformed typia calls in the output code.
-     * These indicate types that typia could not process.
-     */
-    private findUntransformedTypiaCalls;
-    /**
-     * Infer type information from a JSON.stringify argument for creating a reusable stringifier.
-     */
-    private inferStringifyType;
-    /**
-     * Gets the root identifier from an expression.
-     * e.g., `user.address.city` -> "user"
-     */
-    private getRootIdentifier;
-    /**
-     * Check if a validated variable has been tainted (mutated) in the function body.
-     * A variable is tainted if it's reassigned, has properties modified, is passed
-     * to a function, has methods called on it, or if an await occurs.
-     */
-    private isTainted;
-    private addTypiaImport;
-    /**
-     * Gets type text for use as a validator map key.
-     * Uses getText() to preserve local aliases (e.g., "User1" vs "User2"),
-     * but falls back to typeToString() for synthesized nodes without source positions.
+     * Transform a TypeScript file by adding runtime validation.
      *
-     * @param typeNode The TypeNode to get a key for
-     * @param typeChecker The TypeChecker to use
-     * @param typeObj Optional Type object - use this for synthesized nodes since
-     *                getTypeFromTypeNode doesn't work correctly on them
-     */
-    private getTypeKey;
-    /**
-     * Simple string hash for creating unique identifiers from type strings.
-     */
-    private hashString;
-    /**
-     * Format typia's error message into a cleaner list format.
-     * Typia outputs verbose messages like:
-     *   "unsupported type detected\n\n- Window.ondevicemotion: unknown\n  - nonsensible intersection\n\n- Window.ondeviceorientation..."
-     * We want to extract just the problematic types and their issues.
-     */
-    private formatTypiaError;
-    /**
-     * Creates a readable name suffix from a type string.
-     * For simple identifiers like "User" or "string", returns the name directly.
-     * For complex types, returns a numeric index.
-     */
-    private getTypeNameSuffix;
-    /**
-     * Generic method to get or create a typed function (validator, stringifier, or parser).
+     * @param fileName - Path to the TypeScript file
+     * @param mode - Output mode: 'ts' returns TypeScript, 'js' would transpile (not yet supported)
+     * @returns Transformed code with validation
      */
-    private getOrCreateTypedFunction;
-    private getOrCreateValidator;
-    private getOrCreateStringifier;
-    private getOrCreateParser;
+    transform(fileName: string, mode?: 'ts' | 'js'): Promise<TransformResult>;
     /**
-     * Creates a nested property access expression from an array of identifiers.
-     * e.g., ['typia', 'json', 'createStringify'] -> typia.json.createStringify
+     * Close the Go compiler process and release resources.
+     * This immediately kills the process without waiting for pending operations.
      */
-    private createPropertyAccessChain;
-    private createValidatorStatements;
+    close(): Promise<void>;
 }