OpenCqs.Net 0.1.0

OpenCQS

Open Command Query Separation - A document format for data retrieval and state modification.

Overview

OpenCQS defines a structured syntax to express two distinct categories of operations:

• Queries - Data retrieval without side effects
• Commands - State modification operations

The format is designed to eliminate over-fetching and under-fetching by allowing clients to specify precisely which fields they need, supporting efficient execution in-process or over a network.

Features

• 🎯 Precise field selection - Request only the data you need
• 🔍 Powerful query capabilities - Filtering, ordering, paging with @orderby, @limit, @page, @count
• 🚀 Lambda expressions - Filter records with type-safe predicates including in operator
• 📝 Command operations - Write and delete operations with validation
• 🎨 Variables - Global and local scope for reusable values (prefixed with $)
• 🔧 Procedures and Functions - Server-side operations for queries and commands
• 📊 Type-safe - Full schema validation and type checking

Project Structure

OpenCQS/
├── OpenCqs/                    # Core library (.NET 10)
│   ├── Parser/                 # Request document parser
│   ├── Runtime/                # Query and command execution
│   └── Tokeniser/              # Lexical analysis
├── OpenCqs.AspNet/             # ASP.NET integration
│   ├── wwwroot/                # Client-side editor with autocomplete
│   └── tests/                  # JavaScript tests (Jest + Playwright)
├── OpenCqs.Tests/              # .NET test suite (xUnit)
├── OpenCqs.Benchmarks/         # Performance benchmarks
└── spec/                       # Specifications
	├── specification.txt       # Request/response document format
	└── schema-specification.txt # Schema definition format

Getting Started

Installation

Install the NuGet packages:

# Core library
dotnet add package OpenCqs

# ASP.NET integration
dotnet add package OpenCqs.AspNet

# Roslyn analyzers (optional)
dotnet add package OpenCqs.Analyzers

Prerequisites

• .NET 10 SDK
• Node.js 20+ (for client-side development)

Building

# Build all projects
dotnet build

# Run .NET tests
dotnet test

# Run JavaScript tests (from OpenCqs.AspNet directory)
cd OpenCqs.AspNet
npm install
npm test           # Jest unit tests
npm run test:e2e   # Playwright E2E tests
npm run test:all   # All tests

Testing

The project has comprehensive test coverage across both backend and frontend:

.NET Tests (xUnit)

• Parser tests
• Runtime execution tests
• Schema validation tests
• Specification compliance tests

JavaScript Tests

• Jest Unit Tests (87 tests)

  • Helper functions (singularize, toCamelCase)
  • Context detection logic
  • Suggestion engine with variable support

• Playwright E2E Tests (72 tests)

  • Editor interactions
  • Autocomplete behavior
  • Variable scoping and suggestions
  • Keyboard navigation

Total: 159 JavaScript tests + comprehensive .NET test suite

CI/CD

The project uses GitHub Actions for continuous integration and deployment:

• ✅ .NET build and test on every push/PR
• ✅ JavaScript unit tests (Jest with coverage)
• ✅ JavaScript E2E tests (Playwright)
• ✅ Parallel job execution for fast feedback
• ✅ Artifact retention for debugging
• 📦 NuGet package generation on main branch
• 🚀 Automatic publishing to NuGet.org on successful builds

NuGet Packages

The pipeline automatically generates and publishes three packages:

Package	Description	NuGet
OpenCqs	Core library with parser and runtime
OpenCqs.AspNet	ASP.NET integration with service extensions
OpenCqs.Analyzers	Roslyn analyzers for compile-time validation

Packages are versioned as 0.1.0-alpha.{build-number} during development.

Editor Features

The web-based editor (OpenCqs.AspNet/wwwroot/opencqs.js) provides intelligent autocomplete:

• Keywords - command, query at root level
• Sets, Procedures, Functions - Context-aware suggestions
• Fields - With duplicate detection
• Modifiers - @orderby, @limit, @page, @count
• Lambda expressions - Field completion after .
• Variables - Global and local scope with $ prefix
• Special fields - #id keyword

Example Request

$userId: 123

query {
  users(u => u.id == $userId) {
	id
	name
	email
	orders(@orderby[createdAt desc], @limit: 10) {
	  id
	  total
	  status
	}
  }
}

Documentation

• Request/Response Specification - Complete grammar and semantics
• Schema Specification - Type system and schema definition
• Test Documentation - JavaScript testing guide

License

Copyright © 2026 Steven Bey. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification and associated documentation files (the "Specification"), to deal in the Specification without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Specification.

THE SPECIFICATION IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

Contributing

This project follows a strict specification-driven development workflow:

1. Update spec/specification.txt FIRST
2. Analyze the diff (added/amended/deleted features)
3. Update unit tests to match the spec
4. Implement the changes
5. Verify all tests pass
6. Update spec web page and examples
7. Commit all changes together

See .github/copilot-instructions.md for detailed workflow.

Status

Version: 0.1
Status: Draft
Date: 2026-04-26