feature: add support for effect as a validator WIP

Author: hobbescodes

.changeset/add-effect-schema-support.md

@@ -0,0 +1,29 @@
+---
+"tangrams": minor
+---
+
+Add Effect Schema as a fourth validation library option alongside Zod, Valibot, and ArkType.
+
+Effect Schema is part of the Effect ecosystem and uses a functional approach to schema definition. Unlike the other validators which natively implement Standard Schema, Effect Schema requires wrapping with `Schema.standardSchemaV1()` for use with TanStack Form - this wrapping is handled automatically in generated form options.
+
+To use Effect Schema:
+
+```typescript
+import { defineConfig } from "tangrams"
+
+export default defineConfig({
+  validator: "effect",
+  sources: [/* ... */],
+})
+```
+
+Custom scalar mappings for Effect use the `Schema.` prefix:
+
+```typescript
+overrides: {
+  scalars: {
+    DateTime: "Schema.String",
+    JSON: "Schema.Unknown",
+  },
+}
+```

apps/docs/content/docs/index.mdx

@@ -233,20 +233,23 @@ export default defineConfig({
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `output` | `string` | `"."` | Directory where the `tangrams` folder will be generated |
-| `validator` | `"zod" \| "valibot" \| "arktype"` | `"zod"` | Validation library for generated schemas |
+| `validator` | `"zod" \| "valibot" \| "arktype" \| "effect"` | `"zod"` | Validation library for generated schemas |
 | `sources` | `SourceConfig[]` | (required) | Array of data sources (minimum 1 required) |
 
 ### Validator Libraries
 
-Tangrams supports three validation libraries that all implement [Standard Schema](https://github.com/standard-schema/standard-schema):
+Tangrams supports four validation libraries that all implement [Standard Schema](https://github.com/standard-schema/standard-schema):
 
 | Library | Import | Description |
 |---------|--------|-------------|
 | **Zod** | `zod` | The default. Full-featured schema validation with great TypeScript inference. |
 | **Valibot** | `valibot` | Lightweight alternative with modular design and smaller bundle size. |
 | **ArkType** | `arktype` | Type-first validation with runtime safety and excellent TypeScript integration. |
+| **Effect** | `effect` | Part of the Effect ecosystem. Requires `Schema.standardSchemaV1()` wrapper for TanStack Form. |
 
-All three libraries work seamlessly with TanStack Form since they implement the Standard Schema protocol. Choose based on your preferences for bundle size, API style, or existing usage in your project.
+All four libraries work seamlessly with TanStack Form since they implement the Standard Schema protocol. Choose based on your preferences for bundle size, API style, or existing usage in your project.
+
+> **Note:** Effect Schema requires wrapping with `Schema.standardSchemaV1()` for Standard Schema compliance. Tangrams handles this automatically in generated form options.
 
 ```typescript
 // Use Zod (default)
@@ -266,11 +269,17 @@ export default defineConfig({
   validator: "arktype",
   sources: [/* ... */],
 })
+
+// Use Effect for the Effect ecosystem
+export default defineConfig({
+  validator: "effect",
+  sources: [/* ... */],
+})
 ```
 
 Install your chosen validator as a peer dependency:
 
-<Tabs items={['Zod', 'Valibot', 'ArkType']}>
+<Tabs items={['Zod', 'Valibot', 'ArkType', 'Effect']}>
   <Tab value="Zod">
 ```bash
 bun add zod
@@ -284,6 +293,11 @@ bun add valibot
   <Tab value="ArkType">
 ```bash
 bun add arktype
+```
+  </Tab>
+  <Tab value="Effect">
+```bash
+bun add effect
 ```
   </Tab>
 </Tabs>
@@ -353,7 +367,7 @@ generates: ["query", "form", "db"] // All three
 
 Map custom GraphQL scalars to validator expressions. Values must be valid expressions for your configured validator library:
 
-<Tabs items={['Zod', 'Valibot', 'ArkType']}>
+<Tabs items={['Zod', 'Valibot', 'ArkType', 'Effect']}>
   <Tab value="Zod">
 ```typescript
 overrides: {
@@ -385,11 +399,22 @@ overrides: {
     Cursor: 'type("string")',
   },
 }
+```
+  </Tab>
+  <Tab value="Effect">
+```typescript
+overrides: {
+  scalars: {
+    DateTime: "Schema.String",
+    JSON: "Schema.Unknown",
+    Cursor: "Schema.String",
+  },
+}
 ```
   </Tab>
 </Tabs>
 
-> **Note:** Scalar values must start with a valid prefix for your validator: `z.` for Zod, `v.` for Valibot, or `type(` / `type.` for ArkType. Using raw TypeScript types like `"string"` or `"Date"` will throw a validation error with a helpful suggestion.
+> **Note:** Scalar values must start with a valid prefix for your validator: `z.` for Zod, `v.` for Valibot, `type(` / `type.` for ArkType, or `Schema.` for Effect. Using raw TypeScript types like `"string"` or `"Date"` will throw a validation error with a helpful suggestion.
 
 **Built-in Scalar Mappings:**
 

bun.lock

@@ -68,6 +68,7 @@
     "@types/picomatch": "^4.0.2",
     "@vitest/coverage-istanbul": "^3.2.3",
     "arktype": "^2.1.20",
+    "effect": "^3.12.0",
     "graphql-request": "^7.1.2",
     "tsup": "^8.5.0",
     "valibot": "^1.1.0",
@@ -78,6 +79,7 @@
     "@better-fetch/fetch": ">=1.0.0",
     "@tanstack/react-query": ">=5.0.0",
     "arktype": ">=2.0.0",
+    "effect": ">=3.0.0",
     "graphql-request": ">=6.0.0",
     "valibot": ">=1.0.0",
     "zod": ">=4.0.0"
@@ -92,6 +94,9 @@
     "arktype": {
       "optional": true
     },
+    "effect": {
+      "optional": true
+    },
     "graphql-request": {
       "optional": true
     },

packages/cli/package.json

@@ -56,6 +56,12 @@ const validatorPatterns: Record<
     string: '"string"',
     enum: "type.enumerated(",
   },
+  effect: {
+    import: 'import { Schema } from "effect"',
+    object: "Schema.Struct(",
+    string: "Schema.String",
+    enum: "Schema.Union(Schema.Literal(",
+  },
 };
 
 // Test schema for unit tests (doesn't require network)
@@ -1245,6 +1251,15 @@ describe("GraphQL Collection Discovery", () => {
       ).not.toThrow();
     });
 
+    it("accepts valid effect scalar expressions", () => {
+      expect(() =>
+        graphqlAdapter.generateSchemas(testSchemaWithScalar, scalarTestConfig, {
+          validator: "effect",
+          scalars: { Cursor: "Schema.String", DateTime: "Schema.String" },
+        }),
+      ).not.toThrow();
+    });
+
     it("throws error for invalid zod scalar with helpful message", () => {
       expect(() =>
         graphqlAdapter.generateSchemas(testSchemaWithScalar, scalarTestConfig, {
@@ -1299,6 +1314,24 @@ describe("GraphQL Collection Discovery", () => {
       ).toThrow(/Did you mean "type\("string"\)"\?/);
     });
 
+    it("throws error for invalid effect scalar", () => {
+      expect(() =>
+        graphqlAdapter.generateSchemas(testSchemaWithScalar, scalarTestConfig, {
+          validator: "effect",
+          scalars: { Cursor: "string" },
+        }),
+      ).toThrow(/Invalid scalar mapping for "Cursor": received "string"/);
+    });
+
+    it("suggests correct effect expression in error message", () => {
+      expect(() =>
+        graphqlAdapter.generateSchemas(testSchemaWithScalar, scalarTestConfig, {
+          validator: "effect",
+          scalars: { Cursor: "string" },
+        }),
+      ).toThrow(/Did you mean "Schema\.String"\?/);
+    });
+
     it("includes validator name in error message", () => {
       expect(() =>
         graphqlAdapter.generateSchemas(testSchemaWithScalar, scalarTestConfig, {

packages/cli/src/adapters/graphql/graphql.test.ts

@@ -210,6 +210,7 @@ class GraphQLAdapterImpl implements IGraphQLAdapter {
     const result = generateFormOptionsCode(mutationOps, {
       schemaImportPath: options.schemaImportPath,
       formOverrides: options.formOverrides,
+      validatorLibrary: options.validatorLibrary,
     });
 
     return {

packages/cli/src/adapters/graphql/index.ts

@@ -151,6 +151,7 @@ class OpenAPIAdapterImpl implements IOpenAPIAdapter {
     const result = generateFormOptionsCode(mutationOps, {
       schemaImportPath: options.schemaImportPath,
       formOverrides: options.formOverrides,
+      validatorLibrary: options.validatorLibrary,
     });
 
     return {

packages/cli/src/adapters/openapi/index.ts

@@ -57,6 +57,14 @@ const validatorPatterns: Record<
     array: "type(",
     nullable: "| null",
   },
+  effect: {
+    import: 'import { Schema } from "effect"',
+    object: "Schema.Struct(",
+    string: "Schema.String",
+    enum: "Schema.Union(Schema.Literal(",
+    array: "Schema.Array(",
+    nullable: "Schema.NullishOr(",
+  },
 };
 
 describe("OpenAPI Adapter", () => {

packages/cli/src/adapters/openapi/openapi.test.ts

@@ -159,6 +159,8 @@ export interface FormGenOptions {
   sourceName: string;
   /** Form overrides from config (validator, validationLogic) */
   formOverrides?: FormOverridesConfig;
+  /** Validation library (needed for Effect's Standard Schema wrapper) */
+  validatorLibrary?: ValidatorLibrary;
 }
 
 // =============================================================================

packages/cli/src/adapters/types.ts

@@ -455,6 +455,46 @@ describe("configSchema", () => {
       expect(result.data.output).toBe("./custom/output");
     }
   });
+
+  it("validates all supported validator libraries", () => {
+    const validators = ["zod", "valibot", "arktype", "effect"] as const;
+    for (const validator of validators) {
+      const config = {
+        validator,
+        sources: [
+          {
+            name: "graphql",
+            type: "graphql",
+            schema: { url: "http://localhost:4000/graphql" },
+            documents: "./src/graphql/**/*.graphql",
+            generates: ["query"],
+          },
+        ],
+      };
+      const result = configSchema.safeParse(config);
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.data.validator).toBe(validator);
+      }
+    }
+  });
+
+  it("rejects invalid validator library", () => {
+    const config = {
+      validator: "invalid",
+      sources: [
+        {
+          name: "graphql",
+          type: "graphql",
+          schema: { url: "http://localhost:4000/graphql" },
+          documents: "./src/graphql/**/*.graphql",
+          generates: ["query"],
+        },
+      ],
+    };
+    const result = configSchema.safeParse(config);
+    expect(result.success).toBe(false);
+  });
 });
 
 describe("defineConfig", () => {