2.2 KiB
2.2 KiB
Project conventions
Error handling
Always use defined error classes for caught / expected exceptions — never
throw new Error('some_string').
- Domain errors live in
packages/functions/src/errors.ts. Each extends a Pikku core error (BadRequestError,ConflictError,ForbiddenError,NotFoundError, …) and is registered withaddError(...)so it maps to the correct HTTP status and a stable client-facing code. - Raw
throw new Error(...)is only acceptable for truly unexpected, programmer-error conditions that should surface as a 500. - Validation/contract failures (bad params, illegal state transitions, etc.) must be a defined error so callers can branch on the type and the client receives a meaningful status + message.
Sessions (optional auth everywhere)
sessionCookieMiddleware is registered globally (addHTTPMiddleware('*', …)
in wirings/middleware.ts), so the session cookie is resolved on every
route — including auth: false / pikkuSessionlessFunc endpoints.
- In a sessionless function, read the optional session from the third arg:
func: async (services, input, { session }) => { const s = await session?.get(); … }.sisundefinedfor anonymous callers and theUserSession({ userId, role }) for logged-in ones. - This lets a public endpoint vary its response by viewer role (e.g. show admins more than anonymous visitors) without a separate authenticated route.
- Use
pikkuFunc(required session, third arg{ session }non-optional) only when the route must reject anonymous callers outright.
Database changes (Pikku DB-first pipeline)
Schema changes go DB-first, in this order — doing it code-first breaks the Pikku inspector / generated types:
- Edit the SQL (
db/sqlite/*.sql,db/sqlite-seed.sql). - Regenerate:
yarn db:reset && yarn db:migrate(pikku db migraterefreshes.pikku/db/schema.d.tsand the generated zod at.pikku/db/zod.gen.ts, imported as#pikku/db/zod.gen.js). - Update backend function logic against the new types.
- Regenerate the client SDK:
yarn workspace @project/functions pikku all. - Update the frontend / consumers.
This is a pre-production project — edit migrations in place rather than appending compatibility migrations.