I am developing two npn packages:
https://github.com/euberdeveloper/mongo-scanner
https://github.com/euberdeveloper/mongo-cleaner
I want to document them by using typedoc. The index.js file is the one provided by the npm module and is obtained by index.ts.
I want to document only what is exported by the library index.ts. I can filter the non-exported things with the typedoc options.
The problem is that the index.ts import things from other TS files and export only some of them. For instance, it imports and re-exports some interfaces from the interfaces/index.ts and the errors classes from errors/index.ts, but imports without exporting the class Database from the utils/database/index.ts.
Being actually exported, things such that Database class are documented even if they are exported by a file different from index.ts.
How can I filter them?
The current #next version of typedoc has a --library mode. Seems that there are going to be big changes with the #beta version and the future 1.0.0 version, where the mode option will even disappear. Development seems to proceed extremely slow, so I think that the only way now is to use the (probably bugged) #next and #beta versions and wait.
Edit: the 0.20.x is no more beta and has been released, it works good, so the problem is solved
Related
By default, when editing a JavaScript file in VSCode, it will assume that the fetch function and related types exist in the current context. This makes sense for JavaScript designed to run in the browser, but when running on node.js the fetch function does not exist unless it is installed via node-fetch. I find that in this context, VSCode is misleading, as it will not highlight an error when you trying calling the fetch function, or access other types such as Request and Response, even though they do not exist unless you have node-fetch installed.
How can I configure vscode to assume a node.js context, and therefore assume that fetch does not exist unless I explicitly import it from node-fetch?
Why web types are there by default
From the docs for tsconfig.json compilerOptions.lib:
TypeScript includes a default set of type definitions for built-in JS APIs (like Math), as well as type definitions for things found in browser environments (like document).
How to change the defaults
Create a tsconfig.json or jsconfig.json, and set the compilerOptions.lib array to not contain "DOM", which means that lib.dom.d.ts (the "DOM standard library" type definitions file that comes with TypeScript) will not be assumed. You should specify which ECMA Script standard you want to write your source code in.
The config file also has fields to control what files it takes effect on: files, include, and exclude. If you specify none of them, include will default to **, which matches everything beside and recursively under subdirectories beside the config file.
Having to create this file could be seen as annoying if you just want to write a single JS file (ie. now you have a whole config file just for one source file!). I don't know if there are alternatives that are more convenient for such a use case. If anyone knows, please edit this answer.
I looked briefly into TypeScript triple-slash directives, which allow specifying things on a per-file basis, but I think you can only add things (ie. I don't think you can use them to remove a lib).
At the time of this writing, there are VS Code settings that can be applied at the user-settings scope that affect settings for implicit projects (JS/TS files which don't have a project config file) (js/ts.implicitProjectConfig.*), but none of them are for setting the compileOptions.lib field, and my gut says it's probably not going to happen (but don't quote me on that).
You probably also want types for the Node API
Use npm to install a version of #types/node. Make sure the major version number of the version you install matches the major version number of the version of Node JS you want to script to be runnable on.
Fun irrelevant facts to this question
Continuing on the point about VS Code's user-settings for implicit projects, VS Code puts some defaults in effect (on top of those that TypeScript itself does) if no project is detected. You can poke through the code at github.dev/microsoft/vscode by doing "Find in Files", using extensions/typescript-language-features/**/* as the "files to include" field, and compilerOptions as the find query. compilerOptions.lib seems to not be something that VS Code touches in such a scenario.
Sometimes I see slightly different imports
import styled, { withTheme } from "styled-components/macro";
import styled, { withTheme } from "styled-components";
Since they have the same functionality I cannot understand the difference between them neither can google anything that could help.
In production styled-components generates unique hashes for css classes like .eeZmbc or .ZzNLl. These are used for saving space but are not useful for developers in development.
For semantic class names in development a babel plugin exists. It generates names like .Navbar__Item-sc-14eztoj-1 as in .FileName__StyledComponent-generatedHash to help us trace an element/style back to its source.
So if you use create-react-app you can use this plugin without ejecting and without adding it to babel config. You just have change your import from styled-components to styled-components/macro. A quick find-and-replace in you IDE will do the trick.
All the compile-time code transformation is handled by babel-plugin-macros
babel-plugin-macros defines a standard interface for libraries that want to use compile-time code transformation without requiring the user to add a babel plugin to their build system (other than babel-plugin-macros, which is ideally already in place).
Personally I add the babel plugins to the config file manually and use standard imports like styled-components.
Let's say that I have dependency X version 1.0 and dependency Y version 1.0 in package.json. If Y requires X version 2.0 (which I know because I looked in package-lock.json), will I still be able to use X version 1.0 in my code without issues?
With a couple of assumptions about good module behavior, it is perfectly feasible for two modules of differing versions to be in use in the same app.
Here are some of the things a "good behavior" module must do in order to allow this:
Not use global symbols that would conflict between versions (stick to exports only). If everything is done via module exports, then two versions of the same module can run just fine. Each one will be separately imported and the code will use only the imports from the appropriate version.
Have the two versions installed in different directories or with different names. The idea here is that the path to the module must be different between the two because that's how module caching works. If the full filename is different (either because of a differing install path or a differing filename), then the module loader will happily load each one separately.
Not register anything globally that would conflict (like not both try to start a server on the same port).
Not try to write data to the same file. If all file activity is relative to the install directory for the module, then this should be safe. But, if the module assumes something about a known path or both are using a path from the same environment variables and they end up conflicting on writing data to the same file, that could cause problems.
Not try to write conflicting property names to the same object. For example if both versions were in action as Express middleware and both were trying to write different things to the req.someProp property that could cause problems. But, if both versions weren't in use on the same requests or both were being used for different functionality, then this could work just fine.
will I still be able to use X version 1.0 in my code without issues?
So, it's certainly possible, but it depends upon the behavior of the module and what exactly it does globally or with shared resources.
I am currently working on a Node.JS project written in TypeScript using Node.JS Tools for Visual Studio (NTVS). I have a few classes and enums spread out in 3 or 4 files in my project. I am now trying to use the classes defined in those files from my main app file. From my previous work with Node, I know that I would normally need a require call to import each other file/class if I were working with a text editor and the command-line compiler. But, if I open any TypeScript file in my project and start typing the name of a class defined in a different file, Visual Studio shows IntelliSense autocomplete for the class name and its members. This makes me think that the NTVS and/or TypeScript configuration are automatically making all of my classes available project-wide. But if I click the 'run' button, errors are printed to the console because Node can't find the referenced classes at runtime.
This behavior leads me to believe that IntelliSense isn't actually telling me that the classes are available, just that they exist (which seems odd). If I add a require call to the top of the file, and use that imported value instead of the original class name, Node finds the class and I can use it in my code. But this presents two problems:
I must come up with a new name to use for the variable that I import the class into. If I require() it with the original name, Visual Studio shows errors saying that the identifier is a duplicate, because it seems to believe that the original class is available project-wide.
I don't get the autocomplete or type checking in my usage of the class. This pretty much defeats the purpose of using TypeScript.
So, what's the proper way to do this import? Is there a way to make all my classes available globally? If not, what import statements do I need?
This behavior leads me to believe that IntelliSense isn't actually telling me that the classes are available, just that they exist
unless you have top level import or export statement the file is considered a global module and is available project wide : http://basarat.gitbooks.io/typescript/content/docs/project/modules.html
A global module will not work at runtime in node.js
You should use file level modules using import/export and compile with --module commonjs
I think it would be great to directly import modules from node_modules directory without need to manually provide a declaration file for it (let us assume that declaration is provided with module itself). I guess that problem are dependencies that come with declarations (file paths could be resolved relative to the module, but that would cause duplicates and compiler can't handle that).
Currently working with node modules is very inconvenient because simple install from npm repository just isn't enough and we have to manually search for declarations and provide them in our project. Let's say that our project is dependent on 10 node modules (all of them have declarations) and after a year we would like to update them. We would have to manually search for new declarations and let's say that we have around 20 projects like this (it would become a nightmare). Maybe there should be an option to directly import .ts file from node module?
Do you have any suggestions?
This is a re-post from CodePlex to hear your opinions ...
If you use grunt-typescript then I've got a pull request which solves this at least for me. See https://github.com/k-maru/grunt-typescript/pull/36
From the pull request README
Working with modules in node_modules (i.e. npm)
The standard way to use npm packages is to provide a definition file
that specifies the package to the typescript and import the module from there.
///<reference path="path/to/mod.d.ts" />
import mod = module('mod')
The typescript compiler will convert the import to a nodejs require.
var mod = require('mod')
This is pretty unwieldy as you need to know the precise path to the
npm installed package and npm can put the package at pretty much any
level when you are working with multiple levels of dependencies.
With the node_modules option in the grunt config you can just
import a npm package without need to know the exact level where the
package has been installed by npm as long as it is installed locally
and not globally.
To import an npm module in your typescript source do
import npmModule = module('node_modules/npmModule/foo')
Mostly due to a lucky chance this works. Typescript compiler will read
the typescript definition file node_modules/npmModule/foo.d.ts if it
is present at some point on the way towards the root and the resulting
javascript file will contain a require for npmModule/foo if needed.
I don't think that node modules will ever contain built-in typescript support. The language still is a 0.x release and officially described as an alpha version.
Nevertheless there are means to ease the configuration process for typescript. Github already contains huge collections of .d.ts files such as:
https://github.com/borisyankov/DefinitelyTyped
or
https://github.com/soywiz/typescript-node-definitions
You might want to take a look at this tool: https://github.com/Diullei/tsd .
I've never used it but it seems like it's almost what you're looking for.
Moreover I've heard that an official database of .d.ts files is planned. Unfortunately I couldn't find the link but it will probably be some time before this is implemented anyways.