@elliots/typical 0.1.9 → 0.1.10

package/dist/src/source-map.js

@@ -0,0 +1,133 @@
+import MagicString from 'magic-string';
+import remapping from '@ampproject/remapping';
+/**
+ * Default source map options.
+ */
+export const defaultSourceMapOptions = {
+    enabled: true,
+    includeContent: true,
+    inline: false,
+};
+/**
+ * Compose multiple source maps together.
+ * Given maps [A->B, B->C], produces A->C.
+ * Maps are applied in order: first map is closest to original source.
+ */
+export function composeSourceMaps(maps, originalFileName) {
+    // Filter out null/undefined maps
+    const validMaps = maps.filter((m) => m !== null && m !== undefined);
+    if (validMaps.length === 0)
+        return null;
+    if (validMaps.length === 1) {
+        const map = validMaps[0];
+        if (typeof map === 'string') {
+            return JSON.parse(map);
+        }
+        return map;
+    }
+    // remapping expects maps in reverse order (final output first)
+    // and a loader function that returns the source map for a given file
+    const reversedMaps = [...validMaps].reverse();
+    try {
+        const result = remapping(reversedMaps, () => null);
+        return result;
+    }
+    catch (e) {
+        // If remapping fails, return the last valid map
+        console.warn('Source map composition failed:', e);
+        const lastMap = validMaps[validMaps.length - 1];
+        if (typeof lastMap === 'string') {
+            return JSON.parse(lastMap);
+        }
+        return lastMap;
+    }
+}
+/**
+ * Generate an inline source map comment (data URL).
+ */
+export function inlineSourceMapComment(map) {
+    const mapString = typeof map === 'string' ? map : JSON.stringify(map);
+    const base64 = Buffer.from(mapString).toString('base64');
+    return `//# sourceMappingURL=data:application/json;charset=utf-8;base64,${base64}`;
+}
+/**
+ * Generate an external source map URL comment.
+ */
+export function externalSourceMapComment(mapFileName) {
+    return `//# sourceMappingURL=${mapFileName}`;
+}
+/**
+ * Create a MagicString instance for tracking source modifications.
+ */
+export function createMagicString(source, filename) {
+    return new MagicString(source, {
+        filename,
+    });
+}
+/**
+ * Generate a source map from a MagicString instance.
+ */
+export function generateSourceMap(ms, options) {
+    return ms.generateMap({
+        source: options.source,
+        file: options.file ?? options.source,
+        includeContent: options.includeContent ?? true,
+        hires: options.hires ?? true,
+    });
+}
+/**
+ * Create an identity source map (maps each position to itself).
+ * Useful as a placeholder when no transformation occurred.
+ */
+export function createIdentityMap(source, fileName, includeContent = true) {
+    const ms = new MagicString(source);
+    return ms.generateMap({
+        source: fileName,
+        file: fileName,
+        includeContent,
+        hires: true,
+    });
+}
+/**
+ * Apply a list of modifications to source code using MagicString.
+ * Returns the modified code and source map.
+ */
+export function applyModifications(source, fileName, modifications, includeContent = true) {
+    const ms = createMagicString(source, fileName);
+    // Sort modifications by position (descending) to apply from end to start
+    // This prevents position shifts from affecting subsequent modifications
+    const sorted = [...modifications].sort((a, b) => b.start - a.start);
+    for (const mod of sorted) {
+        switch (mod.type) {
+            case 'insert-before':
+                ms.prependLeft(mod.start, mod.replacement);
+                break;
+            case 'insert-after':
+                ms.appendRight(mod.end, mod.replacement);
+                break;
+            case 'replace':
+                ms.overwrite(mod.start, mod.end, mod.replacement);
+                break;
+            case 'prepend':
+                ms.prepend(mod.replacement);
+                break;
+            case 'append':
+                ms.append(mod.replacement);
+                break;
+        }
+    }
+    return {
+        code: ms.toString(),
+        map: generateSourceMap(ms, {
+            source: fileName,
+            includeContent,
+        }),
+    };
+}
+/**
+ * Strip any existing source map comments from code.
+ */
+export function stripSourceMapComment(code) {
+    return code.replace(/\/\/[#@]\s*sourceMappingURL=.*/g, '');
+}
+//# sourceMappingURL=source-map.js.map

package/dist/src/source-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-map.js","sourceRoot":"","sources":["../../src/source-map.ts"],"names":[],"mappings":"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"}

package/dist/src/transformer.d.ts

@@ -1,24 +1,60 @@
 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;
 }
 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);
+    /**
+     * Create a new TypeScript program with transformed source code.
+     * This is needed so typia can resolve types from our generated typia.createAssert<T>() calls.
+     */
+    private createTypiaProgram;
+    /**
+     * 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(sourceFile: ts.SourceFile | string, mode: "basic" | "typia" | "js", skippedTypes?: Set<string>): string;
+    /**
+     * 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 string, or a retry signal with the failed type.
+     * 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;
     /**
@@ -34,11 +70,38 @@ export declare class TypicalTransformer {
      * 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:
@@ -66,12 +129,16 @@ export declare class TypicalTransformer {
     /**
      * 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 ignore pattern.
+     * Check if a single type name matches any pre-compiled ignore pattern.
+     * @param patterns Pre-compiled RegExp patterns
      */
-    private matchesIgnorePattern;
+    private matchesIgnorePatternCompiled;
     /**
      * Find untransformed typia calls in the output code.
      * These indicate types that typia could not process.