README.md

tpl-ts-jsdoc

Plain JavaScript with types by leveraging TypeScript's JSDoc support.

• Why?
• Stack
• npm scripts
• Tools
• FAQ
• Random tips
• Changelog

Why?

• Plain JavaScript and JSDoc
• 💄 TypeScript is good at types
• 📜 Types are already part of docs, repeating creates noise
• 💕 Incentivize documentation writing by giving them static typing powers ⚡
• 🧠 Thinking about types and code logic are different mental activities. One is zoomed-in, focused on what each piece is, the other, zoomed-out and focused on how the data flows from one transition to another

Stack

• Main: JavaScript + types using TypeScript support for JSDoc
• Testing: riteway
• Linting: ESLint, @asd14/eslint-config
• Formatting: ESLint rules + prettier
• Environment variable: dotenv

npm scripts

• Clean package install

# "setup": "rm -rf ./node_modules && npm install && npm audit fix",
npm run setup

• Check for package updates (with interactive console)

# "update": "npm-check --update",
npm run update

• Compile "src" folder into "dist" while also generating ".d.ts" - see tsconfig.json

# "build": "tsc --skipLibCheck",
npm run build

• Lint source files - see .eslintrc

# "lint:md": "markdownlint *.md",
# "lint:js": "eslint --quiet src",
# "lint": "npm run lint:md && npm run lint:js",
npm run lint

• Run all ".test.js" files from "dist" folder - see example test file

# "pretest": "npm run build",
# "test": "riteway 'dist/**/*.test.js' | tap-nirvana",
npm run test

• Watch changes in "src" folder and re-run tests

# "tdd": "nodemon --ext js,json --watch src --exec 'npm test'"
npm run tdd

Tools

• jsdoc - An API documentation generator for JavaScript
• better-docs - Beautiful toolbox for JSDoc generated documentation - with 'typescript', 'category' and 'component' plugins
• documentation.js - The documentation system for modern JavaScript
• apidoc - Inline Documentation for RESTful web APIs
• jsdoc-to-markdown - Generate markdown documentation from jsdoc-annotated JavaScript

FAQ

1. Can I use both JSDocs infered types and TypeScript annotations?

No, TypeScript draws a hard line between functionalities provided in .js and .ts files. TypeScript specific syntax is only available in .ts files, while JSDoc interpretation in .js.

Random tips

• Naming conventions that work
• Hierarchical Model-View-Controller
• Better repeat yourself than a wrong abstraction
• Don't fix imaginary future problem
• Extract code in libraries and test 100%
• If possible, don't mock, E2E test

Changelog

See the releases section for details.