Cursor rule

1---
2description: Guidelines for Data Access Layer via API
3globs: 
4alwaysApply: false
5---
6# Guidelines for Data Access Layer via API 
7 
8## Purpose & Overview
9These rules define the standard patterns for implementing CRUD operations in the data access layer. The guidelines are based on the implementation of the 'users' module and should be followed for all API operations to maintain consistency across the codebase.
10 
11## File Structure
12 
13### Shared Domain
14 
15By default, place all data access files in the shared data directory. Only use feature domains when explicitly specified in requirements.
16 
17```
18src/data/[entity-name]/
19├── create-[entity].ts      # Create operation
20├── get-[entity].ts         # Get single entity
21├── get-[entity]s.ts        # Get multiple entities
22├── update-[entity].ts      # Update operation
23├── delete-[entity].ts      # Delete operation
24├── search-[entity]s.ts     # Search with filters
25└── __test-utils__/         # Test utilities
26```
27 
28### Feature Domain
29 
30When a prompt/requirement explicitly specifies that code should be organized in a feature domain, follow this structure:
31 
32```
33src/features/[feature-name]/
34└── _data/[entity-name]/    # Feature-specific data access layer
35    ├── create-[entity].ts  # Create operation
36    ├── get-[entity].ts     # Get single entity
37    ├── get-[entity]s.ts    # Get multiple entities
38    ├── update-[entity].ts  # Update operation
39    ├── delete-[entity].ts  # Delete operation
40    ├── search-[entity]s.ts # Search with filters
41    └── __test-utils__/     # Test utilities
42```
43 
44## Naming Conventions
45 
46### Function Naming
47- `create[Entity]Data`: For creating resources via API
48- `get[Entity]Data`: For retrieving a single resource via API
49- `get[Entity]sData`: For retrieving multiple resources via API
50- `update[Entity]Data`: For updating resources via API
51- `delete[Entity]Data`: For deleting resources via API
52- `search[Entity]sData`: For searching resources with filters via API
53 
54### Type Naming
55- `[Entity]`: Main entity type from API schema
56- `Create[Entity]`: Type for creating entity, typically omitting auto-generated fields
57- `Update[Entity]`: Type for updating entity, typically partial of the main entity
58- `[Operation][Entity]DataArgs`: Type for function arguments
59- `[Operation][Entity]DataResponse`: Type for function return value
60 
61## Implementation Patterns
62 
63 
64## Test Utilities
65Create test utilities in the `__test-utils__` directory to help with testing:
66 
67```typescript
68// __test-utils__/make-fake-entity.ts
69import { type Entity } from '@/data/schema';
70import { faker } from '@faker-js/faker';
71 
72// Create a fake entity with realistic test data
73export function makeFake[Entity] {
74  return {
75    id: faker.string.uuid(),
76    created_at: faker.date.recent(),
77    updated_at: faker.date.recent(),
78    deleted_at: null,
79    // ... entity-specific fields with realistic fake data
80    ...overrides,
81  } satisfies Entity;
82}
83```
84 
85### Create Operation
86```typescript
87// create-[entity].ts
88import { type Entity } from './schema';
89 
90export type CreateEntityDataArgs = {
91  // Entity properties to be sent to API
92};
93 
94export async function createEntityData(args: CreateEntityDataArgs): Promise<Entity> {
95  const response = await fetch('https://api.example.com/entities', {
96    method: 'POST',
97    headers: {
98      'Content-Type': 'application/json',
99    },
100    body: JSON.stringify(args),
101  });
102  
103  if (!response.ok) {
104    throw new Error(`API error: ${response.status}`);
105  }
106  
107  return await response.json();
108}
109```