README
TsReflect is a CommonJS module for Node applications for working with JSON declaration files generated by the tsreflect-compiler. The library is essentially a wrapper for the TypeScript 1.4 compiler type system along with methods for loading the JSON declaration file format.
NOTE! Currently, there are not plans to support any version of TypeScript beyond 1.4. If in the future the TypeScript compiler supports an extensible emitter, this project will be picked up again.
Examples
Example: load all declaration files in the cwd and it's subdirectories, then print the name of any exported interfaces.
/// <reference path="./lib/tsreflect.d.ts" />
import reflect = require("tsreflect");
// load all declaration files in the cwd and it's subdirectories.
reflect.load("**/*.d.json", (err, symbols) => {
if(err) throw err;
// print name of all exported interfaces
for(var i = 0, l = symbols.length; i < l; i++) {
var symbol = symbols[i];
if(symbol.isInterface()) {
process.stdout.write(symbol.getName() + '\n');
}
else if(symbol.isModule()) {
var moduleExports = symbol.getExports();
for(var j = 0, k = moduleExports.length; j < k; j++) {
if(moduleExports[j].isInterface()) {
process.stdout.write(moduleExports[j].getName() + '\n');
}
}
}
}
});
Documentation
require
reference
load
loadSync
resolve
createContext
getSymbol
ReflectContext
Symbol
Annotation
Type
Signature
Diagnostic
DiagnosticError
Constructor
require(moduleName)
Load type information for an external module in the global context. Analogous to Node's require function.
This method assumes that the .d.json file is in the same directory as the .js file that it contains type information for. Just like Node's require function, if a relative path is specified, it is considered to be relative to the source file that called require. Also like Node's require function, files are loaded synchronously. If you would like to load type information asynchronously, see the load function.
Parameters
- moduleName
string
- The name of the module to load.
Returns: Symbol
reference(fileName)
Load type information for an internal module or global declarations in the global context. Analogous to TypeScript's reference tags.
This method assumes that the .d.json file is in the same directory as the .js file that it contains type information for. Just like TypeScript's /// <reference path="... tags, the path is considered to be relative to the source file that called reference. Files are loaded synchronously. If you would like to load type information asynchronously, see the load function.
Parameters
- fileName
string
- The name of the file to load.
Returns: void
load(callback)
Asynchronously load type information for the given filename pattern(s) in the global context. If the path is not specified then symbol information is loaded, if available, for all required modules.
This method assumes that the .d.json files are in the same directory as the .js file that they contain type information for. The load method supports glob patterns for filename matching. Relative paths are considered to be relative to the current working directory.
Once all declaration files have been loaded, the callback is called with the symbols for any external modules and any top level global declarations in the processed files.
Parameters
- callback - Called when the load operation completes.
Returns: void
load(path, callback)
Parameters
- path
string
- callback
Returns: void
load(path, callback)
Parameters
- path
string[]
- callback
Returns: void
loadSync()
Synchronously load type information for the given filename pattern(s) in the global context. If the path is not specified then symbol information is loaded, if available, for all required modules.
This method assumes that the .d.json files are in the same directory as the .js file that they contain type information for. The load method supports glob patterns for filename matching. Relative paths are considered to be relative to the current working directory.
Once all declaration files have been loaded, a list of symbols is returned any external modules and any top level global declarations in the processed files.
Returns: Symbol[]
loadSync(path)
Parameters
- path
string
Returns: Symbol[]
loadSync(path)
Parameters
- path
string[]
Returns: Symbol[]
resolve(entityName)
Finds the symbol for the given entity name in the global context. If a global symbol with the given name cannot be found, an exception is thrown.
Parameters
- entityName
string
- The global entity name to resolve.
Returns: Symbol
createContext()
Creates a reflection context.
Returns: ReflectContext
getSymbol(ctr)
Searches all loaded symbol information for the given constructor and returns the symbol if found.
Parameters
- ctr
Constructor
- The constructor to search for. Note this does not work for global symbols.
Returns: Symbol
ReflectContext Interface
Reflection context.
require(moduleName)
Load type information for an external module in the current context. Analogous to Node's require function.
This method assumes that the .d.json file is in the same directory as the .js file that it contains type information for. Just like Node's require function, if a relative path is specified, it is considered to be relative to the source file that called require. Also like Node's require function, files are loaded synchronously. If you would like to load type information asynchronously, see the load function.
Parameters
- moduleName
string
- The name of the module to load.
Returns: Symbol
reference(fileName)
Load type information for an internal module or global declarations in the current context. Analogous to TypeScript's reference tags.
This method assumes that the .d.json file is in the same directory as the .js file that it contains type information for. Just like TypeScript's /// <reference path="... tags, the path is considered to be relative to the source file that called reference. Files are loaded synchronously. If you would like to load type information asynchronously, see the load function.
Parameters
- fileName
string
- The name of the file to load.
Returns: void
load(callback)
Asynchronously load type information for the given filename pattern(s) in the current context.
This method assumes that the .d.json files are in the same directory as the .js file that they contain type information for. The load method supports glob patterns for filename matching. Relative paths are considered to be relative to the current working directory.
Once all declaration files have been loaded, the callback is called with the symbols for any external modules and any top level global declarations in the processed files.
Parameters
- callback - Called when the load operation completes.
Returns: void
load(path, callback)
Parameters
- path
string
- callback
Returns: void
load(path, callback)
Parameters
- path
string[]
- callback
Returns: void
loadSync()
Synchronously load type information for the given filename pattern(s) in the global context. If the path is not specified then symbol information is loaded, if available, for all required modules.
This method assumes that the .d.json files are in the same directory as the .js file that they contain type information for. The load method supports glob patterns for filename matching. Relative paths are considered to be relative to the current working directory.
Once all declaration files have been loaded, a list of symbols is returned any external modules and any top level global declarations in the processed files.
Returns: Symbol[]
loadSync(path)
Parameters
- path
string
Returns: Symbol[]
loadSync(path)
Parameters
- path
string[]
Returns: Symbol[]
resolve(entityName)
Finds the symbol for the given entity name in the current context. If a global symbol with the given name cannot be found, an exception is thrown.
Parameters
- entityName
string
- The global entity name to resolve.
Returns: Symbol
getSymbol(ctr)
Searches all loaded symbol information in the current context for the given constructor and returns the symbol if found.
Parameters
- ctr
Constructor
- The constructor to search for. Note this does not work for global symbols.
Returns: Symbol
Symbol Interface
Represents a named identifier.
getName
getFullName
getDescription
getAnnotations
hasAnnotation
getType
getDeclaredType
getExports
resolve
getValue
setValue
invoke
isVariable
isFunction
isClass
isInterface
isEnum
isModule
isImport
isTypeParameter
isProperty
isMethod
isAccessor
isGetAccessor
isSetAccessor
isEnumMember
isTypeAlias
getName()
Gets the name of the symbol.
Returns: string
getFullName()
Gets the qualified name of the symbol.
Returns: string
getDescription()
Gets the description of the symbol.
Returns: string
getAnnotations(name)
Finds annotations with the specified name. If no name is specified, then all annotations are returned.
Parameters
- name
string
- The name of the annotation to find.
Returns: Annotation[]
hasAnnotation(name)
Returns true if the symbols has an annotation with the specified name; Otherwise, returns false.
Parameters
- name
string
- The name of the annotation to find.
Returns: boolean
getType()
Gets the type of the symbol.
Returns: Type
getDeclaredType()
Gets the type declared by the symbol. For a class getType() returns the static side of the class and getDeclaredType() returns the instance side of the class.
Returns: Type
getExports()
Gets all symbols exported by this symbol. This is used to get the members of a module or the static members of a class.
Returns: Symbol[]
resolve(entityName)
Finds the symbol for the given entity name relative to the current symbol. If a symbol with the given name cannot be found, an exception is thrown.
Parameters
- entityName
string
- The entity name to resolve.
Returns: Symbol
getValue(obj)
Gets the value of the symbol on the given object. The symbol must be a property, variable, or accessor.
Parameters
- obj
any
- The object to get the value for.
Returns: any
setValue(obj, value)
Sets the value of the symbol on the given object. The symbol must be a property, variable, or accessor.
Parameters
- obj
any
- The object to set the value on. - value
any
- The value to set.
Returns: void
invoke(obj, args)
Invokes the method described by the symbol on the given object. The symbol must be a method.
Parameters
- obj
any
- The object to call the method on. - args
any[]
- The arguments to pass to the method.
Returns: any
isVariable()
Returns true if the symbol is a variable; Otherwise, returns false.
Returns: boolean
isFunction()
Returns true if the symbol is a function; Otherwise, returns false.
Returns: boolean
isClass()
Returns true if the symbol is a class; Otherwise, returns false.
Returns: boolean
isInterface()
Returns true if the symbol is an interface; Otherwise, returns false.
Returns: boolean
isEnum()
Returns true if the symbol is an enum; Otherwise, returns false.
Returns: boolean
isModule()
Returns true if the symbol is a module; Otherwise, returns false.
Returns: boolean
isImport()
Returns true if the symbol is an import; Otherwise, returns false.
Returns: boolean
isTypeParameter()
Returns true if the symbol is a type parameter; Otherwise, returns false.
Returns: boolean
isProperty()
Returns true if the symbol is a class or interface property; Otherwise, returns false.
Returns: boolean
isMethod()
Returns true if the symbol is a class or interface method; Otherwise, returns false.
Returns: boolean
isAccessor()
Returns true if the symbol is an accessor; Otherwise, returns false.
Returns: boolean
isGetAccessor()
Returns true if the symbol is a get accessor; Otherwise, returns false.
Returns: boolean
isSetAccessor()
Returns true if the symbol is a set accessor; Otherwise, returns false.
Returns: boolean
isEnumMember()
Returns true if the symbol is an enum member; Otherwise, returns false.
Returns: boolean
isTypeAlias()
Returns true if the symbol is a type alias; Otherwise, returns false.
Returns: boolean
Annotation Interface
Represents a custom annotation.
name
The name of the annotation.
Type: string
value
The value of the annotation.
Type: any
getDeclarationFileName()
Returns the name of the file that the annotation was declared in.
Returns: string
Type Interface
Represents a type.
getName
getFullName
getDescription
getAnnotations
hasAnnotation
getProperties
getProperty
getCallSignatures
getConstructSignatures
getStringIndexType
getNumberIndexType
isIdenticalTo
isSubtypeOf
isAssignableTo
isSubclassOf
getBaseTypes
getBaseType
hasBaseType
getBaseClass
getInterfaces
getInterface
hasInterface
isClass
isInterface
isTuple
isUnion
isArray
isIndex
isAnonymous
isReference
isEnum
isStringLiteral
isTypeParameter
isAny
isString
isNumber
isBoolean
isVoid
isIntrinsic
isObjectType
getEnumValue
getEnumName
getEnumNames
getElementType
getElementTypes
createInstance
getConstructor
getName()
Gets the name of the type, if any.
Returns: string
getFullName()
Gets the qualified name of the type, if any.
Returns: string
getDescription()
Gets the description of the type.
Returns: string
getAnnotations(inherit)
Gets all annotations declared for the type.
Parameters
- inherit
boolean
- True if annotations should be inherited from base types.
Returns: Annotation[]
getAnnotations(name, inherit)
Finds annotations with the specified name. If no name is specified, then all annotations are returns.
Parameters
- name
string
- The name of the annotation to find. - inherit
boolean
- True if annotations should be inherited from base types.
Returns: Annotation[]
hasAnnotation(name, inherit)
Returns true if the type has an annotation with the specified name; Otherwise, returns false.
Parameters
- name
string
- The name of the annotation to find. - inherit
boolean
- True if base types should be checked for the annotation as well.
Returns: boolean
getProperties()
Gets a list of all properties of the type. Note that properties include fields, accessors, and methods.
Returns: Symbol[]
getProperty(name)
Finds a property with the specified name. If no property is found, undefined is returned. Note that properties include fields, accessors, and methods.
Parameters
- name
string
- The property name to find.
Returns: Symbol
getCallSignatures()
Gets all call signatures of the type.
Returns: Signature[]
getConstructSignatures()
Gets all construct signatures of the type.
Returns: Signature[]
getStringIndexType()
Gets the string index type of the type. For example, for { [key: string]: boolean }, getStringIndexType() will return the intrinsic boolean type.
Returns: Type
getNumberIndexType()
Gets the number index type of the type. For example, for { [key: number]: string }, getNumberIndexType() will return the intrinsic string type.
Returns: Type
isIdenticalTo(target, diagnostics)
Returns true if the current type is identical to the target type; Otherwise, returns false. If diagnostic information regarding the differences between the types is desired, any empty array should be passed to the diagnostics parameter.
Parameters
- target
Type
- The target type. - diagnostics
Diagnostic[]
- Array where diagnostic information regarding the differences between the types is placed.
Returns: boolean
isSubtypeOf(target, diagnostics)
Returns true if the current type is a subtype of the target type; Otherwise, returns false. If diagnostic information regarding the differences between the types is desired, any empty array should be passed to the diagnostics parameter.
Parameters
- target
Type
- The target type. - diagnostics
Diagnostic[]
- Array where diagnostic information regarding the differences between the types is placed.
Returns: boolean
isAssignableTo(target, diagnostics)
Returns true if the current type is assignable to the target type; Otherwise, returns false. If diagnostic information regarding the differences between the types is desired, any empty array should be passed to the diagnostics parameter.
Parameters
- target
Type
- The target type. - diagnostics
Diagnostic[]
- Array where diagnostic information regarding the differences between the types is placed.
Returns: boolean
isSubclassOf(target)
Returns true if the current type if a subclass of the target type; Otherwise, returns false.
Parameters
- target
Type
- The target type.
Returns: boolean
getBaseTypes()
Gets a list of types that this class or interface extends.
Returns: Type[]
getBaseType(name)
Gets the type that this class or interface extends that matches the specified name or undefined if no match is found.
Parameters
- name
string
- The name of the base type to find.
Returns: Type
hasBaseType(target)
Returns true if the target type is extended by the current type; Otherwise, returns false.
Parameters
- target
Type
- The target type.
Returns: boolean
getBaseClass()
Gets the base class of a class type.
Returns: Type
getInterfaces()
Gets a list of interface that this class implements.
Returns: Type[]
getInterface(name)
Gets the interface that is implemented or inherited by the current class that matches the specified name.
Parameters
- name
string
- The name of the base type to find.
Returns: Type
hasInterface(target)
Returns true if the target interface is implemented or inherited by the current class; Otherwise, returns false.
Parameters
- target
Type
- The target type.
Returns: boolean
isClass()
Returns true if the type is a class; Otherwise, returns false.
Returns: boolean
isInterface()
Returns true if the type is an interface; Otherwise, returns false.
Returns: boolean
isTuple()
Returns true if the type is a tuple; Otherwise, returns false.
Returns: boolean
isUnion()
Returns true if the type is a union type; Otherwise, returns false.
Returns: boolean
isArray()
Returns true if the type is an array; Otherwise, returns false.
Returns: boolean
isIndex()
Returns true if the type is an index type; Otherwise, returns false.
Returns: boolean
isAnonymous()
Returns true if the type is anonymous; Otherwise, returns false.
Returns: boolean
isReference()
Returns true if the type is a generic reference; Otherwise, returns false.
Returns: boolean
isEnum()
Returns true if the type is an enum; Otherwise, returns false.
Returns: boolean
isStringLiteral()
Returns true if the type is a string literal; Otherwise, returns false.
Returns: boolean
isTypeParameter()
Returns true if the type is a type parameter; Otherwise, returns false.
Returns: boolean
isAny()
Returns true if the type is the intrinsic any type; Otherwise, returns false.
Returns: boolean
isString()
Returns true if the type is the intrinsic string type; Otherwise, returns false.
Returns: boolean
isNumber()
Returns true if the type is the intrinsic number type; Otherwise, returns false.
Returns: boolean
isBoolean()
Returns true if the type is the intrinsic boolean type; Otherwise, returns false.
Returns: boolean
isVoid()
Returns true if the type is the intrinsic void type; Otherwise, returns false.
Returns: boolean
isIntrinsic()
Returns true if the type is an intrinsic type; Otherwise, returns false.
Returns: boolean
isObjectType()
Returns true if the type is an object type; Otherwise, returns false.
Returns: boolean
getEnumValue(value, ignoreCase)
Gets the numeric enum value for the given member name.
Parameters
- value
string
- The enum member name to get the value for. - ignoreCase
boolean
- True if case should be ignored when finding the member name.
Returns: number
getEnumName(value)
Gets the enum member name for the given numeric enum value.
Parameters
- value
number
- The numeric value to get the name for.
Returns: string
getEnumNames()
Gets a list of enum member names.
Returns: string[]
getElementType()
Gets the element type for an array type.
Returns: Type
getElementTypes()
Gets the element types a union or tuple type.
Returns: Type[]
createInstance(args)
Creates an instance of a class. If arguments are provided then the constructor is called; Otherwise, the object is created without calling the constructor. To call a parameter-less constructor, pass an empty array to args.
Note that This method assumes that the .d.json file is in the same directory as the .js file that it contains type information for. For external modules, Node's require method is used to load the JavaScript module.
Parameters
- args
any[]
- The constructor arguments.
Returns: any
getConstructor()
Gets the JavaScript constructor for a class type.
Note that This method assumes that the .d.json file is in the same directory as the .js file that it contains type information for. For external modules, Node's require method is used to load the JavaScript module.
Returns: Function
Signature Interface
Represents a call signature.
getDescription()
Gets a description of the signature.
Returns: string
getAnnotations(name)
Finds annotations with the specified name. If no name is specified, then all annotations are returned.
Parameters
- name
string
- The name of the annotation to find.
Returns: Annotation[]
hasAnnotation(name)
Returns true if the symbols has an annotation with the specified name; Otherwise, returns false.
Parameters
- name
string
- The name of the annotation to find.
Returns: boolean
getParameters()
Gets a list of all parameters for the call signature.
Returns: Symbol[]
getParameter(name)
Gets a parameter for the signature with the specified name. If no parameter matches the name then undefined is returned.
Parameters
- name
string
- The parameter name to find.
Returns: Symbol
getReturnType()
Gets the return type of the signature.
Returns: Type
Diagnostic Interface
Diagnostic information.
filename
The name of the .d.json file that contained the error
Type: string
messageText
Message explaining the error.
Type: string
code
Error code.
Type: number
DiagnosticError Interface
Extension of standard Error that includes diagnostic information.
diagnostics
Array of Diagnostics that provides details on the error that occurred.
Type: Diagnostic[]
name
Type: string
message
Type: string
Constructor Interface
A Constructor.
name
Type: string