@elliots/typical 0.1.9 → 0.2.0-beta.1

package/dist/src/tsc-plugin.d.ts

@@ -1,3 +1,10 @@
 import type ts from 'typescript';
 import type { TransformerExtras, PluginConfig } from 'ts-patch';
-export default function (program: ts.Program, pluginConfig: PluginConfig, { ts: tsInstance }: TransformerExtras): ts.TransformerFactory<ts.SourceFile>;
+/**
+ * TSC Plugin for typical.
+ *
+ * NOTE: This plugin has been moved to a separate package: @elliots/typical-tsc-plugin
+ * This stub is kept for backwards compatibility but will throw an error directing
+ * users to the new package.
+ */
+export default function (_program: ts.Program, _pluginConfig: PluginConfig, _extras: TransformerExtras): void;

package/dist/src/tsc-plugin.js

@@ -1,9 +1,13 @@
-import { TypicalTransformer } from './transformer.js';
-import { loadConfig } from './config.js';
-export default function (program, pluginConfig, { ts: tsInstance }) {
-    const config = loadConfig();
-    const transformer = new TypicalTransformer(config, program, tsInstance);
-    // Create the typical transformer with typia integration
-    return transformer.getTransformer(true);
+/**
+ * TSC Plugin for typical.
+ *
+ * NOTE: This plugin has been moved to a separate package: @elliots/typical-tsc-plugin
+ * This stub is kept for backwards compatibility but will throw an error directing
+ * users to the new package.
+ */
+export default function (_program, _pluginConfig, _extras) {
+    throw new Error('The typical tsc-plugin has moved to a separate package. ' +
+        'Install @elliots/typical-tsc-plugin and update your tsconfig.json to use ' +
+        '"@elliots/typical-tsc-plugin" instead of "@elliots/typical/tsc-plugin".');
 }
 //# sourceMappingURL=tsc-plugin.js.map

package/dist/src/tsc-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"tsc-plugin.js","sourceRoot":"","sources":["../../src/tsc-plugin.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,CAAC,OAAO,WAAW,OAAmB,EAAE,YAA0B,EAAE,EAAE,EAAE,EAAE,UAAU,EAAqB;IAC7G,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,WAAW,GAAG,IAAI,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAExE,wDAAwD;IACxD,OAAO,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"tsc-plugin.js","sourceRoot":"","sources":["../../src/tsc-plugin.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,WAAW,QAAoB,EAAE,aAA2B,EAAE,OAA0B;IACpG,MAAM,IAAI,KAAK,CACb,0DAA0D;QACxD,2EAA2E;QAC3E,yEAAyE,CAC5E,CAAA;AACH,CAAC"}

package/package.json

@@ -1,74 +1,84 @@
 {
   "name": "@elliots/typical",
-  "version": "0.1.9",
+  "version": "0.2.0-beta.1",
   "description": "Runtime safe TypeScript transformer using typia",
-  "main": "dist/src/index.js",
-  "type": "module",
+  "keywords": [
+    "runtime",
+    "transformer",
+    "typescript",
+    "typia",
+    "validation"
+  ],
+  "homepage": "https://github.com/elliots/typical#readme",
+  "bugs": {
+    "url": "https://github.com/elliots/typical/issues"
+  },
+  "license": "MIT",
+  "author": "Elliot Shepherd <elliot@jarofworms.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elliots/typical.git"
+  },
   "bin": {
-    "typical": "bin/typical",
     "ttsx": "bin/ttsx",
-    "ttsc": "bin/ttsc"
+    "typical": "bin/typical"
   },
+  "files": [
+    "bin",
+    "src",
+    "dist/src"
+  ],
+  "type": "module",
+  "main": "dist/src/index.js",
   "exports": {
     ".": "./dist/src/index.js",
-    "./tsc-plugin": "./dist/src/tsc-plugin.js",
     "./esm": "./dist/src/esm-loader-register.js",
     "./loader": "./dist/src/esm-loader.js"
   },
-  "files": [
-    "dist/src",
-    "bin",
-    "src"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/elliots/typical.git"
-  },
-  "bugs": {
-    "url": "https://github.com/elliots/typical/issues"
-  },
-  "homepage": "https://github.com/elliots/typical#readme",
-  "keywords": [
-    "typescript",
-    "runtime",
-    "validation",
-    "typia",
-    "transformer"
-  ],
-  "author": "Elliot Shepherd <elliot@jarofworms.com>",
-  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "commander": "14.0.2",
-    "glob": "13.0.0",
-    "minimatch": "10.0.1",
-    "strip-json-comments": "5.0.3",
-    "ts-patch": "3.3.0",
-    "tsx": "4.21.0",
-    "typescript": "^5.0.0",
-    "typia": "11.0.0",
-    "unplugin": "2.3.11"
+    "@elliots/typical-compiler": "0.2.0-beta.1"
   },
   "devDependencies": {
-    "@types/node": "22"
+    "@types/node": "22",
+    "c8": "10.1.3",
+    "oxfmt": "^0.21.0",
+    "oxlint": "1.36.0",
+    "oxlint-tsgolint": "0.10.1",
+    "typescript": "5.9.3"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"
   },
+  "engines": {
+    "pnpm": ">=10"
+  },
   "scripts": {
+    "lint": "oxlint --type-aware",
+    "lint:fix": "oxlint --type-aware --fix",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
     "build": "tsc",
+    "build:all": "pnpm run build:go:all && pnpm run build:ts",
+    "build:go": "cd packages/compiler && npm run build:go",
+    "build:go:all": "./scripts/build-binaries.sh",
+    "build:ts": "pnpm --filter './packages/*' run build && pnpm run build",
     "dev": "tsc --watch",
     "test": "rm -f test/test.temp.ts && tsc && node --import ./dist/src/esm-loader-register.js --test dist/test/*.test.js",
-    "bench": "cd bench && npm install && npm run bench",
+    "test:coverage": "rm -f test/test.temp.ts && tsc && node --import ./dist/src/esm-loader-register.js --test --experimental-test-coverage dist/test/*.test.js",
+    "test:coverage:html": "rm -f test/test.temp.ts && tsc && c8 --reporter=html --reporter=text --include='dist/src/**' node --import ./dist/src/esm-loader-register.js --test dist/test/*.test.js",
+    "bench": "pnpm run build && cd bench && pnpm install && npm run bench",
     "test:all": "npm test && npm run bench",
-    "sample:esm": "cd samples/esm && npm install && npm run start",
-    "sample:ttsx": "cd samples/ttsx && npm install && npm run start",
-    "sample:tsc": "cd samples/tsc && npm install && npm run build && npm run start",
-    "sample:ttsc": "cd samples/ttsc && npm install && npm run build && npm run start",
+    "sample:esm": "cd samples/esm && pnpm install && npm run start",
+    "sample:ttsx": "cd samples/ttsx && pnpm install && npm run start",
+    "sample:tsc": "cd samples/tsc && pnpm install && npm run build && npm run start",
+    "sample:ttsc": "cd samples/ttsc && pnpm install && npm run build && npm run start",
     "sample:vite-react": "cd samples/vite-react && pnpm install && pnpm run test",
-    "samples": "npm run sample:esm && npm run sample:ttsx && npm run sample:tsc && npm run sample:ttsc && npm run sample:vite-react",
-    "publish:all": "node scripts/publish.js"
+    "sample:bun": "cd samples/bun && pnpm install && bun run start",
+    "samples": "npm run sample:esm && npm run sample:ttsx && npm run sample:vite-react && npm run sample:bun",
+    "publish:all": "npm run lint && npm run format:check && node scripts/publish.js"
   }
 }

package/src/cli.ts

@@ -1,19 +1,14 @@
 #!/usr/bin/env node
 
-import { Command } from 'commander';
-import * as fs from 'fs';
-import * as path from 'path';
-import { TypicalTransformer } from './transformer.js';
-import * as ts from 'typescript';
-import { loadConfig } from './config.js';
-import { shouldIncludeFile } from './file-filter.js';
+import { Command } from 'commander'
+import * as fs from 'fs'
+import * as path from 'path'
+import { TypicalTransformer } from './transformer.js'
+import { loadConfig, validateConfig } from './config.js'
 
-const program = new Command();
+const program = new Command()
 
-program
-  .name('typical')
-  .description('Runtime safe TypeScript transformer using typia')
-  .version('0.1.0');
+program.name('typical').description('Runtime safe TypeScript transformer').version('0.1.0')
 
 program
   .command('transform')
@@ -21,91 +16,43 @@ program
   .argument('<file>', 'TypeScript file to transform')
   .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')
-  .action(async (file: string, options: { output?: string; config?: string; mode?: 'basic' | 'typia' | 'js' }) => {
-    try {
-      const config = loadConfig(options.config);
-      const transformer = new TypicalTransformer(config);
-      
-      if (!fs.existsSync(file)) {
-        console.error(`File not found: ${file}`);
-        process.exit(1);
+  .option('-p, --project <file>', 'TypeScript config file path', 'tsconfig.json')
+  .action(
+    async (
+      file: string,
+      options: {
+        output?: string
+        config?: string
+        project?: string
+      },
+    ) => {
+      let transformer: TypicalTransformer | null = null
+      try {
+        const config = validateConfig(loadConfig(options.config))
+        transformer = new TypicalTransformer(config, options.project)
+
+        if (!fs.existsSync(file)) {
+          console.error(`File not found: ${file}`)
+          process.exit(1)
+        }
+
+        console.log(`Transforming ${file}...`)
+        const result = await transformer.transform(path.resolve(file), 'ts')
+
+        // Determine output file path
+        const outputFile = options.output ? path.resolve(options.output) : file + '.transformed.ts'
+
+        fs.writeFileSync(outputFile, result.code)
+        console.log(`Transformed code written to ${outputFile}`)
+      } catch (error) {
+        console.error('Transformation failed:', error)
+        process.exit(1)
+      } finally {
+        if (transformer) {
+          await transformer.close()
+        }
       }
+    },
+  )
 
-      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);
-      
-      console.log(`Transformed code written to ${outputFile}`);
-    } catch (error) {
-      console.error('Transformation failed:', error);
-      process.exit(1);
-    }
-  });
-
-// program
-//   .command('build')
-//   .description('Transform all TypeScript files in the project')
-//   .option('-c, --config <file>', 'Config file path')
-//   .option('--dry-run', 'Show what would be transformed without making changes')
-//   .action(async (options: { config?: string, dryRun?: boolean }) => {
-//     try {
-//       const transformer = new TypicalTransformer();
-      
-//       const { glob } = await import('glob');
-
-//       const config = loadConfig(options.config);
-      
-//       if (!config.include || config.include.length === 0) {
-//         console.error('No include patterns specified in config');
-//         process.exit(1);
-//       }
-      
-//       const files: string[] = [];
-      
-//       for (const pattern of config.include) {
-//         const matched = await glob(pattern, { 
-//           ignore: config.exclude,
-//           absolute: true 
-//         });
-//         files.push(...matched);
-//       }
-      
-//       console.log(`Found ${files.length} files to transform`);
-      
-//       if (options.dryRun) {
-//         files.forEach(file => console.log(`Would transform: ${file}`));
-//         return;
-//       }
-      
-//       let transformed = 0;
-      
-//       for (const file of files) {
-//         // Double-check with our shared filtering logic
-//         if (!shouldIncludeFile(file, config)) {
-//           console.log(`Skipping ${file} (excluded by filters)`);
-//           continue;
-//         }
-        
-//         try {
-//           console.log(`Transforming ${file}...`);
-//           const transformedCode = transformer.transformFile(file, ts);
-//           fs.writeFileSync(file, transformedCode);
-//           transformed++;
-//         } catch (error) {
-//           console.error(`Failed to transform ${file}:`, error);
-//         }
-//       }
-      
-//       console.log(`Successfully transformed ${transformed}/${files.length} files`);
-//     } catch (error) {
-//       console.error('Build failed:', error);
-//       process.exit(1);
-//     }
-//   });
-
-program.parse();
+program.parse()

package/src/config.ts

@@ -1,38 +1,74 @@
 export interface TypicalDebugConfig {
-  writeIntermediateFiles?: boolean;
+  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[];
-  reusableValidators?: boolean;
-  validateCasts?: boolean;
-  hoistRegex?: boolean;
-  debug?: TypicalDebugConfig;
+  include?: string[]
+  exclude?: string[]
+  reusableValidators?: boolean
+  validateCasts?: boolean
+  hoistRegex?: boolean
+  debug?: TypicalDebugConfig
   /**
    * Type patterns to skip validation for (supports wildcards).
    * Use this for types that typia cannot process (e.g., React event types).
    * Example: ["React.*", "Express.Request", "*.Event"]
    */
-  ignoreTypes?: string[];
+  ignoreTypes?: string[]
   /**
    * Skip validation for DOM types (Document, Element, Node, etc.) and their subclasses.
    * These types have complex Window intersections that typia cannot process.
    * Default: true
    */
-  ignoreDOMTypes?: boolean;
+  ignoreDOMTypes?: boolean
   /**
    * Validate function parameters and return types at runtime.
    * When enabled, typed function parameters get runtime validation calls injected.
    * Default: true
    */
-  validateFunctions?: boolean;
+  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 const defaultConfig: TypicalConfig = {
-  include: ["**/*.ts", "**/*.tsx"],
-  exclude: ["node_modules/**", "**/*.d.ts", "dist/**", "build/**"],
-  reusableValidators: true,
+  include: ['**/*.ts', '**/*.tsx'],
+  exclude: ['node_modules/**', '**/*.d.ts', 'dist/**', 'build/**'],
+  reusableValidators: false, // Off by default for accurate source maps (set to true for production)
   validateCasts: false,
   validateFunctions: true,
   hoistRegex: true,
@@ -40,7 +76,12 @@ export const defaultConfig: TypicalConfig = {
   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
 /**
@@ -49,61 +90,163 @@ export const defaultConfig: TypicalConfig = {
  */
 export const DOM_TYPES_TO_IGNORE = [
   // Core DOM types
-  "Document",
-  "DocumentFragment",
-  "Element",
-  "Node",
-  "ShadowRoot",
-  "Window",
-  "EventTarget",
+  'Document',
+  'DocumentFragment',
+  'Element',
+  'Node',
+  'ShadowRoot',
+  'Window',
+  'EventTarget',
   // HTML Elements
-  "HTML*Element",
-  "HTMLElement",
-  "HTMLCollection",
+  'HTML*Element',
+  'HTMLElement',
+  'HTMLCollection',
   // SVG Elements
-  "SVG*Element",
-  "SVGElement",
+  'SVG*Element',
+  'SVGElement',
   // Events
-  "*Event",
+  '*Event',
   // Other common DOM types
-  "NodeList",
-  "DOMTokenList",
-  "NamedNodeMap",
-  "CSSStyleDeclaration",
-  "Selection",
-  "Range",
-  "Text",
-  "Comment",
-  "CDATASection",
-  "ProcessingInstruction",
-  "DocumentType",
-  "Attr",
-  "Table",
-  "TableRow",
-  "TableCell",
-  "StyleSheet",
-];
-
-import fs from 'fs';
-import path from 'path';
+  'NodeList',
+  'DOMTokenList',
+  'NamedNodeMap',
+  'CSSStyleDeclaration',
+  'Selection',
+  'Range',
+  'Text',
+  'Comment',
+  'CDATASection',
+  'ProcessingInstruction',
+  'DocumentType',
+  'Attr',
+  'Table',
+  'TableRow',
+  'TableCell',
+  'StyleSheet',
+]
+
+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: string): RegExp | null {
+  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 as Error).message}`)
+    return null
+  }
+}
+
+/**
+ * Pre-compile all ignore patterns for efficient matching.
+ */
+export function compileIgnorePatterns(config: TypicalConfig): CompiledIgnorePatterns {
+  const userPatterns: RegExp[] = []
+  const domPatterns: RegExp[] = []
+
+  // 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: CompiledIgnorePatterns | null = null
+let cachedConfig: TypicalConfig | null = null
+
+/**
+ * Get compiled ignore patterns, using cache if config hasn't changed.
+ */
+export function getCompiledIgnorePatterns(config: TypicalConfig): CompiledIgnorePatterns {
+  // 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?: string): TypicalConfig {
-  const configFile = configPath || path.join(process.cwd(), 'typical.json');
-  
+  const configFile = configPath || path.join(process.cwd(), 'typical.json')
+
   if (fs.existsSync(configFile)) {
     try {
-      const configContent = fs.readFileSync(configFile, 'utf8');
-      const userConfig: Partial<TypicalConfig> = JSON.parse(configContent);
-      
+      const configContent = fs.readFileSync(configFile, 'utf8')
+      const userConfig: Partial<TypicalConfig> = JSON.parse(configContent)
+
       return {
         ...defaultConfig,
         ...userConfig,
-      };
+      }
     } catch (error) {
-      console.warn(`Failed to parse config file ${configFile}:`, error);
-      return defaultConfig;
+      console.warn(`Failed to parse config file ${configFile}:`, error)
+      return defaultConfig
+    }
+  }
+
+  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 defaultConfig;
-}
+  return result
+}

package/src/esm-loader-register.ts

@@ -1,2 +1,2 @@
-import { register } from 'node:module';
-register('./esm-loader.js', { parentURL: import.meta.url });
+import { register } from 'node:module'
+register('./esm-loader.js', { parentURL: import.meta.url })