@elliots/typical 0.1.9 → 0.1.10

package/README.md

@@ -35,18 +35,23 @@ npm add typical
 
 Optional: Create a `typical.json` file in your project root.
 
-If not provided, these default settings will be used.
+If not provided, these default settings will be used (optimized for development):
 
 ```json
 {
   "include": ["**/*.ts", "**/*.tsx"],
   "exclude": ["node_modules/**", "**/*.d.ts", "dist/**", "build/**"],
-  "reusableValidators": true,
+  "reusableValidators": false,
   "validateFunctions": true,
   "validateCasts": false,
   "hoistRegex": true,
   "ignoreDOMTypes": true,
-  "ignoreTypes": []
+  "ignoreTypes": [],
+  "sourceMap": {
+    "enabled": true,
+    "includeContent": true,
+    "inline": false
+  }
 }
 ```
 
@@ -56,12 +61,31 @@ If not provided, these default settings will be used.
 |--------|---------|-------------|
 | `include` | `["**/*.ts", "**/*.tsx"]` | Glob patterns for files to transform |
 | `exclude` | `["node_modules/**", "**/*.d.ts", "dist/**", "build/**"]` | Glob patterns for files to skip |
-| `reusableValidators` | `true` | Create shared validators for identical types (smaller output, allows reuse) |
+| `reusableValidators` | `false` | Create shared validators for identical types (smaller output). Incompatible with source maps. |
 | `validateFunctions` | `true` | Validate function parameters and return types at runtime |
 | `validateCasts` | `false` | Validate type assertions (`as Type`) at runtime |
 | `hoistRegex` | `true` | Hoist regex patterns to top-level constants (improves performance) |
 | `ignoreDOMTypes` | `true` | Skip validation for DOM types (Document, Element, etc.) |
 | `ignoreTypes` | `[]` | Type patterns to skip validation for (supports wildcards, e.g., `["React.*"]`) |
+| `sourceMap.enabled` | `true` | Generate source maps for transformed code |
+| `sourceMap.includeContent` | `true` | Include original source content in source maps |
+| `sourceMap.inline` | `false` | Use inline source maps (data URL) instead of external files |
+| `debug.writeIntermediateFiles` | `false` | Write `.typical.ts` files showing code before typia transform |
+
+### Production Configuration
+
+For production builds, disable source maps and enable reusable validators for smaller output:
+
+```json
+{
+  "reusableValidators": true,
+  "sourceMap": {
+    "enabled": false
+  }
+}
+```
+
+Note: `reusableValidators` and `sourceMap.enabled` are mutually exclusive. Source maps require inline validators so each validation call can map back to its original type annotation. If both are enabled, `reusableValidators` will be automatically disabled with a warning.
 
 ## Usage
 
@@ -174,6 +198,139 @@ But basically you shouldn't need to care about how it works internally, it makes
 
 * sort of. probably. something like it anyway.
 
+## Flow Analysis
+
+Typical includes smart flow analysis to avoid redundant validations. When you return a value that was already validated (either as a parameter or via a type-annotated const), the return statement won't be wrapped in another validation call.
+
+### When return validation is skipped:
+
+```typescript
+interface User { name: string; }
+
+// Direct parameter return - no redundant validation
+function validate(user: User): User {
+  return user;  // Already validated on entry, skip return validation
+}
+
+// Property access from validated parameter
+function getAddress(user: User): Address {
+  return user.address;  // user was validated, address is safe
+}
+
+// Type-annotated const
+function getUser(): User {
+  const user: User = fetchData();  // const is validated here
+  return user;  // skip redundant validation
+}
+```
+
+### When return validation IS applied (tainting):
+
+```typescript
+// After mutation
+function updateUser(user: User): User {
+  user.name = "modified";  // Mutation taints the value
+  return user;  // Must re-validate
+}
+
+// After passing to another function
+function processUser(user: User): User {
+  someFunction(user);  // Could have mutated user
+  return user;  // Must re-validate
+}
+
+// After await (async boundary)
+async function asyncProcess(user: User): Promise<User> {
+  await delay();  // Async boundary taints values
+  return user;  // Must re-validate
+}
+
+// Spread into new object
+function cloneUser(user: User): User {
+  return { ...user };  // New object, must validate
+}
+```
+
+## Debugging
+
+### Intermediate Files
+
+To see what code Typical generates before typia processes it, enable intermediate file output:
+
+```json
+{
+  "debug": {
+    "writeIntermediateFiles": true
+  }
+}
+```
+
+This creates `.typical.ts` files alongside your output showing the code with typia calls injected but not yet transformed.
+
+### Verbose Logging
+
+Set `DEBUG=1` environment variable for detailed logging:
+
+```bash
+DEBUG=1 npm run build
+```
+
+## Troubleshooting
+
+### "Failed to transform the following types"
+
+This error means typia couldn't generate validation code for certain types. Common causes:
+
+1. **DOM types**: Types like `HTMLElement`, `Document`, etc. have complex intersections typia can't process.
+   - Solution: Enable `ignoreDOMTypes: true` (default) or add specific types to `ignoreTypes`
+
+2. **React types**: Event handlers, refs, and other React types often can't be validated.
+   - Solution: Add `"React.*"` to `ignoreTypes`
+
+3. **Third-party library types**: Some library types are too complex.
+   - Solution: Add the specific type patterns to `ignoreTypes`
+
+```json
+{
+  "ignoreTypes": ["React.*", "Express.Request", "Prisma.*"]
+}
+```
+
+### "Window & typeof globalThis" errors
+
+This occurs when a type includes DOM globals. Enable `ignoreDOMTypes: true` or add the specific type to `ignoreTypes`.
+
+### Generic type parameters not validated
+
+Type parameters (`T`, `U`, etc.) cannot be validated at runtime because the actual type isn't known until the function is called. This is by design:
+
+```typescript
+function identity<T>(value: T): T {
+  return value;  // T is not validated - no runtime type info
+}
+```
+
+Concrete types in the same function ARE validated:
+
+```typescript
+function process<T>(value: T, user: User): User {
+  return user;  // User IS validated
+}
+```
+
+### Constructor parameters not validated
+
+Currently, class constructors are not transformed. This is a known limitation. Validate in the constructor body if needed:
+
+```typescript
+class Client {
+  constructor(options: Options) {
+    // Manual validation if needed
+    if (!options.timeout) throw new Error("timeout required");
+  }
+}
+```
+
 ## Credits
 The actual validation work is done by [typia](https://github.com/samchon/typia). This package just generates the necessary code to call typia's functions based on your TypeScript types.
 

package/dist/src/cli.js

@@ -3,7 +3,8 @@ import { Command } from 'commander';
 import * as fs from 'fs';
 import * as path from 'path';
 import { TypicalTransformer } from './transformer.js';
-import { loadConfig } from './config.js';
+import { loadConfig, validateConfig } from './config.js';
+import { inlineSourceMapComment, externalSourceMapComment } from './source-map.js';
 const program = new Command();
 program
     .name('typical')
@@ -16,19 +17,45 @@ program
     .option('-o, --output <file>', 'Output file')
     .option('-c, --config <file>', 'Config file path', 'typical.json')
     .option('-m, --mode <mode>', 'Transformation mode:  basic, typia, js', 'basic')
+    .option('--source-map', 'Generate external source map file')
+    .option('--inline-source-map', 'Include inline source map in output')
+    .option('--no-source-map', 'Disable source map generation')
     .action(async (file, options) => {
     try {
-        const config = loadConfig(options.config);
+        const config = validateConfig(loadConfig(options.config));
         const transformer = new TypicalTransformer(config);
         if (!fs.existsSync(file)) {
             console.error(`File not found: ${file}`);
             process.exit(1);
         }
+        // Determine source map behavior
+        const generateSourceMap = options.inlineSourceMap || options.sourceMap !== false;
         console.log(`Transforming ${file}...`);
-        const transformedCode = transformer.transform(path.resolve(file), options.mode ?? 'basic');
-        const outputFilename = options.output ? path.resolve(options.output) : options.mode === 'js' ? file + '.js' : file + '.transformed.ts';
-        const outputFile = options.output ? path.resolve(options.output) : file + '.transformed.ts';
-        fs.writeFileSync(outputFile, transformedCode);
+        const result = transformer.transform(path.resolve(file), options.mode ?? 'basic', {
+            sourceMap: generateSourceMap,
+        });
+        // Determine output file path
+        const outputFile = options.output
+            ? path.resolve(options.output)
+            : options.mode === 'js'
+                ? file.replace(/\.tsx?$/, '.js')
+                : file + '.transformed.ts';
+        let outputCode = result.code;
+        // Handle source maps
+        if (result.map) {
+            if (options.inlineSourceMap) {
+                // Inline source map as data URL
+                outputCode += '\n' + inlineSourceMapComment(result.map);
+            }
+            else if (options.sourceMap !== false) {
+                // Write external source map file
+                const mapFile = outputFile + '.map';
+                fs.writeFileSync(mapFile, JSON.stringify(result.map, null, 2));
+                outputCode += '\n' + externalSourceMapComment(path.basename(mapFile));
+                console.log(`Source map written to ${mapFile}`);
+            }
+        }
+        fs.writeFileSync(outputFile, outputCode);
         console.log(`Transformed code written to ${outputFile}`);
     }
     catch (error) {

package/dist/src/cli.js.map

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

package/dist/src/config.d.ts

@@ -1,6 +1,23 @@
 export interface TypicalDebugConfig {
     writeIntermediateFiles?: boolean;
 }
+/**
+ * Configuration options for source map generation.
+ */
+export interface TypicalSourceMapConfig {
+    /**
+     * Generate source maps. Default: true
+     */
+    enabled?: boolean;
+    /**
+     * Include original source content in the map. Default: true
+     */
+    includeContent?: boolean;
+    /**
+     * Use inline source maps (data URL) instead of external files. Default: false
+     */
+    inline?: boolean;
+}
 export interface TypicalConfig {
     include?: string[];
     exclude?: string[];
@@ -26,6 +43,23 @@ export interface TypicalConfig {
      * Default: true
      */
     validateFunctions?: boolean;
+    /**
+     * Source map generation settings.
+     * Controls whether and how source maps are generated for transformed code.
+     */
+    sourceMap?: TypicalSourceMapConfig;
+}
+/**
+ * Pre-compiled regex patterns for ignore type matching.
+ * This is populated during config loading for performance.
+ */
+export interface CompiledIgnorePatterns {
+    /** Compiled patterns from user ignoreTypes config */
+    userPatterns: RegExp[];
+    /** Compiled patterns from DOM_TYPES_TO_IGNORE (when ignoreDOMTypes is true) */
+    domPatterns: RegExp[];
+    /** All patterns combined for quick checking */
+    allPatterns: RegExp[];
 }
 export declare const defaultConfig: TypicalConfig;
 /**
@@ -33,4 +67,26 @@ export declare const defaultConfig: TypicalConfig;
  * These are the base DOM types - classes extending them are checked separately.
  */
 export declare const DOM_TYPES_TO_IGNORE: string[];
+/**
+ * Convert a glob pattern to a RegExp for type matching.
+ * Supports wildcards: "React.*" -> /^React\..*$/
+ */
+export declare function compileIgnorePattern(pattern: string): RegExp | null;
+/**
+ * Pre-compile all ignore patterns for efficient matching.
+ */
+export declare function compileIgnorePatterns(config: TypicalConfig): CompiledIgnorePatterns;
+/**
+ * Get compiled ignore patterns, using cache if config hasn't changed.
+ */
+export declare function getCompiledIgnorePatterns(config: TypicalConfig): CompiledIgnorePatterns;
 export declare function loadConfig(configPath?: string): TypicalConfig;
+/**
+ * Validate and adjust config for consistency.
+ * Currently handles:
+ * - Disabling reusableValidators when source maps are enabled (required for accurate mappings)
+ *
+ * @param config The config to validate
+ * @returns Validated/adjusted config
+ */
+export declare function validateConfig(config: TypicalConfig): TypicalConfig;

package/dist/src/config.js

@@ -1,7 +1,7 @@
 export const defaultConfig = {
     include: ["**/*.ts", "**/*.tsx"],
     exclude: ["node_modules/**", "**/*.d.ts", "dist/**", "build/**"],
-    reusableValidators: true,
+    reusableValidators: false, // Off by default for accurate source maps (set to true for production)
     validateCasts: false,
     validateFunctions: true,
     hoistRegex: true,
@@ -9,6 +9,11 @@ export const defaultConfig = {
     debug: {
         writeIntermediateFiles: false,
     },
+    sourceMap: {
+        enabled: true, // On by default for debugging (set to false for production)
+        includeContent: true,
+        inline: false,
+    },
 };
 // FIXME: find a better way to work out which types to ignore
 /**
@@ -53,6 +58,65 @@ export const DOM_TYPES_TO_IGNORE = [
 ];
 import fs from 'fs';
 import path from 'path';
+/**
+ * Convert a glob pattern to a RegExp for type matching.
+ * Supports wildcards: "React.*" -> /^React\..*$/
+ */
+export function compileIgnorePattern(pattern) {
+    try {
+        const regexStr = '^' + pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape special regex chars except *
+            .replace(/\*/g, '.*') + '$';
+        return new RegExp(regexStr);
+    }
+    catch (error) {
+        console.warn(`TYPICAL: Invalid ignoreTypes pattern "${pattern}": ${error}`);
+        return null;
+    }
+}
+/**
+ * Pre-compile all ignore patterns for efficient matching.
+ */
+export function compileIgnorePatterns(config) {
+    const userPatterns = [];
+    const domPatterns = [];
+    // Compile user patterns
+    for (const pattern of config.ignoreTypes ?? []) {
+        const compiled = compileIgnorePattern(pattern);
+        if (compiled) {
+            userPatterns.push(compiled);
+        }
+    }
+    // Compile DOM patterns if enabled (default: true)
+    if (config.ignoreDOMTypes !== false) {
+        for (const pattern of DOM_TYPES_TO_IGNORE) {
+            const compiled = compileIgnorePattern(pattern);
+            if (compiled) {
+                domPatterns.push(compiled);
+            }
+        }
+    }
+    return {
+        userPatterns,
+        domPatterns,
+        allPatterns: [...userPatterns, ...domPatterns],
+    };
+}
+// Cache for compiled patterns, keyed by config identity
+let cachedPatterns = null;
+let cachedConfig = null;
+/**
+ * Get compiled ignore patterns, using cache if config hasn't changed.
+ */
+export function getCompiledIgnorePatterns(config) {
+    // Simple identity check - if same config object, use cache
+    if (cachedConfig === config && cachedPatterns) {
+        return cachedPatterns;
+    }
+    cachedConfig = config;
+    cachedPatterns = compileIgnorePatterns(config);
+    return cachedPatterns;
+}
 export function loadConfig(configPath) {
     const configFile = configPath || path.join(process.cwd(), 'typical.json');
     if (fs.existsSync(configFile)) {
@@ -71,4 +135,32 @@ export function loadConfig(configPath) {
     }
     return defaultConfig;
 }
+let warnedAboutSourceMaps = false;
+/**
+ * Validate and adjust config for consistency.
+ * Currently handles:
+ * - Disabling reusableValidators when source maps are enabled (required for accurate mappings)
+ *
+ * @param config The config to validate
+ * @returns Validated/adjusted config
+ */
+export function validateConfig(config) {
+    let result = config;
+    // Source maps require inline validators (not reusable) because each validation
+    // call needs its own source map marker pointing to the correct type annotation.
+    // With reusable validators, the expanded typia code would all map to the validator
+    // declaration rather than the individual usage sites.
+    const sourceMapEnabled = config.sourceMap?.enabled !== false;
+    const reusableValidatorsEnabled = config.reusableValidators === true;
+    if (sourceMapEnabled && reusableValidatorsEnabled) {
+        if (!warnedAboutSourceMaps) {
+            warnedAboutSourceMaps = true;
+            console.warn("TYPICAL: Both sourceMap and reusableValidators are enabled. " +
+                "Disabling reusableValidators for accurate source mapping. " +
+                "For production builds, set sourceMap.enabled: false to use reusableValidators.");
+        }
+        result = { ...result, reusableValidators: false };
+    }
+    return result;
+}
 //# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AA+BA,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C,OAAO,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;IAChC,OAAO,EAAE,CAAC,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,CAAC;IAChE,kBAAkB,EAAE,IAAI;IACxB,aAAa,EAAE,KAAK;IACpB,iBAAiB,EAAE,IAAI;IACvB,UAAU,EAAE,IAAI;IAChB,cAAc,EAAE,IAAI;IACpB,KAAK,EAAE;QACL,sBAAsB,EAAE,KAAK;KAC9B;CACF,CAAC;AAEF,6DAA6D;AAC7D;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,iBAAiB;IACjB,UAAU;IACV,kBAAkB;IAClB,SAAS;IACT,MAAM;IACN,YAAY;IACZ,QAAQ;IACR,aAAa;IACb,gBAAgB;IAChB,cAAc;IACd,aAAa;IACb,gBAAgB;IAChB,eAAe;IACf,aAAa;IACb,YAAY;IACZ,SAAS;IACT,QAAQ;IACR,yBAAyB;IACzB,UAAU;IACV,cAAc;IACd,cAAc;IACd,qBAAqB;IACrB,WAAW;IACX,OAAO;IACP,MAAM;IACN,SAAS;IACT,cAAc;IACd,uBAAuB;IACvB,cAAc;IACd,MAAM;IACN,OAAO;IACP,UAAU;IACV,WAAW;IACX,YAAY;CACb,CAAC;AAEF,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,UAAU,UAAU,CAAC,UAAmB;IAC5C,MAAM,UAAU,GAAG,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAC;IAE1E,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,aAAa,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;YAC1D,MAAM,UAAU,GAA2B,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;YAErE,OAAO;gBACL,GAAG,aAAa;gBAChB,GAAG,UAAU;aACd,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,+BAA+B,UAAU,GAAG,EAAE,KAAK,CAAC,CAAC;YAClE,OAAO,aAAa,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}

package/dist/src/esm-loader.d.ts

@@ -4,5 +4,6 @@
 export declare function resolve(specifier: string, context: any, nextResolve: any): Promise<any>;
 /**
  * Load hook - transforms TypeScript files on the fly
+ * Includes inline source maps for proper error stack traces in Node.js
  */
 export declare function load(url: string, context: any, nextLoad: any): Promise<any>;

package/dist/src/esm-loader.js

@@ -1,7 +1,10 @@
 import { fileURLToPath, pathToFileURL } from "url";
 import { existsSync } from "fs";
 import { TypicalTransformer } from "./transformer.js";
-const transformer = new TypicalTransformer();
+import { inlineSourceMapComment } from "./source-map.js";
+import { loadConfig, validateConfig } from "./config.js";
+const config = validateConfig(loadConfig());
+const transformer = new TypicalTransformer(config);
 /**
  * Resolve hook - rewrites .js imports to .ts if the .ts file exists
  */
@@ -25,6 +28,7 @@ export async function resolve(specifier, context, nextResolve) {
 }
 /**
  * Load hook - transforms TypeScript files on the fly
+ * Includes inline source maps for proper error stack traces in Node.js
  */
 export async function load(url, context, nextLoad) {
     if (!url.endsWith(".ts")) {
@@ -32,10 +36,16 @@ export async function load(url, context, nextLoad) {
     }
     const filePath = fileURLToPath(url);
     try {
-        const transformedCode = transformer.transform(filePath, 'js');
+        // Transform with source map support enabled
+        const result = transformer.transform(filePath, 'js', { sourceMap: true });
+        // Append inline source map for Node.js source map support
+        let source = result.code;
+        if (result.map) {
+            source += '\n' + inlineSourceMapComment(result.map);
+        }
         return {
             format: "module",
-            source: transformedCode,
+            source,
             shortCircuit: true,
         };
     }

package/dist/src/esm-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"esm-loader.js","sourceRoot":"","sources":["../../src/esm-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,WAAW,GAAG,IAAI,kBAAkB,EAAE,CAAC;AAE7C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,SAAiB,EAAE,OAAY,EAAE,WAAgB;IAC7E,6CAA6C;IAC7C,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;QAC9B,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;YAC5C,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YACjE,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;YAE1D,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvB,OAAO;oBACL,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI;oBAC/B,YAAY,EAAE,IAAI;iBACnB,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,GAAW,EAAE,OAAY,EAAE,QAAa;IACjE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC9D,OAAO;YACL,MAAM,EAAE,QAAQ;YAChB,MAAM,EAAE,eAAe;YACvB,YAAY,EAAE,IAAI;SACnB,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,sBAAsB,QAAQ,GAAG,EAAE,KAAK,CAAC,CAAC;QACxD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"esm-loader.js","sourceRoot":"","sources":["../../src/esm-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,EAAE,CAAC,CAAC;AAC5C,MAAM,WAAW,GAAG,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAEnD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,SAAiB,EAAE,OAAY,EAAE,WAAgB;IAC7E,6CAA6C;IAC7C,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;QAC9B,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,UAAU,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;YAC5C,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YACjE,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;YAE1D,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvB,OAAO;oBACL,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI;oBAC/B,YAAY,EAAE,IAAI;iBACnB,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,GAAW,EAAE,OAAY,EAAE,QAAa;IACjE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAI,CAAC;QACH,4CAA4C;QAC5C,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE1E,0DAA0D;QAC1D,IAAI,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;QACzB,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC;YACf,MAAM,IAAI,IAAI,GAAG,sBAAsB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtD,CAAC;QAED,OAAO;YACL,MAAM,EAAE,QAAQ;YAChB,MAAM;YACN,YAAY,EAAE,IAAI;SACnB,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,sBAAsB,QAAQ,GAAG,EAAE,KAAK,CAAC,CAAC;QACxD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/src/index.d.ts

@@ -1,2 +1,4 @@
-export { TypicalTransformer } from './transformer.js';
-export { loadConfig, defaultConfig, TypicalConfig } from './config.js';
+export { TypicalTransformer, TransformResult } from './transformer.js';
+export { loadConfig, validateConfig, defaultConfig, TypicalConfig, TypicalSourceMapConfig } from './config.js';
+export { composeSourceMaps, inlineSourceMapComment, externalSourceMapComment, createIdentityMap, stripSourceMapComment, } from './source-map.js';
+export type { SourceMapOptions } from './source-map.js';

package/dist/src/index.js

@@ -1,3 +1,4 @@
 export { TypicalTransformer } from './transformer.js';
-export { loadConfig, defaultConfig } from './config.js';
+export { loadConfig, validateConfig, defaultConfig } from './config.js';
+export { composeSourceMaps, inlineSourceMapComment, externalSourceMapComment, createIdentityMap, stripSourceMapComment, } from './source-map.js';
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAiB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAmB,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAyC,MAAM,aAAa,CAAC;AAC/G,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC"}

package/dist/src/source-map.d.ts

@@ -0,0 +1,78 @@
+import MagicString from 'magic-string';
+import type { DecodedSourceMap, EncodedSourceMap } from '@ampproject/remapping';
+/**
+ * Result of a transformation that includes source map information.
+ */
+export interface TransformResult {
+    code: string;
+    map: EncodedSourceMap | null;
+}
+/**
+ * Configuration options for source map generation.
+ */
+export interface SourceMapOptions {
+    /** Generate source maps. Default: true */
+    enabled?: boolean;
+    /** Include source content in map. Default: true */
+    includeContent?: boolean;
+    /** Use inline source maps (data URL). Default: false */
+    inline?: boolean;
+}
+/**
+ * Default source map options.
+ */
+export declare const defaultSourceMapOptions: Required<SourceMapOptions>;
+/**
+ * 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 declare function composeSourceMaps(maps: (EncodedSourceMap | DecodedSourceMap | string | null | undefined)[], originalFileName: string): EncodedSourceMap | null;
+/**
+ * Generate an inline source map comment (data URL).
+ */
+export declare function inlineSourceMapComment(map: EncodedSourceMap | string): string;
+/**
+ * Generate an external source map URL comment.
+ */
+export declare function externalSourceMapComment(mapFileName: string): string;
+/**
+ * Create a MagicString instance for tracking source modifications.
+ */
+export declare function createMagicString(source: string, filename?: string): MagicString;
+/**
+ * Generate a source map from a MagicString instance.
+ */
+export declare function generateSourceMap(ms: MagicString, options: {
+    source: string;
+    file?: string;
+    includeContent?: boolean;
+    hires?: boolean | 'boundary';
+}): EncodedSourceMap;
+/**
+ * Create an identity source map (maps each position to itself).
+ * Useful as a placeholder when no transformation occurred.
+ */
+export declare function createIdentityMap(source: string, fileName: string, includeContent?: boolean): EncodedSourceMap;
+/**
+ * Represents a tracked modification to source code.
+ */
+export interface SourceModification {
+    /** Start position in original source */
+    start: number;
+    /** End position in original source */
+    end: number;
+    /** The replacement text */
+    replacement: string;
+    /** Type of modification */
+    type: 'insert-before' | 'insert-after' | 'replace' | 'prepend' | 'append';
+}
+/**
+ * Apply a list of modifications to source code using MagicString.
+ * Returns the modified code and source map.
+ */
+export declare function applyModifications(source: string, fileName: string, modifications: SourceModification[], includeContent?: boolean): TransformResult;
+/**
+ * Strip any existing source map comments from code.
+ */
+export declare function stripSourceMapComment(code: string): string;