polen 0.11.0-next.12 → 0.11.0-next.14

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

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

@@ -0,0 +1,240 @@
+/**
+ * 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 ''
+}
+
+/**
+ * Decode a string expression into a definition path
+ *
+ * @param expression - The string expression to decode
+ * @returns The decoded definition path or null if invalid
+ * @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
+}
+
+/**
+ * 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
+}
+
+/**
+ * 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
+}
+
+/**
+ * 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 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'
+}
+
+/**
+ * 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'
+}
+
+/**
+ * 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)]
+}
+
+/**
+ * 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)]
+}
+
+/**
+ * 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
+
+/**
+ * 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
+
+/**
+ * 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

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

@@ -0,0 +1,118 @@
+/**
+ * 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()
+
+/**
+ * Encode a query path to a human-readable expression string
+ *
+ * @param path - The query path to encode
+ * @returns A string expression representation
+ * @example
+ * encode(builder().type('User').field('posts').type('Post').field('title').build()) // '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('.')
+}
+
+/**
+ * Decode a string expression into a query path
+ * 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
+ * @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
+}

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

@@ -0,0 +1,55 @@
+/**
+ * GraphQL Path type definitions
+ */
+
+/**
+ * Base segment representing a GraphQL type in a path
+ */
+export interface TypeSegment {
+  kind: 'type'
+  type: string
+}
+
+/**
+ * Base segment representing a field in a path
+ */
+export interface FieldSegment {
+  kind: 'field'
+  field: string
+}
+
+/**
+ * Base segment representing an argument in a path
+ */
+export interface ArgumentSegment {
+  kind: 'argument'
+  argument: string
+}
+
+/**
+ * Union of all possible segments
+ */
+export type Segment = TypeSegment | FieldSegment | ArgumentSegment
+
+/**
+ * Query segments - only types and fields can be traversed in queries
+ * Arguments cannot be part of query paths as they are not traversable
+ */
+export type QuerySegment = TypeSegment | FieldSegment
+
+/**
+ * Query/Data paths - potentially deep paths that span multiple types through fields
+ * These represent traversal paths through the schema graph
+ *
+ * @example
+ * User.posts.author.name would be:
+ * [
+ *   { kind: 'type', type: 'User' },
+ *   { kind: 'field', field: 'posts' },
+ *   { kind: 'type', type: 'Post' },
+ *   { kind: 'field', field: 'author' },
+ *   { kind: 'type', type: 'User' },
+ *   { kind: 'field', field: 'name' }
+ * ]
+ */
+export type QueryPath = QuerySegment[]

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

@@ -1,4 +1,4 @@
-import { Grafaid } from '#lib/grafaid/index'
+import { Grafaid } from '#lib/grafaid'
 import { Fs } from '@wollybeard/kit'
 import { neverCase } from '@wollybeard/kit/language'
 import { Graffle } from 'graffle'

package/src/lib/html-utils/$$.ts

@@ -0,0 +1,2 @@
+export * from './html-transformer.js'
+export * from './inject-global-data.js'

package/src/lib/html-utils/$.ts

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

package/src/lib/kit-temp.ts

@@ -656,3 +656,6 @@ export const spreadShallow = <T extends object>(...objects: (T | undefined)[]):
 
   return result
 }
+
+// Utility type for non-empty arrays
+export type NonEmptyArray<T> = [T, ...T[]]

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

@@ -1,3 +1,4 @@
+import { Path } from '@wollybeard/kit'
 import * as fc from 'fast-check'
 import { describe, expect, it } from 'vitest'
 import { PathMap } from './$.js'
@@ -208,9 +209,9 @@ describe('PathMap', () => {
     // Helper to build absolute paths with proper handling of root base
     const buildAbsolutePath = (normalizedBase: string, segments: string[]): string => {
       if (segments.length === 0) return normalizedBase
-      return normalizedBase === '/'
-        ? `/${segments.join('/')}`
-        : `${normalizedBase}/${segments.join('/')}`
+
+      // Use the same Path.join logic as the actual implementation
+      return Path.join(normalizedBase, ...segments)
     }
 
     // Arbitrary for valid path segments

package/src/lib/react-router-aid/$.ts

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

package/src/lib/react-router-loader/$.ts

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

package/src/lib/schema-lifecycle/$$.ts

@@ -0,0 +1,19 @@
+export * from './FieldLifecycle.js'
+export * from './LifecycleEvent.js'
+export * from './NamedTypeLifecycle.js'
+export * from './SchemaLifecycle.js'
+
+export {
+  getFieldAddedDate,
+  getFieldLifecycle,
+  getFieldLifecycleDescription,
+  getFieldRemovedDate,
+  getTypeAddedDate,
+  getTypeLifecycle,
+  getTypeLifecycleDescription,
+  getTypeRemovedDate,
+  getTypesAddedOnDate,
+  getTypesRemovedOnDate,
+  isFieldCurrentlyAvailable,
+  isTypeCurrentlyAvailable,
+} from './utils.js'