polen 0.11.0-next.23 → 0.11.0-next.25

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 }),
+  ]
+}

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

@@ -2,117 +2,34 @@
  * Query path operations
  */
 
-import { createFieldSegment, createTypeSegment } from './constructors.js'
-import type { QueryPath, QuerySegment } from './types.js'
-
-/**
- * Builder class for creating query paths with a fluent interface
- *
- * @example
- * ```ts
- * const path = builder()
- *   .type('User')
- *   .field('posts')
- *   .type('Post')
- *   .field('author')
- *   .build()
- * ```
- */
-export class QueryPathBuilder {
-  private segments: QuerySegment[] = []
-
-  /**
-   * Add a type segment to the path
-   *
-   * @param typeName - The type name
-   * @returns The builder for chaining
-   */
-  type(typeName: string): this {
-    this.segments.push(createTypeSegment(typeName))
-    return this
-  }
-
-  /**
-   * Add a field segment to the path
-   *
-   * @param fieldName - The field name
-   * @returns The builder for chaining
-   */
-  field(fieldName: string): this {
-    this.segments.push(createFieldSegment(fieldName))
-    return this
-  }
-
-  /**
-   * Build the final query path
-   *
-   * @returns The constructed query path
-   */
-  build(): QueryPath {
-    return this.segments
-  }
-}
-
-/**
- * Create a new query path builder
- *
- * @returns A new query path builder instance
- * @example
- * ```ts
- * const path = builder()
- *   .type('User')
- *   .field('posts')
- *   .type('Post')
- *   .field('author')
- *   .build()
- * ```
- */
-export const builder = (): QueryPathBuilder => new QueryPathBuilder()
+import { S } from '#lib/kit-temp/effect'
+import { QueryPath } from './types.js'
 
 /**
  * Encode a query path to a human-readable expression string
+ * Uses the Effect Schema codec for QueryPath
  *
- * @param path - The query path to encode
+ * @param path - The query path segments to encode
  * @returns A string expression representation
  * @example
- * encode(builder().type('User').field('posts').type('Post').field('title').build()) // 'User.posts.Post.title'
+ * encode([
+ *   { _tag: 'TypeSegment', type: 'User' },
+ *   { _tag: 'FieldSegment', field: 'posts' },
+ *   { _tag: 'TypeSegment', type: 'Post' },
+ *   { _tag: 'FieldSegment', field: 'title' }
+ * ]) // 'User.posts.Post.title'
  */
-export const encode = (path: QueryPath): string => {
-  return path.map(segment => {
-    if (segment.kind === 'type') return segment.type
-    if (segment.kind === 'field') return segment.field
-    return ''
-  }).filter(Boolean).join('.')
-}
+export const encode = S.encodeSync(QueryPath)
 
 /**
  * Decode a string expression into a query path
+ * Uses the Effect Schema codec for QueryPath
  * Note: This assumes alternating type.field.type.field pattern
  *
  * @param expression - The string expression to decode
- * @returns The decoded query path or null if invalid
+ * @returns The decoded query path segments
+ * @throws ParseError if the expression is invalid
  * @example
  * decode('User.posts.Post.title') // Query path traversing User->posts->Post->title
  */
-export const decode = (expression: string): QueryPath | null => {
-  if (!expression) return null
-
-  const parts = expression.split('.')
-  const segments: QuerySegment[] = []
-
-  // Assume alternating pattern: type.field.type.field...
-  for (let i = 0; i < parts.length; i++) {
-    const part = parts[i]
-    if (!part) continue
-
-    if (i % 2 === 0) {
-      // Even indices are types
-      segments.push(createTypeSegment(part))
-    } else {
-      // Odd indices are fields
-      segments.push(createFieldSegment(part))
-    }
-  }
-
-  return segments
-}
+export const decode = S.decodeUnknownSync(QueryPath)

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

@@ -0,0 +1,136 @@
+/**
+ * GraphQL schema location utilities for definition paths
+ */
+
+import { Grafaid } from '#lib/grafaid'
+import { Data, Either, Match } from 'effect'
+import * as Definition from './definition.js'
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export class TypeNotFoundError extends Data.TaggedError('TypeNotFoundError')<{
+  typeName: string
+  path: string
+}> {}
+
+export class FieldNotFoundError extends Data.TaggedError('FieldNotFoundError')<{
+  typeName: string
+  fieldName: string
+  path: string
+}> {}
+
+// ============================================================================
+// Locate Functions
+// ============================================================================
+
+/**
+ * Locate a type in the GraphQL schema from a type definition path.
+ *
+ * @param schema - The GraphQL schema
+ * @param path - The type definition path
+ * @returns Either the located type or a TypeNotFoundError
+ */
+export const locateType = (
+  schema: Grafaid.Schema.Schema,
+  path: Definition.TypeDefinitionPath,
+): Either.Either<Grafaid.Schema.TypesLike.Named, TypeNotFoundError> => {
+  const typeName = Definition.getType(path)
+  const type = schema.getType(typeName)
+  if (!type) {
+    return Either.left(
+      new TypeNotFoundError({
+        typeName,
+        path: Definition.encodeSync(path),
+      }),
+    )
+  }
+  return Either.right(type)
+}
+
+/**
+ * Locate a field in the GraphQL schema from a field definition path.
+ *
+ * @param schema - The GraphQL schema
+ * @param path - The field definition path
+ * @returns Either the located field or a FieldNotFoundError
+ */
+export const locateField = (
+  schema: Grafaid.Schema.Schema,
+  path: Definition.FieldDefinitionPath,
+): Either.Either<Grafaid.Schema.NodesLike.Field, FieldNotFoundError> => {
+  const typeName = Definition.getType(path)
+  const fieldName = Definition.getField(path)
+
+  const type = schema.getType(typeName)
+  if (!type) {
+    return Either.left(
+      new FieldNotFoundError({
+        typeName,
+        fieldName,
+        path: Definition.encodeSync(path),
+      }),
+    )
+  }
+
+  if (!Grafaid.Schema.TypesLike.isFielded(type)) {
+    return Either.left(
+      new FieldNotFoundError({
+        typeName,
+        fieldName,
+        path: Definition.encodeSync(path),
+      }),
+    )
+  }
+
+  const fields = type.getFields()
+  const field = fields[fieldName]
+
+  if (!field) {
+    // dprint-ignore
+    return Either.left(new FieldNotFoundError({
+      typeName,
+      fieldName,
+      path: Definition.encodeSync(path),
+    }))
+  }
+
+  return Either.right(field)
+}
+
+/**
+ * Locate a type or field in the GraphQL schema from a definition path.
+ *
+ * @param schema - The GraphQL schema
+ * @param path - The definition path (type or field)
+ * @returns Either the located type/field or an error
+ */
+export const locate = (
+  schema: Grafaid.Schema.Schema,
+  path: Definition.DefinitionPath,
+): Either.Either<
+  Grafaid.Schema.TypesLike.Named | Grafaid.Schema.NodesLike.Field,
+  TypeNotFoundError | FieldNotFoundError
+> => {
+  return Match.value(path).pipe(
+    Match.when(
+      Definition.isTypeDefinitionPath,
+      (p) => locateType(schema, p),
+    ),
+    Match.when(
+      Definition.isFieldDefinitionPath,
+      (p) => locateField(schema, p),
+    ),
+    Match.orElse(() => {
+      // This should never happen with proper path types
+      // Return a generic error for unsupported path types
+      return Either.left(
+        new TypeNotFoundError({
+          typeName: 'unknown',
+          path: Definition.encodeSync(path),
+        }),
+      )
+    }),
+  )
+}