TypeScript organization: namespaces? modules? confusion

Question

I'm new to TypeScript and the more I read about modules and namespaces, the more it confuses me. Should I go with modules? Should I go with namespaces? should I use both? help!

I have existing javascript (.js) files that I'm trying to convert to TypeScript. There is one .js file with some general functions and one .js file with some functions specific to filters.

Now I would like to organize this a bit more with TypeScript, as I would normally do with C#.

Is this correct usage or how should it be organized?

I'm not using a module, should I? (how?)

Company.ts

namespace Company {

  // nothing yet, but in future it might.

}

Company.Project.ts

namespace Company.Project {

  import Company; // like this?

  let myVar : string = "something";

  export function handyGeneralFunction1(foo, bar) {
    // ...
  }

  export function handyGeneralFunction2(foo, bar, foo, bar) {
    // ...
    doInternalCalc();
    // ...
  }

  export function handyGeneralFunction3() {
    // ...
  }

  function doInternalCalc() {
    // ...
  }
}

Company.Project.Filter.ts

namespace Company.Project.Filter {

    import Project = Company.Project; // like this?

    export function initializeFilter() {
        // ...
        initMetadata();
        // ...
    }

    function initMetadata() {
        // ...
        Project.handyGeneralFunction3();

        let helper : FilterHelper = new FilterHelper("aaaa,bbbb");
        let res:string[] = helper.parseData();
    }

    function foo() {
        // ...
        let x :string = Project.myVar + " else"; // can I use myVar here?
    }

   // a class in the namespace
   export class FilterHelper {

         data: string;

        constructor(theData: string) {
            this.data = theData;
        }

        parseData() : string[] {
             // ...
             return new Array<string>();
        }
   }

}

Answer 1

If you have the possibility to really improve the project structure, you should definitely go with modules instead of namespaces. Depending on the size of the project, this can require some effort.

Introducing namespaces could be useful if your app is not that large and you don't want to invest in switching to a different build system that can handle real modules. Using namespaces is not much more than some named global variables that contain the functions and variables. This can get confusing pretty soon as you don't have any proper dependency structures. You need to take care of importing all files in the correct order for namespaces to work correctly. The import syntax you used can even be omitted, as you anyway only reference another global object, that needs to be initialized at that point in time.

So namespaces could be your very first step if you don't have the possibility to do any larger changes on your codebase. For a future-proof setup, I would definitely suggest to use real modules. But be aware that this doesn't come for free.

For further information, I suggest to have a look at the official comment on this at https://www.typescriptlang.org/docs/handbook/namespaces-and-modules.html or the section in TypeScript Deep Dive at https://basarat.gitbooks.io/typescript/content/docs/project/namespaces.html