Merge pull request #2523 from omidkrad/master

Backbone updates and comments

backbone/backbone-tests.ts

@@ -113,9 +113,12 @@ class EmployeeCollection extends Backbone.Collection<Employee> {
 class Book extends Backbone.Model {
     title: string;
     author: string;
+    published: boolean;
 }
 
 class Library extends Backbone.Collection<Book> {
+    // This model definition is here only to test type compatibility of the model, but it
+    // is not necessary in working code as it is automatically inferred through generics.
     model: typeof Book;
 }
 
@@ -123,31 +126,31 @@ class Books extends Backbone.Collection<Book> { }
 
 function test_collection() {
 
-    var books = new Library();
+    var books = new Books();
 
-    books.each(book => {
-        book.get("title");
-    });
+    var book1: Book = new Book({ title: "Title 1", author: "Mike" });
+    books.add(book1);
 
-    var titles = books.map(book => {
-        return book.get("title");
-    });
+    // Objects can be added to collection by casting to model type.
+    // Compiler will check if object properties are valid for the cast.
+    // This gives better type checking than declaring an `any` overload.
+    books.add(<Book>{ title: "Title 2", author: "Mikey" });
 
-    var publishedBooks = books.filter(book => {
-        return book.get("published") === true;
-    });
-
-    var alphabetical = books.sortBy((book: Book): number => {
-        return null;
-    });
-
-    var model: Book = new Book({title: "Test", author: "Mike"});
-    books.add(model);
-    var model2: Book = model.collection.first();
-    if (model !== model2) {
+    var model: Book = book1.collection.first();
+    if (model !== book1) {
         throw new Error("Error");
     }
 
+    books.each(book =>
+        book.get("title"));
+
+    var titles = books.map(book =>
+        book.get("title"));
+
+    var publishedBooks = books.filter(book =>
+        book.get("published") === true);
+
+    var alphabetical = books.sortBy((book: Book): number => null);
 }
 
 //////////

backbone/backbone.d.ts

@@ -113,8 +113,23 @@ declare module Backbone {
 
         fetch(options?: ModelFetchOptions): JQueryXHR;
 
-        get(attributeName: string): any;
-        set(attributeName: string, value: any, options?: ModelSetOptions): Model;
+        /**
+        * For strongly-typed access to attributes, use the `get` method only privately in public getter properties.
+        * @example
+        * get name(): string {
+        *    return super.get("name");
+        * }
+        **/
+        /*private*/ get(attributeName: string): any;
+
+        /**
+        * For strongly-typed assignment of attributes, use the `set` method only privately in public setter properties.
+        * @example
+        * set name(value: string) {
+        *    super.set("name", value);
+        * }
+        **/
+        /*private*/ set(attributeName: string, value: any, options?: ModelSetOptions): Model;
         set(obj: any, options?: ModelSetOptions): Model;
 
         change(): any;
@@ -170,7 +185,12 @@ declare module Backbone {
         add(model: TModel, options?: AddOptions): Collection<TModel>;
         add(models: TModel[], options?: AddOptions): Collection<TModel>;
         at(index: number): TModel;
+        /**
+         * Get a model from a collection, specified by an id, a cid, or by passing in a model.
+         **/
+        get(id: number): TModel;
         get(id: string): TModel;
+        get(id: Model): TModel;
         create(attributes: any, options?: ModelSaveOptions): TModel;
         pluck(attribute: string): any[];
         push(model: TModel, options?: AddOptions): TModel;
@@ -359,7 +379,7 @@ declare module Backbone {
 
     // Utility
     function noConflict(): typeof Backbone;
-    function setDomLibrary(jQueryNew: any): any;
+    var $: JQueryStatic;
 }
 
 declare module "backbone" {