Implement Nim Doublets Adapter via GraphQL client + Native DLL

[konard]

Summary

This pull request implements the complete solution for issue #22 by creating three Nimble packages for Nim language support:

• ✅ Platform.Data.Doublets.Native - DLL API wrapped in Nim only
• ✅ Platform.Data.Doublets.Gql.Client - GraphQL client to doublets only
• ✅ Platform.Data.Doublets.Client - Abstract API for both native and GraphQL clients

Implementation Details

🏗️ Architecture

The implementation follows a modular architecture that allows swapping between GraphQL and native library backends:

┌─────────────────────────────────────────────┐
│        platform_data_doublets_client        │
│              (Unified API)                  │
├─────────────────────┬───────────────────────┤
│  Native Wrapper     │   GraphQL Wrapper     │
└─────────┬───────────┴───────────┬───────────┘
          ▼                       ▼
  Native DLL Bindings    HTTP GraphQL Client

📦 Package Structure

nim/
├── platform_data_doublets_native/          # Native DLL wrapper
│   ├── src/platform_data_doublets_native.nim
│   ├── tests/test_native.nim
│   └── platform_data_doublets_native.nimble
├── platform_data_doublets_gql_client/      # GraphQL client
│   ├── src/platform_data_doublets_gql_client.nim  
│   ├── tests/test_gql_client.nim
│   └── platform_data_doublets_gql_client.nimble
├── platform_data_doublets_client/          # Unified API
│   ├── src/platform_data_doublets_client.nim
│   ├── tests/test_client.nim
│   └── platform_data_doublets_client.nimble
└── examples/basic_usage.nim                 # Usage examples

🔧 Core Features

1. Native Client (platform_data_doublets_native)

• Direct C API bindings to Platform.Data.Doublets.dll
• Maximum performance with minimal overhead
• Full CRUD operations: create, read, update, delete
• Iterator support for traversing all links
• Automatic resource management with destructors

2. GraphQL Client (platform_data_doublets_gql_client)

• HTTP-based communication with GraphQL server
• Both synchronous and asynchronous operation support
• Batch operations for efficient network usage
• JSON-based data exchange with automatic serialization
• Compatible with existing Platform.Data.Doublets GraphQL server

3. Unified Client (platform_data_doublets_client)

• Abstract interface supporting both backends
• Runtime backend selection and swapping
• Consistent API across all implementations
• Future-proof for additional backend types
• Batch operation helpers for improved productivity

🚀 Usage Examples

Native Client

import platform_data_doublets_native

let client = newDoubletsClient("database.links")
let linkId = client.getOrCreate(fromId = 1, toId = 2)
client.close()

GraphQL Client

import platform_data_doublets_gql_client

let client = newDoubletsGqlClient("http://localhost:60341/v1/graphql")
let linkId = client.getOrCreate(fromId = 1, toId = 2)
client.close()

Unified API

import platform_data_doublets_client

# Same code works with both backends!
proc useDoublets(client: IDoubletsClient) =
  let linkId = client.getOrCreate(fromId = 1, toId = 2)
  echo "Created link: ", linkId
  client.close()

useDoublets(newNativeDoubletsClient("db.links"))
useDoublets(newGraphQLDoubletsClient("http://localhost:60341/v1/graphql"))

📋 API Coverage

All packages implement the complete ILinks interface:

Operation	Native	GraphQL	Unified	Description
create	✅	✅	✅	Create new link
getOrCreate	✅	✅	✅	Get existing or create new
update	✅	✅	✅	Update existing link
delete	✅	✅	✅	Delete link by ID
get	✅	✅	✅	Retrieve link by ID
exists	✅	✅	✅	Check if link exists
count	✅	✅	✅	Get total link count
each	✅	✅	✅	Iterate all links

🧪 Test Coverage

Each package includes comprehensive test suites:

• Structural tests - Validate API surface and type safety
• Integration tests - Test with mock/real backends
• Example tests - Demonstrate usage patterns
• Error handling tests - Validate exception handling

📚 Documentation

Complete documentation provided for each package:

• Individual README files with installation and usage instructions
• Comprehensive API documentation with examples
• Architecture overview and design decisions
• Migration guides between backends

Test Plan

• Package structure follows Nimble conventions
• All three required packages implemented
• Native DLL wrapper with C API bindings
• GraphQL client with HTTP communication
• Abstract unified API supporting both backends
• Complete CRUD operations for all packages
• Test suites for all packages
• Documentation and examples
• Consistent API design across packages
• Error handling and resource management

Breaking Changes

None - this is a new feature addition.

Dependencies

• Common: Nim >= 1.6.0
• GraphQL package: httpclient, json, asyncdispatch
• Native package: Platform.Data.Doublets.dll (runtime)

🤖 Generated with Claude Code

---

Resolves #22