From 25de4289ef324e08b7f5ddc31d2dd2e151f13942 Mon Sep 17 00:00:00 2001 From: Dave Allen Date: Thu, 22 Jan 2015 15:35:30 -0800 Subject: [PATCH] Updated for Meteor 1.0.3.1 --- meteor/README.md | 111 ++++++++++++++++++++++++++++----------------- meteor/meteor.d.ts | 77 +++++++++++-------------------- 2 files changed, 97 insertions(+), 91 deletions(-) diff --git a/meteor/README.md b/meteor/README.md index 286d20a496..4bd829d861 100644 --- a/meteor/README.md +++ b/meteor/README.md @@ -1,11 +1,11 @@ # Meteor Type Definitions -These are the definitions for version 1.0.2.1 of Meteor. This readme will be updated soon. +These are the definitions for version 1.0.3.1 of Meteor. Although these definitions can be downloaded separately for use, the recommended way to use these definitions in a Meteor application is by installing the [typescript-libs](https://atmosphere.meteor.com/package/typescript-libs) Meteor smart package. The smart package contains TypeScript definitions forMeteor, common third-party libraries (e.g. jquery, underscore, d3 etc.), and common smart packages -(e.g. iron-router, underscore, d3, etc.). +(e.g. iron-router, etc). From within any Meteor application that is version 0.9.0 or later, install this package in the standard manner: @@ -13,28 +13,42 @@ From within any Meteor application that is version 0.9.0 or later, install this -## Usage Overview -For most applications, there are 4 specific steps you will have to take to write your Meteor application in TypeScript using this package: +## Usage -1. [Reference the definitions] (#usage-type-definition-references) -2. [Declare functions for Templates in a special way] (#usage-templates) -3. [Declare Collections in a special way] (#usage-collections) -4. [Create custom definitions for code you write] (#usage-creating-definitions) -5. [Transpile your .ts files into .js files] (#usage-transpilation) +1. Add a symbolic link to the definitions from within some directory within your project (e.g. ".typescript" or "lib"). The definitions can be found somewhere +deep within `/.meteor/...`. The following will probably work: + + $ ln -s ../.meteor/local/build/programs/server/assets/packages/meteortypescript_typescript-libs/definitions package_defs + If the definitions can't be found within the .meteor directory, you will have to manually pull down the definitions from github and add them to your project: + -## Usage: Type Definition References -Within any TypeScript file, you can reference the Meteor definition file with this line: +2. Install the [Typescript compiler for Meteor](https://github.com/meteor-typescript/meteor-typescript-compiler) or an [IDE which can transpile TypeScript to JavaScript](#transpiling-typescript). +3. From the typescript files, add references. Reference the definition files with a single line: - /// + /// (substitute path in your project) + Or you can reference definition files individually: -## Usage: Templates -When specifying template functions, you will need to use "bracket notation" instead of "dot notation": + /// (substitue path in your project) + /// + /// - Template['myTemplateName']['rendered'] = function ( ) { ... } +4. Be aware of differences in coding styles when using TypeScript (see below) + + +## TypeScript/Meteor coding style + +### References + +Try to stay away from referencing *file.ts*, rather generate a *file.d.ts* using `tsc --reference file.ts`, and reference it in your file. Compilation will +be much faster and code cleaner - it's always better to split definition from implemention. + +### Templates + +When specifying template *helpers*, *events*, and functions for *created*, *rendered*, and *destroyed*, you will need to use a "bracket notation" instead of the "dot notation": Template['myTemplateName']['helpers']({ foo: function () { @@ -42,21 +56,28 @@ When specifying template functions, you will need to use "bracket notation" inst } }); - Template['myTemplateName']['foo'] = function () { - return Session.get("foo"); - }; + Template['myTemplateName']['rendered'] = function ( ) { ... } +This is because TypeScript enforces typing and it will throw an error saying "myTemplateName" does not exist when using the dot notation. -For "dot" notation, TypeScript requires properties be specified on a variable (but not for bracket notation), and it will throw an error saying "myTemplateName" -does not exist on Template. +### Accessing a Form field +Trying to read a form field value? use `(evt.target).value`. +### Global variables -## Usage: Collections -The majority of extra work required to use TypeScript with Meteor is creating and maintaining the collection interfaces. However, doing so also provides the +Preface any global variable declarations with a TypeScript "declare var" statement: + + declare var NavbarHelpers; + NavbarHelpers = {}; + NavbarHelpers.someMethod = function() {...} + +### Collections + +The majority of extra work required to use TypeScript with Meteor is creating and maintaining the collection interfaces. However, doing so also provides the additional benefit of succinctly documenting collection schema definitions (that are actually enforced). -To define collections, you will need to create an interface representing the collection, and then declare a Collection type variable with that interface type (as a generic): +To define collections, you will need to create an interface representing the collection and then declare a Collection type variable with that interface type (as a generic): interface JobDAO { _id?: string; @@ -65,39 +86,47 @@ To define collections, you will need to create an interface representing the col queuedAt?: string; } - declare var Jobs: Meteor.Collection; - Jobs = new Meteor.Collection('jobs'); + declare var Jobs: Mongo.Collection; + Jobs = new Mongo.Collection('jobs'); Finally, any TypeScript file using collections will need to contain a reference at the top pointing to the collection definitions: - /// - /// - /// + /// + /// +### Creating definition files -If you choose to define collections (using the code above) in a separate file (e.g. collections/models/models.ts) and then create a separate file per collection -with the methods and permissions for that collection (e.g. collections/jobs.ts), the collection definitions should be one directory deeper than the collection -method/permission declarations so that Meteor can find the variable declarations before use. (e.g. collections/models/models.ts). - - - -## Usage: Creating Definitions Here is a guide to creating definitions: +If you have lots of custom definitions for a project, you can: +- Create multiple definition files and include individual references to each definition file. +- Create one huge monolithic definition file so you only have to refer to that file. +- Create multiple definition files, and create a definition file with references to the other definitions files so that you only have to maintain one reference +for all of you custom definitions. e.g. contents of ".typescript/custom_defs/custom-definitions.d.ts": -## Usage: Transpilation -WebStorm is good TypeScript-aware editor. It can automatically transpile your TypeScript code into JavaScript every time you save a file. To enable this + /// + /// + /// + /// + + +## Transpiling TypeScript + +### Meteor plugin +One solution for transpiling typescript is to install the following meteor package [https://github.com/meteor-typescript/meteor-typescript-compiler](https://github.com/meteor-typescript/meteor-typescript-compiler) + +### IDE/Editor Transpilation +WebStorm is a good TypeScript-aware editor. It can automatically transpile your TypeScript code into JavaScript every time you save a file. To enable this feature in WebStorm on OSX, first install the TypeScript transpiler on your system: $ [sudo -H] npm install -g typescript Then, within WebStorm, go to Preferences -> File Watchers -> "+" symbol and add TypeScript. -If you are not using a TypeScript-aware editor, you can transpile the files using the [Meteor Typescript Compiler](https://github.com/orefalo/meteor-typescript-compiler). +### Command line +Last option, is to compile code from the command line. With node and the typescript compiler installed: - -## Example/Reference Projects -* [TypeScript demos](https://github.com/orefalo/meteor-typescript-demos) + $ tsc *.ts \ No newline at end of file diff --git a/meteor/meteor.d.ts b/meteor/meteor.d.ts index 7049e02f93..f640d0f17a 100644 --- a/meteor/meteor.d.ts +++ b/meteor/meteor.d.ts @@ -288,7 +288,7 @@ declare module Accounts { function config(options: { sendVerificationEmail?: boolean; forbidClientAccountCreation?: Boolean; - restrictCreationByEmailDomain?: string; + restrictCreationByEmailDomain?: string | Function; loginExpirationInDays?: number; oauthSecretKey?: string; }): void; @@ -320,27 +320,17 @@ declare module Accounts { declare module Blaze { var currentView: Blaze.View; - function With(data: Object, contentFunc: Function): Blaze.View; - function With(data: Function, contentFunc: Function): Blaze.View; + function With(data: Object | Function, contentFunc: Function): Blaze.View; function If(conditionFunc: Function, contentFunc: Function, elseFunc?: Function): Blaze.View; function Unless(conditionFunc: Function, contentFunc: Function, elseFunc?: Function): Blaze.View; function Each(argFunc: Function, contentFunc: Function, elseFunc?: Function): Blaze.View; function isTemplate(value: any): boolean; - function render(templateOrView: Template, parentNode: Node, nextNode?: Node, parentView?: Blaze.View): Blaze.View; - function render(templateOrView: Blaze.View, parentNode: Node, nextNode?: Node, parentView?: Blaze.View): Blaze.View; - function renderWithData(templateOrView: Template, data: Object, parentNode: Node, nextNode?: Node, parentView?: Blaze.View): Blaze.View; - function renderWithData(templateOrView: Template, data: Function, parentNode: Node, nextNode?: Node, parentView?: Blaze.View): Blaze.View; - function renderWithData(templateOrView: Blaze.View, data: Object, parentNode: Node, nextNode?: Node, parentView?: Blaze.View): Blaze.View; - function renderWithData(templateOrView: Blaze.View, data: Function, parentNode: Node, nextNode?: Node, parentView?: Blaze.View): Blaze.View; + function render(templateOrView: Template | Blaze.View, parentNode: Node, nextNode?: Node, parentView?: Blaze.View): Blaze.View; + function renderWithData(templateOrView: Template | Blaze.View, data: Object | Function, parentNode: Node, nextNode?: Node, parentView?: Blaze.View): Blaze.View; function remove(renderedView: Blaze.View): void; - function toHTML(templateOrView: Template): string; - function toHTML(templateOrView: Blaze.View): string; - function toHTMLWithData(templateOrView: Template, data: Object): string; - function toHTMLWithData(templateOrView: Template, data: Function): string; - function toHTMLWithData(templateOrView: Blaze.View, data: Object): string; - function toHTMLWithData(templateOrView: Blaze.View, data: Function): string; - function getData(elementOrView?: HTMLElement): Object; - function getData(elementOrView?: Blaze.View): Object; + function toHTML(templateOrView: Template | Blaze.View): string; + function toHTMLWithData(templateOrView: Template | Blaze.View, data: Object | Function): string; + function getData(elementOrView?: HTMLElement | Blaze.View): Object; function getView(element?: HTMLElement): Blaze.View; function Template(viewName?: string, renderFunction?: Function): void; function TemplateInstance(view: Blaze.View): void; @@ -372,7 +362,7 @@ declare module EJSON { function toJSONValue(val: EJSON): JSON; function fromJSONValue(val: JSON): any; function stringify(val: EJSON, options?: { - indent?: boolean; + indent?: boolean | number | string; canonical?: Boolean; }): string; function parse(str: string): EJSON; @@ -410,9 +400,7 @@ declare module Meteor { userEmail?: string; loginStyle?: string; }, callback?: Function): void; - function loginWithPassword(user: Object, password: string, callback?: Function): void; - function loginWithPassword(user: string, password: string, callback?: Function): void; - function subscribe(name: string, ...args): SubscriptionHandle; + function loginWithPassword(user: Object | string, password: string, callback?: Function): void; function subscribe(name: string, ...args): SubscriptionHandle; function call(name: string, ...args): void; function apply(name: string, args: EJSON[], options?: { @@ -553,12 +541,13 @@ declare module Package { version?: string; name?: string; git?: string; + documentation?: string; }): void; function onUse(func: Function): void; function onTest(func: Function): void; function registerBuildPlugin(options?: { name?: string; - use?: string; + use?: string | string[]; sources?: string[]; npmDependencies?: Object; }): void; @@ -574,16 +563,10 @@ declare module Cordova { } declare module Session { - function set(key: string, value: EJSON): void; - function set(key: string, value: any /** Undefined **/): void; - function setDefault(key: string, value: EJSON): void; - function setDefault(key: string, value: any /** Undefined **/): void; + function set(key: string, value: EJSON | any /** Undefined **/): void; + function setDefault(key: string, value: EJSON | any /** Undefined **/): void; function get(key: string): any; - function equals(key: string, value: string): boolean; - function equals(key: string, value: number): boolean; - function equals(key: string, value: boolean): boolean; - function equals(key: string, value: any /** Null **/): boolean; - function equals(key: string, value: any /** Undefined **/): boolean; + function equals(key: string, value: string | number | boolean | any /** Null **/ | any /** Undefined **/): boolean; } declare module HTTP { @@ -606,10 +589,10 @@ declare module HTTP { declare module Email { function send(options: { from?: string; - to?: string; - cc?: string; - bcc?: string; - replyTo?: string; + to?: string | string[]; + cc?: string | string[]; + bcc?: string | string[]; + replyTo?: string | string[]; subject?: string; text?: string; html?: string; @@ -638,6 +621,9 @@ declare module ReactiveVar { declare function Template(): void; declare module Template { + var onCreated; /** TODO: add return value **/ + var onRendered; /** TODO: add return value **/ + var onDestroyed; /** TODO: add return value **/ var created: Function; var rendered: Function; var destroyed: Function; @@ -647,7 +633,7 @@ declare module Template { function instance(): Blaze.TemplateInstance; function currentData(): {}; function parentData(numLevels?: number): {}; - function registerHelper(name: string, func: Function): void; + function registerHelper(name: string, helperFunction: Function): void; } declare function CompileStep(): void; @@ -674,29 +660,20 @@ declare module CompileStep { sourcePath?: string; }); /** TODO: add return value **/ function addAsset(options: { - }, path: string, data: any /** Buffer **/); /** TODO: add return value **/ - function addAsset(options: { - }, path: string, data: string); /** TODO: add return value **/ + }, path: string, data: any /** Buffer **/ | string); /** TODO: add return value **/ function error(options: { }, message: string, sourcePath?: string, line?: number, func?: string); /** TODO: add return value **/ } declare function PackageAPI(): void; declare module PackageAPI { - function use(packageNames: string, architecture?: string, options?: { + function use(packageNames: string | string[], architecture?: string, options?: { weak?: boolean; unordered?: Boolean; }): void; - function use(packageNames: string[], architecture?: string, options?: { - weak?: boolean; - unordered?: Boolean; - }): void; - function imply(packageSpecs: string): void; - function imply(packageSpecs: string[]): void; - function addFiles(filename: string, architecture?: string): void; - function addFiles(filename: string[], architecture?: string): void; - function versionsFrom(meteorRelease: string): void; - function versionsFrom(meteorRelease: string[]): void; + function imply(packageSpecs: string | string[]): void; + function addFiles(filename: string | string[], architecture?: string): void; + function versionsFrom(meteorRelease: string | string[]): void; // function export(exportedObject: string, architecture?: string): void; }