typescript-functions
Style and good practices when implementing or refactoring TypeScript functions and methods
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-15
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- typescript-functions
- description
- Style and good practices when implementing or refactoring TypeScript functions and methods
03 SKILL.md 正文
typescript-functions
Best practices and style guide for implementing TypeScript functions and methods.
Architecture
Avoid side-effects. Most functions and methods should be pure or at least provide local reasoning. Leave the most egregious side effects either to the framework or to an outer layer of the application.
For reference, the list shows effects from best to worst.
- no side effects, pure function (best).
- logging.
- local mutation of self.
- local mutation of input args.
- caching.
- print and input.
- file I/O,
- database access.
- image display, sound, complex rendering of markup.
- network access.
- global mutation of application behavior (worst).
Try to keep implementations as high as possible in this list.
Testing
Pure functions should be tested with examples in unit tests. If the function
respect some invariant, use property-based testing to generate a wide range of
TypeScript's fast-check library is a good choice for this.
Functions up to "local mutation of input args" can be tested with no special setup. Always use property based tests, when an invariant is known.
Functions that use caching should usually reset the cache before each test.
Functions with simple IO should capture output using appropriate mocking for
console.log and console.error and for prompt.
Functions that read files should use mocking and functions that write files
should do so in temporary directories, e.g., using the tmp library.
Functions that access databases should use transactions and rollbacks to avoid leaving the database in a dirty state. Many frameworks provide built-in support for this via pytest fixtures.
Functions that produces complex multimedia usually should be tested via approval testing. Python have the approvaltests.Python library for this.
Network access should usually be mocked in unit tests and tested in integration tests.
When a function produces a global mutation of application behavior, it should should also provide a snapshot mechanism that restore the application to its previous state. Ideally it should be done using context managers. Ask the user if this mechanism should be exposed as a public API or not.
Coding style
Names of functions are camelCase. Always document public functions. Always type
input and output parameters. At toplevel, use function declarations instead of
const with arrow functions. Use arrow functions as callbacks and for inner
functions.
Arguments
Use at most 4 positional arguments in a function. If it has more then 4 parameters, use a single object parameter with named properties.
If the function has more than 2 arguments of the same type, prefer an object parameter with named properties. Break this rule if the function expresses a clear relation between the two arguments or if the position does not matter.
A clear relation has form word(first, second) and can be understood as
first word second.
// good
function join(a: string, b: string): string { ... }
function hasPrefix(text: string, prefix: string): boolean { ... }
function replace(text: string, { sub, by }: { sub: string, by: string }): string { ... }
// bad
function replace(text: string, sub: string, by: string): string { ... }
If the function expresses a relation between two arguments and the role of each argument is implicit by position, also require them to be positional. E.g.,
def swap[T](a: T, b: T, /) -> tuple[T, T]: ...
If the function has more than one optional argument with the same type, require
both to be keyword-only. If it has more than 3 optional arguments, require all
of them to be keyword-only. Use the * symbol to enforce this in the function
signature. E.g.,
def join_items(data: Iterable[str], *, sep: str = ",", end: str = "\n") -> str: ...
If the function does not change the input args, prefer interfaces over concrete types.
Documentation comments
Use JSDoc style. Always break the block comment to have more then one line, even for short comments, e.g.,
/**
* Return a new array in reverse order of elements.
*/
function reverse() {
// ...
}
Use markdown to structure information (e.g., lists, code blocks).
The first line should be a short summary of the function's purpose. If there are more relevant details, they should be included as one or more paragraphs separated by blank lines.
Use JSDoc tags @param, @returns, and @throws to document parameters,
return values and exceptions. Do not include the types in the @param and
@returns tags. Specify them in the function signature.
Put a blank line before the first @param tag and before the @returns tag and @throws tags.
Public functions that do not produce side effects should be documented with a
doctest example. Use the @example tag. Skip the test if it is too complex or
requires too much external dependencies or preparation.
Below is a good example of how to document a function:
/**
* Return a new array in reverse order of elements.
*
* @example reverse([1, 2, 3])
* //=> [3,2,1]
*
* @param arr - The array to reverse.
* @param inplace - If true, reverse the array in place. Otherwise, return a new array.
*
* @returns A new array with the elements in reverse order.
*/
function reverse<T>(arr: T[], inplace: boolean = false): T[] {
return inplace? arr.reverse() : [...arr].reverse();
}
04 同仓库更多 Skills
unslop
Cut AI tells from any writing. Must always apply.
python-publish
Guidelines to publish Python packages
python-projects
Style and good practices when implementing Python projects
python-paths
Good practices when working with file paths in Python
python-modules
Style and good practices when implementing or refactoring Python modules
python-functions
Style and good practices when implementing or refactoring Python functions and methods