The repository for high quality TypeScript type definitions
2016-02-29 18:55
603 查看
Best practices
This is a guide to the best practices to follow when creating typing files. There are a variety of different ways that typing files can be constructed. Different approaches can be used - this is intended as a guide to what approaches make sense in certain scenarios.Also, it's a steer on how to deal with limitations in TypeScript. As much as it hurts to say it, TypeScript v1.0 is not flawless. There are certain minor flaws / shortcomings in the language which have implicatations for how typings are created. Here we will detail those limitations, how they can be worked around at present and how you can best vote for improvements in the language on the TypeScript site.
Ghost modules
Also callednon-instantiated modules. Instead of polluting the global namespace with many interfaces, it is okay to create a module that contains interfaces only. This does not introduce a variable on the global namespace (see safety in below sample) and this module can only be used for types.
// this pattern has 3 name in top level interface NodeFoo { } interface NodeBar { } interface NodeBuzz { } // this ghost module has 1 name in top level declare module NodeJS { interface Foo { } interface Bar { } interface Buzz { } } // safety! var n = NodeJS; // TS Error : Could not find symbol NodeJS
This also allows you to open up further customization in external modules as interfaces declared inside external module declarations cannot be extended e.g. the following is good as people can customize
foofurther in other library definitions.
// Usage when declaring an external module declare module 'foo' { var foo: NodeJS.Foo; export = foo; }
Extending built-in types
There isn't a way to add static members to native objects at the moment aslib.d.tsdefines them as a
var Date:{/*members*/}and
vars are not extendable. Two solutions are proposed to the TS team. Either use interfaces instead of var in lib.d.ts (vote) and/or make variables/classes open ended (vote)
For adding members to instances of native types there are relevant interfaces in available in
lib.d.tse.g.
// add members to Date instances interface Date { newMember: number; } // usage var foo = new Date(); foo.newMember = 123; // okay
Getter / Setter
Instead of :declare function duration(value?: number): any;
better to do:
declare function duration(): number; declare function duration(value: number): void;
Fluent
Pretty self explanatory:interface Something { foo(): Something; bar(): Something; }
Callback signatures
Do not mark callback arguments as optional if they are passed in everytime by the calling code. Also leave the return asanyif the calling code doesn't care. For example in the following good declaration
foois the calling code we are declaring that always calls with
barand
basand doesn't care of the callback return value:
declare function foo(callback: (bar: any, bas: any) => any): void; // Usage is as expected by a JavaScript developer foo(() => { }); foo((bar) => 123); foo((bar, bas) => '');
A wrong way to model it would be as shown below as it enforces restrictions the original calling code doesn't impose:
declare function foo(callback: (bar?: any, bas?: any) => void);
Function Overloading
A Union Type (anyfor now) is needed only for config object bags. For functions / constructors use function overloading e.g.
declare class Foo { constructor(foo: number); constructor(foo: string); } new Foo(123); // okay new Foo('123'); // okay new Foo(true); // Error
Overload Ordering
Code with overloads must be manually sorted from the tightest/more-specific overload to loosest. See example below:interface Parent { x; } interface Child extends Parent { y; } function foo(p: Child): Child; function foo(p: Parent): Parent; function foo(p: any): any; function foo(p: any) { return p; } var a = foo({ x: 3, y: 4 }); // a: Child var b = foo({ x: 5 }); // b: Parent var y: any; var c = foo(y); // c: any
相关文章推荐
- bean的初始化过程和对应源代码
- less
- IOS开发之UIView总结
- uva10271 经典DP
- hiredis aeStop仅在redis命令的回调函数中生效 分析
- 大数据之一:几个概念
- [Android] 怎么在应用中实现密码隐藏?
- TI DSP TMS320C66x学习笔记之SPI Nor Flash多核程序烧写(七)
- maven之伺服仓库
- 奕新集团---单实例到RAC11g生产环境搭建(无图)
- 多线程--GCD
- io_service work 的作用
- WPF 支持分组互斥的 RadioButton 式单选菜单
- socket http文件下载器c语言实现
- Gallery2 让图库不显示bmp格式图片
- log4net记录日志
- keepalived配置
- MMS存储与显示
- JSP2 自定义标签
- 用BOOST_FOREACH简化遍历操作