typescript-node
Use when writing or reviewing TypeScript or Node.js code. Strict mode, async/await footguns, error handling, null safety, real types vs any, ESM/CJS interop, npm hygiene (engines, lockfile, scripts, ci).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- typescript-node
- triggers
- [ "user", "model" ]
- description
- Use when writing or reviewing TypeScript or Node.js code. Strict mode, async/await footguns, error handling, null safety, real types vs any, ESM/CJS interop, npm hygiene (engines, lockfile, scripts, ci).
- allowed-tools
- [ "read", "exec", "grep", "edit" ]
03 SKILL.md 正文
TypeScript & Node.js
Modern TypeScript and Node.js. The compiler only helps if you do not lie to it - any, as, and ! disable the protection that justifies the cost of TS.
Config and types
strict: truein tsconfig (includesstrictNullChecks,noImplicitAny). A project without strict is JavaScript with annotations.noUncheckedIndexedAccessfor safe indexing (arr[i]returnsT | undefined- the source of most "undefined is not a function" bugs).exactOptionalPropertyTypeswhen the repo uses it -x?: Tdoes not accept explicitundefined.any= virus: propagates and disables checking. Preferunknown+ narrowing (typeof,instanceof, type guard).as Tonly when you KNOW more than the compiler (rarely).satisfiesvalidates without widening.!non-null assertion = "trust me": use only after a check that guarantees it, or refactor to narrowing.- Type guard:
function isX(v: unknown): v is X- real narrowing instead of cast. interfacefor objects/contracts,typefor unions/intersections/utilities.enumonly when a runtime value is needed;as const+ union covers the rest.- Generics with constraints (
<T extends X>); hiddenanyin a generic does not count as typed.
Null safety
?./??for optional access and fallback;??(not||) when0/''/falseare valid values -||swallows them.Array.find/Map.getreturnundefined: handle it, do not assume.- External API data is
unknownuntil validated:zod/valibotat the boundary (parse, not cast) -JSON.parsereturnsanyand lies. - With
strictNullCheckson,T | null | undefinedis explicit - do not bypass with!.
Async/await footguns
- Forgotten
await= dangling promise: anasyncreturningPromise<T>must be awaited or returned. forEach(async)does NOT wait: runs in parallel without awaiting. Correct: sequentialfor...oforPromise.all(map)for parallel.Promise.allrejects on the first failure and abandons the others (which keep running).Promise.allSettledwhen each result matters.- try/catch only catches errors after
await- a promise without await escapes the try (floating promise). ESLint@typescript-eslint/no-floating-promisescatches this. unhandledRejectioncrashes modern Node: every promise gets await,.catch(), orPromise.allSettled.asyncin event-handler/fire-and-forget callbacks: explicit.catch(log).- Fetch timeout:
AbortSignal.timeout(ms)- fetch without timeout can hang forever.
Error handling
throw new Error('msg', { cause: e })- neverthrow 'string'orthrow ewithout context.catch (e):eisunknownunder strict - narrow (e instanceof Error) beforee.message.- Custom errors: class
extends Errorwithname-instanceofdistinguishes failure types. - A catch that only logs and continues = swallowing: handle or re-throw with context.
process.on('unhandledRejection')as a safety net in services - not as a strategy.
Node and runtime
node:fs/promisesover sync callbacks; sync (readFileSync) blocks the whole event loop - only in scripts/CLIs, never in servers.- Buffer/stream for large files; whole-file
readFileinto memory explodes on big files. process.env.Xisstring | undefined: validate at the boundary (throw at boot if missing) or explicit default - neverprocess.env.KEY!.- ESM (
import) vs CJS (require): new projects ESM ("type": "module");__dirnamedoes not exist in ESM (import.meta.dirnameon Node 20.11+). - Top-level await only in ESM; in CJS wrap in
async main().
npm and dependencies
npm ciin CI/deploy (respects lockfile);npm installonly in dev.engines.nodedeclared; version pinned via.nvmrc/devcontainers.- Dependency
prepublish/postinstallscripts are supply-chain surface -npm install --ignore-scriptswhen not needed. npm audit/npm ls <pkg>before adopting a dep; commit the lockfile together withpackage.json(dep change without lockfile = CI installs something different from local).npxexecutes remote code:npx pkgdownloads and runs - confirm the package is official.
Common review findings
any/as/!proliferating (fake typing).forEach(async)ormapwith async withoutPromise.all.- Promises without await/catch (floating).
||where??was meant (swallows0/'').JSON.parse/res.json()cast straight to a type (lie).process.env.Xused unvalidated.readFileSync/execSyncin a server (blocks the loop).trywithout a realcatch(empty catch, log-only catch).- New dependency without updated
package-lock. console.logof large objects/objects with secrets in prod.
Cascade
- JS test fundamentals:
testing(vitest/jest at the boundary). - npm/shell script footguns:
shell-safe. - Node CI (npm ci, cache):
github-actions,deploy.
04 同仓库更多 Skills
montador-de-ideias
Use when assembling, expanding, or elevating a raw project idea or initial prompt into an ultra-detailed, first-principles dossier and compiled master prompt with journalistic OSINT market research, Tech Lead and Staff Architect justifications, atomic and modular hardening/optimization, and high-impact contact surfaces.
git-github-adaptive-engineering
Use when any task touches git history, GitHub issues/PRs/releases/CI, repo governance, or branch and merge decisions. Runs the Fase Zero situational-awareness battery, picks one of five delivery flows via the adaptive decision engine, and enforces commit/PR information-density standards. Orchestrates the gh, git-workflows, github-actions, pr, and debug/finish skills.
adaptive-agenda-calendar-routine-engine
Use when planning or executing work across hours, days, weeks, or sprints. Turns the calendar into a strict time-blocked agenda (HH:MM-HH:MM blocks carrying a routine profile, expected inputs, and a handoff output artifact), runs the 5-stage cognitive flow (Radar and Hunt -> Triage plus Steve Jobs conception -> workbench manifest -> >=32-cycle loop -> Close plus Open-Minded Scrum), and unfolds macro calendar milestones into micro agenda blocks through extensions/gcal/wrapper.py.
demo
Use when demonstrating a skill in a fixture project.
duplicate-skill
Use when testing duplicate skill name detection.
duplicate-skill
Use when testing duplicate skill name detection.