ai-qakit 1.0.0

package/templates/.cursor/rules/typescript-pro/references/conditional-types.md

@@ -0,0 +1,85 @@
+# Conditional Types
+
+Create types that depend on conditions, enabling sophisticated type logic.
+
+## Basic Conditional Type
+
+```typescript
+type IsString<T> = T extends string ? true : false;
+
+type A = IsString<string>;    // true
+type B = IsString<number>;    // false
+```
+
+## Extracting Types with infer
+
+```typescript
+// Extract return type
+type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+
+function getUser() { return { id: 1, name: "John" }; }
+type User = ReturnType<typeof getUser>;
+// Type: { id: number; name: string }
+
+// Extract array element type
+type ElementType<T> = T extends (infer U)[] ? U : never;
+type Num = ElementType<number[]>;  // number
+
+// Extract promise type
+type Awaited<T> = T extends Promise<infer U> ? U : T;
+type AsyncNum = Awaited<Promise<number>>;  // number
+```
+
+## Distributive Conditional Types
+
+Union types distribute over conditional types:
+
+```typescript
+type ToArray<T> = T extends any ? T[] : never;
+
+type StrOrNumArray = ToArray<string | number>;
+// Type: string[] | number[]
+
+// Prevent distribution with tuple wrapper
+type ToArrayNonDist<T> = [T] extends [any] ? T[] : never;
+type Mixed = ToArrayNonDist<string | number>;
+// Type: (string | number)[]
+```
+
+## Nested Conditions
+
+```typescript
+type TypeName<T> =
+  T extends string ? "string" :
+  T extends number ? "number" :
+  T extends boolean ? "boolean" :
+  T extends undefined ? "undefined" :
+  T extends Function ? "function" :
+  "object";
+
+type T1 = TypeName<string>;     // "string"
+type T2 = TypeName<() => void>; // "function"
+```
+
+## Extract Function Parameters
+
+```typescript
+type Parameters<T> = T extends (...args: infer P) => any ? P : never;
+
+function foo(a: string, b: number) {}
+type FooParams = Parameters<typeof foo>;  // [string, number]
+
+// First parameter only
+type FirstParam<T> = T extends (first: infer F, ...rest: any[]) => any ? F : never;
+type First = FirstParam<typeof foo>;  // string
+```
+
+## Conditional with Constraints
+
+```typescript
+type MessageOf<T> = T extends { message: infer M } ? M : never;
+
+interface ErrorWithMessage { message: string; }
+type ErrMsg = MessageOf<ErrorWithMessage>;  // string
+type NoMsg = MessageOf<{ title: string }>;  // never
+```

package/templates/.cursor/rules/typescript-pro/references/generics.md

@@ -0,0 +1,97 @@
+# Generics
+
+Create reusable, type-flexible components while maintaining type safety.
+
+## Basic Generic Function
+
+```typescript
+function identity<T>(value: T): T {
+  return value;
+}
+
+const num = identity<number>(42);     // Type: number
+const str = identity("hello");        // Type inferred: string
+```
+
+## Generic Constraints
+
+```typescript
+interface HasLength {
+  length: number;
+}
+
+function logLength<T extends HasLength>(item: T): T {
+  console.log(item.length);
+  return item;
+}
+
+logLength("hello");           // OK: string has length
+logLength([1, 2, 3]);         // OK: array has length
+// logLength(42);             // Error: number has no length
+```
+
+## Multiple Type Parameters
+
+```typescript
+function merge<T, U>(obj1: T, obj2: U): T & U {
+  return { ...obj1, ...obj2 };
+}
+
+const merged = merge({ name: "John" }, { age: 30 });
+// Type: { name: string } & { age: number }
+```
+
+## Generic Classes
+
+```typescript
+class Stack<T> {
+  private items: T[] = [];
+
+  push(item: T): void { this.items.push(item); }
+  pop(): T | undefined { return this.items.pop(); }
+}
+
+const numStack = new Stack<number>();
+numStack.push(1);
+numStack.push(2);
+```
+
+## Default Type Parameters
+
+```typescript
+interface Response<T = unknown> {
+  data: T;
+  status: number;
+}
+
+const res: Response = { data: "any", status: 200 };
+const typedRes: Response<User> = { data: user, status: 200 };
+```
+
+## Generic Interfaces
+
+```typescript
+interface Repository<T, ID = string> {
+  findById(id: ID): Promise<T | null>;
+  save(entity: T): Promise<T>;
+  delete(id: ID): Promise<void>;
+}
+
+class UserRepo implements Repository<User> {
+  async findById(id: string) { /* ... */ }
+  async save(user: User) { /* ... */ }
+  async delete(id: string) { /* ... */ }
+}
+```
+
+## Constrained Generics with keyof
+
+```typescript
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+const user = { name: "John", age: 30 };
+const name = getProperty(user, "name"); // Type: string
+// getProperty(user, "invalid");        // Error
+```

package/templates/.cursor/rules/typescript-pro/references/mapped-types.md

@@ -0,0 +1,99 @@
+# Mapped Types
+
+Transform existing types by iterating over their properties.
+
+## Basic Mapped Type
+
+```typescript
+type Readonly<T> = {
+  readonly [P in keyof T]: T[P];
+};
+
+interface User { id: number; name: string; }
+type ReadonlyUser = Readonly<User>;
+// { readonly id: number; readonly name: string; }
+```
+
+## Optional Properties
+
+```typescript
+type Partial<T> = {
+  [P in keyof T]?: T[P];
+};
+
+type PartialUser = Partial<User>;
+// { id?: number; name?: string; }
+```
+
+## Key Remapping (as clause)
+
+```typescript
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K]
+};
+
+interface Person { name: string; age: number; }
+type PersonGetters = Getters<Person>;
+// { getName: () => string; getAge: () => number; }
+```
+
+## Filtering Properties
+
+```typescript
+// Pick properties of specific type
+type PickByType<T, U> = {
+  [K in keyof T as T[K] extends U ? K : never]: T[K]
+};
+
+interface Mixed {
+  id: number;
+  name: string;
+  age: number;
+  active: boolean;
+}
+
+type OnlyNumbers = PickByType<Mixed, number>;
+// { id: number; age: number; }
+```
+
+## Removing Modifiers
+
+```typescript
+// Remove readonly
+type Mutable<T> = {
+  -readonly [P in keyof T]: T[P];
+};
+
+// Remove optional
+type Required<T> = {
+  [P in keyof T]-?: T[P];
+};
+```
+
+## Combining Mapped Types
+
+```typescript
+// Nullable properties
+type Nullable<T> = {
+  [P in keyof T]: T[P] | null;
+};
+
+// Async version of methods
+type Async<T> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => Promise<R>
+    : T[K];
+};
+```
+
+## Nested Mapped Types
+
+```typescript
+type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends object
+    ? T[P] extends Function
+      ? T[P]
+      : DeepReadonly<T[P]>
+    : T[P];
+};
+```

package/templates/.cursor/rules/typescript-pro/references/template-literals.md

@@ -0,0 +1,85 @@
+# Template Literal Types
+
+Create string-based types with pattern matching and transformation.
+
+## Basic Template Literal
+
+```typescript
+type EventName = "click" | "focus" | "blur";
+type EventHandler = `on${Capitalize<EventName>}`;
+// "onClick" | "onFocus" | "onBlur"
+```
+
+## String Manipulation Utilities
+
+```typescript
+type Upper = Uppercase<"hello">;      // "HELLO"
+type Lower = Lowercase<"HELLO">;      // "hello"
+type Cap = Capitalize<"john">;        // "John"
+type Uncap = Uncapitalize<"John">;    // "john"
+```
+
+## Pattern Matching
+
+```typescript
+type ExtractRouteParams<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractRouteParams<Rest>
+    : T extends `${string}:${infer Param}`
+      ? Param
+      : never;
+
+type Params = ExtractRouteParams<"/users/:id/posts/:postId">;
+// "id" | "postId"
+```
+
+## Path Building
+
+```typescript
+type Path<T> = T extends object
+  ? { [K in keyof T]: K extends string
+      ? `${K}` | `${K}.${Path<T[K]>}`
+      : never
+    }[keyof T]
+  : never;
+
+interface Config {
+  server: { host: string; port: number };
+  database: { url: string };
+}
+
+type ConfigPath = Path<Config>;
+// "server" | "database" | "server.host" | "server.port" | "database.url"
+```
+
+## CSS Property Types
+
+```typescript
+type CSSUnit = "px" | "em" | "rem" | "%";
+type CSSValue = `${number}${CSSUnit}`;
+
+const width: CSSValue = "100px";   // OK
+const height: CSSValue = "50%";    // OK
+// const bad: CSSValue = "100";    // Error
+```
+
+## Event Handler Types
+
+```typescript
+type DOMEvents = "click" | "change" | "submit" | "keydown";
+type Handler<E extends string> = `on${Capitalize<E>}`;
+type Callback<E extends string> = `handle${Capitalize<E>}`;
+
+type ClickHandler = Handler<"click">;     // "onClick"
+type ClickCallback = Callback<"click">;   // "handleClick"
+```
+
+## HTTP Methods
+
+```typescript
+type HTTPMethod = "get" | "post" | "put" | "delete";
+type Endpoint = `/${string}`;
+type Route = `${Uppercase<HTTPMethod>} ${Endpoint}`;
+
+const route: Route = "GET /users";  // OK
+```

package/templates/.cursor/rules/typescript-pro/references/type-inference.md

@@ -0,0 +1,94 @@
+# Type Inference Techniques
+
+## The infer Keyword
+
+Extract types from complex type structures:
+
+```typescript
+// Array element type
+type ElementOf<T> = T extends (infer E)[] ? E : never;
+type Num = ElementOf<number[]>;  // number
+
+// Promise unwrap
+type Unwrap<T> = T extends Promise<infer U> ? U : T;
+type Data = Unwrap<Promise<string>>;  // string
+
+// Function return
+type Return<T> = T extends (...args: any[]) => infer R ? R : never;
+
+// Tuple first/last
+type First<T> = T extends [infer F, ...any[]] ? F : never;
+type Last<T> = T extends [...any[], infer L] ? L : never;
+```
+
+## Type Guards
+
+Narrow types with custom predicates:
+
+```typescript
+function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+function isArrayOf<T>(arr: unknown, guard: (x: unknown) => x is T): arr is T[] {
+  return Array.isArray(arr) && arr.every(guard);
+}
+
+// Usage
+const data: unknown = ["a", "b"];
+if (isArrayOf(data, isString)) {
+  data.forEach(s => s.toUpperCase());  // Type: string[]
+}
+```
+
+## Assertion Functions
+
+Assert type or throw:
+
+```typescript
+function assertIsString(value: unknown): asserts value is string {
+  if (typeof value !== "string") throw new Error("Not a string");
+}
+
+function assertDefined<T>(value: T): asserts value is NonNullable<T> {
+  if (value == null) throw new Error("Value is null or undefined");
+}
+
+// Usage
+function process(value: unknown) {
+  assertIsString(value);
+  console.log(value.toUpperCase());  // Type: string
+}
+```
+
+## Const Assertions
+
+```typescript
+const config1 = { endpoint: "/api", method: "GET" };  // types widened
+const config2 = { endpoint: "/api", method: "GET" } as const;  // literal types
+// { readonly endpoint: "/api"; readonly method: "GET" }
+
+const methods = ["GET", "POST"] as const; // readonly ["GET", "POST"]
+```
+
+## Satisfies Operator
+
+```typescript
+type Colors = Record<string, [number, number, number] | string>;
+const palette = { red: [255, 0, 0], green: "#00ff00" } satisfies Colors;
+palette.red[0];   // Type: number (preserves literal, not union)
+```
+
+## Discriminated Type Guards
+
+```typescript
+type Shape = { kind: "circle"; radius: number } | { kind: "square"; side: number };
+
+function isCircle(shape: Shape): shape is { kind: "circle"; radius: number } {
+  return shape.kind === "circle";
+}
+
+function area(shape: Shape) {
+  return isCircle(shape) ? Math.PI * shape.radius ** 2 : shape.side ** 2;
+}
+```

package/templates/.cursor/rules/typescript-pro/references/utility-types.md

@@ -0,0 +1,96 @@
+# Utility Types
+
+Built-in type helpers for common type transformations.
+
+## Object Property Utilities
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  password: string;
+}
+
+// Partial<T> - Make all properties optional
+type PartialUser = Partial<User>;
+// { id?: number; name?: string; email?: string; password?: string; }
+
+// Required<T> - Make all properties required
+type RequiredUser = Required<PartialUser>;
+
+// Readonly<T> - Make all properties readonly
+type ReadonlyUser = Readonly<User>;
+
+// Pick<T, K> - Select specific properties
+type UserName = Pick<User, "name" | "email">;
+// { name: string; email: string; }
+
+// Omit<T, K> - Remove specific properties
+type SafeUser = Omit<User, "password">;
+// { id: number; name: string; email: string; }
+```
+
+## Union Utilities
+
+```typescript
+type Status = "pending" | "active" | "inactive" | "deleted";
+
+// Exclude<T, U> - Exclude types from union
+type ActiveStatus = Exclude<Status, "deleted">;
+// "pending" | "active" | "inactive"
+
+// Extract<T, U> - Extract types from union
+type EndStates = Extract<Status, "inactive" | "deleted">;
+// "inactive" | "deleted"
+
+// NonNullable<T> - Exclude null and undefined
+type T = NonNullable<string | null | undefined>;
+// string
+```
+
+## Record Type
+
+```typescript
+// Record<K, T> - Create object type with keys K and values T
+type PageInfo = Record<"home" | "about" | "contact", { title: string }>;
+// { home: { title: string }; about: { title: string }; contact: { title: string }; }
+
+// Dynamic keys
+type UserRoles = Record<string, string[]>;
+const roles: UserRoles = { admin: ["read", "write"], user: ["read"] };
+```
+
+## Function Utilities
+
+```typescript
+function createUser(name: string, age: number): User {
+  return { id: 1, name, email: "", password: "", age } as User;
+}
+
+// Parameters<T> - Get function parameter types
+type CreateUserParams = Parameters<typeof createUser>;
+// [string, number]
+
+// ReturnType<T> - Get function return type
+type CreateUserReturn = ReturnType<typeof createUser>;
+// User
+
+// ConstructorParameters<T> - Get constructor parameter types
+class UserClass {
+  constructor(public name: string, public age: number) {}
+}
+type UserClassParams = ConstructorParameters<typeof UserClass>;
+// [string, number]
+
+// InstanceType<T> - Get instance type from constructor
+type UserInstance = InstanceType<typeof UserClass>;
+// UserClass
+```
+
+## ThisType
+
+```typescript
+type Obj = { data: string } & ThisType<{ data: string; log(): void }>;
+const obj: Obj = { data: "hello", log() { console.log(this.data); } };
+```

package/templates/.cursor/rules/typescript-pro/typescript-pro.mdc

@@ -0,0 +1,101 @@
+---
+description: Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, designing type-safe API clients, building form validation systems, or ensuring compile-time type safety. Triggers on "type inference", "generic constraints", "conditional type", "mapped type", "template literal type", "utility type".
+globs:
+  - "**/*.ts"
+  - "**/*.tsx"
+---
+
+# TypeScript Pro
+
+Comprehensive guidance for mastering TypeScript's advanced type system to build robust, type-safe applications.
+
+## When to Use
+
+- Building type-safe libraries or frameworks
+- Creating reusable generic components
+- Implementing complex type inference logic
+- Designing type-safe API clients
+- Building form validation systems
+- Creating strongly-typed configuration objects
+- Implementing type-safe state management
+- Migrating JavaScript to TypeScript
+
+## Core Concepts
+
+### Generics
+Create reusable, type-flexible components. See `references/generics.md` for:
+- Basic generic functions and classes
+- Generic constraints with `extends`
+- Multiple type parameters
+- Default type parameters
+
+### Conditional Types
+Create types that depend on conditions. See `references/conditional-types.md` for:
+- Basic conditional patterns
+- `infer` keyword for type extraction
+- Distributive conditional types
+- Nested conditions
+
+### Mapped Types
+Transform existing types by iterating properties. See `references/mapped-types.md` for:
+- Property transformation
+- Key remapping with `as`
+- Filtering properties
+- Modifier manipulation (+/- readonly/optional)
+
+### Template Literal Types
+String-based types with pattern matching. See `references/template-literals.md` for:
+- String manipulation utilities
+- Event naming patterns
+- Path building types
+
+### Utility Types
+Built-in type helpers. See `references/utility-types.md` for:
+- `Partial`, `Required`, `Readonly`
+- `Pick`, `Omit`, `Record`
+- `Exclude`, `Extract`, `NonNullable`
+- `Parameters`, `ReturnType`
+
+## Advanced Patterns
+
+See `references/advanced-patterns.md` for:
+- Type-safe event emitters
+- Type-safe API clients
+- Builder pattern with type safety
+- Deep Readonly/Partial
+- Discriminated unions
+- Type-safe form validation
+
+## Type Inference Techniques
+
+See `references/type-inference.md` for:
+- `infer` keyword patterns
+- Type guards (`is`)
+- Assertion functions (`asserts`)
+- `const` assertions
+
+## Best Practices
+
+See `references/best-practices.md` for:
+- `unknown` vs `any`
+- `interface` vs `type`
+- Strict mode configuration
+- Type testing patterns
+- Common pitfalls to avoid
+- Performance considerations
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `T extends U` | Generic constraints |
+| `T extends U ? X : Y` | Conditional types |
+| `[K in keyof T]` | Mapped types |
+| `infer R` | Type extraction |
+| `as const` | Literal preservation |
+| `satisfies T` | Type validation with inference |
+
+## Resources
+
+- TypeScript Handbook: https://www.typescriptlang.org/docs/handbook/
+- Type Challenges: https://github.com/type-challenges/type-challenges