mirror of https://github.com/buster-so/buster.git
50 lines
2.0 KiB
Plaintext
50 lines
2.0 KiB
Plaintext
---
|
|
description: Rules for the components directory
|
|
globs: src/lib/**/*
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Utils Directory Structure and Guidelines
|
|
|
|
The `src/utils` directory contains global utility files that provide reusable helper functions across the application. Each file is organized by its specific domain (e.g., array.ts, text.ts, date.ts).
|
|
|
|
## File Organization
|
|
- Each utility file should focus on a single domain of functionality
|
|
- Files should be named according to their domain (e.g., `array.ts`, `text.ts`, `date.ts`)
|
|
- Keep files focused and cohesive - split into new files if functionality grows too diverse
|
|
|
|
## TypeScript Requirements
|
|
- All utility functions MUST have explicit TypeScript types for parameters and return values
|
|
- Use generics when functions can work with multiple types
|
|
- Avoid using `any` type - prefer `unknown` if type is truly uncertain
|
|
- Include comprehensive type guards where necessary
|
|
- Use union types and intersections appropriately to ensure type safety
|
|
- Document complex types with TSDoc comments
|
|
|
|
## Function Guidelines
|
|
- Functions should be pure when possible
|
|
- Each function should have a single responsibility
|
|
- Include TSDoc comments explaining the purpose, parameters, and return value
|
|
- Add examples in the documentation for complex utilities
|
|
- Include unit tests for all utility functions
|
|
- Handle edge cases explicitly and document them
|
|
|
|
## Example Structure
|
|
```typescript
|
|
/**
|
|
* Safely filters an array by removing null and undefined values
|
|
* @param arr - The input array that may contain null/undefined
|
|
* @returns A new array with null and undefined values removed
|
|
*/
|
|
export function filterNullable<T>(arr: (T | null | undefined)[]): T[] {
|
|
return arr.filter((item): item is T => item != null);
|
|
}
|
|
```
|
|
|
|
## Best Practices
|
|
- Export all utilities as named exports (not default exports)
|
|
- Group related utilities in the same file
|
|
- Keep functions small and focused
|
|
- Prioritize type safety over convenience
|
|
- Include error handling for edge cases
|
|
- Use immutable patterns - don't modify input parameters |