typescript
Must always be enabled when writing/reviewing TypeScript code.
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- typescript
- description
- Must always be enabled when writing/reviewing TypeScript code.
03 SKILL.md 正文
<philosophy>
Core Philosophy: Type-Level Verification
LLM-generated code faces inherent challenges with E2E testing and runtime verification. Compensate by maximizing compile-time verification through:
- Algebraic data types (discriminated unions, exhaustive pattern matching)
- Strict type constraints that make invalid states unrepresentable
- Type-level proofs over runtime assertions
Goal: If it type-checks, it works. Shift as many bugs as possible from runtime to compile-time. </philosophy>
<type_assertions>
Type Assertions: Banned by Default
Rule: as Type Assertions are Prohibited
Rationale: Type assertions bypass TypeScript's type system and introduce type unsoundness. They are frequently misused to silence legitimate type errors.
Policy:
- ❌ Never use
asto resolve type errors - ❌ Never use
as anyoras unknown as X - ⚠️ Rare exceptions: Compiler limitations (e.g., specific generic inference bugs)
- If you encounter such cases, leave the type error unresolved
- Escalate to user with explanation: "Type error at
path/to/file.ts:123- requires manual review for potentialasusage"
Why you cannot judge appropriately: As an LLM, you lack the contextual understanding to determine if a type assertion is truly necessary vs. masking a real type error. When in doubt, preserve type safety.
Alternative: Fix the Root Cause
Instead of as, address the underlying type issue:
- Refine function signatures
- Use type guards (
if (typeof x === 'string')) - Employ discriminated unions
- Add generic constraints </type_assertions>
<strict_typing>
Strict Typing Patterns
Prefer as const satisfies Over Loose Annotations
Problem with loose typing:
const config: Config = {
mode: 'development', // Type widened to string
port: 3000
}
// config.mode is string, not 'development' | 'production'
Solution - strict typing with as const satisfies:
const config = {
mode: 'development',
port: 3000
} as const satisfies Config
// config.mode is exactly 'development' (literal type preserved)
Benefits:
- Preserves literal types
- Catches typos at definition site
- Enables exhaustive checking in consumers
- No type widening
Application:
- Configuration objects
- Constant lookup tables
- Route definitions
- Action type constants
Avoid Explicit Type Annotations When Inference Suffices
// ❌ Redundant annotation
const result: number = calculateTotal(items)
// ✅ Let TypeScript infer
const result = calculateTotal(items)
Use annotations when:
- Constraining function parameters
- Enforcing strict object shapes (
as const satisfies) - Documenting public API boundaries </strict_typing>
<external_data>
External Data: Never Trust, Always Validate
Rule: No any for External Data
Sources requiring validation:
- API responses (fetch, axios, etc.)
JSON.parse()results- LocalStorage/SessionStorage reads
- FormData / user input
- Environment variables
- File system reads
Strategy 1: Type-Safe API Clients (Preferred)
Check for generated type definitions first:
- Hono:
hono/clientwith type inference - orval: OpenAPI-generated types and hooks
- tRPC: End-to-end type safety
- GraphQL Code Generator: Typed queries
Example (Hono client):
import { hc } from 'hono/client'
import type { AppType } from './server'
const client = hc<AppType>('/api')
const response = await client.users.$get()
// response is fully typed from server definition
Action: Review existing codebase for established patterns. Most projects already have type-safe API layers.
Strategy 2: Runtime Validation Libraries
When type generation is unavailable, use schema validation:
Preference order:
- Existing project dependency (check
package.json) - valibot (lightweight, install if needed:
pnpm add valibot) - zod (popular, larger bundle)
Example (valibot):
import * as v from 'valibot'
const UserSchema = v.object({
id: v.number(),
name: v.string(),
role: v.union([v.literal('admin'), v.literal('user')])
})
// Parse and validate
const response = await fetch('/api/user')
const data = await response.json()
const user = v.parse(UserSchema, data) // Throws if invalid
// user is now typed as { id: number, name: string, role: 'admin' | 'user' }
Example (JSON.parse):
// ❌ Unsafe
const data = JSON.parse(localStorage.getItem('config')!)
// ✅ Validated
const raw = localStorage.getItem('config')
if (raw) {
const data = v.parse(ConfigSchema, JSON.parse(raw))
}
Never Skip Validation
Even if "you know" the shape, external data can change:
- API contracts evolve
- Users manipulate localStorage
- Third-party services have bugs
Type safety = static types + runtime validation </external_data>
<best_practices>
General Best Practices
Prefer Arrow Functions Over Function Declarations
Rule: Use arrow functions (=>) instead of function keyword for consistency and lexical scoping benefits.
Rationale:
- Consistent lexical
thisbinding (no context confusion) - More concise syntax
- Better integration with modern TypeScript patterns
- Prevents accidental hoisting-related bugs
// ❌ Function declaration
function calculateTotal(items: Item[]): number {
return items.reduce((sum, item) => sum + item.price, 0)
}
// ✅ Arrow function
const calculateTotal = (items: Item[]): number => {
return items.reduce((sum, item) => sum + item.price, 0)
}
// ✅ Concise form (single expression)
const calculateTotal = (items: Item[]): number =>
items.reduce((sum, item) => sum + item.price, 0)
Exception: When hoisting is genuinely required (rare), document the reason.
Discriminated Unions for State
type LoadingState<T> =
| { status: 'idle' }
| { status: 'loading' }
| { status: 'success'; data: T }
| { status: 'error'; error: Error }
const render = (state: LoadingState<User>) => {
switch (state.status) {
case 'idle':
return 'Not started'
case 'loading':
return 'Loading...'
case 'success':
return state.data.name // data is available
case 'error':
return state.error.message // error is available
}
}
Benefits: Impossible to access data when status is 'error'.
Exhaustiveness Checking
const assertNever = (x: never): never => {
throw new Error(`Unexpected value: ${x}`)
}
switch (state.status) {
case 'idle':
case 'loading':
case 'success':
case 'error':
return
default:
assertNever(state) // Compile error if cases are missing
}
Avoid Optional Properties for State
// ❌ Ambiguous state
type User = {
data?: UserData
error?: Error
}
// What if both are defined? Neither?
// ✅ Explicit state
type User =
| { status: 'success'; data: UserData }
| { status: 'error'; error: Error }
Use unknown Over any for Truly Unknown Types
// ❌ Disables all type checking
const process = (data: any) => {
return data.foo.bar // No errors, runtime explosion
}
// ✅ Forces validation
const process = (data: unknown) => {
if (typeof data === 'object' && data !== null && 'foo' in data) {
// Narrow the type before use
}
}
Readonly by Default
// Prevent accidental mutations
type Config = {
readonly apiUrl: string
readonly timeout: number
}
// For arrays
const items = ['a', 'b'] as const
Avoid Type-Level Gymnastics
If type definitions become incomprehensible, simplify the design:
- Complex conditional types often indicate over-abstraction
- Prefer explicit discriminated unions over heavily generic types
- Maintainability > cleverness </best_practices>
<error_handling>
When Type Errors Cannot Be Resolved
If you encounter legitimate type errors you cannot fix without as:
- Leave the error in place
- Document the issue:
// TODO: Type error at line X - potential TypeScript limitation // Requires manual review before using type assertion const result = someComplexOperation() // Type error here - Notify the user: "Type error remains at
src/module.ts:45- escalated for review"
Do not:
- Silently add
asassertions - Use
anyto bypass the error - Restructure correct code to satisfy incorrect types </error_handling>
04 同仓库更多 Skills
seedance-prompt-en
Write effective prompts for Jimeng Seedance 2.0 multimodal AI video generation. Use when users want to create video prompts using text, images, videos, and audio inputs with the @ reference system. Covers camera movements, effects replication, video extension, editing, music beat-matching, e-commerce ads, short dramas, and educational content.
onepage-pdf
Convert an HTML page into a single continuous-page PDF (one tall page, no pagination breaks), preserving desktop layout, backgrounds and selectable text. Use when the user asks to turn an HTML file/report/proposal into a "single-page PDF", "long PDF", "不分页 PDF", "单页 PDF", "长图式 PDF", or complains that an HTML-to-PDF export breaks into pages or cuts content. Supports optional string redaction with leak verification.
native-feel-cross-platform-desktop
Use when the user is designing, prototyping, or rewriting a desktop app that must run on multiple OSes (macOS + Windows, optionally Linux) AND feel indistinguishable from a native app to its users — fast launch, native windowing, native input handling, native materials. Trigger words include "cross-platform desktop", "Electron alternative", "Tauri vs native", "WebView wrapper", "near-native performance", "Raycast architecture", "WebKit/WebView2 quirks", "WKWebView", "system tray app", "global hotkey app", "launcher app". Do NOT trigger this skill for pure web apps, pure mobile apps, or for greenfield projects that have no native-feel requirement.
gstack
Router for the gstack skill suite. (gstack)
fireworks-tech-graph
Use when the user wants to create any technical diagram - architecture, data flow, flowchart, sequence, agent/memory, or concept map - and export as SVG+PNG. Trigger on: "画图" "帮我画" "生成图" "做个图" "架构图" "流程图" "可视化一下" "出图" "generate diagram" "draw diagram" "visualize" or any system/flow description the user wants illustrated.
dbs-video-extract
接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。