{"id":21327871,"url":"https://github.com/siddiqsoft/cosmosclient","last_synced_at":"2026-05-04T02:08:26.343Z","repository":{"id":46726750,"uuid":"397477229","full_name":"SiddiqSoft/CosmosClient","owner":"SiddiqSoft","description":"Cosmos REST-API Client for Modern C++","archived":false,"fork":false,"pushed_at":"2025-02-05T00:02:55.000Z","size":873,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-04-14T23:41:59.950Z","etag":null,"topics":["asynchronous","azure","azure-cosmos","azure-cosmos-db","cosmos-db","cpp","cpp20","json-api","nuget-package","rest-api","windows"],"latest_commit_sha":null,"homepage":"https://siddiqsoft.github.io/CosmosClient/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SiddiqSoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-08-18T04:57:06.000Z","updated_at":"2021-12-22T23:57:00.000Z","dependencies_parsed_at":"2025-01-30T01:19:59.632Z","dependency_job_id":"09ab3f44-fa59-46ae-b444-2ba2ebc56d87","html_url":"https://github.com/SiddiqSoft/CosmosClient","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiddiqSoft%2FCosmosClient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiddiqSoft%2FCosmosClient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiddiqSoft%2FCosmosClient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiddiqSoft%2FCosmosClient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SiddiqSoft","download_url":"https://codeload.github.com/SiddiqSoft/CosmosClient/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248981258,"owners_count":21193143,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asynchronous","azure","azure-cosmos","azure-cosmos-db","cosmos-db","cpp","cpp20","json-api","nuget-package","rest-api","windows"],"created_at":"2024-11-21T21:20:09.213Z","updated_at":"2026-05-04T02:08:26.336Z","avatar_url":"https://github.com/SiddiqSoft.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CosmosClient: Azure Cosmos REST-API Client for Modern C++\n\n\u003c!-- badges --\u003e\n[![CodeQL](https://github.com/SiddiqSoft/CosmosClient/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/SiddiqSoft/CosmosClient/actions/workflows/codeql-analysis.yml)\n[![Build Status](https://dev.azure.com/siddiqsoft/siddiqsoft/_apis/build/status/SiddiqSoft.CosmosClient?branchName=main)](https://dev.azure.com/siddiqsoft/siddiqsoft/_build/latest?definitionid=15\u0026branchName=main)\n![](https://img.shields.io/github/v/tag/SiddiqSoft/CosmosClient)\n![](https://img.shields.io/nuget/v/SiddiqSoft.CosmosClient)\n![](https://img.shields.io/nuget/dt/SiddiqSoft.CosmosClient)\n![](https://img.shields.io/azure-devops/tests/siddiqsoft/siddiqsoft/15)\n![](https://img.shields.io/github/license/siddiqsoft/CosmosClient)\n\u003c!-- end badges --\u003e\n\n---\n\n## 🎯 Quick Links\n\n**New to the project?** Start here:\n- 📖 **[START_HERE.md](START_HERE.md)** - Main entry point for all developers\n- ⚡ **[QUICK_START.md](QUICK_START.md)** - Get started in 5 minutes\n- 📚 **[DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)** - Find what you need\n\n**Want to build and test?**\n- 🔧 **[DEVELOPER_BUILD_GUIDE.md](DEVELOPER_BUILD_GUIDE.md)** - Complete build guide\n- 🚀 **[SCRIPTS_README.md](SCRIPTS_README.md)** - Automated build script\n\n**Need API documentation?**\n- 📖 **[API Documentation](https://siddiqsoft.github.io/CosmosClient/)** - Full API reference\n\n---\n\n## 📋 Overview\n\nA lightweight, modern C++ client for Azure Cosmos DB REST API. Designed for C++ developers who want a simple, functional interface without unnecessary abstractions.\n\n### Key Features\n\n- **C++23 Native** - Modern C++ with structured bindings and initializer lists\n- **JSON-First** - Configuration, I/O, and results all use JSON\n- **Simple Interface** - Minimal abstractions, maximum clarity\n- **Full Cosmos SQL API** - Complete REST API implementation\n- **Single Header** - Easy integration\n- **Cross-Platform** - Windows, macOS, and Linux support\n- **Async Operations** - Built-in async/await support\n- **Zero-Cost Abstractions** - Only pay for what you use\n\n### Dependencies\n\n- [nlohmann/json](https://github.com/nlohmann/json) - JSON library\n- [azure-cpp-utils](https://github.com/siddiqsoft/azure-cpp-utils) - Azure utilities\n- [restcl](https://github.com/siddiqsoft/restcl) - REST client library\n\n---\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/SiddiqSoft/CosmosClient.git\ncd CosmosClient\ngit submodule update --init --recursive\n```\n\n### Build\n\n```bash\n# macOS\nmkdir -p build \u0026\u0026 cd build\ncmake --preset Apple-Debug ..\ncmake --build .\n\n# Linux\nmkdir -p build \u0026\u0026 cd build\ncmake --preset Linux-Clang-Debug ..\ncmake --build .\n```\n\n### Usage Example\n\n```cpp\n#include \"nlohmann/json.hpp\"\n#include \"siddiqsoft/cosmoscl.hpp\"\n\nint main() {\n    // Create client instance\n    siddiqsoft::CosmosClient cc;\n\n    // Configure with connection strings\n    cc.configure({\n        {\"partitionKeyNames\", {\"__pk\"}},\n        {\"connectionStrings\", {primaryCS, secondaryCS}}\n    });\n\n    // Create a document\n    auto response = cc.createDocument({\n        .database   = \"mydb\",\n        .collection = \"mycoll\",\n        .document   = {\n            {\"id\", \"doc1\"},\n            {\"__pk\", \"partition1\"},\n            {\"name\", \"My Document\"},\n            {\"value\", 42}\n        }\n    });\n\n    if (response.statusCode == 201) {\n        std::cout \u003c\u003c \"Document created!\" \u003c\u003c std::endl;\n    }\n\n    return 0;\n}\n```\n\n---\n\n## 📚 Documentation\n\n### For Developers\n\n| Document | Purpose | Time |\n|----------|---------|------|\n| [START_HERE.md](START_HERE.md) | Main entry point | 2 min |\n| [QUICK_START.md](QUICK_START.md) | 5-minute quick start | 5 min |\n| [DEVELOPER_BUILD_GUIDE.md](DEVELOPER_BUILD_GUIDE.md) | Comprehensive guide | 30 min |\n| [DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md) | Navigation hub | 5 min |\n| [SCRIPTS_README.md](SCRIPTS_README.md) | Automated scripts | 2 min |\n\n### For Understanding Changes\n\n| Document | Purpose | Time |\n|----------|---------|------|\n| [TEST_CONSOLIDATION_SUMMARY.md](TEST_CONSOLIDATION_SUMMARY.md) | Test consolidation | 10 min |\n| [PIPELINE_CONSOLIDATION_UPDATE.md](PIPELINE_CONSOLIDATION_UPDATE.md) | CI/CD updates | 10 min |\n| [COMPLETE_CONSOLIDATION_SUMMARY.md](COMPLETE_CONSOLIDATION_SUMMARY.md) | Complete overview | 15 min |\n\n### API Reference\n\n- **[Full API Documentation](https://siddiqsoft.github.io/CosmosClient/)** - Complete API reference\n\n---\n\n## 🛠️ Development\n\n### Prerequisites\n\n**macOS:**\n```bash\nbrew install cmake llvm docker\n```\n\n**Linux (Ubuntu/Debian):**\n```bash\nsudo apt-get install cmake clang-15 docker.io\n```\n\n### Build \u0026 Test\n\n```bash\n# Automated build and test\n./build_and_test.sh debug macos  # or linux\n\n# Manual build\nmkdir -p build \u0026\u0026 cd build\ncmake --preset Apple-Debug ..\ncmake --build . -j$(nproc)\n\n# Run tests\nctest --output-on-failure --verbose\n```\n\n### Test Suite\n\n- **100+ Tests** - Comprehensive test coverage\n- **5 Categories** - Validation, Connection, Endpoint, Integration, Comprehensive\n- **Unified Setup** - Single shared database for all tests\n- **No Emulator Required** - Validation tests run without Azure Cosmos Emulator\n\n#### Windows Docker Tests\n\nDocker-based tests are **disabled on Windows** in the CI/CD pipeline. This is because the Azure Cosmos DB Emulator Docker image is only available for Linux containers, and Windows agents cannot run Linux containers without additional virtualization overhead. Windows builds focus on compilation and packaging validation. For full integration testing, use macOS or Linux environments.\n\nFor detailed testing information, see [DEVELOPER_BUILD_GUIDE.md](DEVELOPER_BUILD_GUIDE.md#running-tests).\n\n---\n\n## 📖 API Usage\n\n### Basic Operations\n\n```cpp\n// Create document\nauto resp = cc.createDocument({\n    .database   = \"db\",\n    .collection = \"coll\",\n    .document   = {{\"id\", \"1\"}, {\"__pk\", \"pk1\"}}\n});\n\n// Find document\nauto resp = cc.findDocument({\n    .database     = \"db\",\n    .collection   = \"coll\",\n    .id           = \"1\",\n    .partitionKey = \"pk1\"\n});\n\n// Update document\nauto resp = cc.updateDocument({\n    .database     = \"db\",\n    .collection   = \"coll\",\n    .id           = \"1\",\n    .partitionKey = \"pk1\",\n    .document     = updatedDoc\n});\n\n// Delete document\nauto resp = cc.removeDocument({\n    .database     = \"db\",\n    .collection   = \"coll\",\n    .id           = \"1\",\n    .partitionKey = \"pk1\"\n});\n\n// Query documents\nauto resp = cc.queryDocuments({\n    .database       = \"db\",\n    .collection     = \"coll\",\n    .partitionKey   = \"*\",\n    .queryStatement = \"SELECT * FROM c WHERE c.status = @status\",\n    .queryParameters = {{{\"name\", \"@status\"}, {\"value\", \"active\"}}}\n});\n```\n\n### Async Operations\n\n```cpp\ncc.async({\n    .operation  = siddiqsoft::CosmosOperation::create,\n    .database   = \"db\",\n    .collection = \"coll\",\n    .document   = {{\"id\", \"1\"}, {\"__pk\", \"pk1\"}},\n    .onResponse = [](auto const\u0026 ctx, auto const\u0026 resp) {\n        if (resp.statusCode == 201) {\n            std::cout \u003c\u003c \"Document created!\" \u003c\u003c std::endl;\n        }\n    }\n});\n```\n\nFor complete API documentation, see [https://siddiqsoft.github.io/CosmosClient/](https://siddiqsoft.github.io/CosmosClient/).\n\n---\n\n## 🏗️ Architecture\n\n### Design Principles\n\n- **Simplicity First** - Minimal abstractions, maximum clarity\n- **JSON Everywhere** - Configuration, I/O, and results use JSON\n- **Modern C++** - Leverage C++23 features\n- **Zero-Cost** - Only pay for what you use\n- **Functional** - Focus on solving problems, not performance\n\n### Project Structure\n\n```\nCosmosClient/\n├── include/\n│   └── siddiqsoft/\n│       └── cosmoscl.hpp          # Main header\n├── tests/\n│   ├── testall.cpp               # Unified test suite (100+ tests)\n│   ├── test_common.hpp           # Test utilities\n│   └── CMakeLists.txt            # Test configuration\n├── CMakeLists.txt                # Build configuration\n├── CMakePresets.json             # CMake presets\n└── [Documentation files]         # See below\n```\n\n---\n\n## 📚 Documentation Files\n\n### Getting Started\n- **[START_HERE.md](START_HERE.md)** - Main entry point\n- **[QUICK_START.md](QUICK_START.md)** - 5-minute quick start\n- **[DEVELOPER_BUILD_GUIDE.md](DEVELOPER_BUILD_GUIDE.md)** - Comprehensive guide\n- **[DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)** - Navigation hub\n\n### Development\n- **[SCRIPTS_README.md](SCRIPTS_README.md)** - Automated scripts\n- **[build_and_test.sh](build_and_test.sh)** - Build script\n\n### Project Information\n- **[TEST_CONSOLIDATION_SUMMARY.md](TEST_CONSOLIDATION_SUMMARY.md)** - Test consolidation\n- **[PIPELINE_CONSOLIDATION_UPDATE.md](PIPELINE_CONSOLIDATION_UPDATE.md)** - CI/CD updates\n- **[COMPLETE_CONSOLIDATION_SUMMARY.md](COMPLETE_CONSOLIDATION_SUMMARY.md)** - Complete overview\n\n---\n\n## 🔄 Development Workflow\n\n### 1. Setup (One-time)\n\n```bash\n# Install tools\nbrew install cmake llvm docker  # macOS\n# or\nsudo apt-get install cmake clang-15 docker.io  # Linux\n\n# Clone repository\ngit clone https://github.com/SiddiqSoft/CosmosClient.git\ncd CosmosClient\ngit submodule update --init --recursive\n```\n\n### 2. Build\n\n```bash\nmkdir -p build \u0026\u0026 cd build\ncmake --preset Apple-Debug ..\ncmake --build . -j$(nproc)\n```\n\n### 3. Test\n\n```bash\n# Start emulator\ndocker run --publish 8081:8081 --publish 10250-10255:10250-10255 \\\n  --name cosmos-emulator --rm --detach \\\n  mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest\nsleep 60\n\n# Run tests\nctest --output-on-failure --verbose\n\n# Stop emulator\ndocker stop cosmos-emulator\n```\n\n### 4. Develop\n\n```bash\n# Make changes\n# Rebuild\ncmake --build build/Apple-Debug -j$(nproc)\n\n# Run specific tests\nctest --output-on-failure -R \"YourTestName\"\n```\n\nFor detailed instructions, see [DEVELOPER_BUILD_GUIDE.md](DEVELOPER_BUILD_GUIDE.md).\n\n---\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| CMake not found | `brew install cmake` (macOS) or `sudo apt-get install cmake` (Linux) |\n| Compiler not found | `brew install llvm` (macOS) or `sudo apt-get install clang-15` (Linux) |\n| Emulator not reachable | Check: `docker ps`, `docker logs cosmos-emulator` |\n| Tests timeout | Increase timeout: `ctest --timeout 1800` |\n| Docker permission denied | `sudo usermod -aG docker $USER \u0026\u0026 newgrp docker` |\n\nFor more troubleshooting, see [DEVELOPER_BUILD_GUIDE.md#troubleshooting](DEVELOPER_BUILD_GUIDE.md#troubleshooting).\n\n---\n\n## 🗺️ Roadmap\n\n- [x] Documentation\n- [x] Unified test suite (100+ tests)\n- [x] Cross-platform support (Windows, macOS, Linux)\n- [ ] Async operations with auto-retry\n- [ ] C++20 modules support\n- [ ] Co-routines support\n- [ ] OpenSSL for non-Windows platforms\n\n---\n\n## 📊 Project Statistics\n\n- **100+ Tests** - Comprehensive test coverage\n- **5 Test Categories** - Validation, Connection, Endpoint, Integration, Comprehensive\n- **Single Database** - Unified test setup\n- **Cross-Platform** - Windows, macOS, Linux\n- **Modern C++** - C++23 features\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests: `ctest --output-on-failure --verbose`\n5. Submit a pull request\n\nFor development guidelines, see [DEVELOPER_BUILD_GUIDE.md](DEVELOPER_BUILD_GUIDE.md).\n\n---\n\n## 📄 License\n\nThis project is licensed under the BSD 3-Clause License. See [LICENSE](LICENSE) file for details.\n\n---\n\n## 📞 Support\n\n- **Documentation**: See [START_HERE.md](START_HERE.md)\n- **API Reference**: [https://siddiqsoft.github.io/CosmosClient/](https://siddiqsoft.github.io/CosmosClient/)\n- **Issues**: [GitHub Issues](https://github.com/SiddiqSoft/CosmosClient/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/SiddiqSoft/CosmosClient/discussions)\n\n---\n\n## 🎯 Quick Navigation\n\n**I want to...**\n\n- **Build and test RIGHT NOW** → [QUICK_START.md](QUICK_START.md)\n- **Understand the complete process** → [DEVELOPER_BUILD_GUIDE.md](DEVELOPER_BUILD_GUIDE.md)\n- **Use automated scripts** → [SCRIPTS_README.md](SCRIPTS_README.md)\n- **Find specific documentation** → [DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)\n- **Understand the API** → [API Documentation](https://siddiqsoft.github.io/CosmosClient/)\n\n---\n\n\u003cp align=\"right\"\u003e\n\u0026copy; 2021 Siddiq Software LLC. All rights reserved.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddiqsoft%2Fcosmosclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiddiqsoft%2Fcosmosclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddiqsoft%2Fcosmosclient/lists"}