Initial Commit
This commit is contained in:
88
packages/foundation/core/schema-registry/README.md
Normal file
88
packages/foundation/core/schema-registry/README.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# @suaveplan/schema-registry - Versioned schema registry with forward/backward compatibility checking for evolving data contracts
|
||||
|
||||
## Summary
|
||||
|
||||
Versioned schema registry with forward/backward/full compatibility checking for evolving data contracts. Register schemas by subject name, enforce evolution rules, and detect breaking changes before they reach production.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
<!-- end:auto-docs --> - [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [compatibility](./src/core/compatibility/compatibility.md) — <!-- begin:auto-docs --> _(no submodules)_- [registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_ - [schema-registry](./src/core/registry/schema-registry.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [schema-registry-error](./src/errors/schema-registry-error.md) — <!-- begin:auto-docs --> _(no submodules)_
|
||||
## Features
|
||||
|
||||
- **Versioned storage** — schemas are registered per subject with auto-incremented versions
|
||||
- **Compatibility enforcement** — BACKWARD, FORWARD, FULL, or NONE modes
|
||||
- **Per-subject overrides** — `setCompatibility()` lets subjects opt into different rules
|
||||
- **Dry-run checks** — `checkCompatibility()` validates without registering
|
||||
- **OTel instrumentation** — `schema_registry.register.total` counter and `schema_registry.check.duration_ms` histogram
|
||||
- **Structured errors** — `SchemaRegistryError` with stable `SCHEMA_REGISTRY.*` codes
|
||||
- **JSON Schema deep analysis** — inspects `required`, `properties`, and `type` fields
|
||||
- **Format-aware** — `zod`, `avro`, and `custom` formats accepted with informational notes
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/schema-registry
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```ts
|
||||
import { createRegistry } from "@suaveplan/schema-registry";
|
||||
|
||||
const registry = createRegistry();
|
||||
|
||||
// Register v1
|
||||
registry.register("UserCreated", {
|
||||
type: "object",
|
||||
properties: { id: { type: "string" }, name: { type: "string" } },
|
||||
required: ["id"],
|
||||
});
|
||||
|
||||
// Register v2 (backward-compatible — adds optional field)
|
||||
registry.register("UserCreated", {
|
||||
type: "object",
|
||||
properties: {
|
||||
id: { type: "string" },
|
||||
name: { type: "string" },
|
||||
email: { type: "string" },
|
||||
},
|
||||
required: ["id"],
|
||||
});
|
||||
|
||||
const latest = registry.getLatest("UserCreated");
|
||||
console.log(latest.version); // 2
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
| Subpath | Description |
|
||||
|---------|-------------|
|
||||
| `@suaveplan/schema-registry` | Full barrel export |
|
||||
| [`@suaveplan/schema-registry/registry`](src/core/registry/schema-registry.md) | `SchemaRegistry` class and `createRegistry` factory |
|
||||
| [`@suaveplan/schema-registry/compatibility`](src/core/compatibility/compatibility.md) | `checkCompatibility` pure function |
|
||||
| [`@suaveplan/schema-registry/errors`](src/errors/schema-registry-error.md) | `SchemaRegistryError` and `SCHEMA_REGISTRY_CODES` |
|
||||
|
||||
## Compatibility Levels
|
||||
|
||||
| Level | Description |
|
||||
|-------|-------------|
|
||||
| `BACKWARD` (default) | New schema can read data written with old schema |
|
||||
| `FORWARD` | Old schema can read data written with new schema |
|
||||
| `FULL` | Both BACKWARD and FORWARD must pass |
|
||||
| `NONE` | No compatibility checks — any schema accepted |
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| `SCHEMA_REGISTRY.SCHEMA_NOT_FOUND` | Requested version does not exist |
|
||||
| `SCHEMA_REGISTRY.INCOMPATIBLE_SCHEMA` | Registration rejected by compatibility rule |
|
||||
| `SCHEMA_REGISTRY.INVALID_SCHEMA` | Schema definition fails validation |
|
||||
| `SCHEMA_REGISTRY.SUBJECT_NOT_FOUND` | Subject has no registered versions |
|
||||
Reference in New Issue
Block a user