mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-25 22:34:56 +00:00
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
187 lines
4.6 KiB
Markdown
187 lines
4.6 KiB
Markdown
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<T> 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<T>"
|
|
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"
|