- Backend: FastAPI app with all models, services, schemas, routes - Admin Panel: Next.js dashboard with all modules (CRM, POS, repairs, warranties, billing, notifications, etc.) - Ecommerce: storefront (submodule) + product catalog - AI Agents: .agents/ skill library for Antigravity IDE - Docs: architecture, billing, notification gateway markdown - Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
---
|
|
description: Adds a new utility function after checking existing utilities first
|
|
---
|
|
|
|
## Add Utility Function
|
|
|
|
This workflow adds a new utility function to `src/utils/` after verifying it doesn't already exist.
|
|
|
|
### Steps
|
|
|
|
1. **Check existing utilities FIRST**
|
|
|
|
- Query Graphify: `uvx --from graphifyy graphify query "utility function for [describe what you need]"`
|
|
- Read `src/utils/` directory to see existing utilities
|
|
- Check `context/utils-catalogue.md` for available utilities
|
|
- Common utility categories:
|
|
- Date: `src/utils/date.ts` (getDisplayDate, formatDateForPayload, etc.)
|
|
- Currency: `src/utils/currency.ts` (formatCurrency, formatCurrencyWithDecimals)
|
|
- Number: `src/utils/number.ts` (numberWithCommas, padd2, toNumber)
|
|
- String: `src/utils/toCaps.ts` (toCaps)
|
|
- Payload: `src/utils/removeEmptyKeys.ts` (removeEmptyKeys)
|
|
- Date field helpers: `src/utils/dateFieldHelpers.ts` (createLinkedDateValidator)
|
|
|
|
2. **If utility exists, import it**
|
|
|
|
- Do NOT recreate existing utilities
|
|
- Import and use the existing one
|
|
|
|
3. **If utility doesn't exist, determine location**
|
|
|
|
- Add to appropriate existing file in `src/utils/`
|
|
- Or create new file if new category
|
|
- Tell the user what you intend to add and where before proceeding
|
|
|
|
4. **Write the utility function**
|
|
|
|
- Pure function - no side effects
|
|
- Properly typed with TypeScript
|
|
- Add JSDoc comment explaining purpose and usage
|
|
- Export from the file
|
|
|
|
5. **Add to index.ts if needed**
|
|
|
|
- If new file created, export from `src/utils/index.ts`
|
|
- If existing file, may already be exported
|
|
|
|
6. **Use the utility**
|
|
- Import from `src/utils/`
|
|
- Never write inline helper logic in components/pages
|
|
|
|
### Common Existing Utilities (Check These First)
|
|
|
|
**Date utilities (`src/utils/date.ts`):**
|
|
|
|
- `getDisplayDate` - Format date for display
|
|
- `formatDateForPayload` - Format date for API payload
|
|
- `formatDateTimeForPayload` - Format datetime for API payload
|
|
- `safeParseDate` - Safely parse date string
|
|
- `normalizeDate` - Normalize date object
|
|
|
|
**Currency utilities (`src/utils/currency.ts`):**
|
|
|
|
- `formatCurrency` - Format as currency
|
|
- `formatCurrencyWithDecimals` - Format with decimals
|
|
|
|
**Number utilities (`src/utils/number.ts`):**
|
|
|
|
- `numberWithCommas` - Add comma separators
|
|
- `padd2` - Zero-pad to 2 digits
|
|
- `toNumber` - Convert to number
|
|
|
|
**String utilities (`src/utils/toCaps.ts`):**
|
|
|
|
- `toCaps` - Capitalize string
|
|
|
|
**Payload utilities (`src/utils/removeEmptyKeys.ts`):**
|
|
|
|
- `removeEmptyKeys` - Remove null/empty keys from object
|
|
|
|
**Date field helpers (`src/utils/dateFieldHelpers.ts`):**
|
|
|
|
- `createLinkedDateValidator` - Create linked date range validator
|
|
|
|
### Alert Rule
|
|
|
|
**STOP and tell the user** if you need to:
|
|
|
|
- Add a new utility function to an existing `src/utils/` file
|
|
- Create a new utility file in `src/utils/`
|
|
|
|
Wait for explicit approval before proceeding.
|
|
|
|
### Checklist
|
|
|
|
- [ ] Checked existing utilities in `src/utils/`
|
|
- [ ] Checked `context/utils-catalogue.md`
|
|
- [ ] Confirmed utility doesn't already exist
|
|
- [ ] Told user what to add and where (if new utility)
|
|
- [ ] Got user approval before adding
|
|
- [ ] Function is pure (no side effects)
|
|
- [ ] Properly typed with TypeScript
|
|
- [ ] Added JSDoc comment
|
|
- [ ] Exported from file
|
|
- [ ] Exported from `src/utils/index.ts` if new file
|