@demokit-ai/schema 0.0.2 → 0.2.0

package/README.md

@@ -0,0 +1,244 @@
+# @demokit-ai/schema
+
+![Tests](https://img.shields.io/badge/tests-79%20passing-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-13%25-red)
+
+OpenAPI schema parsing with relationship detection for DemoKit.
+
+## Installation
+
+```bash
+npm install @demokit-ai/schema
+```
+
+## Features
+
+- **OpenAPI Parsing** - Parse OpenAPI 3.x specifications
+- **Relationship Detection** - Automatically detect model relationships
+- **Schema Normalization** - Convert to DemoKit's internal schema format
+- **Type Inference** - Infer property types and constraints
+- **Validation** - Validate schemas against OpenAPI spec
+- Full TypeScript support
+
+## Usage
+
+### Parse OpenAPI Spec
+
+```ts
+import { parseOpenAPI } from '@demokit-ai/schema'
+
+const schema = await parseOpenAPI('./openapi.yaml')
+
+console.log(schema.models)
+// {
+//   User: {
+//     properties: {
+//       id: { type: 'string', format: 'uuid' },
+//       name: { type: 'string' },
+//       email: { type: 'string', format: 'email' },
+//     },
+//     required: ['id', 'name', 'email'],
+//   },
+//   Order: { ... },
+// }
+
+console.log(schema.relationships)
+// [
+//   { from: { model: 'Order', field: 'userId' }, to: { model: 'User', field: 'id' }, type: 'many-to-one' },
+// ]
+```
+
+### Parse from URL
+
+```ts
+import { parseOpenAPI } from '@demokit-ai/schema'
+
+const schema = await parseOpenAPI('https://api.example.com/openapi.json')
+```
+
+### Parse from Object
+
+```ts
+import { parseOpenAPIObject } from '@demokit-ai/schema'
+
+const spec = {
+  openapi: '3.0.0',
+  paths: { ... },
+  components: {
+    schemas: {
+      User: { ... },
+    },
+  },
+}
+
+const schema = parseOpenAPIObject(spec)
+```
+
+### Detect Relationships
+
+```ts
+import { detectRelationships } from '@demokit-ai/schema'
+
+const models = {
+  User: {
+    properties: {
+      id: { type: 'string' },
+    },
+  },
+  Order: {
+    properties: {
+      id: { type: 'string' },
+      userId: { type: 'string' },
+    },
+  },
+}
+
+const relationships = detectRelationships(models)
+// [
+//   {
+//     from: { model: 'Order', field: 'userId' },
+//     to: { model: 'User', field: 'id' },
+//     type: 'many-to-one',
+//   },
+// ]
+```
+
+### Define Schema Manually
+
+```ts
+import { defineSchema } from '@demokit-ai/schema'
+
+const schema = defineSchema({
+  models: {
+    User: {
+      properties: {
+        id: { type: 'string', format: 'uuid' },
+        name: { type: 'string', minLength: 1 },
+        email: { type: 'string', format: 'email' },
+        role: { type: 'string', enum: ['admin', 'user', 'guest'] },
+        createdAt: { type: 'string', format: 'date-time' },
+      },
+      required: ['id', 'name', 'email'],
+    },
+    Order: {
+      properties: {
+        id: { type: 'string', format: 'uuid' },
+        userId: {
+          type: 'string',
+          relationshipTo: { model: 'User', field: 'id' },
+        },
+        total: { type: 'number', minimum: 0 },
+        status: { type: 'string', enum: ['pending', 'completed', 'cancelled'] },
+      },
+      required: ['id', 'userId', 'total', 'status'],
+    },
+  },
+})
+```
+
+### Validate Schema
+
+```ts
+import { validateSchema } from '@demokit-ai/schema'
+
+const result = validateSchema(schema)
+
+if (!result.valid) {
+  console.error('Schema errors:', result.errors)
+}
+```
+
+## API Reference
+
+### `parseOpenAPI(pathOrUrl)`
+
+Parse an OpenAPI spec from a file path or URL.
+
+Returns: `Promise<DemokitSchema>`
+
+### `parseOpenAPIObject(spec)`
+
+Parse an OpenAPI spec from a JavaScript object.
+
+Returns: `DemokitSchema`
+
+### `detectRelationships(models)`
+
+Detect relationships between models based on field naming conventions.
+
+Returns: `Relationship[]`
+
+### `defineSchema(options)`
+
+Define a schema manually with full type inference.
+
+Options:
+- `models` - Model definitions
+- `relationships` - Explicit relationship definitions (optional)
+
+Returns: `DemokitSchema`
+
+### `validateSchema(schema)`
+
+Validate a schema for correctness.
+
+Returns:
+- `valid` - Whether schema is valid
+- `errors` - Array of validation errors
+- `warnings` - Array of warnings
+
+## Types
+
+### `DemokitSchema`
+
+```ts
+interface DemokitSchema {
+  version: string
+  models: Record<string, DataModel>
+  relationships: Relationship[]
+}
+```
+
+### `DataModel`
+
+```ts
+interface DataModel {
+  properties: Record<string, PropertyDef>
+  required?: string[]
+}
+```
+
+### `PropertyDef`
+
+```ts
+interface PropertyDef {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object'
+  name?: string
+  format?: string
+  enum?: unknown[]
+  minimum?: number
+  maximum?: number
+  minLength?: number
+  maxLength?: number
+  pattern?: string
+  nullable?: boolean
+  default?: unknown
+  example?: unknown
+  relationshipTo?: { model: string; field: string }
+  items?: PropertyDef | DataModel
+}
+```
+
+### `Relationship`
+
+```ts
+interface Relationship {
+  from: { model: string; field: string }
+  to: { model: string; field: string }
+  type: 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many'
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@demokit-ai/schema",
-  "version": "0.0.2",
+  "version": "0.2.0",
   "description": "OpenAPI schema parsing with relationship detection for DemoKit",
   "type": "module",
   "main": "./dist/index.cjs",