polen 0.11.0-next.12 → 0.11.0-next.13

package/src/cli/commands/cache/show.ts

@@ -0,0 +1,99 @@
+import { Api } from '#api/index'
+import { Command } from '@molt/command'
+import { z } from 'zod'
+
+const args = Command.create()
+  .parameter(
+    `--depth -d`,
+    z.number().min(0).max(5).default(2).describe(`Maximum depth for directory tree display`),
+  )
+  .settings({
+    parameters: {
+      environment: {
+        $default: {
+          prefix: `POLEN_CACHE_`,
+          enabled: false,
+        },
+      },
+    },
+  })
+  .parse()
+
+// Helper to format bytes
+const formatBytes = (bytes: number): string => {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
+}
+
+// Helper to render directory tree
+const renderTree = (nodes: Api.Cache.TreeNode[], prefix = ``, isLast = true): string[] => {
+  const lines: string[] = []
+
+  nodes.forEach((node, index) => {
+    const isLastNode = index === nodes.length - 1
+    const connector = isLastNode ? `└─` : `├─`
+    const extension = isLastNode ? `  ` : `│ `
+
+    let line = `${prefix}${connector} ${node.name}`
+    if (node.type === `file` && node.size !== undefined) {
+      line += ` (${formatBytes(node.size)})`
+    }
+    lines.push(line)
+
+    if (node.children && node.children.length > 0) {
+      const childLines = renderTree(node.children, prefix + extension, isLastNode)
+      lines.push(...childLines)
+    }
+  })
+
+  return lines
+}
+
+// Get cache info
+const info = await Api.Cache.info({ depth: args.depth })
+
+console.log(`Root: ${info.rootPath}`)
+console.log()
+
+// Development assets
+console.log(`Development assets: ${info.developmentAssets.path.replace(info.rootPath + `/`, ``)}`)
+if (info.developmentAssets.exists) {
+  const size = info.developmentAssets.size ? ` (${formatBytes(info.developmentAssets.size)})` : ``
+  console.log(`  Status: exists${size}`)
+
+  if (info.developmentAssets.tree && info.developmentAssets.tree.length > 0) {
+    console.log(`  Contents:`)
+    const treeLines = renderTree(info.developmentAssets.tree, `    `)
+    treeLines.forEach(line => console.log(line))
+  }
+} else {
+  console.log(`  Status: empty`)
+}
+
+console.log()
+
+// Vite cache
+console.log(`Vite:`)
+if (info.vite.exists) {
+  const size = info.vite.size ? ` (${formatBytes(info.vite.size)})` : ``
+  console.log(`  Status: exists${size}`)
+
+  if (info.vite.optimizedDependencies && info.vite.optimizedDependencies.length > 0) {
+    const deps = info.vite.optimizedDependencies
+    const showing = Math.min(10, deps.length)
+    const more = deps.length - showing
+
+    console.log(`  Optimized dependencies (${deps.length}):`)
+    deps.slice(0, showing).forEach(dep => {
+      console.log(`    ${dep.name} (${formatBytes(dep.size)})`)
+    })
+
+    if (more > 0) {
+      console.log(`    ... (${more} more)`)
+    }
+  }
+} else {
+  console.log(`  Status: empty`)
+}

package/src/cli/commands/cache.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { Cli, Path } from '@wollybeard/kit'
+
+// Remove the "cache" argument before dispatching to subcommands
+process.argv = process.argv.slice(0, 2).concat(process.argv.slice(3))
+
+const commandsDir = Path.join(import.meta.dirname, `cache`)
+await Cli.dispatch(commandsDir)

package/src/cli/commands/config.ts

@@ -2,5 +2,8 @@
 
 import { Cli, Path } from '@wollybeard/kit'
 
+// Remove the "config" argument before dispatching to subcommands
+process.argv = process.argv.slice(0, 2).concat(process.argv.slice(3))
+
 const commandsDir = Path.join(import.meta.dirname, `config`)
 await Cli.dispatch(commandsDir)

package/src/cli/commands/open.ts

@@ -9,8 +9,8 @@
 
 import { Api } from '#api/index'
 import { Vite } from '#dep/vite/index'
-import { Grafaid } from '#lib/grafaid/index'
-import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader/index'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader'
 import { Command } from '@molt/command'
 import type { Fn } from '@wollybeard/kit'
 import { Err, Fs, Json, Path, Rec } from '@wollybeard/kit'

package/src/cli/commands/static.ts

@@ -2,5 +2,8 @@
 
 import { Cli, Path } from '@wollybeard/kit'
 
+// Remove the "static" argument before dispatching to subcommands
+process.argv = process.argv.slice(0, 2).concat(process.argv.slice(3))
+
 const commandsDir = Path.join(import.meta.dirname, `static`)
 await Cli.dispatch(commandsDir)

package/src/lib/errors/$.ts

@@ -0,0 +1 @@
+export * as Errors from './$$.js'

package/src/lib/file-router/$.ts

@@ -0,0 +1 @@
+export * as FileRouter from './$$.js'

package/src/lib/file-router/index.test.ts

@@ -1,7 +1,7 @@
 import { Fn } from '@wollybeard/kit'
 import { describe, expect } from 'vitest'
 import { test } from '../../../tests/unit/helpers/test.js'
-import { FileRouter } from './index.js'
+import { FileRouter } from './$.js'
 
 /* Note
 

package/src/lib/grafaid/$.ts

@@ -0,0 +1 @@
+export * as Grafaid from './$$.js'

package/src/lib/grafaid/schema/type.ts

@@ -3,6 +3,7 @@ import {
   type GraphQLInputObjectType,
   type GraphQLInterfaceType,
   type GraphQLList,
+  type GraphQLNamedType,
   type GraphQLNonNull,
   type GraphQLObjectType,
   type GraphQLScalarType,

package/src/lib/graphql-change/{graphql-change.ts → $$.ts}

@@ -1,5 +1,5 @@
 import { GraphqlInspector } from '#dep/graphql-inspector/index'
-import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { GrafaidOld } from '#lib/grafaid-old'
 import type { Change } from './change-types.js'
 
 export * from './change-types.js'

package/src/lib/graphql-change/$.ts

@@ -0,0 +1 @@
+export * as GraphqlChange from './$$.js'

package/src/lib/graphql-change/change-groups.ts

@@ -277,31 +277,61 @@ export type Type =
   | 'SchemaRootType'
   | 'DirectiveUsage'
 
-export const getType = (change: Change): Type => {
-  if (isTypeOperation(change)) return 'TypeOperation'
-  if (isTypeDescription(change)) return 'TypeDescription'
-  if (isFieldOperation(change)) return 'FieldOperation'
-  if (isFieldDescription(change)) return 'FieldDescription'
-  if (isFieldDeprecation(change)) return 'FieldDeprecation'
-  if (isFieldDeprecationReason(change)) return 'FieldDeprecationReason'
-  if (isFieldArgumentOperation(change)) return 'FieldArgumentOperation'
-  if (isFieldArgument(change)) return 'FieldArgument'
-  if (isFieldArgumentDescription(change)) return 'FieldArgumentDescription'
-  if (isEnumValueOperation(change)) return 'EnumValueOperation'
-  if (isEnumValueDescription(change)) return 'EnumValueDescription'
-  if (isEnumValueDeprecationReason(change)) return 'EnumValueDeprecationReason'
-  if (isInputFieldOperation(change)) return 'InputFieldOperation'
-  if (isInputFieldDescription(change)) return 'InputFieldDescription'
-  if (isInputFieldDefaultValue(change)) return 'InputFieldDefaultValue'
-  if (isUnionMemberOperation(change)) return 'UnionMemberOperation'
-  if (isObjectTypeInterfaceOperation(change)) return 'ObjectTypeInterfaceOperation'
-  if (isDirectiveOperation(change)) return 'DirectiveOperation'
-  if (isDirectiveDescription(change)) return 'DirectiveDescription'
-  if (isDirectiveLocationOperation(change)) return 'DirectiveLocationOperation'
-  if (isDirectiveArgumentOperation(change)) return 'DirectiveArgumentOperation'
-  if (isDirectiveArgument(change)) return 'DirectiveArgument'
-  if (isDirectiveArgumentDescription(change)) return 'DirectiveArgumentDescription'
-  if (isSchemaRootType(change)) return 'SchemaRootType'
-  if (isDirectiveUsage(change)) return 'DirectiveUsage'
+/**
+ * Conditional type that maps each change type to its corresponding group type
+ */
+export type getType<$Change extends Change> = $Change extends TypeOperation ? 'TypeOperation'
+  : $Change extends TypeDescription ? 'TypeDescription'
+  : $Change extends FieldOperation ? 'FieldOperation'
+  : $Change extends FieldDescription ? 'FieldDescription'
+  : $Change extends FieldDeprecation ? 'FieldDeprecation'
+  : $Change extends FieldDeprecationReason ? 'FieldDeprecationReason'
+  : $Change extends FieldArgumentOperation ? 'FieldArgumentOperation'
+  : $Change extends FieldArgument ? 'FieldArgument'
+  : $Change extends FieldArgumentDescription ? 'FieldArgumentDescription'
+  : $Change extends EnumValueOperation ? 'EnumValueOperation'
+  : $Change extends EnumValueDescription ? 'EnumValueDescription'
+  : $Change extends EnumValueDeprecationReason ? 'EnumValueDeprecationReason'
+  : $Change extends InputFieldOperation ? 'InputFieldOperation'
+  : $Change extends InputFieldDescription ? 'InputFieldDescription'
+  : $Change extends InputFieldDefaultValue ? 'InputFieldDefaultValue'
+  : $Change extends UnionMemberOperation ? 'UnionMemberOperation'
+  : $Change extends ObjectTypeInterfaceOperation ? 'ObjectTypeInterfaceOperation'
+  : $Change extends DirectiveOperation ? 'DirectiveOperation'
+  : $Change extends DirectiveDescription ? 'DirectiveDescription'
+  : $Change extends DirectiveLocationOperation ? 'DirectiveLocationOperation'
+  : $Change extends DirectiveArgumentOperation ? 'DirectiveArgumentOperation'
+  : $Change extends DirectiveArgument ? 'DirectiveArgument'
+  : $Change extends DirectiveArgumentDescription ? 'DirectiveArgumentDescription'
+  : $Change extends SchemaRootType ? 'SchemaRootType'
+  : $Change extends DirectiveUsage ? 'DirectiveUsage'
+  : never
+
+export const getType = <change extends Change>(change: change): getType<change> => {
+  if (isTypeOperation(change)) return 'TypeOperation' as getType<change>
+  if (isTypeDescription(change)) return 'TypeDescription' as getType<change>
+  if (isFieldOperation(change)) return 'FieldOperation' as getType<change>
+  if (isFieldDescription(change)) return 'FieldDescription' as getType<change>
+  if (isFieldDeprecation(change)) return 'FieldDeprecation' as getType<change>
+  if (isFieldDeprecationReason(change)) return 'FieldDeprecationReason' as getType<change>
+  if (isFieldArgumentOperation(change)) return 'FieldArgumentOperation' as getType<change>
+  if (isFieldArgument(change)) return 'FieldArgument' as getType<change>
+  if (isFieldArgumentDescription(change)) return 'FieldArgumentDescription' as getType<change>
+  if (isEnumValueOperation(change)) return 'EnumValueOperation' as getType<change>
+  if (isEnumValueDescription(change)) return 'EnumValueDescription' as getType<change>
+  if (isEnumValueDeprecationReason(change)) return 'EnumValueDeprecationReason' as getType<change>
+  if (isInputFieldOperation(change)) return 'InputFieldOperation' as getType<change>
+  if (isInputFieldDescription(change)) return 'InputFieldDescription' as getType<change>
+  if (isInputFieldDefaultValue(change)) return 'InputFieldDefaultValue' as getType<change>
+  if (isUnionMemberOperation(change)) return 'UnionMemberOperation' as getType<change>
+  if (isObjectTypeInterfaceOperation(change)) return 'ObjectTypeInterfaceOperation' as getType<change>
+  if (isDirectiveOperation(change)) return 'DirectiveOperation' as getType<change>
+  if (isDirectiveDescription(change)) return 'DirectiveDescription' as getType<change>
+  if (isDirectiveLocationOperation(change)) return 'DirectiveLocationOperation' as getType<change>
+  if (isDirectiveArgumentOperation(change)) return 'DirectiveArgumentOperation' as getType<change>
+  if (isDirectiveArgument(change)) return 'DirectiveArgument' as getType<change>
+  if (isDirectiveArgumentDescription(change)) return 'DirectiveArgumentDescription' as getType<change>
+  if (isSchemaRootType(change)) return 'SchemaRootType' as getType<change>
+  if (isDirectiveUsage(change)) return 'DirectiveUsage' as getType<change>
   neverCase(change)
 }

package/src/lib/graphql-changeset/$$.ts

@@ -0,0 +1,3 @@
+export * from './changelog.js'
+export * from './changeset.js'
+export * from './versioned-schema.js'

package/src/lib/graphql-changeset/$.ts

@@ -0,0 +1 @@
+export * as GraphqlChangeset from './$$.js'

package/src/lib/graphql-changeset/changelog.ts

@@ -0,0 +1,9 @@
+import type { ChangeSet, ChangeSetLinked } from './changeset.js'
+
+// Changelog
+
+export type Changelog = [ChangeSet, ...ChangeSet[]]
+
+// Linked
+
+export type ChangelogLinked = [ChangeSetLinked, ...ChangeSetLinked[]]

package/src/lib/graphql-changeset/changeset.ts

@@ -0,0 +1,190 @@
+import type { GrafaidOld } from '#lib/grafaid-old'
+import type { GraphqlChange } from '#lib/graphql-change'
+import type { GraphQLSchema } from 'graphql'
+import { SuperJSON } from 'superjson'
+import type { VersionableSchema, VersionableSchemaLinked } from './versioned-schema.js'
+
+const superjson = new SuperJSON()
+
+superjson.registerCustom({
+  isApplicable: (v): v is GraphQLSchema => v?.constructor?.name === 'GraphQLSchema',
+  serialize: () => null,
+  deserialize: () => null,
+}, 'GraphQLSchema')
+
+// ChangeSet
+
+export type ChangeSet = IntermediateChangeSet | InitialChangeSet
+
+export interface IntermediateChangeSet {
+  type: 'IntermediateChangeSet'
+  changes: GraphqlChange.Change[]
+  date: Date
+  after: VersionableSchema
+  before: VersionableSchema
+}
+
+export interface InitialChangeSet {
+  type: 'InitialChangeSet'
+  date: Date
+  after: VersionableSchema
+}
+
+// Linked
+
+export type ChangeSetLinked = InitialChangeSetLinked | IntermediateChangeSetLinked
+
+export interface IntermediateChangeSetLinked extends IntermediateChangeSet {
+  after: VersionableSchemaLinked
+  before: VersionableSchemaLinked
+}
+
+export interface InitialChangeSetLinked extends InitialChangeSet {
+  after: VersionableSchemaLinked
+}
+
+// Predicate Functions
+
+/**
+ * Type guard to check if a value is any type of ChangeSet
+ */
+export const isChangeSet = (value: unknown): value is ChangeSet => {
+  return value !== null
+    && typeof value === 'object'
+    && 'type' in value
+    && ((value as any).type === 'InitialChangeSet' || (value as any).type === 'IntermediateChangeSet')
+}
+
+/**
+ * Type guard to check if a changeset is an InitialChangeSet
+ */
+export const isInitialChangeSet = (changeSet: ChangeSet): changeSet is InitialChangeSet => {
+  return changeSet.type === 'InitialChangeSet'
+}
+
+/**
+ * Type guard to check if a changeset is an IntermediateChangeSet
+ */
+export const isIntermediateChangeSet = (changeSet: ChangeSet): changeSet is IntermediateChangeSet => {
+  return changeSet.type === 'IntermediateChangeSet'
+}
+
+/**
+ * Type guard to check if a linked changeset is an InitialChangeSetLinked
+ */
+export const isInitialChangeSetLinked = (changeSet: ChangeSetLinked): changeSet is InitialChangeSetLinked => {
+  return changeSet.type === 'InitialChangeSet'
+}
+
+/**
+ * Type guard to check if a linked changeset is an IntermediateChangeSetLinked
+ */
+export const isIntermediateChangeSetLinked = (changeSet: ChangeSetLinked): changeSet is IntermediateChangeSetLinked => {
+  return changeSet.type === 'IntermediateChangeSet'
+}
+
+/**
+ * Type guard to check if a changeset is linked (has schema data)
+ */
+export const isLinked = (changeSet: ChangeSet | ChangeSetLinked): changeSet is ChangeSetLinked => {
+  if (isInitialChangeSet(changeSet)) {
+    return changeSet.after.data !== null
+  } else {
+    return changeSet.after.data !== null && changeSet.before.data !== null
+  }
+}
+
+// JSON Codecs
+
+/**
+ * Convert an unlinked changeset to linked by adding schema references
+ */
+export const link = (
+  changeset: ChangeSet,
+  schemaResolver: (version: string | null) => GrafaidOld.Schema.Schema | null,
+): ChangeSetLinked => {
+  if (isInitialChangeSet(changeset)) {
+    const afterSchema = schemaResolver(changeset.after.version)
+    if (!afterSchema) {
+      throw new Error(`Unable to resolve schema for version: ${changeset.after.version}`)
+    }
+    return {
+      type: 'InitialChangeSet',
+      date: changeset.date,
+      after: {
+        version: changeset.after.version,
+        data: afterSchema,
+      },
+    }
+  } else {
+    const afterSchema = schemaResolver(changeset.after.version)
+    const beforeSchema = schemaResolver(changeset.before.version)
+    if (!afterSchema || !beforeSchema) {
+      throw new Error(
+        `Unable to resolve schemas for versions: after=${changeset.after.version}, before=${changeset.before.version}`,
+      )
+    }
+    return {
+      type: 'IntermediateChangeSet',
+      changes: changeset.changes,
+      date: changeset.date,
+      after: {
+        version: changeset.after.version,
+        data: afterSchema,
+      },
+      before: {
+        version: changeset.before.version,
+        data: beforeSchema,
+      },
+    }
+  }
+}
+
+/**
+ * Convert a linked changeset to unlinked by removing schema references
+ */
+// export const unlink = (changeset: ChangeSetLinked): ChangeSet => {
+//   if (isInitialChangeSetLinked(changeset)) {
+//     return {
+//       type: 'InitialChangeSet',
+//       date: changeset.date,
+//       after: {
+//         version: changeset.after.version,
+//         data: null,
+//       },
+//     }
+//   } else {
+//     return {
+//       type: 'IntermediateChangeSet',
+//       changes: changeset.changes,
+//       date: changeset.date,
+//       after: {
+//         version: changeset.after.version,
+//         data: null,
+//       },
+//       before: {
+//         version: changeset.before.version,
+//         data: null,
+//       },
+//     }
+//   }
+// }
+
+/**
+ * Convert a changeset to JSON string (handles both linked and unlinked)
+ */
+export const toJson = (changeset: ChangeSet, options?: { pretty?: boolean }): string => {
+  const isPretty = options?.pretty ?? true
+  if (isPretty) {
+    const serialized = superjson.serialize(changeset)
+    return JSON.stringify(serialized, null, 2)
+  }
+  return superjson.stringify(changeset)
+}
+
+/**
+ * Parse changeset from JSON string
+ */
+export const fromJson = (json: string): ChangeSet => {
+  return superjson.parse(json)
+}

package/src/lib/graphql-changeset/versioned-schema.ts

@@ -0,0 +1,43 @@
+import type { GrafaidOld } from '#lib/grafaid-old'
+
+// VersionableSchema
+
+export interface VersionableSchema {
+  /**
+   * `null` if schema is not versioned.
+   */
+  version: string | null
+  /**
+   * `null` if schema has not been hydrated.
+   * Something external is resonsible for linking this.
+   * It should use `version` if not null to get the correct schema somehow.
+   * If `version` is null, it should use some schema singleton.
+   */
+  data: GrafaidOld.Schema.Schema | null
+}
+
+export interface VersionableSchemaUnlinked {
+  version: string | null
+  data: null
+}
+
+export interface VersionableSchemaLinked {
+  version: string | null
+  data: GrafaidOld.Schema.Schema
+}
+
+// Predicate Functions
+
+/**
+ * Type guard to check if a schema is linked (has data)
+ */
+export const isVersionableSchemaLinked = (schema: VersionableSchema): schema is VersionableSchemaLinked => {
+  return schema.data !== null
+}
+
+/**
+ * Type guard to check if a schema is unlinked (no data)
+ */
+export const isVersionableSchemaUnlinked = (schema: VersionableSchema): schema is VersionableSchemaUnlinked => {
+  return schema.data === null
+}

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

@@ -0,0 +1,42 @@
+/**
+ * GraphQL Path Library
+ *
+ * This library provides type-safe path representations for GraphQL schemas.
+ * It distinguishes between definition paths (addresses to schema elements)
+ * and query paths (traversal paths through the schema graph).
+ *
+ * @example
+ * ```ts
+ * import { GraphQLPath } from '#lib/graphql-path'
+ *
+ * // Create a path to a type definition
+ * const userTypePath = GraphQLPath.Definition.type('User')
+ *
+ * // Create a path to a field definition
+ * const userNameFieldPath = GraphQLPath.Definition.field('User', 'name')
+ *
+ * // Create a path to an argument definition
+ * const userPostsLimitArgPath = GraphQLPath.Definition.argument('User', 'posts', 'limit')
+ *
+ * // Encode/decode definition paths
+ * const encoded = GraphQLPath.Definition.encode(userNameFieldPath) // "User.name"
+ * const decoded = GraphQLPath.Definition.decode("User.name") // field definition path
+ *
+ * // Create a query path
+ * const queryPath = GraphQLPath.Query.builder()
+ *   .type('User')
+ *   .field('posts')
+ *   .type('Post')
+ *   .field('author')
+ *   .type('User')
+ *   .field('name')
+ *   .build()
+ *
+ * // Encode/decode query paths
+ * const encodedQuery = GraphQLPath.Query.encode(queryPath) // "User.posts.Post.author.User.name"
+ * const decodedQuery = GraphQLPath.Query.decode("User.posts.Post.author") // query path
+ * ```
+ */
+
+export * as Definition from './definition.js'
+export * as Query from './query.js'

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

@@ -0,0 +1,4 @@
+/**
+ * Namespace export for graphql-path library
+ */
+export * as GraphQLPath from './$$.js'

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

@@ -0,0 +1,81 @@
+/**
+ * Constructor functions and type guards
+ */
+
+import type { ArgumentSegment, FieldSegment, QuerySegment, Segment, TypeSegment } from './types.js'
+
+/**
+ * Type guard to check if a segment is a type segment
+ *
+ * @param segment - The segment to check
+ * @returns True if the segment is a type segment
+ */
+export const isTypeSegment = (segment: Segment): segment is TypeSegment => {
+  return segment.kind === 'type'
+}
+
+/**
+ * Type guard to check if a segment is a field segment
+ *
+ * @param segment - The segment to check
+ * @returns True if the segment is a field segment
+ */
+export const isFieldSegment = (segment: Segment): segment is FieldSegment => {
+  return segment.kind === 'field'
+}
+
+/**
+ * Type guard to check if a segment is an argument segment
+ *
+ * @param segment - The segment to check
+ * @returns True if the segment is an argument segment
+ */
+export const isArgumentSegment = (segment: Segment): segment is ArgumentSegment => {
+  return segment.kind === 'argument'
+}
+
+/**
+ * Type guard to check if a segment can be used in a query path
+ *
+ * @param segment - The segment to check
+ * @returns True if the segment can be used in a query path
+ */
+export const isQuerySegment = (segment: Segment): segment is QuerySegment => {
+  return segment.kind === 'type' || segment.kind === 'field'
+}
+
+/**
+ * Create a type segment
+ *
+ * @param type - The type name
+ * @returns A type segment
+ * @example createTypeSegment('User') // { kind: 'type', type: 'User' }
+ */
+export const createTypeSegment = (type: string): TypeSegment => ({
+  kind: 'type',
+  type,
+})
+
+/**
+ * Create a field segment
+ *
+ * @param field - The field name
+ * @returns A field segment
+ * @example createFieldSegment('name') // { kind: 'field', field: 'name' }
+ */
+export const createFieldSegment = (field: string): FieldSegment => ({
+  kind: 'field',
+  field,
+})
+
+/**
+ * Create an argument segment
+ *
+ * @param argument - The argument name
+ * @returns An argument segment
+ * @example createArgumentSegment('limit') // { kind: 'argument', argument: 'limit' }
+ */
+export const createArgumentSegment = (argument: string): ArgumentSegment => ({
+  kind: 'argument',
+  argument,
+})