synthra 0.1.0

data/docs/GRAPHQL_EXPORT.md

@@ -0,0 +1,303 @@
+# GraphQL Schema Export
+
+FakeDataDSL can export schemas to GraphQL SDL (Schema Definition Language), making it easy to generate type-safe GraphQL APIs from your data schemas.
+
+## Quick Start
+
+### Ruby API
+
+```ruby
+require 'fake_data_dsl'
+
+# Load schema
+schema = FakeDataDSL.load("schemas/user.dsl")
+
+# Export to GraphQL
+graphql = FakeDataDSL.to_graphql(schema)
+puts graphql
+```
+
+### CLI
+
+```bash
+# Export single schema
+fake_data_dsl export User -d schemas -f graphql -o schema.graphql
+
+# Export all schemas
+fake_data_dsl export --all -d schemas -f graphql -o schema.graphql
+```
+
+## Output Example
+
+Given this DSL:
+
+```
+User:
+  id: uuid
+  name: text
+  email: email
+  age: number
+  active: boolean
+  role: enum(user, admin, moderator)
+```
+
+Generates this GraphQL:
+
+```graphql
+# FakeDataDSL Generated GraphQL Schema
+# Generated at: 2024-01-15T10:30:00Z
+
+enum UserRoleEnum {
+  USER
+  ADMIN
+  MODERATOR
+}
+
+type User {
+  id: ID!
+  name: String!
+  email: String!
+  age: Int!
+  active: Boolean!
+  role: UserRoleEnum!
+}
+
+type Query {
+  user(id: ID!): User
+  users(limit: Int = 10, offset: Int = 0): [User!]!
+}
+```
+
+## Type Mapping
+
+FakeDataDSL types are mapped to GraphQL types:
+
+| FakeDataDSL | GraphQL | Notes |
+|-------------|---------|-------|
+| `uuid`, `ulid`, `id_sequence` | `ID` | Identifier types |
+| `text`, `name`, `email`, `phone` | `String` | String types |
+| `number`, `integer`, `age` | `Int` | Integer types |
+| `float`, `money`, `latitude` | `Float` | Floating point |
+| `boolean` | `Boolean` | Boolean type |
+| `date`, `timestamp` | `String` | Dates as ISO strings |
+| `enum(...)` | `enum` | Auto-generated enums |
+| `array(T)` | `[T!]!` | Non-nullable arrays |
+| `Schema` reference | `Schema` | Nested types |
+
+## Features
+
+### Nullable Fields
+
+Optional and nullable fields omit the `!`:
+
+```
+User:
+  id: uuid
+  bio?: text       # Optional field
+  nickname: text?  # Nullable field
+```
+
+```graphql
+type User {
+  id: ID!
+  bio: String      # No ! (optional)
+  nickname: String # No ! (nullable)
+}
+```
+
+### Enum Generation
+
+Enums are automatically extracted and named:
+
+```
+Product:
+  status: enum(draft, published, archived)
+  category: enum(electronics, clothing, home)
+```
+
+```graphql
+enum ProductStatusEnum {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+enum ProductCategoryEnum {
+  ELECTRONICS
+  CLOTHING
+  HOME
+}
+
+type Product {
+  status: ProductStatusEnum!
+  category: ProductCategoryEnum!
+}
+```
+
+### Array Fields
+
+Arrays map to GraphQL list types:
+
+```
+Order:
+  items: array(OrderItem, 1..10)
+  tags: array(text, 0..5)
+```
+
+```graphql
+type Order {
+  items: [OrderItem!]!
+  tags: [String!]!
+}
+```
+
+### Schema References
+
+Cross-schema references maintain their types:
+
+```
+Order:
+  id: uuid
+  customer: Customer
+  items: array(OrderItem, 1..5)
+```
+
+```graphql
+type Order {
+  id: ID!
+  customer: Customer!
+  items: [OrderItem!]!
+}
+```
+
+## Export All Schemas
+
+Export an entire registry to a single GraphQL file:
+
+```ruby
+registry = FakeDataDSL::Registry.new
+registry.load_dir("schemas/")
+
+graphql = FakeDataDSL.to_graphql_all(registry)
+File.write("schema.graphql", graphql)
+```
+
+This generates:
+- All types from all schemas
+- All enums extracted from schemas
+- A Query type with CRUD-like queries for each type
+
+## Query Type Generation
+
+When exporting all schemas, a Query type is automatically generated:
+
+```graphql
+type Query {
+  user(id: ID!): User
+  users(limit: Int = 10, offset: Int = 0): [User!]!
+  
+  order(id: ID!): Order
+  orders(limit: Int = 10, offset: Int = 0): [Order!]!
+  
+  product(id: ID!): Product
+  products(limit: Int = 10, offset: Int = 0): [Product!]!
+}
+```
+
+## Customization
+
+### With Registry
+
+Pass a registry for cross-schema reference resolution:
+
+```ruby
+registry = FakeDataDSL::Registry.new
+registry.load_dir("schemas/")
+
+schema = registry.schema("User")
+graphql = FakeDataDSL.to_graphql(schema, registry: registry)
+```
+
+## Integration with GraphQL Servers
+
+### Ruby (graphql-ruby)
+
+```ruby
+# Use the generated schema as a starting point
+schema_string = FakeDataDSL.to_graphql_all(registry)
+File.write("app/graphql/schema.graphql", schema_string)
+
+# Then implement resolvers
+class QueryType < GraphQL::Schema::Object
+  field :user, UserType, null: true do
+    argument :id, ID, required: true
+  end
+  
+  def user(id:)
+    User.find(id)
+  end
+end
+```
+
+### Node.js
+
+```javascript
+// Save the generated schema
+const fs = require('fs');
+const schema = fs.readFileSync('schema.graphql', 'utf8');
+
+// Use with Apollo Server
+const { ApolloServer } = require('apollo-server');
+const typeDefs = gql(schema);
+```
+
+## Best Practices
+
+### 1. Keep Schemas in Sync
+
+Generate GraphQL schemas as part of your build process:
+
+```bash
+# In CI or pre-commit hook
+fake_data_dsl export --all -d schemas -f graphql -o schema.graphql
+git diff --exit-code schema.graphql || echo "GraphQL schema out of sync!"
+```
+
+### 2. Use Consistent Naming
+
+FakeDataDSL uses PascalCase for types and camelCase for fields:
+
+```
+UserProfile:          # → type UserProfile
+  firstName: name     # → firstName: String!
+  lastName: name      # → lastName: String!
+```
+
+### 3. Document Deprecated Fields
+
+```
+User:
+  @deprecated "Use email_verified instead"
+  verified: boolean
+  email_verified: boolean
+```
+
+```graphql
+type User {
+  verified: Boolean! @deprecated
+  emailVerified: Boolean!
+}
+```
+
+## Limitations
+
+- Custom scalars not yet supported
+- Directives limited to `@deprecated`
+- Interfaces and unions not supported
+- Input types not generated (only output types)
+
+## See Also
+
+- [Export Guide](../tech_docs/export/README.md)
+- [Type Reference](../tech_docs/appendices/type_chart.md)
+- [CLI Usage](../tech_example/04_cli_usage.md)