Refactor code structure for improved readability and maintainability; remove redundant code blocks and optimize function calls.

docs/express-sql-to-monorepo-guide.md

@@ -0,0 +1,303 @@
+# From Express + SQL to Monorepo with Nest Fastify, Vite React, and trest
+
+This guide is for developers who already know Express APIs and SQL, and are new to Yarn workspaces, NestJS, and private package usage.
+
+## 1) What You Are Building
+
+Target architecture:
+
+- Backend API: NestJS on Fastify
+- Frontend: Vite + React + Ant Design
+- Shared/private integration: trest in an isolated adapter package
+- Monorepo manager: Yarn workspaces
+
+Why this shape:
+
+- Keep your main backend on a scalable Fastify stack.
+- Evaluate trest without coupling everything to Koa ecosystem packages.
+- Keep one repo and one lockfile for easier onboarding.
+
+## 2) Mental Map (Old to New)
+
+If you came from Express + SQL, map concepts like this:
+
+- Express app -> Nest application
+- Express route handler -> Nest controller method
+- Express middleware -> Nest middleware/guards/interceptors
+- Service classes (manual) -> Nest providers with dependency injection
+- SQL repository/service layer -> same idea in Nest modules
+- One project folder -> monorepo with apps and packages
+
+## 3) Your Current Repo State
+
+Current important files and meaning:
+
+- Root package.json: defines Yarn workspaces and root dependencies
+- .yarnrc.yml: private registry and auth settings for company packages
+- apps/api: backend app workspace
+- docs/*: onboarding and test notes
+
+Current private registry behavior:
+
+- Scope @jig-software points to Gitea npm endpoint
+- Auth token comes from JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN
+- nodeLinker is PnP (not node_modules)
+
+## 4) Core Concepts You Must Know First
+
+### Yarn Workspaces
+
+One repo with many packages/apps. Each workspace has its own package.json.
+
+- Root should hold shared tooling only.
+- App-specific dependencies should stay in the app workspace.
+
+### PnP (Plug'n'Play)
+
+Yarn resolves dependencies without creating a large node_modules tree.
+
+- Pros: faster installs, stricter dependency boundaries.
+- Cons: missing peer dependencies fail earlier and louder.
+
+### Peer Dependencies
+
+A package can require your app to provide certain dependencies.
+
+Example here:
+
+- trest expects koa, @koa/router, koa-body, path-to-regexp, zod, bson as peers.
+
+If peers are missing under PnP, imports can fail at runtime.
+
+### Why You Saw Peer Warnings
+
+You previously installed some Nest dependencies in root workspace.
+Then Yarn expected root-level peer providers there.
+
+Fix pattern:
+
+- Keep Nest dependencies inside apps/api only.
+- Keep root focused on workspace orchestration.
+
+## 5) Step-by-Step Learning Path
+
+Do this sequence in order and verify at each checkpoint.
+
+### Step A: Verify Toolchain
+
+```bash
+node -v
+yarn -v
+yarn workspaces list
+```
+
+Checkpoint:
+
+- You can see root workspace and apps/api workspace.
+
+### Step B: Verify Private Package Access
+
+```bash
+export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-token>"
+yarn npm info @jig-software/trest
+```
+
+Checkpoint:
+
+- You see trest package metadata and versions.
+
+### Step C: Backend Workspace Hygiene
+
+From repo root, ensure Nest runtime dependencies live in apps/api.
+
+Important:
+
+- Your current workspace name may be api-npx even if the folder is apps/api.
+- Check the name field in apps/api/package.json and use that in yarn workspace commands.
+
+```bash
+yarn workspace api-npx add @nestjs/platform-fastify fastify reflect-metadata rxjs
+yarn workspace api-npx remove @nestjs/platform-express
+```
+
+Checkpoint:
+
+- apps/api package contains fastify platform and no express platform.
+
+### Step D: Start Backend
+
+```bash
+yarn workspace api-npx start:dev
+```
+
+If you rename the workspace package name to api, the command becomes:
+
+```bash
+yarn workspace api start:dev
+```
+
+Checkpoint:
+
+- API starts successfully.
+
+### Step E: Create Frontend Workspace
+
+```bash
+yarn create vite apps/web --template react-ts
+cd apps/web
+yarn
+yarn add antd @ant-design/icons
+```
+
+Add style reset import in app entry:
+
+```ts
+import "antd/dist/reset.css";
+```
+
+Checkpoint:
+
+- Vite app runs and Ant Design components render.
+
+### Step F: Introduce trest Safely
+
+Recommended approach:
+
+- Keep trest usage in a dedicated package, for example packages/trest-adapter.
+- Expose only framework-agnostic functions from that adapter.
+- Avoid leaking Koa-specific types into app-wide contracts.
+
+Starter commands:
+
+```bash
+mkdir -p packages/trest-adapter
+cd packages/trest-adapter
+yarn init -y
+yarn add @jig-software/trest koa @koa/router koa-body path-to-regexp zod bson
+```
+
+Checkpoint:
+
+- Importing trest from adapter works.
+
+### Step G: Wire API and Web
+
+- Add one simple API endpoint in Nest.
+- Call endpoint from React page.
+- Render response using an Ant Design component.
+
+Checkpoint:
+
+- Browser request reaches backend and returns expected payload.
+
+## 6) Suggested Repo Layout
+
+```text
+marco-trest-test/
+  apps/
+    api/
+    web/
+  packages/
+    trest-adapter/
+  docs/
+  package.json
+  yarn.lock
+  .yarnrc.yml
+```
+
+## 7) Root vs Workspace Dependency Rules
+
+Use these rules to avoid confusion:
+
+1. Put backend runtime dependencies in apps/api.
+2. Put frontend runtime dependencies in apps/web.
+3. Put trest boundary dependencies in packages/trest-adapter.
+4. Keep root dependencies minimal and mostly tooling.
+5. Run installs from root unless targeting one workspace intentionally.
+
+## 8) Troubleshooting You Are Likely to Hit
+
+### Debugger feels broken in monorepo
+
+Common causes:
+
+- VS Code TypeScript server is not using Yarn SDK under PnP.
+- No workspace launch/tasks config exists for API + web.
+
+Fix checklist:
+
+```bash
+yarn dlx @yarnpkg/sdks vscode
+```
+
+Then in VS Code:
+
+1. Run command: TypeScript: Select TypeScript Version
+2. Choose: Use Workspace Version
+3. Restart TypeScript server if diagnostics look stale
+
+Use debug profiles from `.vscode/launch.json`:
+
+- API: Attach Nest (9229)
+- Web: Chrome (Vite 5173)
+- Full Stack Debug
+
+They depend on tasks in `.vscode/tasks.json` that start each app in watch mode.
+
+### Nest scaffold error: collection cannot be resolved
+
+Symptom:
+
+- Error resolving @nestjs/schematics with yarn dlx under this setup.
+
+Workaround:
+
+```bash
+CI=1 npx -y @nestjs/cli new apps/api --skip-git --package-manager yarn --strict
+```
+
+### Peer dependency warnings for reflect-metadata and rxjs
+
+Cause:
+
+- Nest packages in root workspace.
+
+Fix:
+
+- Move/add those dependencies in apps/api workspace.
+
+### 404 on yarn npm whoami
+
+Cause:
+
+- Endpoint may not support whoami.
+
+Fix:
+
+- Use yarn npm info @jig-software/trest to verify access.
+
+## 9) How to Decide if trest Is Right for Future Projects
+
+Use this checklist:
+
+- Type safety benefit vs integration complexity
+- Runtime coupling to Koa ecosystem
+- Team familiarity and onboarding cost
+- Performance and operational fit
+- Exit strategy if you stop using trest
+
+Practical policy many teams use:
+
+- Allow trest in adapter layer first.
+- Keep core services on standard Nest Fastify patterns.
+- Reassess after one pilot project.
+
+## 10) 30-Minute Practice Plan
+
+1. Run Step A and Step B.
+2. Start backend in Step D.
+3. Create web in Step E.
+4. Add one API call from web to backend.
+5. Write what was easy/hard in your notes.
+
+If you can complete this once, you have a strong foundation for real project work.

docs/trest-onboarding.md

@@ -0,0 +1,256 @@
+# TREST Onboarding Guide (Private Repo)
+
+This guide is designed for a new joiner to quickly set up access, install, and understand usage of the private `trest` package hosted at:
+
+- https://gitea.jig.com.hk/jig-software/trest
+
+Because the repository is private, this guide uses a secure workflow that works in most teams.
+
+## 1) Access Prerequisites
+
+Make sure you have:
+
+- A working company VPN connection (if required by network policy).
+- A Gitea account with access to `jig-software/trest`.
+- A Personal Access Token (PAT) in Gitea with at least repository read scope.
+- Git installed locally.
+
+Quick checks:
+
+```bash
+git --version
+ssh -T git@gitea.jig.com.hk
+```
+
+If SSH is not configured yet, follow section 2.
+
+## 2) Set Up Git Access
+
+Choose one method.
+
+### Option A: SSH (recommended)
+
+1. Generate a key if you do not already have one:
+
+```bash
+ssh-keygen -t ed25519 -C "your.name@company.com"
+```
+
+2. Start agent and add key:
+
+```bash
+eval "$(ssh-agent -s)"
+ssh-add ~/.ssh/id_ed25519
+```
+
+3. Copy and add your public key to Gitea:
+
+```bash
+cat ~/.ssh/id_ed25519.pub
+```
+
+4. Test auth:
+
+```bash
+ssh -T git@gitea.jig.com.hk
+```
+
+### Option B: HTTPS + PAT
+
+Use HTTPS clone and enter your username + PAT when prompted.
+
+```bash
+git clone https://gitea.jig.com.hk/jig-software/trest.git
+```
+
+## 3) Clone and Inspect the Repository
+
+```bash
+git clone git@gitea.jig.com.hk:jig-software/trest.git
+cd trest
+```
+
+Collect quick project facts:
+
+```bash
+ls -la
+find . -maxdepth 2 -type f | head -50
+```
+
+Identify the ecosystem from marker files:
+
+- `package.json` -> Node.js package
+- `pyproject.toml` or `setup.py` -> Python package
+- `Cargo.toml` -> Rust crate
+- `go.mod` -> Go module
+
+## 4) Install Runtime and Dependencies
+
+Use the matching path below.
+
+### If `trest` is Node.js
+
+If your team distributes `trest` through Gitea Packages (npm registry), configure Yarn auth first.
+
+If Yarn is new to you, read `docs/yarn-basics-cheatsheet.md` first.
+
+#### Yarn 4 + Gitea Registry Setup
+
+This workspace already uses a scoped registry in `.yarnrc.yml`.
+
+Required scope assumptions:
+
+- Scope: `@jig-software`
+- Registry URL: `https://gitea.jig.com.hk/api/packages/jig-software/npm/`
+
+Set your token in the current shell:
+
+```bash
+export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-gitea-token>"
+```
+
+Verify package access (recommended):
+
+```bash
+yarn npm info @jig-software/trest
+```
+
+Optional identity check (only if your Gitea npm endpoint supports whoami):
+
+```bash
+yarn npm whoami --scope jig-software
+```
+
+If package info is returned, install `trest`:
+
+```bash
+yarn add @jig-software/trest
+```
+
+If package naming differs, discover the exact name from your team or the Gitea Packages page, then run `yarn add <exact-package-name>`.
+
+#### Fallback: Install Directly From Gitea Git
+
+Use this when `trest` exists as a private repository but is not published in Gitea Packages npm.
+
+SSH form:
+
+```bash
+yarn add trest@git+ssh://git@gitea.jig.com.hk/jig-software/trest.git
+```
+
+HTTPS form:
+
+```bash
+yarn add trest@git+https://gitea.jig.com.hk/jig-software/trest.git
+```
+
+Pin to a branch, tag, or commit for reproducibility:
+
+```bash
+yarn add trest@git+ssh://git@gitea.jig.com.hk/jig-software/trest.git#main
+```
+
+```bash
+node -v
+npm -v
+npm ci
+npm test
+```
+
+Yarn note:
+
+- This repo uses Plug'n'Play (`nodeLinker: pnp`). If a tool expects `node_modules`, you can switch linker mode for that project.
+
+### If `trest` is Python
+
+```bash
+python3 --version
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install -r requirements.txt
+pytest -q
+```
+
+### If `trest` is Rust
+
+```bash
+rustc --version
+cargo --version
+cargo test
+```
+
+### If `trest` is Go
+
+```bash
+go version
+go test ./...
+```
+
+## 5) Understand Package Usage Quickly
+
+Work top-down with this sequence:
+
+1. Read `README.md` and `docs/` first.
+2. Find entry points:
+   - Node: `main`, `exports`, `src/index.*`
+   - Python: package `__init__.py`, public modules
+   - Rust: `src/lib.rs`, `src/main.rs`
+   - Go: exported symbols in key package files
+3. Locate examples/tests to learn intended behavior.
+4. Build a tiny local consumer project and call the simplest public API.
+
+Search commands:
+
+```bash
+rg "example|usage|quick start|getting started|test" -n .
+rg "export|public|def |class |func " -n src tests .
+```
+
+## 6) Create a Minimal Consumer Sandbox
+
+In a separate directory, create a tiny app that imports `trest` and performs one happy-path call.
+
+Suggested structure:
+
+```text
+sandbox/
+  README.md
+  <language standard files>
+  smoke_test.*
+```
+
+Your first smoke test should validate:
+
+- Package can be installed or linked.
+- Import works.
+- One primary API call returns expected output.
+- Error handling behavior for invalid input is understood.
+
+## 7) Team Questions to Ask Early
+
+Ask these within your first day to avoid drift:
+
+- Which branch/tag/version should new projects consume?
+- Is there a compatibility matrix (runtime versions, OS, architecture)?
+- What APIs are stable vs experimental?
+- Any required env vars, secrets, or service dependencies?
+- Preferred testing strategy for downstream consumers?
+
+## 8) Troubleshooting
+
+- `404`/auth failures: confirm VPN, permissions, token scope, and clone URL.
+- SSL/cert issues: check corporate certificate installation and git SSL settings.
+- Install failures: pin runtime version from project config files (`.nvmrc`, `pyproject`, etc.).
+- Test failures: run a single test first, then expand scope.
+
+## 9) Onboarding Completion Checklist
+
+You are done when all are true:
+
+- [ ] Can clone `jig-software/trest` locally.
+- [ ] Can install dependencies successfully.
+- [ ] Can run test suite (or at least smoke tests).
+- [ ] Can explain top 3 public APIs in your own words.
+- [ ] Have written notes on setup steps and pitfalls for the team.

docs/trest-test-plan.md

@@ -0,0 +1,151 @@
+# TREST Test Plan (First Week)
+
+Use this checklist to validate `trest` behavior while you learn the package.
+
+## Scope
+
+- Confirm installability and importability.
+- Confirm one core workflow works end-to-end.
+- Capture edge-case behavior.
+- Produce notes useful for maintainers and future joiners.
+
+## Test Environment Matrix
+
+Start small, then expand.
+
+- OS: Linux (current machine)
+- Runtime: project default version
+- Branch/tag: team-approved target
+
+If needed, expand to:
+
+- Alternate runtime version
+- CI environment parity run
+
+## Phase 1: Setup Validation
+
+1. Access check
+
+```bash
+git ls-remote git@gitea.jig.com.hk:jig-software/trest.git
+```
+
+If using Yarn with private Gitea Packages, verify package access:
+
+```bash
+export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-gitea-token>"
+yarn npm info @jig-software/trest
+```
+
+Optional check (if supported by your Gitea npm endpoint):
+
+```bash
+yarn npm whoami --scope jig-software
+```
+
+2. Fresh clone and dependency install
+
+```bash
+git clone git@gitea.jig.com.hk:jig-software/trest.git
+cd trest
+# run the package-manager-specific install command
+```
+
+For package-consumer verification:
+
+```bash
+yarn add @jig-software/trest
+```
+
+If npm package publishing is not enabled, verify direct git installation instead:
+
+```bash
+yarn add trest@git+ssh://git@gitea.jig.com.hk/jig-software/trest.git
+```
+
+3. Baseline tests
+
+```bash
+# run project test command, examples:
+# npm test
+# pytest -q
+# cargo test
+# go test ./...
+```
+
+Record:
+
+- Exact command
+- Runtime version
+- Pass/fail summary
+- Any flaky tests
+
+## Phase 2: API Smoke Tests
+
+Pick the top 1-3 public APIs used by other services.
+
+For each API, test:
+
+- Happy path input
+- Empty/null-ish input
+- Invalid type/format input
+- Boundary values
+
+Template:
+
+```text
+API name:
+Input:
+Expected:
+Actual:
+Status: PASS/FAIL
+Notes:
+```
+
+## Phase 3: Integration-Style Check
+
+Build a tiny consumer app and verify:
+
+- Package install from private source
+- Import path correctness
+- Typical call sequence
+- Error handling contract
+
+Keep the script minimal and reproducible.
+
+## Phase 4: Non-Functional Checks
+
+- Performance sanity: does a basic call return in expected time?
+- Logging: are errors actionable?
+- Determinism: same input gives same output (if expected behavior)
+
+## Defect Reporting Format
+
+When filing issues, include:
+
+- Environment (OS, runtime version)
+- `trest` commit hash or version
+- Repro steps
+- Expected vs actual
+- Logs/stack trace
+- Minimal repro snippet
+
+## Daily Notes Template
+
+```text
+Date:
+Goal:
+Commands run:
+Results:
+Questions:
+Blockers:
+Next step:
+```
+
+## Exit Criteria
+
+- [ ] Setup is reproducible from a clean machine.
+- [ ] Core APIs validated with at least happy path + one edge case.
+- [ ] At least one consumer-style integration tested.
+- [ ] Issues documented with clear repro steps.
+- [ ] Personal onboarding notes shared with team.

docs/yarn-basics-cheatsheet.md

@@ -0,0 +1,191 @@
+# Yarn Basics Cheat Sheet (Beginner)
+
+This page explains Yarn from zero and gives a short command set you can use daily.
+
+## 1) What Yarn Is
+
+Yarn is a JavaScript/TypeScript package manager.
+
+It helps you:
+
+- Install libraries your project depends on.
+- Keep dependency versions consistent.
+- Run scripts defined by the project.
+- Work with private package registries.
+
+## 2) Core Concepts
+
+### Package
+
+A package is reusable code published to a registry (for example npm or your company Gitea registry).
+
+Example in this project context:
+
+- `@jig-software/trest`
+
+### Dependency
+
+A dependency is a package your app needs to run.
+
+- Regular dependency: needed at runtime.
+- Dev dependency: needed for development/testing only.
+
+### package.json
+
+This file declares project metadata and dependencies.
+
+### yarn.lock
+
+This lock file pins exact dependency versions to keep installs reproducible across machines and CI.
+
+### Registry
+
+A registry is where packages are downloaded from.
+
+- Public: npmjs
+- Private: your company Gitea Packages endpoint
+
+### Scope
+
+A scope is a package namespace like `@jig-software`.
+
+A scope can be routed to a custom registry in `.yarnrc.yml`.
+
+### .yarnrc.yml
+
+Project-level Yarn config. It controls behavior such as:
+
+- Registry URLs
+- Authentication token source
+- Install/link strategy
+
+### PnP (Plug'n'Play)
+
+PnP is Yarn's alternative to `node_modules`.
+
+- Faster and stricter dependency resolution.
+- Dependencies are mapped through `.pnp.cjs`.
+- Some tools that assume `node_modules` may need extra config.
+
+## 3) How Your Current .yarnrc.yml Works
+
+From this repo config:
+
+- `nodeLinker: pnp` means no traditional `node_modules` tree.
+- `npmScopes.jig-software` routes `@jig-software/*` packages to Gitea.
+- `npmAuthToken` reads token from env var `JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN`.
+- `npmAlwaysAuth: true` always sends auth to that private registry.
+
+## 4) 8 Commands You Need Day-to-Day
+
+1. Check Yarn version
+
+```bash
+yarn --version
+```
+
+2. Install all dependencies from lockfile
+
+```bash
+yarn install
+```
+
+3. Add a dependency
+
+```bash
+yarn add <package-name>
+```
+
+4. Add a dev dependency
+
+```bash
+yarn add -D <package-name>
+```
+
+5. Remove a dependency
+
+```bash
+yarn remove <package-name>
+```
+
+6. Run a package script
+
+```bash
+yarn <script-name>
+```
+
+7. Inspect package info in registry
+
+```bash
+yarn npm info @jig-software/trest
+```
+
+8. Install trest from private scope
+
+```bash
+yarn add @jig-software/trest
+```
+
+## 5) Private Registry Quick Start (This Company)
+
+1. Export token in shell:
+
+```bash
+export JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN="<your-gitea-token>"
+```
+
+2. Verify package access:
+
+```bash
+yarn npm info @jig-software/trest
+```
+
+3. Install package:
+
+```bash
+yarn add @jig-software/trest
+```
+
+## 6) Common Errors and Fixes
+
+### Error: 401 Unauthorized
+
+Likely causes:
+
+- Missing or expired token.
+- Wrong token scopes.
+
+Fix:
+
+- Re-export token and retry.
+- Regenerate PAT with package read access.
+
+### Error: 404 on whoami
+
+Some Gitea npm endpoints do not support whoami.
+
+Fix:
+
+- Use `yarn npm info @jig-software/trest` as the verification command.
+
+### Error: tool expects node_modules
+
+Cause:
+
+- Project uses PnP.
+
+Fix:
+
+- Configure that tool for PnP, or switch linker mode for that project if approved by the team.
+
+## 7) Mental Model
+
+Use this flow every time:
+
+1. package.json asks for packages.
+2. yarn.lock pins exact versions.
+3. .yarnrc.yml tells Yarn where/how to fetch.
+4. Yarn installs and links dependencies (PnP here).
+5. Scripts run with the installed dependency graph.
+
+If one step fails, debug that layer first.