JSV System - JSON CSV Database

A simple, file-based data system with JST templates, JB databases, and JQL queries.

🚀 Quick Start

# Install globally
npm install -g jsv-system

# Or use with npx (no installation)
npx jsv-system init myproject

📖 What is JSV?

JSV is a three-file system for managing data:

1. .jst - JSON Source Template (human writes this)
2. .jb - JSON Bytecode (system stores this)
3. .jsv - JSON CSV Export (Excel opens this)

✨ Features

· ✅ Simple JST syntax - Write data like key: value · ✅ JB databases - Optimized, indexed storage · ✅ JQL queries - Simple path-based queries · ✅ Excel export - .jsv files open in Excel · ✅ No servers - Everything is file-based · ✅ Schema validation - Type checking built-in

📝 JST Syntax Example

import required

database{
  name: "users"
  version: "1.0"
}

required{
  *
}

schema{
  id: {type: "int", primary: true, auto: true}
  name: {type: "string", required: true}
  email: {type: "string", unique: true}
  age: {type: "int", min: 0, max: 150}
  active: {type: "bool", default: true}
}

data{
  {name: "Alice", email: "[email protected]", age: 30}
  {name: "Bob", email: "[email protected]", age: 25}
}

🛠️ Installation

# Global installation (recommended)
npm install -g jsv-system

# Local installation
npm install jsv-system

# Development installation
git clone https://github.com/JSV-net/jsv-system.git
cd jsv-system
npm install
npm link

💻 Usage

Initialize a Project

jsv init myproject
cd myproject

Compile JST to JB

jsv compile users.jst
# Creates: .jsv/databases/users.jb

Query with JQL

# Get all users
jsv query "QUERY users.data"

# Filter users
jsv query "QUERY users.data WHERE age > 25"

# Count records
jsv query "COUNT users.data WHERE active = true"

Export to JSV/CSV

jsv export users.jb users.csv
# Creates: exports/users.csv (opens in Excel)

Interactive Shell

jsv shell
# Enter interactive mode

📚 JQL Query Language

Basic Queries

QUERY users.data
QUERY products.data WHERE price < 100
COUNT orders.data WHERE status = "shipped"

Path Queries

QUERY users.data[0]              # Get first user
QUERY users.indexes.name.Alice   # Find by index
QUERY users.data GET name, email # Select specific fields

Conditions

WHERE age > 25
WHERE name = "Alice" AND active = true
WHERE price BETWEEN 10 AND 100
WHERE email LIKE "%@gmail.com"

📁 File Structure

myproject/
├── data.jst                    # Your JST files
├── .jsv/                       # System folder (auto-created)
│   └── databases/
│       └── data.jb            # Compiled databases
└── exports/
    └── data.jsv               # Exported files (Excel-ready)

🔧 Commands

Command Description jsv init [name] Create new project jsv compile <file.jst> Compile JST to JB jsv query "" Run JQL query jsv export <file.jb> [output] Export to JSV/CSV jsv shell Start interactive shell jsv help [command] Show help

📊 Example: Inventory System

inventory.jst:

import required

database{ name: "inventory" }
required{ * }

schema{
  sku: {type: "string", primary: true}
  name: {type: "string"}
  price: {type: "float", min: 0}
  stock: {type: "int", min: 0}
  category: {type: "string"}
}

data{
  {sku: "A100", name: "Laptop", price: 999.99, stock: 10, category: "electronics"}
  {sku: "B200", name: "Mouse", price: 25.50, stock: 50, category: "electronics"}
}

Commands:

jsv compile inventory.jst
jsv query "QUERY inventory.data WHERE category = 'electronics'"
jsv query "QUERY inventory.data WHERE stock < 20"
jsv export inventory.jb low-stock.csv

🎯 Use Cases

· Small businesses - Inventory, customers, invoices · Researchers - Experiment data, surveys · Teachers - Student records, grades · Developers - App configuration, local caching · Analysts - Data cleaning before Excel/PowerBI

📦 Data Types

Type Example Description int {age: 25} Integer numbers float {price: 19.99} Decimal numbers string {name: "Alice"} Text bool {active: true} Boolean timestamp {created: auto} Date/time json {meta: {}} JSON objects/arrays

⚡ Performance

· Compression - JB files are 30-50% smaller than JSON · Indexing - Queries use indexes for 100x faster lookups · Memory - Only loads required data, not entire files · Export - Direct streaming to CSV format

🔒 Data Safety

· Automatic backups - Configurable backup system · Validation - Schema validation on compile · Checksums - Data integrity verification · Atomic writes - Prevents corruption

❓ FAQ

Q: Do I need a database server?

A: No! JSV is completely file-based. No servers, no installations.

Q: Can I open JSV files in Excel?

A: Yes! .jsv files are CSV with metadata comments. Excel ignores # lines.

Q: How is this different from JSON/CSV?

A: JSV adds schema validation, indexing, and queries while keeping file simplicity.

Q: Can multiple users access the same JB file?

A: Yes, but for production use, implement file locking or use as read-only.

Q: Is there a GUI?

A: Currently CLI only, but web GUI is planned.

🚧 Roadmap

· Web-based GUI · Real-time collaboration · Cloud sync · Plugins/extensions · Mobile app

📄 License

MIT License - see LICENSE file

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

🐛 Bug Reports

Please report bugs on the GitHub Issues page.

🌟 Support

· 📚 Documentation · 💬 Discord Community · 🐦 Twitter

Made with ❤️ for people who love data but hate complexity.