@elliots/typical 0.2.1 → 0.2.3

package/README.md

@@ -294,6 +294,7 @@ Create a `typical.json` file in your project root (optional):
 | `validateCasts`          | `false`                                                   | Validate type assertions (`as Type`)                              |
 | `transformJSONParse`     | `true`                                                    | Transform `JSON.parse` to validate and filter to typed properties |
 | `transformJSONStringify` | `true`                                                    | Transform `JSON.stringify` to only include typed properties       |
+| `reusableValidators`     | `true`                                                    | Hoist validators to module scope for reduced code size            |
 
 ---
 
@@ -346,15 +347,15 @@ Typical uses a Go-based compiler that leverages the TypeScript type checker to a
 
 Types that can't be validated at runtime (like generic type parameters `T`) are skipped. You can still use `any` and `unknown` to opt out of validation.
 
-## Compiler Optimizations
+## Compiler Optimisations
 
-The generated validation code is optimized for runtime performance:
+The generated validation code is optimised for runtime performance:
 
-- **Skip redundant validation** - When returning a validated parameter directly, the return validation is skipped (e.g., `return x` where `x: string` was already validated)
-- **Subtype-aware skipping** - If a validated type is assignable to the return type, validation is skipped (e.g., `string` parameter returned as `string | null`)
-- **Property chain tracking** - Accessing properties of validated objects skips re-validation (e.g., `return user.name` when `user: User` was validated)
-- **Type-aware dirty tracking** - Primitives stay validated after being passed to functions (they're copied), but objects are re-validated (they could be mutated)
+- **Reusable validators** - When the same type is validated multiple times, Typical hoists the validation logic to a reusable function at module scope. Nested types that appear in multiple places (e.g., `Address` used in both `User` and `Company`) are also extracted and reused.
+- **Smart redundancy elimination** - Skips validation when returning values that are already known to be valid: validated parameters, properties of validated objects, variables assigned from casts or `JSON.parse`, and aliased variables
+- **Type-aware dirty tracking** - Tracks when validated values might become invalid. Primitives stay valid after being passed to functions (they're copied), but objects are re-validated if passed to unknown functions. Pure functions (listed in the config) like `console.log` don't invalidate objects.
 - **Union early bail-out** - Union type checks use if-else chains so the first matching type succeeds immediately
+- **Skip comments** - Add `// @typical-ignore` before a function to skip all validation for it
 
 ## Debugging
 
@@ -370,3 +371,41 @@ DEBUG=1 npm run build
 - Type-only imports of classes aren't checked (can't do instanceof on type-only imports)
 - Validation of functions is just not done. Need to think about that one.
 - Some complex types may not be fully supported yet. If you find any that fail, please open an issue!
+
+---
+
+## Benchmarks
+
+Runtime validation performance comparing Typical vs Zod vs no validation:
+
+| Scenario                           |   Nothing |   Typical |       Zod |                     vs Nothing |                          vs Zod |
+| ---------------------------------- | --------: | --------: | --------: | -----------------------------: | ------------------------------: |
+| string                             |  23.91M/s |  24.86M/s |  24.80M/s | ${\textsf{\color{olive}1.0x}}$ |  ${\textsf{\color{olive}1.0x}}$ |
+| number                             |  24.33M/s |  25.44M/s |  24.44M/s | ${\textsf{\color{olive}1.0x}}$ |  ${\textsf{\color{olive}1.0x}}$ |
+| boolean                            |  24.49M/s |  24.49M/s |  24.19M/s | ${\textsf{\color{olive}1.0x}}$ |  ${\textsf{\color{olive}1.0x}}$ |
+| object w/ template literals        |  24.53M/s |  21.39M/s |   7.71M/s | ${\textsf{\color{olive}0.9x}}$ |  ${\textsf{\color{green}2.8x}}$ |
+| nested w/ template literals        |  24.69M/s |   8.05M/s |   2.31M/s |   ${\textsf{\color{red}0.3x}}$ |  ${\textsf{\color{green}3.5x}}$ |
+| array w/ templates (10)            |  29.89M/s |   7.10M/s |   1.54M/s |   ${\textsf{\color{red}0.2x}}$ |  ${\textsf{\color{green}4.6x}}$ |
+| array w/ templates (100)           |  30.18M/s | 795.31K/s | 150.09K/s |   ${\textsf{\color{red}0.0x}}$ |  ${\textsf{\color{green}5.3x}}$ |
+| union types                        |  29.77M/s |  30.69M/s |  10.76M/s | ${\textsf{\color{olive}1.0x}}$ |  ${\textsf{\color{green}2.9x}}$ |
+| template literals                  |  30.09M/s |  17.23M/s |   1.71M/s |   ${\textsf{\color{red}0.6x}}$ | ${\textsf{\color{green}10.1x}}$ |
+| complex config                     |  30.56M/s |  29.14M/s |   3.51M/s | ${\textsf{\color{olive}1.0x}}$ |  ${\textsf{\color{green}8.3x}}$ |
+| JSON.parse (small)                 |   4.61M/s |   4.37M/s |   3.85M/s | ${\textsf{\color{olive}0.9x}}$ |  ${\textsf{\color{green}1.1x}}$ |
+| JSON.parse (small+filtered extras) |   4.65M/s |   4.32M/s |   3.79M/s | ${\textsf{\color{olive}0.9x}}$ |  ${\textsf{\color{green}1.1x}}$ |
+| JSON.parse (medium)                |   2.85M/s |   2.26M/s | 928.42K/s |   ${\textsf{\color{red}0.8x}}$ |  ${\textsf{\color{green}2.4x}}$ |
+| JSON.parse (large)                 | 209.41K/s | 186.91K/s |  99.28K/s | ${\textsf{\color{olive}0.9x}}$ |  ${\textsf{\color{green}1.9x}}$ |
+| JSON.parse (1000 large)            |     211/s |     212/s |     104/s | ${\textsf{\color{olive}1.0x}}$ |  ${\textsf{\color{green}2.0x}}$ |
+| JSON.stringify (small)             |   9.99M/s |   9.30M/s |   6.70M/s | ${\textsf{\color{olive}0.9x}}$ |  ${\textsf{\color{green}1.4x}}$ |
+| JSON.stringify (small+extras)      |   2.85M/s |   9.20M/s |   6.98M/s | ${\textsf{\color{green}3.2x}}$ |  ${\textsf{\color{green}1.3x}}$ |
+| JSON.stringify (medium)            |   5.09M/s |   3.82M/s |   1.16M/s |   ${\textsf{\color{red}0.8x}}$ |  ${\textsf{\color{green}3.3x}}$ |
+| JSON.stringify (large)             | 392.53K/s | 330.45K/s | 132.50K/s |   ${\textsf{\color{red}0.8x}}$ |  ${\textsf{\color{green}2.5x}}$ |
+| JSON.stringify (1000 large)        |     362/s |     339/s |     128/s | ${\textsf{\color{olive}0.9x}}$ |  ${\textsf{\color{green}2.7x}}$ |
+
+- **vs Nothing**: Speed relative to no validation or filtering (1.0x = same speed)
+- **vs Zod**: Speed relative to Zod (1.0x = same speed)
+
+Key findings:
+
+- Primitives and simple types have near-zero overhead
+- Typical is **2-10x faster than Zod** for complex types
+- JSON operations have minimal overhead while providing full type safety

package/dist/src/config.d.ts

@@ -21,7 +21,13 @@ export interface TypicalSourceMapConfig {
 export interface TypicalConfig {
     include?: string[];
     exclude?: string[];
-    reusableValidators?: boolean;
+    /**
+     * Controls whether validators are hoisted to module scope for reuse.
+     * - 'auto' (default): Hoist only validators used more than once
+     * - 'never': Never hoist, always generate inline validators
+     * - 'always': Always hoist validators, even if only used once
+     */
+    reusableValidators?: 'auto' | 'never' | 'always';
     validateCasts?: boolean;
     hoistRegex?: boolean;
     debug?: TypicalDebugConfig;
@@ -67,8 +73,6 @@ export declare const defaultConfig: TypicalConfig;
 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

package/dist/src/config.js

@@ -1,7 +1,7 @@
 export const defaultConfig = {
     include: ['**/*.ts', '**/*.tsx'],
     exclude: ['node_modules/**', '**/*.d.ts', 'dist/**', 'build/**'],
-    reusableValidators: false, // Off by default for accurate source maps (set to true for production)
+    reusableValidators: 'auto', // Hoists validators to module scope for reduced code size
     validateCasts: false,
     validateFunctions: true,
     transformJSONParse: true,
@@ -11,7 +11,7 @@ export const defaultConfig = {
         writeIntermediateFiles: false,
     },
     sourceMap: {
-        enabled: true, // On by default for debugging (set to false for production)
+        enabled: true,
         includeContent: true,
         inline: false,
     },
@@ -36,30 +36,15 @@ 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;
+    // Reusable validators now throw at the call site, so they work correctly
+    // with source maps. No need for special handling.
+    return config;
 }
 //# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAoEA,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,KAAK,EAAE,uEAAuE;IAClG,aAAa,EAAE,KAAK;IACpB,iBAAiB,EAAE,IAAI;IACvB,kBAAkB,EAAE,IAAI;IACxB,sBAAsB,EAAE,IAAI;IAC5B,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE;QACL,sBAAsB,EAAE,KAAK;KAC9B;IACD,SAAS,EAAE;QACT,OAAO,EAAE,IAAI,EAAE,4DAA4D;QAC3E,cAAc,EAAE,IAAI;QACpB,MAAM,EAAE,KAAK;KACd;CACF,CAAA;AAED,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,IAAI,MAAM,MAAM,CAAA;AAEvB,MAAM,UAAU,UAAU,CAAC,UAAmB;IAC5C,MAAM,UAAU,GAAG,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAA;IAEzE,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,aAAa,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;YACzD,MAAM,UAAU,GAA2B,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;YAEpE,OAAO;gBACL,GAAG,aAAa;gBAChB,GAAG,UAAU;aACd,CAAA;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,+BAA+B,UAAU,GAAG,EAAE,KAAK,CAAC,CAAA;YACjE,OAAO,aAAa,CAAA;QACtB,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAA;AACtB,CAAC;AAED,IAAI,qBAAqB,GAAG,KAAK,CAAA;AAEjC;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,IAAI,MAAM,GAAG,MAAM,CAAA;IAEnB,+EAA+E;IAC/E,gFAAgF;IAChF,mFAAmF;IACnF,sDAAsD;IACtD,MAAM,gBAAgB,GAAG,MAAM,CAAC,SAAS,EAAE,OAAO,KAAK,KAAK,CAAA;IAC5D,MAAM,yBAAyB,GAAG,MAAM,CAAC,kBAAkB,KAAK,IAAI,CAAA;IAEpE,IAAI,gBAAgB,IAAI,yBAAyB,EAAE,CAAC;QAClD,IAAI,CAAC,qBAAqB,EAAE,CAAC;YAC3B,qBAAqB,GAAG,IAAI,CAAA;YAC5B,OAAO,CAAC,IAAI,CACV,8DAA8D,GAAG,4DAA4D,GAAG,gFAAgF,CACjN,CAAA;QACH,CAAC;QACD,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,CAAA;IACnD,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AA0EA,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,MAAM,EAAE,0DAA0D;IACtF,aAAa,EAAE,KAAK;IACpB,iBAAiB,EAAE,IAAI;IACvB,kBAAkB,EAAE,IAAI;IACxB,sBAAsB,EAAE,IAAI;IAC5B,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE;QACL,sBAAsB,EAAE,KAAK;KAC9B;IACD,SAAS,EAAE;QACT,OAAO,EAAE,IAAI;QACb,cAAc,EAAE,IAAI;QACpB,MAAM,EAAE,KAAK;KACd;CACF,CAAA;AAED,OAAO,EAAE,MAAM,IAAI,CAAA;AACnB,OAAO,IAAI,MAAM,MAAM,CAAA;AAEvB,MAAM,UAAU,UAAU,CAAC,UAAmB;IAC5C,MAAM,UAAU,GAAG,UAAU,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAA;IAEzE,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,aAAa,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;YACzD,MAAM,UAAU,GAA2B,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;YAEpE,OAAO;gBACL,GAAG,aAAa;gBAChB,GAAG,UAAU;aACd,CAAA;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CAAC,+BAA+B,UAAU,GAAG,EAAE,KAAK,CAAC,CAAA;YACjE,OAAO,aAAa,CAAA;QACtB,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAA;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,yEAAyE;IACzE,kDAAkD;IAClD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/src/transformer.js

@@ -45,8 +45,8 @@ export class TypicalTransformer {
         }
         await this.ensureInitialized();
         const resolvedPath = resolve(fileName);
-        // Pass ignoreTypes and maxGeneratedFunctions from config to the Go compiler
-        const result = await this.compiler.transformFile(this.projectHandle, resolvedPath, this.config.ignoreTypes, this.config.maxGeneratedFunctions);
+        // Pass config options to the Go compiler
+        const result = await this.compiler.transformFile(this.projectHandle, resolvedPath, this.config.ignoreTypes, this.config.maxGeneratedFunctions, this.config.reusableValidators);
         return {
             code: result.code,
             map: result.sourceMap ?? null,

package/dist/src/transformer.js.map

@@ -1 +1 @@
-{"version":3,"file":"transformer.js","sourceRoot":"","sources":["../../src/transformer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAC9B,OAAO,EAAE,eAAe,EAAyC,MAAM,2BAA2B,CAAA;AAElG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAOxC,MAAM,OAAO,kBAAkB;IACtB,MAAM,CAAe;IACpB,QAAQ,CAAiB;IACzB,aAAa,GAAyB,IAAI,CAAA;IAC1C,WAAW,GAAyB,IAAI,CAAA;IACxC,UAAU,CAAQ;IAE1B,YAAY,MAAsB,EAAE,aAAqB,eAAe;QACtE,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,UAAU,EAAE,CAAA;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,CAAC,QAAQ,GAAG,IAAI,eAAe,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAC7D,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,iBAAiB;QAC7B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;gBAC7B,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;gBAC3B,IAAI,CAAC,aAAa,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;YACvE,CAAC,CAAC,EAAE,CAAA;QACN,CAAC;QACD,MAAM,IAAI,CAAC,WAAW,CAAA;IACxB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,CAAC,QAAgB,EAAE,OAAoB,IAAI;QACxD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAA;QACpF,CAAC;QAED,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAA;QAE9B,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;QACtC,4EAA4E;QAC5E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,aAAc,EAAE,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAA;QAE/I,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;SAC9B,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,aAAa,GAAG,IAAI,CAAA;QACzB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;QACvB,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;IAC7B,CAAC;CACF"}
+{"version":3,"file":"transformer.js","sourceRoot":"","sources":["../../src/transformer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AAC9B,OAAO,EAAE,eAAe,EAAyC,MAAM,2BAA2B,CAAA;AAElG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAOxC,MAAM,OAAO,kBAAkB;IACtB,MAAM,CAAe;IACpB,QAAQ,CAAiB;IACzB,aAAa,GAAyB,IAAI,CAAA;IAC1C,WAAW,GAAyB,IAAI,CAAA;IACxC,UAAU,CAAQ;IAE1B,YAAY,MAAsB,EAAE,aAAqB,eAAe;QACtE,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,UAAU,EAAE,CAAA;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,CAAC,QAAQ,GAAG,IAAI,eAAe,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAC7D,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,iBAAiB;QAC7B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,WAAW,GAAG,CAAC,KAAK,IAAI,EAAE;gBAC7B,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;gBAC3B,IAAI,CAAC,aAAa,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;YACvE,CAAC,CAAC,EAAE,CAAA;QACN,CAAC;QACD,MAAM,IAAI,CAAC,WAAW,CAAA;IACxB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,CAAC,QAAgB,EAAE,OAAoB,IAAI;QACxD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAA;QACpF,CAAC;QAED,MAAM,IAAI,CAAC,iBAAiB,EAAE,CAAA;QAE9B,MAAM,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;QACtC,yCAAyC;QACzC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,aAAc,EAAE,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,qBAAqB,EAAE,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAA;QAE/K,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;SAC9B,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,aAAa,GAAG,IAAI,CAAA;QACzB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;QACvB,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAA;IAC7B,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliots/typical",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Runtime safe TypeScript transformer using typia",
   "keywords": [
     "runtime",
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "commander": "14.0.2",
-    "@elliots/typical-compiler": "0.2.1"
+    "@elliots/typical-compiler": "0.2.3"
   },
   "devDependencies": {
     "@types/node": "22",

package/src/config.ts

@@ -23,7 +23,13 @@ export interface TypicalSourceMapConfig {
 export interface TypicalConfig {
   include?: string[]
   exclude?: string[]
-  reusableValidators?: boolean
+  /**
+   * Controls whether validators are hoisted to module scope for reuse.
+   * - 'auto' (default): Hoist only validators used more than once
+   * - 'never': Never hoist, always generate inline validators
+   * - 'always': Always hoist validators, even if only used once
+   */
+  reusableValidators?: 'auto' | 'never' | 'always'
   validateCasts?: boolean
   hoistRegex?: boolean
   debug?: TypicalDebugConfig
@@ -69,7 +75,7 @@ export interface TypicalConfig {
 export const defaultConfig: TypicalConfig = {
   include: ['**/*.ts', '**/*.tsx'],
   exclude: ['node_modules/**', '**/*.d.ts', 'dist/**', 'build/**'],
-  reusableValidators: false, // Off by default for accurate source maps (set to true for production)
+  reusableValidators: 'auto', // Hoists validators to module scope for reduced code size
   validateCasts: false,
   validateFunctions: true,
   transformJSONParse: true,
@@ -79,7 +85,7 @@ export const defaultConfig: TypicalConfig = {
     writeIntermediateFiles: false,
   },
   sourceMap: {
-    enabled: true, // On by default for debugging (set to false for production)
+    enabled: true,
     includeContent: true,
     inline: false,
   },
@@ -109,35 +115,14 @@ export function loadConfig(configPath?: string): TypicalConfig {
   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: TypicalConfig): TypicalConfig {
-  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
+  // Reusable validators now throw at the call site, so they work correctly
+  // with source maps. No need for special handling.
+  return config
 }

package/src/transformer.ts

@@ -58,8 +58,8 @@ export class TypicalTransformer {
     await this.ensureInitialized()
 
     const resolvedPath = resolve(fileName)
-    // Pass ignoreTypes and maxGeneratedFunctions from config to the Go compiler
-    const result = await this.compiler.transformFile(this.projectHandle!, resolvedPath, this.config.ignoreTypes, this.config.maxGeneratedFunctions)
+    // Pass config options to the Go compiler
+    const result = await this.compiler.transformFile(this.projectHandle!, resolvedPath, this.config.ignoreTypes, this.config.maxGeneratedFunctions, this.config.reusableValidators)
 
     return {
       code: result.code,