ts-ref-kit 1.1.27 → 1.2.0

package/README.md

@@ -22,97 +22,98 @@ npm install ts-ref-kit
 ### Type Reflection Example
 
 ```typescript
-import { getClassDefinition, getInterfaceDefinition, getTypeAliasDefinition, getEnumDefinition } from 'ts-ref-kit';
+import { getClassDefinition, getInterfaceDefinition, getTypeAliasDefinition, getEnumDefinition } from 'ts-ref-kit'
 
 // Get class definition
-const classDef = getClassDefinition('MyClass');
-console.log(classDef?.name); // Output: class name
-console.log(classDef?.properties); // Output: class properties list
-console.log(classDef?.methods); // Output: class methods list
+const classDef = getClassDefinition('MyClass')
+console.log(classDef?.name) // Output: class name
+console.log(classDef?.properties) // Output: class properties list
+console.log(classDef?.methods) // Output: class methods list
 
 // Get interface definition
-const interfaceDef = getInterfaceDefinition('MyInterface');
-console.log(interfaceDef?.name); // Output: interface name
-console.log(interfaceDef?.properties); // Output: interface properties list
-console.log(interfaceDef?.methods); // Output: interface methods list
+const interfaceDef = getInterfaceDefinition('MyInterface')
+console.log(interfaceDef?.name) // Output: interface name
+console.log(interfaceDef?.properties) // Output: interface properties list
+console.log(interfaceDef?.methods) // Output: interface methods list
 
 // Get type alias definition
-const typeAliasDef = getTypeAliasDefinition('MyTypeAlias');
-console.log(typeAliasDef?.name); // Output: type alias name
-console.log(typeAliasDef?.type); // Output: type definition
+const typeAliasDef = getTypeAliasDefinition('MyTypeAlias')
+console.log(typeAliasDef?.name) // Output: type alias name
+console.log(typeAliasDef?.type) // Output: type definition
 
 // Get enum definition
-const enumDef = getEnumDefinition('MyEnum');
-console.log(enumDef?.name); // Output: enum name
-console.log(enumDef?.members); // Output: enum members
+const enumDef = getEnumDefinition('MyEnum')
+console.log(enumDef?.name) // Output: enum name
+console.log(enumDef?.members) // Output: enum members
 ```
 
 ### Type Validation Example
 
 ```typescript
-import { isType, assertType } from 'ts-ref-kit';
+import { isType, assertType } from 'ts-ref-kit'
 
 // Validate if value matches type
-const value = 'test';
-const isString = isType(value, 'string');
-console.log(isString); // Output: true
+const value = 'test'
+const isString = isType(value, 'string')
+console.log(isString) // Output: true
 
 // Assert value matches type (throws error if not)
-assertType<string>(value, 'string');
+assertType<string>(value, 'string')
 
-// Validate complex type
+// Validate a reflected interface
 interface User {
-  name: string;
-  age: number;
+    name: string
+    age: number
 }
 
-const user = { name: 'John', age: 30 };
-const isUser = isType(user, '{ name: string, age: number }');
-console.log(isUser); // Output: true
+const user = { name: 'John', age: 30 }
+const isUser = isType(user, 'User')
+console.log(isUser) // Output: true
 ```
 
 ### JSON Conversion Example
 
 ```typescript
-import { JSONTransfer } from 'ts-ref-kit';
+import { JSONTransfer } from 'ts-ref-kit'
 
 class User {
-  name: string;
-  age: number;
-  constructor() {
-    this.name = '';
-    this.age = 0;
-  }
+    name: string
+    age: number
+
+    constructor() {
+        this.name = ''
+        this.age = 0
+    }
 }
 
-const jsonString = '{"name":"John","age":30}';
-const jsonTransfer = new JSONTransfer();
+const jsonString = '{"name":"John","age":30}'
+const jsonTransfer = new JSONTransfer()
 
 // Convert JSON string to class instance
-const user = jsonTransfer.parse<User>(jsonString, User);
-console.log(user instanceof User); // Output: true
-console.log(user.name); // Output: John
-console.log(user.age); // Output: 30
+const user = jsonTransfer.parse<User>(jsonString, 'User')
+console.log(user instanceof User) // Output: true
+console.log(user.name) // Output: John
+console.log(user.age) // Output: 30
 ```
 
 ### Enum Operations Example
 
 ```typescript
-import { getEnumNames, getEnumValues } from 'ts-ref-kit';
+import { getEnumNames, getEnumValues } from 'ts-ref-kit'
 
 enum Color {
-  Red,
-  Green,
-  Blue
+    Red,
+    Green,
+    Blue
 }
 
 // Get enum names list
-const colorNames = getEnumNames('Color');
-console.log(colorNames); // Output: ['Red', 'Green', 'Blue']
+const colorNames = getEnumNames('Color')
+console.log(colorNames) // Output: ['Red', 'Green', 'Blue']
 
 // Get enum values list
-const colorValues = getEnumValues({ Color });
-console.log(colorValues); // Output: [0, 1, 2]
+const colorValues = getEnumValues({ Color })
+console.log(colorValues) // Output: [0, 1, 2]
 ```
 
 ## API Documentation
@@ -128,50 +129,64 @@ console.log(colorValues); // Output: [0, 1, 2]
 ### Type Reflection API
 
 #### Class Related
+
 - `getClassDefinition(arg: Constructor | object | string): ClassDefinition | undefined`
 - `getClassByName(className: string): Constructor | undefined`
 
 #### Interface Related
+
 - `getInterfaceDefinition(name: string): InterfaceDefinition | undefined`
 
 #### Type Alias Related
+
 - `getTypeAliasDefinition(name: string, genericArgs?: TypeDefinition[]): TypeAliasDefinition | undefined`
 
 #### Enum Related
+
 - `getEnumDefinition(name: string): EnumDefinition | undefined`
 - `getEnumNames(enumName: string): string[]`
 - `getEnumValues(args: { [enumName: string]: Record<string, string | number> }): (string | number)[]`
 
-#### Generic Type
-- `getTypeDefinition(typeName: string, genericArgs?: TypeDefinition[]): TypeDefinition`
+#### Type Utilities
+
+- `getTypeDef(type: Type | TypeDefinition): TypeDefinition`
+- `TypeDefinition.isPrimitiveType(type: TypeDefinition): boolean`
+- `TypeDefinition.isArrayType(type: TypeDefinition): boolean`
+- `TypeDefinition.isLiteralType(type: TypeDefinition): boolean`
+- `TypeDefinition.isTypeLiteralType(type: TypeDefinition): boolean`
+- `TypeDefinition.isUnionType(type: TypeDefinition): boolean`
+- `TypeDefinition.isIntersectionType(type: TypeDefinition): boolean`
+- `TypeDefinition.isTupleType(type: TypeDefinition): boolean`
+- `TypeDefinition.isClassDefinition(type: TypeDefinition): boolean`
+- `TypeDefinition.hasGenerics(type: TypeDefinition): boolean`
 
 ### Type Validation API
 
 - `isType(value: unknown, type: Type | TypeDefinition, depth: number = 5): boolean`
 - `assertType<T>(data: unknown, type: Type, depth: number = 5): T`
-- `validateValue(value: unknown, typeDef: TypeDefinition, depth: number = 5): ValidateResult`
+- `validateValue(value: unknown, typeDef: TypeDefinition, depth: number = 1): ValidateResult`
 
 ### JSON Conversion API
 
 - `JSONTransfer` class
-  - `parse<T = unknown>(jsonString: JSONString<T>, type?: Type): T`
+    - `parse<T = unknown>(jsonString: JSONString<T>, type?: Type): T`
 
 ### Configuration Options
 
 ```typescript
-import { ReflectConfig } from 'ts-ref-kit';
-
-ReflectConfig {
-  // Validation error handler
-  validationErrorHandler: function (e: ValidationError): void {
-    console.error(e.message);
-    console.error(e.failureResult?.errorStackFlow);
-  },
-  // Whether to enable validation
-  validation: true,
-  // Whether to enable debug mode
-  debug: false
+import { ReflectConfig } from 'ts-ref-kit'
+
+// Validation error handler
+ReflectConfig.validationErrorHandler = e => {
+    console.error(e.message)
+    console.error(e.failureResult?.errorStackFlow)
 }
+
+// Whether to enable validation
+ReflectConfig.validation = true
+
+// Whether to enable debug mode
+ReflectConfig.debug = false
 ```
 
 ## Advanced Usage
@@ -179,43 +194,45 @@ ReflectConfig {
 ### Generic Type Handling
 
 ```typescript
-import { getTypeDefinition } from 'ts-ref-kit';
+import { getTypeDef } from 'ts-ref-kit'
 
-// Get generic type definition
-const arrayOfStringType = getTypeDefinition('Array<string>');
-console.log(arrayOfStringType.arrayElementType?.name); // Output: string
+// Get a generic type definition
+const mapType = getTypeDef('Map<string, number>')
+console.log(mapType.name) // Output: Map
+console.log(mapType.generics?.[0].name) // Output: string
+console.log(mapType.generics?.[1].name) // Output: number
 
-// Use type literals
-const mapType = getTypeDefinition('Map<string, number>');
+// Get a reflected type by name
+const userType = getTypeDef('User')
+console.log(userType.classDefinition?.name || userType.interfaceName || userType.typeAliasName)
 ```
 
 ### Type Relationship Queries
 
 ```typescript
-import { getClassDefinition, getInterfaceDefinition } from 'ts-ref-kit';
+import { getClassDefinition } from 'ts-ref-kit'
 
 // Query if a class is a subclass of another class
-const classDef = getClassDefinition('MyClass');
-const isSubClass = classDef?.isSubClassOf('BaseClass');
+const classDef = getClassDefinition('MyClass')
+const isSubClass = classDef?.isSubClassOf('BaseClass')
 
 // Query if a class is a superclass of another class
-const isSuperClass = classDef?.isSuperClassOf('DerivedClass');
+const isSuperClass = classDef?.isSuperClassOf('DerivedClass')
 ```
 
 ### Special Type Registration
 
 ```typescript
-import { registerSpecialType } from 'ts-ref-kit';
+import { registerSpecialType } from 'ts-ref-kit'
 
 // Register custom special type
-registerSpecialType('MySpecialType', (typeArgs) => {
-  return {
+registerSpecialType({
     name: 'MySpecialType',
-    type: {
-      // Type definition
+    genericParams: ['T'],
+    getType(typeArg) {
+        return typeArg
     }
-  };
-});
+})
 ```
 
 ## Parser Configuration
@@ -231,34 +248,77 @@ import { defineConfig } from 'vite'
 import { reflectParserPlugin } from 'ts-ref-kit/parser'
 
 export default defineConfig({
-  plugins: [
-    reflectParserPlugin({
-      entry: 'src/main.ts',
-      sourcePaths: 'src'
-    })
-  ]
+    plugins: [
+        reflectParserPlugin({
+            entry: 'src/main.ts',
+            sourcePaths: 'src'
+        })
+    ]
 })
 ```
 
-When multiple built projects run in the same browser context, assign each one a
-separate reflect module and select it at runtime before using reflection APIs:
+When multiple independently built projects run in the same browser or Node.js
+context, assign each project a separate reflect module. `default` is only safe
+for a single project/build output; if multiple outputs all write metadata to
+`default`, the last one loaded may overwrite the others.
 
 ```typescript
 // vite.config.ts
 reflectParserPlugin({
-  entry: 'src/main.ts',
-  sourcePaths: 'src',
-  reflectModule: 'project-a'
+    entry: 'src/main.ts',
+    sourcePaths: 'src',
+    reflectModule: 'project-a'
 })
 ```
 
+#### Shared runtime usage
+
+```typescript
+// src/reflect.ts
+import { getReflectModule } from 'ts-ref-kit'
+
+export const reflect = getReflectModule('project-a')
+export const ReflectClass = reflect.ReflectClass
+export const ReflectValidate = reflect.ReflectValidate
+```
+
 ```typescript
-// src/main.ts
+import { reflect } from './reflect'
+
+reflect.getClassDefinition('User')
+reflect.isType(user, 'User')
+```
+
+Use this style when several packages share the same `ts-ref-kit` runtime, for
+example when libraries depend on the application's installed copy. In this
+scenario, avoid `setReflectModule` for isolation: it changes the shared default
+module name and can affect other packages using the same runtime.
+
+#### Bundled runtime compatibility
+
+If a package bundles its own copy of `ts-ref-kit`, its default module state is
+local to that bundled copy. Existing code that uses top-level APIs can be kept by
+setting the module once at package startup:
+
+```typescript
+// package entry
 import { setReflectModule } from 'ts-ref-kit'
 
 setReflectModule('project-a')
 ```
 
+After that, top-level APIs in that bundled package use `project-a`:
+
+```typescript
+import { getClassDefinition, isType } from 'ts-ref-kit'
+
+getClassDefinition('User')
+isType(user, 'User')
+```
+
+This compatibility style is intended for bundled/inline runtimes. For shared
+runtimes, prefer the explicit `getReflectModule(name)` API shown above.
+
 ### Custom Build Configuration
 
 If you're using other build tools or a custom build process, you can directly use `reflectLoader`:
@@ -267,16 +327,17 @@ If you're using other build tools or a custom build process, you can directly us
 import { reflectLoader } from 'ts-ref-kit/parser'
 
 const loader = reflectLoader({
-  sourcePaths: 'src',
-  exclude: /node_modules/,
-  outputLog: true
+    sourcePaths: 'src',
+    reflectModule: 'project-a',
+    exclude: /node_modules/,
+    outputLog: true
 })
 
 // Transform a single file
 const transformedCode = loader.transform(sourceCode, sourceFileName)
 
-// Generate all metadata
-const allMetas = loader.outputAllMetas()
+// Generate metadata injection code for the entry module
+const metadataCode = loader.outputAllMetas()
 ```
 
 ### Parser Options
@@ -286,7 +347,7 @@ const allMetas = loader.outputAllMetas()
 - `exclude`: File paths to exclude, can be a string, regular expression, or array of them
 - `forEnabledClassOnly`: Whether to only process classes that implement the `EnableReflect` interface
 - `outputLog`: Whether to output log information
-- `reflectModule`: Optional reflect module name for isolating metadata when multiple built projects share one browser context
+- `reflectModule`: Optional reflect module name for isolating metadata. Use a unique value for each independently built project/package that can run in the same browser or Node.js context.
 
 ### Working Principle
 
@@ -297,67 +358,41 @@ const allMetas = loader.outputAllMetas()
 
 ### Node.js Environment Usage
 
-In Node.js environments, you can directly use the parser to analyze TypeScript files:
+In Node.js environments, you can directly use the parser to analyze TypeScript files and generate injection code:
 
 ```javascript
-const { reflectLoader } = require('ts-ref-kit/parser');
-const fs = require('fs');
+const { reflectLoader } = require('ts-ref-kit/parser')
+const fs = require('fs')
 
-const sourceCode = fs.readFileSync('src/types.ts', 'utf8');
+const sourceCode = fs.readFileSync('src/types.ts', 'utf8')
 const loader = reflectLoader({
-  sourcePaths: 'src'
-});
-
-const transformedCode = loader.transform(sourceCode, 'src/types.ts');
-const metadata = loader.outputAllMetas();
-
-console.log(metadata);
-```
-
-### tsconfig.json Configuration
+    sourcePaths: 'src',
+    reflectModule: 'project-a'
+})
 
-To enable decorator metadata generation, add the following configuration to your `tsconfig.json`:
+const transformedCode = loader.transform(sourceCode, 'src/types.ts')
+const metadataCode = loader.outputAllMetas()
 
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "plugins": [
-      {
-        "transform": "ts-ref-kit/parser"
-      }
-    ]
-  }
-}
+console.log(metadataCode)
 ```
 
-### Webpack Configuration
-
-In Webpack projects, you can configure through custom transformers:
+You can also initialize reflection directly in Node.js with `setupReflectTypes`.
+The `reflectModule` option is optional and defaults to `default`, but it should
+match the runtime module name when you isolate multiple projects:
 
 ```javascript
-const { ReflectParserPlugin } = require('ts-ref-kit/parser');
-
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.tsx?$/,
-        use: [
-          {
-            loader: 'ts-loader',
-            options: {
-              getCustomTransformers: () => ({
-                before: [ReflectParserPlugin()]
-              })
-            }
-          }
-        ]
-      }
-    ]
-  }
-};
+const { setupReflectTypes } = require('ts-ref-kit/parser')
+const { getReflectModule } = require('ts-ref-kit')
+
+await setupReflectTypes({
+    filePaths: ['src'],
+    sourceFolder: process.cwd(),
+    distFolder: process.cwd(),
+    reflectModule: 'project-a'
+})
+
+const reflect = getReflectModule('project-a')
+const classDef = reflect.getClassDefinition('User')
 ```
 
 ## Development