Initial commit: JMESPath Testing Tool
- React-based web application for testing JMESPath expressions - macOS-first containerization with Apple container command - Bootstrap UI with real-time evaluation - GitHub Actions CI/CD pipeline - Docker fallback support - Comprehensive documentation and development scripts
This commit is contained in:
279
README.md
Normal file
279
README.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# JMESPath Testing Tool
|
||||
|
||||
A React-based web application for testing and validating JMESPath expressions against JSON data in real-time. This interactive tool provides a user-friendly interface to experiment with JMESPath queries and see results instantly.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
- 🎯 **Real-time Evaluation**: JMESPath expressions are evaluated instantly as you type
|
||||
- 📝 **JSON Validation**: Built-in JSON syntax validation and error reporting
|
||||
- 🎨 **Bootstrap UI**: Clean, responsive interface with Bootstrap styling
|
||||
- 🔄 **Sample Data**: Pre-loaded examples to get started quickly
|
||||
- 📱 **Responsive Design**: Works on desktop, tablet, and mobile devices
|
||||
- 🐳 **Container Ready**: Containerized for easy deployment (macOS + Docker)
|
||||
- ✅ **Error Handling**: Clear error messages for both JSON and JMESPath syntax issues
|
||||
- 🚀 **CI/CD Ready**: GitHub Actions workflow for automated container builds
|
||||
|
||||
## Application Layout
|
||||
|
||||
The application is divided into three main sections:
|
||||
|
||||
1. **Top Section**: Title and description of the tool
|
||||
2. **Middle Section**: Input area for JMESPath expressions
|
||||
3. **Bottom Sections**:
|
||||
- **Left**: JSON data input area
|
||||
- **Right**: Query results output area
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 24 LTS or higher
|
||||
- npm or yarn package manager
|
||||
- **macOS recommended** (optimized for Apple's container toolset)
|
||||
|
||||
### Local Development
|
||||
|
||||
1. **Clone the repository**:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd jmespath-playground
|
||||
```
|
||||
|
||||
2. **Install dependencies**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Start the development server** (macOS optimized):
|
||||
```bash
|
||||
npm run dev
|
||||
# or traditional:
|
||||
npm start
|
||||
```
|
||||
|
||||
4. **Open your browser** and navigate to `http://localhost:3000`
|
||||
|
||||
### Container Deployment
|
||||
|
||||
#### macOS with Apple Container (Recommended)
|
||||
|
||||
```bash
|
||||
# Build using macOS-optimized script
|
||||
npm run build:macos
|
||||
|
||||
# Or manually with Apple container command
|
||||
container build -t jmespath-playground .
|
||||
container run -p 3000:3000 jmespath-playground
|
||||
|
||||
# Using npm scripts
|
||||
npm run container:build
|
||||
npm run container:run
|
||||
```
|
||||
|
||||
#### Docker (Fallback Option)
|
||||
|
||||
```bash
|
||||
# Build the Docker image
|
||||
docker build -t jmespath-playground .
|
||||
|
||||
# Run the container
|
||||
docker run -p 3000:3000 jmespath-playground
|
||||
|
||||
# Using npm scripts
|
||||
npm run docker:build
|
||||
npm run docker:run
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
1. **Enter a JMESPath expression** in the top input field (e.g., `people[*].name`)
|
||||
2. **Paste or type JSON data** in the bottom-left textarea
|
||||
3. **View the results** in the bottom-right output area
|
||||
4. **Use the toolbar buttons** to:
|
||||
- Load sample data
|
||||
- Format JSON
|
||||
- Clear all inputs
|
||||
|
||||
### Example JMESPath Expressions
|
||||
|
||||
Try these examples with the sample data:
|
||||
|
||||
- `people[*].name` - Get all names
|
||||
- `people[0]` - Get the first person
|
||||
- `people[?age > 30]` - Filter people older than 30
|
||||
- `people[*].skills[0]` - Get the first skill of each person
|
||||
- `length(people)` - Count the number of people
|
||||
|
||||
## Available Scripts
|
||||
|
||||
In the project directory, you can run:
|
||||
|
||||
### Development Scripts
|
||||
|
||||
### `npm run dev`
|
||||
|
||||
Starts the development server with macOS optimizations. Checks environment and opens the app at http://localhost:3000.
|
||||
|
||||
### `npm start`
|
||||
|
||||
Runs the app in development mode using React's default development server. The page will reload when you make edits.
|
||||
|
||||
### `npm test`
|
||||
|
||||
Launches the test runner in interactive watch mode.
|
||||
|
||||
### Build Scripts
|
||||
|
||||
### `npm run build:macos`
|
||||
|
||||
Builds the application and creates containers using macOS-optimized build script. Prioritizes Apple's container command with Docker fallback.
|
||||
|
||||
### `npm run build`
|
||||
|
||||
Builds the app for production to the `build` folder. It correctly bundles React in production mode and optimizes the build for the best performance.
|
||||
|
||||
### `npm run serve`
|
||||
|
||||
Serves the production build locally on port 3000.
|
||||
|
||||
### Container Scripts
|
||||
|
||||
### `npm run container:build`
|
||||
|
||||
Builds a container using Apple's container command (macOS).
|
||||
|
||||
### `npm run container:run`
|
||||
|
||||
Runs the container using Apple's container command.
|
||||
|
||||
### `npm run docker:build`
|
||||
|
||||
Builds a Docker container (fallback option).
|
||||
|
||||
### `npm run docker:run`
|
||||
|
||||
Runs the Docker container.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
jmespath-playground/
|
||||
├── .github/
|
||||
│ ├── workflows/
|
||||
│ │ └── build-container.yml # CI/CD pipeline
|
||||
│ └── copilot-instructions.md # AI agent instructions
|
||||
├── public/
|
||||
│ ├── index.html
|
||||
│ ├── manifest.json
|
||||
│ └── favicon.ico
|
||||
├── src/
|
||||
│ ├── App.js # Main application component
|
||||
│ ├── App.css # App-specific styles
|
||||
│ ├── App.test.js # App tests
|
||||
│ ├── index.js # React entry point
|
||||
│ ├── index.css # Global styles
|
||||
│ ├── setupTests.js # Test configuration
|
||||
│ └── reportWebVitals.js
|
||||
├── scripts/
|
||||
│ ├── build.sh # macOS-optimized build script
|
||||
│ └── dev.sh # macOS-optimized development script
|
||||
├── Containerfile # Apple container build file
|
||||
├── Dockerfile # Docker container (fallback)
|
||||
├── Dockerfile.dev # Development container
|
||||
├── docker-compose.yml # Container orchestration
|
||||
├── package.json # Dependencies and scripts
|
||||
├── README.md # Comprehensive documentation
|
||||
├── DEVELOPMENT.md # Developer guide
|
||||
└── demo.sh # Demo script
|
||||
```
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **React 18.2.0**: Frontend framework
|
||||
- **Bootstrap 5.3.2**: CSS framework for styling
|
||||
- **JMESPath 0.16.0**: JMESPath expression evaluation
|
||||
- **Node.js 24 LTS**: Runtime environment
|
||||
- **Apple Container**: Primary containerization (macOS)
|
||||
- **Docker**: Containerization fallback
|
||||
- **GitHub Actions**: Automated CI/CD pipeline
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
The project includes a GitHub Actions workflow that automatically:
|
||||
|
||||
- 🔍 **Triggers** on pushes to `main` or `develop` branches when `src/` directory changes
|
||||
- 📦 **Builds** the React application with Node.js 24 LTS
|
||||
- 🧪 **Runs** the test suite with coverage reporting
|
||||
- 🐳 **Creates** container image using Docker (GitHub Actions environment)
|
||||
- ✅ **Tests** the container by starting it and verifying HTTP response
|
||||
- 🏗️ **Builds** multi-platform images (amd64/arm64) for main branch
|
||||
- 📤 **Uploads** build artifacts for later use
|
||||
|
||||
The workflow is optimized for the GitHub Actions environment while respecting the project's macOS-first philosophy for local development.
|
||||
|
||||
## Deployment
|
||||
|
||||
### Container Deployment (macOS Recommended)
|
||||
|
||||
The application is designed for macOS-first containerization:
|
||||
|
||||
1. **Build using macOS toolset**:
|
||||
```bash
|
||||
npm run build:macos
|
||||
```
|
||||
|
||||
2. **Deploy using Apple container command**:
|
||||
```bash
|
||||
container run -p 3000:3000 jmespath-playground
|
||||
```
|
||||
|
||||
### Docker Deployment (Fallback)
|
||||
|
||||
For environments without Apple's container toolset:
|
||||
|
||||
1. **Build the Docker image**:
|
||||
```bash
|
||||
docker build -t jmespath-playground .
|
||||
```
|
||||
|
||||
2. **Deploy to your container platform** (Docker Swarm, Kubernetes, etc.)
|
||||
|
||||
### Static Hosting
|
||||
|
||||
You can also deploy the built application to static hosting services:
|
||||
|
||||
1. **Build the application**:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
2. **Deploy the `build` folder** to services like:
|
||||
- Netlify
|
||||
- Vercel
|
||||
- GitHub Pages
|
||||
- AWS S3 + CloudFront
|
||||
- Azure Static Web Apps
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch: `git checkout -b feature/new-feature`
|
||||
3. Make your changes and commit them: `git commit -m 'Add new feature'`
|
||||
4. Push to the branch: `git push origin feature/new-feature`
|
||||
5. Submit a pull request
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## About JMESPath
|
||||
|
||||
JMESPath is a query language for JSON. It allows you to declaratively specify how to extract elements from a JSON document. For more information about JMESPath syntax and capabilities, visit the [official JMESPath website](https://jmespath.org/).
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter any issues or have questions, please [open an issue](../../issues) on GitHub.
|
||||
Reference in New Issue
Block a user