feat: add examples

.eslintrc.cjs

@@ -1,7 +1,7 @@
 module.exports = {
   parser: '@typescript-eslint/parser',
   parserOptions: {
-    ecmaVersion: 12,
+    ecmaVersion: 'latest',
     sourceType: 'module',
     project: './tsconfig.json',
   },
@@ -47,7 +47,7 @@ module.exports = {
       parser: 'espree',
       parserOptions: {
         project: null, 
-        ecmaVersion: 2020,
+        ecmaVersion: 'latest',
         sourceType: 'module'
       },
       rules: {
@@ -98,7 +98,12 @@ module.exports = {
         },
       },
     ],
-    'import/no-unresolved': 'error',
+    'import/no-unresolved':  [
+      'error',
+      {
+        ignore: ['^@junjie-wu/echo-service']
+      }
+    ],
     'import/no-cycle': 'error',
     'import/no-duplicates': 'error',
     'import/first': 'error',

.lintstagedrc.js

@@ -1,4 +1,5 @@
 export default {
-  '**/*.{js,ts,json,yml}': 'eslint --cache --fix',
-  "src/**/*.{js,ts}": ["jest --bail --passWithNoTests --findRelatedTests"]
+  '(src|tests|scripts)/**/*.{js,ts,json,yml}': 'eslint --cache --fix',
+  'src/**/*.{js,ts}': 'jest --bail --passWithNoTests --findRelatedTests',
+  'examples/**/*.js': 'eslint --cache --fix'
 };

README.md

@@ -8,91 +8,93 @@
 ![ESLint](https://img.shields.io/badge/ESLint-enabled-brightgreen)
 ![Husky](https://img.shields.io/badge/Husky-enabled-brightgreen)
 
-A flexible HTTP echo service that mirrors back request details. Available as an NPM package for both library integration and CLI usage, as well as a Docker image for containerized deployment.
+An HTTP echo service that mirrors back request details. 
+Available as a [Docker image](https://hub.docker.com/r/junjiewu0/echo-service) for containerized deployment, as well as an [NPM package](https://www.npmjs.com/package/@junjie-wu/echo-service) for both CLI usage and library integration.
 
-## 🚀 Quick Start
+## ⭐ Quick Start
 
 ```bash
 # Using Docker
 docker run -p 3000:3000 junjiewu0/echo-service
 
-# Using NPM (global)
-npm install -g @junjie-wu/echo-service
-echo-service
+# Using NPM (with CLI)
+npx @junjie-wu/echo-service
 
 # Using NPM (as library)
 npm install @junjie-wu/echo-service
 ```
 
 ## 📚 Usage
 
-### 🔷 NPM Package
-
-#### Library Integration
-```typescript
-import { createServer } from '@junjie-wu/echo-service';
-const server = createServer(3000);
-```
-
-#### CLI Usage
-```bash
-npm install -g @junjie-wu/echo-service
-echo-service --port 3000
-```
-
 ### 🐳 Docker
 
 ```bash
-# Using pre-built image
+# Using Pre-built Image
 docker run -p 3000:3000 junjiewu0/echo-service
 
 # Using Docker Compose
 docker compose up -d
 
-# Building locally
+# Building Locally
 docker build -t echo-service .
 docker run -p 3000:3000 echo-service
 ```
 
-## ⚡ API Endpoints
+### 📦 NPM Package
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/` | GET | Service info |
-| `/health` | GET | Health check |
-| `/echo` | ANY | Request mirror |
+#### CLI Usage
 
-## ⚙️ Configuration
+```bash
+# Run directly without installation
+npx @junjie-wu/echo-service --port 3000
 
-### Environment Variables
+# Or with global installation
+npm install -g @junjie-wu/echo-service
+echo-service --port 3000
+```
 
-```bash
-# Server Configuration
-PORT=3000                  # Server port (default: 3000)
-NODE_ENV=production        # Environment (default: development)
+#### Library Integration
 
-# Docker Specific
-DOCKER_PORT=3000          # Container exposed port
+```typescript
+import { createServer } from '@junjie-wu/echo-service';
+const server = createServer(3000);
 ```
 
-### Runtime Options
+### 🧪 Test the Service
 
 ```bash
-# CLI Options
-echo-service --port 3000
-echo-service --env production
+# Check service health
+http://localhost:3000/health
 
-# Docker Environment
-docker run -e PORT=3000 -e NODE_ENV=production junjiewu0/echo-service
+# Echo back request details
+http://localhost:3000/echo
+
+# Supports all HTTP methods and parameters
+http://localhost:3000/echo?name=test
 ```
 
-## 🛠️ Development
+### 📋 Examples
+For complete working examples of all usage methods, check out the [examples](./examples) directory:
+```bash
+git clone https://github.com/junjie-w/echo-service.git
+cd echo-service/examples
 
-### Prerequisites
+# Try different examples
+npm install
+npm run start:docker     # Docker usage
+npm run start:cli        # CLI usage
+npm run start:lib        # Library usage
+```
 
-- Node.js >= 20
-- npm
-- Docker (optional)
+## ⚡ API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Service info |
+| `/health` | GET | Health check |
+| `/echo` | ALL | Request mirror |
+
+## 🛠️ Development
 
 ### Setup
 
@@ -107,24 +109,6 @@ cd echo-service
 npm install
 ```
 
-3. Enable Git hooks:
-```bash
-npm run prepare
-```
-
-### Scripts
-
-| Script | Description |
-|--------|-------------|
-| `dev` | Start development server |
-| `build` | Build package |
-| `test` | Run all tests |
-| `test:unit` | Run unit tests |
-| `test:integration` | Run integration tests |
-| `test:api` | Run API tests |
-| `docker:build` | Build Docker image |
-| `docker:start` | Start Docker container |
-
 ### Commit Convention
 
 This project follows [Conventional Commits](https://www.conventionalcommits.org/):
@@ -143,11 +127,11 @@ Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
 
 Contributions, issues, and feature requests are welcome. Feel free to check [issues page](https://github.com/junjie-w/echo-service/issues).
 
-## 📦 Distribution
+## 🚀 Distribution
 
-- NPM Registry: [@junjie-wu/echo-service](https://www.npmjs.com/package/@junjie-wu/echo-service)
 - Docker Hub: [junjiewu0/echo-service](https://hub.docker.com/r/junjiewu0/echo-service)
+- NPM Registry: [@junjie-wu/echo-service](https://www.npmjs.com/package/@junjie-wu/echo-service)
 
 ## 📄 License
 
-MIT
+MIT

examples/README.md

@@ -0,0 +1,83 @@
+# Echo Service Examples
+
+Examples of using the [Echo Service](https://github.com/junjie-w/echo-service) via [Docker image](https://hub.docker.com/r/junjiewu0/echo-service) and [NPM package](https://www.npmjs.com/package/@junjie-wu/echo-service).
+Each example runs on a different port to avoid conflicts.
+
+## 🐳 Docker Usage (Port 3003)
+
+### Using Container
+
+```bash
+# Start container
+npm run start:docker
+
+# Stop container
+npm run docker:stop
+```
+
+### Using Docker Compose
+
+```bash
+# Start services
+npm run compose:up
+
+# View logs
+npm run compose:logs
+
+# Stop services
+npm run compose:down
+```
+
+## 🎯 CLI Usage (Port 3002)
+
+Using the package as a command-line tool:
+```bash
+npm run start:cli
+```
+
+## 📦 Library Usage (Port 3001)
+
+Using the package as a library in your code:
+```bash
+npm run start:lib
+```
+
+## 🧪 Testing the Examples
+
+Each example runs on a different port to avoid conflicts.
+
+### Docker Example (Port 3003)
+```bash
+curl http://localhost:3003/health
+curl http://localhost:3003/echo
+```
+
+### CLI Example (Port 3002)
+```bash
+curl http://localhost:3002/health
+curl http://localhost:3002/echo
+```
+
+### Library Example (Port 3001)
+```bash
+curl http://localhost:3001/health
+curl http://localhost:3001/echo
+```
+
+## ⚠️ Troubleshooting
+
+### Port Already in Use
+If you see "Port in use" error:
+```bash
+# Check what's using the port
+lsof -i :<port_number>
+
+# Kill the process
+kill -9 <PID>
+```
+
+### Docker on Apple Silicon (M1/M2/M3)
+The example automatically handles platform differences, but you can manually run:
+```bash
+docker run --platform linux/amd64 -p 3003:3000 junjiewu0/echo-service
+```

examples/docker-compose.yml

@@ -0,0 +1,9 @@
+version: "3.8"
+services:
+  echo-service:
+    image: junjiewu0/echo-service
+    platform: linux/amd64
+    ports:
+      - "3003:3000"
+    environment:
+      - NODE_ENV=production

examples/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "echo-service-examples",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start:lib": "node src/library-usage.js",
+    "start:cli": "node src/cli-usage.js",
+    "start:docker": "node src/docker-usage.js",
+    "stop:docker": "docker stop echo-service-example && docker rm echo-service-example || true",
+    "start:docker-compose": "docker compose up -d",
+    "stop:docker-compose": "docker-compose down",
+    "logs:docker-compose": "docker compose logs -f"
+  },
+  "dependencies": {
+    "@junjie-wu/echo-service": "file:../"
+  }
+}