johndoe6345789
49f40177b5
README.md
LICENSE
AGENTS.md
api/ # Language-agnostic contract (source of truth)
schema/
entities/ # Entity definitions (conceptual models)
user.yaml
session.yaml
...
operations/ # CRUD + domain operations (semantic, not SQL)
user.ops.yaml
...
errors.yaml # Standard error codes (conflict, not_found, etc.)
capabilities.yaml # Feature flags per backend (tx, joins, ttl, etc.)
idl/
dbal.proto # Optional: RPC/IPC contract if needed
dbal.fbs # Optional: FlatBuffers schema if you prefer
versioning/
compat.md # Compatibility rules across TS/C++
common/ # Shared test vectors + fixtures + golden results
fixtures/
seed/
datasets/
golden/
query_results/
contracts/
conformance_cases.yaml
ts/ # Development implementation in TypeScript
package.json
tsconfig.json
src/
index.ts # Public entrypoint (creates client)
core/
client.ts # DBAL client facade
types.ts # TS types mirroring api/schema
errors.ts # Error mapping to api/errors.yaml
validation/ # Runtime validation (zod/io-ts/etc.)
input.ts
output.ts
capabilities.ts # Capability negotiation
telemetry/
logger.ts
metrics.ts
tracing.ts
adapters/ # Backend implementations (TS)
prisma/
index.ts
prisma_client.ts # Wraps Prisma client (server-side only)
mapping.ts # DB <-> entity mapping, select shaping
migrations/ # Optional: Prisma migration helpers
sqlite/
index.ts
sqlite_driver.ts
schema.ts
migrations/
mongodb/
index.ts
mongo_driver.ts
schema.ts
query/ # Query builder / AST (no backend leakage)
ast.ts
builder.ts
normalize.ts
optimize.ts
runtime/
config.ts # DBAL config (env, URLs, pool sizes)
secrets.ts # Secret loading boundary (server-only)
util/
assert.ts
retry.ts
backoff.ts
time.ts
tests/
unit/
integration/
conformance/ # Runs common/contract vectors on TS adapters
harness/
setup.ts
cpp/ # Production implementation in C++
CMakeLists.txt
include/
dbal/
dbal.hpp # Public API
client.hpp # Facade
types.hpp # Entity/DTO types
errors.hpp
capabilities.hpp
telemetry.hpp
query/
ast.hpp
builder.hpp
normalize.hpp
adapters/
adapter.hpp # Adapter interface
sqlite/
sqlite_adapter.hpp
mongodb/
mongodb_adapter.hpp
prisma/
prisma_adapter.hpp # Usually NOT direct; see note below
util/
expected.hpp
result.hpp
uuid.hpp
src/
client.cpp
errors.cpp
capabilities.cpp
telemetry.cpp
query/
ast.cpp
builder.cpp
normalize.cpp
adapters/
sqlite/
sqlite_adapter.cpp
sqlite_pool.cpp
sqlite_migrations.cpp
mongodb/
mongodb_adapter.cpp
mongo_pool.cpp
prisma/
prisma_adapter.cpp # See note below (often an RPC bridge)
util/
uuid.cpp
backoff.cpp
tests/
unit/
integration/
conformance/ # Runs common/contract vectors on C++ adapters
harness/
main.cpp
backends/ # Backend-specific assets not tied to one lang
sqlite/
schema.sql
migrations/
mongodb/
indexes.json
prisma/
schema.prisma
migrations/
tools/ # Codegen + build helpers (prefer Python)
codegen/
gen_types.py # api/schema -> ts/core/types.ts and cpp/types.hpp
gen_errors.py
gen_capabilities.py
conformance/
run_all.py # runs TS + C++ conformance suites
dev/
lint.py
format.py
scripts/ # Cross-platform entrypoints (Python per your pref)
build.py
test.py
conformance.py
package.py
dist/ # Build outputs (gitignored)
.github/
workflows/
ci.yml
.gitignore
.editorconfig
4.6 KiB
version: "1.0"
compatibility: description: "Compatibility rules for API versioning across TypeScript and C++ implementations"
semver: major: "Breaking changes - requires migration" minor: "New features - backward compatible" patch: "Bug fixes - backward compatible"
breaking_changes: - "Removing entity fields" - "Removing operations" - "Changing field types incompatibly" - "Changing operation signatures" - "Removing enum values"
non_breaking_changes: - "Adding new entities" - "Adding new operations" - "Adding optional fields" - "Adding new enum values" - "Adding indexes"
deprecation_policy: duration: "2 major versions" process: - "Mark as deprecated in API schema" - "Add deprecation warnings in both implementations" - "Document migration path" - "Remove in next major version"
language_compatibility: typescript: min_version: "5.0" target: "ES2022" module: "ES2022" notes: - "Uses async/await for all operations" - "Errors thrown as DBALError instances" - "Optional fields use TypeScript ? syntax"
cpp: min_version: "C++17" compiler: "GCC 9+, Clang 10+, MSVC 2019+" notes: - "Uses std::optional for optional fields" - "Errors returned via Result type" - "Thread-safe by default"
type_mapping: uuid: typescript: "string" cpp: "std::string" notes: "UUID v4 format"
string: typescript: "string" cpp: "std::string"
text: typescript: "string" cpp: "std::string" notes: "Large text, no length limit"
integer: typescript: "number" cpp: "int" notes: "32-bit signed integer"
bigint: typescript: "bigint" cpp: "int64_t" notes: "64-bit integer"
boolean: typescript: "boolean" cpp: "bool"
datetime: typescript: "Date" cpp: "std::chrono::system_clock::time_point" notes: "ISO 8601 format in JSON"
json: typescript: "Record<string, unknown>" cpp: "Json (map<string, string>)" notes: "Serialized as JSON string in storage"
enum: typescript: "string union type" cpp: "enum class" notes: "Values must be defined in schema"
error_handling: typescript: pattern: "Throw DBALError" example: | throw DBALError.notFound('User not found')
cpp: pattern: "Return Result" example: | return Error::notFound("User not found");
compatibility: - "Error codes must match exactly" - "Error messages should be identical" - "Additional fields in details are allowed"
async_patterns: typescript: pattern: "async/await with Promises" example: | const user = await client.users.read(id)
cpp: pattern: "Synchronous (blocking)" example: | auto result = client.createUser(input); if (result.isOk()) { User user = result.value(); } notes: - "C++ daemon handles async I/O internally" - "Client calls are synchronous for simplicity" - "Future: Consider coroutines (C++20)"
serialization: json: format: "Standard JSON" date_format: "ISO 8601" null_handling: "Optional fields may be omitted or null"
wire_protocol: development: "JSON over WebSocket" production: "Protobuf over gRPC" fallback: "JSON over HTTP"
testing_compatibility: conformance_tests: format: "YAML test vectors" runner: "Python script" execution: "Parallel (TS and C++)" comparison: "Output must match exactly"
test_structure: input: "Operation + parameters" expected: "Status + output or error" variables: "Support $prev, $steps[n]"
tolerance: timestamps: "Within 1 second" float_precision: "6 decimal places" uuid_format: "Any valid v4"
migration_guide: v1_to_v2: - "Review CHANGELOG.md" - "Run migration script: scripts/migrate_v1_to_v2.py" - "Update entity schemas" - "Regenerate types: python tools/codegen/gen_types.py" - "Rebuild both implementations" - "Run conformance tests"
rollback: - "Restore from backup" - "Downgrade DBAL version" - "Revert schema changes" - "Rebuild"
versioning_in_production: strategy: "Side-by-side versions" example: | /usr/local/lib/dbal/v1/ /usr/local/lib/dbal/v2/
client_selection: - "Client specifies API version in config" - "Daemon routes to appropriate handler" - "Multiple versions supported simultaneously"
sunset_policy: - "Support N-2 versions" - "6 month deprecation period" - "Email notifications before removal"