Setup initial project
This commit is contained in:
commit
db79af06f7
119 changed files with 20761 additions and 0 deletions
360
docs/instructions/typescript-zod.md
Normal file
360
docs/instructions/typescript-zod.md
Normal file
|
|
@ -0,0 +1,360 @@
|
|||
# TypeScript & Zod Best Practices — MeshiTrack
|
||||
|
||||
> Instruction file for TypeScript configuration, shared types, and Zod validation schemas in the monorepo.
|
||||
|
||||
## TypeScript Configuration
|
||||
|
||||
### Strict mode everywhere
|
||||
|
||||
All packages use `strict: true` (via `tsconfig.base.json`). This enables:
|
||||
|
||||
- `strictNullChecks` — forces handling of `null`/`undefined`
|
||||
- `noImplicitAny` — requires explicit types when inference fails
|
||||
- `strictPropertyInitialization` — ensures class properties are initialized
|
||||
|
||||
### Project-specific overrides
|
||||
|
||||
```json
|
||||
// packages/api/tsconfig.json — inherits ESM from base
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"target": "ES2022"
|
||||
}
|
||||
}
|
||||
|
||||
// packages/web/tsconfig.json — bundler module resolution for Next.js
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"module": "esnext",
|
||||
"moduleResolution": "bundler",
|
||||
"verbatimModuleSyntax": false,
|
||||
"jsx": "preserve",
|
||||
"noEmit": true,
|
||||
"paths": {
|
||||
"@/*": ["./src/*"],
|
||||
"@meshitrack/shared": ["../shared/src"]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// packages/shared/tsconfig.json
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "./dist",
|
||||
"rootDir": "./src",
|
||||
"declaration": true,
|
||||
"declarationMap": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ESM-first module system
|
||||
|
||||
All packages use `"type": "module"` and `"module": "nodenext"` (from base). Key rules:
|
||||
|
||||
- **Always use `.js` extensions** on relative imports (TypeScript resolves `.ts` from `.js` in nodenext)
|
||||
- **Use `import type` for type-only imports** (`verbatimModuleSyntax: true` enforces this)
|
||||
- **No `require()`** — use `import` exclusively
|
||||
- **No `esModuleInterop`** — use namespace imports for CJS packages if needed
|
||||
|
||||
## Type Design Principles
|
||||
|
||||
### 1. Types represent domain concepts
|
||||
|
||||
```typescript
|
||||
// Good: clearly represents the domain
|
||||
export interface Product {
|
||||
id: string;
|
||||
householdId: string;
|
||||
name: string;
|
||||
nutrition: NutritionInfo;
|
||||
}
|
||||
|
||||
// Bad: generic/vague naming
|
||||
export interface Item {
|
||||
id: string;
|
||||
hId: string;
|
||||
n: string;
|
||||
data: any;
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Use enums for fixed sets of values
|
||||
|
||||
```typescript
|
||||
export enum ProductCategory {
|
||||
DAIRY = 'dairy',
|
||||
MEAT = 'meat',
|
||||
VEGETABLES = 'vegetables',
|
||||
// ...
|
||||
}
|
||||
|
||||
// Use string values for readability in DB and API responses
|
||||
```
|
||||
|
||||
### 3. Use discriminated unions for status-dependent data
|
||||
|
||||
```typescript
|
||||
export type PantryItemState =
|
||||
| { status: 'sealed'; purchaseDate: Date }
|
||||
| { status: 'opened'; purchaseDate: Date; openedDate: Date }
|
||||
| { status: 'prepared'; purchaseDate: Date; openedDate: Date; preparedDate: Date }
|
||||
| { status: 'consumed'; consumedDate: Date }
|
||||
| { status: 'discarded'; discardedDate: Date; reason?: string };
|
||||
```
|
||||
|
||||
### 4. Use `Pick`, `Omit`, `Partial` for derived types
|
||||
|
||||
```typescript
|
||||
// Create DTO from entity
|
||||
export type CreateProductInput = Omit<Product, 'id' | 'createdAt' | 'updatedAt' | 'createdBy'>;
|
||||
export type UpdateProductInput = Partial<CreateProductInput>;
|
||||
|
||||
// API response (without internal fields)
|
||||
export type ProductResponse = Omit<Product, 'deletedAt'>;
|
||||
```
|
||||
|
||||
### 5. Use branded types for IDs (optional but recommended)
|
||||
|
||||
```typescript
|
||||
// Prevents accidentally passing a ProductId where a HouseholdId is expected
|
||||
declare const __brand: unique symbol;
|
||||
type Brand<T, B> = T & { [__brand]: B };
|
||||
|
||||
export type ProductId = Brand<string, 'ProductId'>;
|
||||
export type HouseholdId = Brand<string, 'HouseholdId'>;
|
||||
export type UserId = Brand<string, 'UserId'>;
|
||||
```
|
||||
|
||||
### 6. Never use `any` — use `unknown` if the type is truly unknown
|
||||
|
||||
```typescript
|
||||
// Bad
|
||||
function parse(data: any): Product { ... }
|
||||
|
||||
// Good
|
||||
function parse(data: unknown): Product {
|
||||
// Validate/narrow first
|
||||
const validated = ProductSchema.parse(data);
|
||||
return validated;
|
||||
}
|
||||
```
|
||||
|
||||
## Shared Package Organization
|
||||
|
||||
```
|
||||
packages/shared/src/
|
||||
├── index.ts # Re-exports everything
|
||||
├── types/
|
||||
│ ├── index.ts
|
||||
│ ├── product.ts # Product, NutritionInfo
|
||||
│ ├── recipe.ts # Recipe, RecipeIngredient, RecipeStep
|
||||
│ ├── pantry.ts # PantryItem, FreshnessEstimate
|
||||
│ ├── meal-plan.ts # MealPlan, PlannedMeal
|
||||
│ ├── shopping-list.ts # ShoppingList, ShoppingItem
|
||||
│ ├── store.ts # Store
|
||||
│ ├── price.ts # PriceRecord
|
||||
│ ├── user.ts # User, Household
|
||||
│ ├── freshness.ts # FreshnessRule
|
||||
│ └── common.ts # PaginatedResponse, ApiError
|
||||
├── enums/
|
||||
│ ├── index.ts
|
||||
│ ├── product.enums.ts # ProductCategory, ServingUnit, ProductSource
|
||||
│ ├── pantry.enums.ts # StorageLocation, ItemStatus, FreshnessUrgency
|
||||
│ ├── recipe.enums.ts # NutritionWarning
|
||||
│ ├── meal-plan.enums.ts # MealType, MealPlanStatus
|
||||
│ └── roles.enums.ts # HouseholdRole
|
||||
├── validation/
|
||||
│ ├── index.ts
|
||||
│ ├── product.schemas.ts
|
||||
│ ├── recipe.schemas.ts
|
||||
│ ├── pantry.schemas.ts
|
||||
│ └── ...
|
||||
└── utils/
|
||||
├── index.ts
|
||||
├── unit-conversion.ts # Serving unit conversions
|
||||
└── nutrition.ts # Nutrition calculation helpers
|
||||
```
|
||||
|
||||
## Zod Validation Schemas
|
||||
|
||||
### Co-locate schemas with types
|
||||
|
||||
Each type file has a corresponding validation file:
|
||||
|
||||
```typescript
|
||||
// validation/product.schemas.ts
|
||||
import { z } from 'zod/v4';
|
||||
import { ProductCategory, ServingUnit, ProductSource } from '../enums/index.js';
|
||||
|
||||
// Nutrition info sub-schema
|
||||
export const NutritionInfoSchema = z.object({
|
||||
calories: z.number().nonnegative(),
|
||||
protein: z.number().nonnegative(),
|
||||
carbs: z.number().nonnegative(),
|
||||
fat: z.number().nonnegative(),
|
||||
fiber: z.number().nonnegative().optional(),
|
||||
sugar: z.number().nonnegative().optional(),
|
||||
sodium: z.number().nonnegative().optional(),
|
||||
saturatedFat: z.number().nonnegative().optional(),
|
||||
cholesterol: z.number().nonnegative().optional(),
|
||||
});
|
||||
|
||||
// Create product schema
|
||||
export const CreateProductSchema = z.object({
|
||||
name: z.string().min(1).max(200).trim(),
|
||||
brand: z.string().max(200).trim().optional(),
|
||||
barcode: z.string().max(50).optional(),
|
||||
category: z.enum(ProductCategory),
|
||||
servingSize: z.number().positive(),
|
||||
servingUnit: z.enum(ServingUnit),
|
||||
nutrition: NutritionInfoSchema,
|
||||
tags: z.array(z.string().max(50)).max(20).default([]),
|
||||
imageUrl: z.url().optional(),
|
||||
});
|
||||
|
||||
// Update product schema (all fields optional)
|
||||
export const UpdateProductSchema = CreateProductSchema.partial();
|
||||
|
||||
// Query params schema
|
||||
export const ProductQuerySchema = z.object({
|
||||
q: z.string().optional(),
|
||||
category: z.enum(ProductCategory).optional(),
|
||||
tags: z.string().optional(), // Comma-separated
|
||||
cursor: z.string().optional(),
|
||||
limit: z.coerce.number().int().min(1).max(100).default(20),
|
||||
sort: z.string().optional(),
|
||||
});
|
||||
|
||||
// Infer TypeScript types from Zod schemas
|
||||
export type CreateProductInput = z.infer<typeof CreateProductSchema>;
|
||||
export type UpdateProductInput = z.infer<typeof UpdateProductSchema>;
|
||||
export type ProductQuery = z.infer<typeof ProductQuerySchema>;
|
||||
```
|
||||
|
||||
### Schema design rules
|
||||
|
||||
1. **Always `trim()` strings** — prevents " Chicken " vs "Chicken" issues
|
||||
2. **Set reasonable `max()` lengths** — prevents abuse
|
||||
3. **Use `nonnegative()` for nutrition values** — calories can't be negative
|
||||
4. **Use `z.coerce.number()`** for query params — they arrive as strings
|
||||
5. **Always set `.default()` for optional arrays** — prevents `undefined` issues
|
||||
6. **Use `z.enum()`** for TypeScript enums (Zod v4 unified `z.enum` handles both string arrays and TS enums)
|
||||
7. **Use `z.email()`, `z.url()`, `z.uuid()`** as top-level validators (Zod v4 style)
|
||||
|
||||
### Using Zod schemas in Fastify
|
||||
|
||||
The `fastify-type-provider-zod` plugin auto-validates request schemas:
|
||||
|
||||
```typescript
|
||||
import type { ZodTypeProvider } from 'fastify-type-provider-zod';
|
||||
import { CreateProductSchema, type CreateProductInput } from '@meshitrack/shared';
|
||||
|
||||
const app = fastify.withTypeProvider<ZodTypeProvider>();
|
||||
|
||||
app.route({
|
||||
method: 'POST',
|
||||
url: '/api/v1/products',
|
||||
schema: {
|
||||
body: CreateProductSchema,
|
||||
response: { 201: ProductResponseSchema },
|
||||
},
|
||||
handler: async (request, reply) => {
|
||||
// request.body is fully typed as CreateProductInput
|
||||
const product = await service.create(request.householdId, request.body);
|
||||
return reply.status(201).send(product);
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Validation errors are automatically caught by the global error handler.
|
||||
|
||||
### Using Zod schemas in Next.js
|
||||
|
||||
```typescript
|
||||
// Form validation with react-hook-form
|
||||
import { useForm } from 'react-hook-form';
|
||||
import { zodResolver } from '@hookform/resolvers/zod';
|
||||
import { CreateProductSchema, type CreateProductInput } from '@meshitrack/shared';
|
||||
|
||||
const form = useForm<CreateProductInput>({
|
||||
resolver: zodResolver(CreateProductSchema),
|
||||
});
|
||||
```
|
||||
|
||||
## Utility Types for API Responses
|
||||
|
||||
```typescript
|
||||
// types/common.ts
|
||||
export interface PaginatedResponse<T> {
|
||||
data: T[];
|
||||
pagination: {
|
||||
cursor: string | null;
|
||||
hasMore: boolean;
|
||||
total?: number;
|
||||
};
|
||||
}
|
||||
|
||||
export interface ApiError {
|
||||
statusCode: number;
|
||||
error: string;
|
||||
message: string;
|
||||
details?: Record<string, string[]>;
|
||||
timestamp: string;
|
||||
path: string;
|
||||
}
|
||||
|
||||
export interface ApiSuccess<T> {
|
||||
data: T;
|
||||
message?: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Null vs Undefined Convention
|
||||
|
||||
- **`undefined`**: field is not provided / not applicable (use in DTO inputs)
|
||||
- **`null`**: field is explicitly empty / cleared (use in database documents)
|
||||
- **In Zod**: use `.optional()` for undefined, `.nullable()` for null, `.nullish()` for both
|
||||
|
||||
```typescript
|
||||
// Input: optional means "not provided"
|
||||
brand: z.string().optional(); // string | undefined
|
||||
|
||||
// Database: null means "explicitly cleared"
|
||||
brand: z.string().nullable(); // string | null
|
||||
|
||||
// API response: could be either
|
||||
brand: z.string().nullish(); // string | null | undefined
|
||||
```
|
||||
|
||||
## Import/Export Convention
|
||||
|
||||
### Barrel exports in each directory
|
||||
|
||||
```typescript
|
||||
// types/index.ts — use .js extensions for ESM
|
||||
export * from './product.js';
|
||||
export * from './recipe.js';
|
||||
export * from './pantry.js';
|
||||
// ...
|
||||
|
||||
// Root index.ts
|
||||
export * from './types/index.js';
|
||||
export * from './enums/index.js';
|
||||
export {} from /* specific schemas */ './validation/index.js';
|
||||
```
|
||||
|
||||
### Use `import type` for types-only
|
||||
|
||||
```typescript
|
||||
// When importing only types, use `import type` (required by verbatimModuleSyntax)
|
||||
import type { Product, NutritionInfo } from '@meshitrack/shared';
|
||||
|
||||
// When importing values (enums, schemas, functions), use regular import
|
||||
import { ProductCategory, CreateProductSchema } from '@meshitrack/shared';
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue