polen 0.11.0-next.24 → 0.11.0-next.26

package/src/lib/graphql-path/$.test.ts

@@ -0,0 +1,175 @@
+import { S } from '#lib/kit-temp/effect'
+import { describe, expect, test } from 'vitest'
+import { GraphQLPath } from './$.js'
+
+describe('decode', () => {
+  test.for([
+    ['User', [{ _tag: 'TypeSegment', type: 'User' }]],
+    ['User.name', [
+      { _tag: 'TypeSegment', type: 'User' },
+      { _tag: 'FieldSegment', field: 'name' },
+    ]],
+    ['User.posts(limit)', [
+      { _tag: 'TypeSegment', type: 'User' },
+      { _tag: 'FieldSegment', field: 'posts' },
+      { _tag: 'ArgumentSegment', argument: 'limit' },
+    ]],
+  ])('decodes "%s"', ([input, expected]) => {
+    expect(GraphQLPath.Definition.decodeSync(input)).toEqual(expected)
+  })
+
+  test.for([
+    '',
+    'Type.field.extra',
+    'Type(arg)',
+    '.field',
+    'Type.',
+  ])('throws on invalid format "%s"', (input) => {
+    expect(() => GraphQLPath.Definition.decodeSync(input)).toThrow()
+  })
+})
+
+describe('encode', () => {
+  test.for(
+    [
+      [GraphQLPath.Definition.type('User'), 'User'],
+      [GraphQLPath.Definition.field('User', 'name'), 'User.name'],
+      [GraphQLPath.Definition.argument('User', 'posts', 'limit'), 'User.posts(limit)'],
+    ] as const,
+  )('encodes path to "%s"', ([path, expected]) => {
+    expect(GraphQLPath.Definition.encodeSync(path as any)).toBe(expected)
+  })
+})
+
+describe('round-trip', () => {
+  test.for([
+    'Query',
+    'Mutation',
+    'User',
+    'User.id',
+    'User.name',
+    'Query.users',
+    'User.posts(limit)',
+    'Query.search(query)',
+    'Mutation.createUser(input)',
+  ])('round-trips "%s"', (pathString) => {
+    const decoded = GraphQLPath.Definition.decodeSync(pathString)
+    const encoded = GraphQLPath.Definition.encodeSync(decoded)
+    expect(encoded).toBe(pathString)
+  })
+})
+
+describe('type guards', () => {
+  const typePath = GraphQLPath.Definition.decodeSync('User')
+  const fieldPath = GraphQLPath.Definition.decodeSync('User.name')
+  const argPath = GraphQLPath.Definition.decodeSync('User.posts(limit)')
+
+  test('isTypeDefinitionPath', () => {
+    expect(GraphQLPath.Definition.isTypeDefinitionPath(typePath)).toBe(true)
+    expect(GraphQLPath.Definition.isTypeDefinitionPath(fieldPath)).toBe(false)
+    expect(GraphQLPath.Definition.isTypeDefinitionPath(argPath)).toBe(false)
+  })
+
+  test('isFieldDefinitionPath', () => {
+    expect(GraphQLPath.Definition.isFieldDefinitionPath(typePath)).toBe(false)
+    expect(GraphQLPath.Definition.isFieldDefinitionPath(fieldPath)).toBe(true)
+    expect(GraphQLPath.Definition.isFieldDefinitionPath(argPath)).toBe(false)
+  })
+
+  test('isArgumentDefinitionPath', () => {
+    expect(GraphQLPath.Definition.isArgumentDefinitionPath(typePath)).toBe(false)
+    expect(GraphQLPath.Definition.isArgumentDefinitionPath(fieldPath)).toBe(false)
+    expect(GraphQLPath.Definition.isArgumentDefinitionPath(argPath)).toBe(true)
+  })
+
+  test('Effect Schema derived segment type guards', async () => {
+    // Import from the types module directly since constructors re-exports them
+    const { isTypeSegment, isFieldSegment, isArgumentSegment } = await import('./types.js')
+
+    const typeSegment = { _tag: 'TypeSegment', type: 'User' } as const
+    const fieldSegment = { _tag: 'FieldSegment', field: 'name' } as const
+    const argSegment = { _tag: 'ArgumentSegment', argument: 'limit' } as const
+
+    // Test that Effect Schema derived guards work correctly
+    expect(isTypeSegment(typeSegment)).toBe(true)
+    expect(isTypeSegment(fieldSegment)).toBe(false)
+    expect(isFieldSegment(fieldSegment)).toBe(true)
+    expect(isFieldSegment(typeSegment)).toBe(false)
+    expect(isArgumentSegment(argSegment)).toBe(true)
+    expect(isArgumentSegment(typeSegment)).toBe(false)
+  })
+})
+
+describe('helper functions', () => {
+  test('getType extracts type from all path types', () => {
+    expect(GraphQLPath.Definition.getType(GraphQLPath.Definition.decodeSync('User'))).toBe('User')
+    expect(GraphQLPath.Definition.getType(GraphQLPath.Definition.decodeSync('User.name'))).toBe('User')
+    expect(GraphQLPath.Definition.getType(GraphQLPath.Definition.decodeSync('User.posts(limit)'))).toBe('User')
+  })
+
+  test('getField extracts field name', () => {
+    const fieldPath = GraphQLPath.Definition.decodeSync('User.name')
+    const argPath = GraphQLPath.Definition.decodeSync('User.posts(limit)')
+
+    if (GraphQLPath.Definition.isFieldDefinitionPath(fieldPath)) {
+      expect(GraphQLPath.Definition.getField(fieldPath)).toBe('name')
+    }
+    if (GraphQLPath.Definition.isArgumentDefinitionPath(argPath)) {
+      expect(GraphQLPath.Definition.getField(argPath)).toBe('posts')
+    }
+  })
+
+  test('getArgument extracts argument name', () => {
+    const argPath = GraphQLPath.Definition.decodeSync('User.posts(limit)')
+    if (GraphQLPath.Definition.isArgumentDefinitionPath(argPath)) {
+      expect(GraphQLPath.Definition.getArgument(argPath)).toBe('limit')
+    }
+  })
+})
+
+describe('constructors', () => {
+  test.for([
+    [GraphQLPath.Definition.type('User'), [{ _tag: 'TypeSegment', type: 'User' }]],
+    [GraphQLPath.Definition.field('User', 'name'), [
+      { _tag: 'TypeSegment', type: 'User' },
+      { _tag: 'FieldSegment', field: 'name' },
+    ]],
+    [GraphQLPath.Definition.argument('User', 'posts', 'limit'), [
+      { _tag: 'TypeSegment', type: 'User' },
+      { _tag: 'FieldSegment', field: 'posts' },
+      { _tag: 'ArgumentSegment', argument: 'limit' },
+    ]],
+  ])('constructor creates correct structure', ([result, expected]) => {
+    expect(result).toEqual(expected)
+  })
+})
+
+describe('Schema validation', () => {
+  test.for(
+    [
+      [GraphQLPath.Definition.TypeDefinitionPath, 'User', [{ _tag: 'TypeSegment', type: 'User' }]],
+      [GraphQLPath.Definition.FieldDefinitionPath, 'User.name', [
+        { _tag: 'TypeSegment', type: 'User' },
+        { _tag: 'FieldSegment', field: 'name' },
+      ]],
+      [GraphQLPath.Definition.ArgumentDefinitionPath, 'User.posts(limit)', [
+        { _tag: 'TypeSegment', type: 'User' },
+        { _tag: 'FieldSegment', field: 'posts' },
+        { _tag: 'ArgumentSegment', argument: 'limit' },
+      ]],
+    ] as const,
+  )('validates through Effect Schema', ([schema, input, expected]) => {
+    const result = S.decodeUnknownSync(schema as any)(input)
+    expect(result).toEqual(expected)
+  })
+
+  test('union automatically selects correct type', () => {
+    const typePath = S.decodeUnknownSync(GraphQLPath.Definition.DefinitionPath)('User')
+    const fieldPath = S.decodeUnknownSync(GraphQLPath.Definition.DefinitionPath)('User.name')
+    const argPath = S.decodeUnknownSync(GraphQLPath.Definition.DefinitionPath)('User.posts(limit)')
+
+    expect(typePath.length).toBe(1)
+    expect(fieldPath.length).toBe(2)
+    expect(argPath.length).toBe(3)
+  })
+})

package/src/lib/graphql-path/definition.ts

@@ -1,73 +1,153 @@
 /**
- * Definition path operations
- */
-
-import { createArgumentSegment, createFieldSegment, createTypeSegment } from './constructors.js'
-
-import type { ArgumentSegment, FieldSegment, TypeSegment } from '#lib/graphql-path/types'
-
-/**
- * Encode a definition path to a human-readable expression string
- *
- * @param path - The definition path to encode
- * @returns A string expression representation
- * @example
- * encode(field('User', 'name')) // 'User.name'
- * encode(argument('User', 'posts', 'limit')) // 'User.posts(limit)'
- */
-export const encode = (path: DefinitionPath): string => {
-  if (isTypeDefinitionPath(path)) {
-    return path[0].type
-  } else if (isFieldDefinitionPath(path)) {
-    return `${path[0].type}.${path[1].field}`
-  } else if (isArgumentDefinitionPath(path)) {
-    return `${path[0].type}.${path[1].field}(${path[2].argument})`
-  }
-  return ''
-}
+ * Definition path operations using Effect Schema transforms
+ */
+
+import { S } from '#lib/kit-temp/effect'
+import { ParseResult } from 'effect'
+import { ArgumentSegment, FieldSegment, TypeSegment } from './types.js'
+
+// ============================================================================
+// Internal Path Schemas (Decoded Forms)
+// ============================================================================
+
+const TypeDefinitionPathDecoded = S.Tuple(TypeSegment)
+const FieldDefinitionPathDecoded = S.Tuple(TypeSegment, FieldSegment)
+const ArgumentDefinitionPathDecoded = S.Tuple(TypeSegment, FieldSegment, ArgumentSegment)
+
+// ============================================================================
+// Transform Codecs (String <-> Struct)
+// ============================================================================
+
+/**
+ * Type definition path codec
+ * Encoded: "User"
+ * Decoded: [{ _tag: 'TypeSegment', type: 'User' }]
+ */
+export const TypeDefinitionPath = S.transformOrFail(
+  S.String,
+  TypeDefinitionPathDecoded,
+  {
+    decode: (str, _options, ast) => {
+      if (!str || str.includes('.') || str.includes('(')) {
+        return ParseResult.fail(new ParseResult.Type(ast, str))
+      }
+      return ParseResult.succeed([TypeSegment.make({ type: str })])
+    },
+    encode: (path) => ParseResult.succeed(path[0].type),
+  },
+).annotations({
+  identifier: 'TypeDefinitionPath',
+  description: 'Path to a type definition',
+})
+
+/**
+ * Field definition path codec
+ * Encoded: "User.name"
+ * Decoded: [{ _tag: 'TypeSegment', type: 'User' }, { _tag: 'FieldSegment', field: 'name' }]
+ */
+export const FieldDefinitionPath = S.transformOrFail(
+  S.String,
+  FieldDefinitionPathDecoded,
+  {
+    decode: (str, _options, ast) => {
+      const parts = str.split('.')
+      if (parts.length !== 2 || !parts[0] || !parts[1] || str.includes('(')) {
+        return ParseResult.fail(new ParseResult.Type(ast, str))
+      }
+      return ParseResult.succeed([
+        TypeSegment.make({ type: parts[0] }),
+        FieldSegment.make({ field: parts[1] }),
+      ])
+    },
+    encode: (path) => ParseResult.succeed(`${path[0].type}.${path[1].field}`),
+  },
+).annotations({
+  identifier: 'FieldDefinitionPath',
+  description: 'Path to a field definition',
+})
+
+/**
+ * Argument definition path codec
+ * Encoded: "User.posts(limit)"
+ * Decoded: [{ _tag: 'TypeSegment', type: 'User' }, { _tag: 'FieldSegment', field: 'posts' }, { _tag: 'ArgumentSegment', argument: 'limit' }]
+ */
+export const ArgumentDefinitionPath = S.transformOrFail(
+  S.String,
+  ArgumentDefinitionPathDecoded,
+  {
+    decode: (str, _options, ast) => {
+      const match = str.match(/^([^.]+)\.([^.(]+)\(([^)]+)\)$/)
+      if (!match || !match[1] || !match[2] || !match[3]) {
+        return ParseResult.fail(new ParseResult.Type(ast, str))
+      }
+      return ParseResult.succeed([
+        TypeSegment.make({ type: match[1] }),
+        FieldSegment.make({ field: match[2] }),
+        ArgumentSegment.make({ argument: match[3] }),
+      ])
+    },
+    encode: (path) => ParseResult.succeed(`${path[0].type}.${path[1].field}(${path[2].argument})`),
+  },
+).annotations({
+  identifier: 'ArgumentDefinitionPath',
+  description: 'Path to an argument definition',
+})
+
+/**
+ * Union of all definition paths
+ * Automatically determines the correct path type from the string format
+ */
+export const DefinitionPath = S.Union(
+  ArgumentDefinitionPath, // Check argument first (most specific)
+  FieldDefinitionPath, // Then field
+  TypeDefinitionPath, // Then type (least specific)
+).annotations({
+  identifier: 'DefinitionPath',
+  description: 'Union of all definition path types',
+})
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type TypeDefinitionPath = S.Schema.Type<typeof TypeDefinitionPath>
+export type FieldDefinitionPath = S.Schema.Type<typeof FieldDefinitionPath>
+export type ArgumentDefinitionPath = S.Schema.Type<typeof ArgumentDefinitionPath>
+export type DefinitionPath = S.Schema.Type<typeof DefinitionPath>
+
+// ============================================================================
+// Codec Functions
+// ============================================================================
 
 /**
  * Decode a string expression into a definition path
- *
  * @param expression - The string expression to decode
- * @returns The decoded definition path or null if invalid
+ * @returns The decoded definition path
  * @example
  * decode('User') // type definition path
  * decode('User.name') // field definition path
  * decode('User.posts(limit)') // argument definition path
  */
-export const decode = (expression: string): DefinitionPath | null => {
-  // Handle argument path: Type.field(argument)
-  const argMatch = expression.match(/^([^.]+)\.([^.(]+)\(([^)]+)\)$/)
-  if (argMatch) {
-    const [, typeName, fieldName, argName] = argMatch
-    if (!typeName || !fieldName || !argName) return null
-    return createArgumentDefinitionPath(typeName, fieldName, argName)
-  }
-
-  // Handle field path: Type.field
-  const fieldMatch = expression.match(/^([^.]+)\.([^.]+)$/)
-  if (fieldMatch) {
-    const [, typeName, fieldName] = fieldMatch
-    if (!typeName || !fieldName) return null
-    return createFieldDefinitionPath(typeName, fieldName)
-  }
-
-  // Handle type path: Type
-  const typeMatch = expression.match(/^[^.]+$/)
-  if (typeMatch) {
-    return createTypeDefinitionPath(expression)
-  }
-
-  return null
-}
+export const decodeSync = S.decodeUnknownSync(DefinitionPath)
+
+/**
+ * Encode a definition path to a string expression
+ * @param path - The definition path to encode
+ * @returns A string expression representation
+ * @example
+ * encode([{ _tag: 'TypeSegment', type: 'User' }]) // 'User'
+ * encode([{ _tag: 'TypeSegment', type: 'User' }, { _tag: 'FieldSegment', field: 'name' }]) // 'User.name'
+ */
+export const encodeSync = S.encodeSync(DefinitionPath)
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
 
 /**
  * Extract the type name from any definition path
- *
  * @param path - The definition path
  * @returns The type name
- * @example getType([{ kind: 'type', type: 'User' }]) // 'User'
  */
 export const getType = (path: DefinitionPath): string => {
   return path[0].type
@@ -75,10 +155,8 @@ export const getType = (path: DefinitionPath): string => {
 
 /**
  * Extract the field name from a field or argument definition path
- *
  * @param path - The field or argument definition path
  * @returns The field name
- * @example getField([{ kind: 'type', type: 'User' }, { kind: 'field', field: 'name' }]) // 'name'
  */
 export const getField = (path: FieldDefinitionPath | ArgumentDefinitionPath): string => {
   return path[1].field
@@ -86,155 +164,77 @@ export const getField = (path: FieldDefinitionPath | ArgumentDefinitionPath): st
 
 /**
  * Extract the argument name from an argument definition path
- *
  * @param path - The argument definition path
  * @returns The argument name
- * @example getArgument([{ kind: 'type', type: 'User' }, { kind: 'field', field: 'posts' }, { kind: 'argument', argument: 'limit' }]) // 'limit'
  */
 export const getArgument = (path: ArgumentDefinitionPath): string => {
   return path[2].argument
 }
 
-/**
- * Parse field path like "User.email" into type and field names
- */
-export const parseFieldPath = (path?: string): { typeName: string | null; fieldName: string | null } => {
-  if (!path) return { typeName: null, fieldName: null }
-
-  const parts = path.split('.')
-  if (parts.length >= 2) {
-    return {
-      typeName: parts[0] || null,
-      fieldName: parts[1] || null,
-    }
-  }
-
-  return { typeName: null, fieldName: null }
-}
-
-/**
- * Definition paths - direct paths to schema definition elements
- * These represent the "address" of a specific schema element
- */
-export type DefinitionPath =
-  | TypeDefinitionPath
-  | FieldDefinitionPath
-  | ArgumentDefinitionPath
-
-/**
- * Path to a type definition
- * @example [{ kind: 'type', type: 'User' }]
- */
-export type TypeDefinitionPath = [TypeSegment]
-
-/**
- * Path to a field definition (type + field)
- * @example [{ kind: 'type', type: 'User' }, { kind: 'field', field: 'name' }]
- */
-export type FieldDefinitionPath = [TypeSegment, FieldSegment]
-
-/**
- * Path to an argument definition (type + field + argument)
- * @example [{ kind: 'type', type: 'User' }, { kind: 'field', field: 'posts' }, { kind: 'argument', argument: 'limit' }]
- */
-export type ArgumentDefinitionPath = [TypeSegment, FieldSegment, ArgumentSegment]
+// ============================================================================
+// Type Guards
+// ============================================================================
 
 /**
  * Type guard to check if a path is a type definition path
- *
- * @param path - The path to check
- * @returns True if the path is a type definition path
  */
 export const isTypeDefinitionPath = (path: DefinitionPath): path is TypeDefinitionPath => {
-  return path.length === 1 && path[0].kind === 'type'
+  return path.length === 1 && path[0]._tag === 'TypeSegment'
 }
 
 /**
  * Type guard to check if a path is a field definition path
- *
- * @param path - The path to check
- * @returns True if the path is a field definition path
  */
 export const isFieldDefinitionPath = (path: DefinitionPath): path is FieldDefinitionPath => {
-  return path.length === 2 && path[0].kind === 'type' && path[1].kind === 'field'
+  return path.length === 2 && path[0]._tag === 'TypeSegment' && path[1]._tag === 'FieldSegment'
 }
 
 /**
  * Type guard to check if a path is an argument definition path
- *
- * @param path - The path to check
- * @returns True if the path is an argument definition path
  */
 export const isArgumentDefinitionPath = (path: DefinitionPath): path is ArgumentDefinitionPath => {
-  return path.length === 3 && path[0].kind === 'type' && path[1].kind === 'field' && path[2].kind === 'argument'
-}
-
-/**
- * Create a path to a type definition
- *
- * @param type - The type name
- * @returns A type definition path
- * @example createTypeDefinitionPath('User') // [{ kind: 'type', type: 'User' }]
- */
-export const createTypeDefinitionPath = (type: string): TypeDefinitionPath => {
-  return [createTypeSegment(type)]
-}
-
-/**
- * Create a path to a field definition
- *
- * @param type - The type name
- * @param field - The field name
- * @returns A field definition path
- * @example createFieldDefinitionPath('User', 'name') // [{ kind: 'type', type: 'User' }, { kind: 'field', field: 'name' }]
- */
-export const createFieldDefinitionPath = (type: string, field: string): FieldDefinitionPath => {
-  return [createTypeSegment(type), createFieldSegment(field)]
+  return (
+    path.length === 3
+    && path[0]._tag === 'TypeSegment'
+    && path[1]._tag === 'FieldSegment'
+    && path[2]._tag === 'ArgumentSegment'
+  )
 }
 
-/**
- * Create a path to an argument definition
- *
- * @param type - The type name
- * @param field - The field name
- * @param argument - The argument name
- * @returns An argument definition path
- * @example createArgumentDefinitionPath('User', 'posts', 'limit') // [{ kind: 'type', type: 'User' }, { kind: 'field', field: 'posts' }, { kind: 'argument', argument: 'limit' }]
- */
-export const createArgumentDefinitionPath = (
-  type: string,
-  field: string,
-  argument: string,
-): ArgumentDefinitionPath => {
-  return [createTypeSegment(type), createFieldSegment(field), createArgumentSegment(argument)]
-}
+// ============================================================================
+// Constructor Functions
+// ============================================================================
 
 /**
  * Create a type definition path
- *
  * @param type - The type name
  * @returns A type definition path
- * @example type('User') // [{ kind: 'type', type: 'User' }]
  */
-export const type = createTypeDefinitionPath
+export const type = (typeName: string): TypeDefinitionPath => {
+  return [TypeSegment.make({ type: typeName })]
+}
 
 /**
  * Create a field definition path
- *
  * @param type - The type name
  * @param field - The field name
  * @returns A field definition path
- * @example field('User', 'name') // [{ kind: 'type', type: 'User' }, { kind: 'field', field: 'name' }]
  */
-export const field = createFieldDefinitionPath
+export const field = (typeName: string, fieldName: string): FieldDefinitionPath => {
+  return [TypeSegment.make({ type: typeName }), FieldSegment.make({ field: fieldName })]
+}
 
 /**
  * Create an argument definition path
- *
  * @param type - The type name
  * @param field - The field name
  * @param argument - The argument name
  * @returns An argument definition path
- * @example argument('User', 'posts', 'limit') // [{ kind: 'type', type: 'User' }, { kind: 'field', field: 'posts' }, { kind: 'argument', argument: 'limit' }]
  */
-export const argument = createArgumentDefinitionPath
+export const argument = (typeName: string, fieldName: string, argumentName: string): ArgumentDefinitionPath => {
+  return [
+    TypeSegment.make({ type: typeName }),
+    FieldSegment.make({ field: fieldName }),
+    ArgumentSegment.make({ argument: argumentName }),
+  ]
+}