kubit-designing-api
在添加新的 API 表面、修改现有 API 或为框架功能定义 TypeScript 类型时使用。在讨论方法签名、返回类型、装饰器 API 或模块导出时使用。
📖 中文导读:在添加新的 API 表面、修改现有 API 或为框架功能定义 TypeScript 类型时使用。在讨论方法签名、返回类型、装饰器 API 或模块导出时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: kubit-designing-api description: Use when adding new API surface, modifying existing APIs, or defining TypeScript types for framework features. Use when discussing method signatures, return types, decorator APIs, or module exports.
Designing Kubit APIs
Overview
Design APIs by starting with ideal usage in skeleton/, then codifying as types in packages/core/, then documenting in SPEC.md.
When to Use
- Adding new method, decorator, or export to framework
- Modifying existing API signatures
- Defining types in packages/core/*.d.ts
- User asks "how should this API look?"
API Design Flow
digraph api_flow {
"Write usage in skeleton/" -> "Add types to packages/core/" -> "Document in SPEC.md" -> "Verify tsc passes";
}
- Usage First: Write the ideal developer experience in skeleton/
- Types Second: Add ambient types to make it compile
- Spec Third: Document with TypeScript signatures
- Verify: Run
tsc --noEmitin skeleton/
Design Principles
| Principle | Application |
|---|---|
| DX First | How does this feel to use? Start from skeleton. |
| Type Safety | Can TypeScript catch mistakes at compile time? |
| Conventions | Follow Laravel/Rails patterns where sensible |
| Minimal API | Smallest surface that solves the problem |
| Extensibility | Can users extend without modifying core? |
Patterns in Use
Decorators: @column(), @before(), @property(), @use() - metadata on classes/properties
Method Chaining: router.get('/').name('home') - fluent API for configuration
Controller Tuples: [Controller, 'method'] - type-safe handler references
Lazy Relations: @hasMany(() => Post) - arrow function to avoid circular deps
Static Dispatch: Job.dispatch({}), Mailable.send({}) - class-level entry points
Type Definition Location
All public types go in packages/core/:
| File | Contents |
|---|---|
kubit.d.ts |
defineConfig, env, use |
router.d.ts |
router object, handler types |
orm.d.ts |
Model, column decorators, relations |
queue.d.ts |
Job, @property |
mail.d.ts |
Mailable |
db.d.ts |
Migration, schema |
inertia.d.ts |
view() |
http.d.ts |
HttpContext |
hash.d.ts |
hash() |
Checklist Before Adding API
- Usage example exists in skeleton/
- Types added to packages/core/
-
tsc --noEmitpasses in skeleton/ - SPEC.md updated with TypeScript signature
- Follows existing patterns (decorators, chaining, etc.)