polen 0.11.0-next.17 → 0.11.0-next.18

package/src/lib/catalog/catalog.ts

@@ -1,13 +1,33 @@
 import { S } from '#lib/kit-temp/effect'
 import { Schema } from '#lib/schema/$'
+import { VersionCoverage } from '#lib/version-coverage'
 import { Version } from '#lib/version/$'
-import { HashMap, Match } from 'effect'
+import { Data, Either, HashMap, Match, Option } from 'effect'
 import * as Unversioned from './unversioned.js'
 import * as Versioned from './versioned.js'
 
 export * as Unversioned from './unversioned.js'
 export * as Versioned from './versioned.js'
 
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * Error thrown when a version is not found in the catalog
+ */
+export class VersionNotFoundInCatalogError extends Data.TaggedError('VersionNotFoundInCatalogError')<{
+  readonly version: string
+  readonly reason: string
+}> {}
+
+/**
+ * Error thrown when a catalog has no entries
+ */
+export class EmptyCatalogError extends Data.TaggedError('EmptyCatalogError')<{
+  readonly reason: string
+}> {}
+
 // ============================================================================
 // Schema
 // ============================================================================
@@ -87,14 +107,77 @@ export const getLatest = (catalog: Catalog): Schema.Schema =>
 
 /**
  * Get the latest version identifier from a catalog.
- * Returns the version for versioned catalogs, or null for unversioned catalogs.
+ * Returns the version for versioned catalogs, or none for unversioned catalogs.
  */
-export const getLatestVersion = (catalog?: Catalog): Version.Version | null => {
-  if (!catalog) return null
+export const getLatestVersion = (catalog?: Catalog): Option.Option<Version.Version> => {
+  if (!catalog) return Option.none()
   return Match.value(catalog).pipe(
     Match.tagsExhaustive({
-      CatalogUnversioned: () => null,
-      CatalogVersioned: (cat) => Versioned.getVersions(cat)[0] ?? null,
+      CatalogUnversioned: () => Option.none(),
+      CatalogVersioned: (cat) => {
+        const versions = Versioned.getVersions(cat)
+        return versions[0] ? Option.some(versions[0]) : Option.none()
+      },
     }),
   )
 }
+
+// ============================================================================
+// Resolution Functions
+// ============================================================================
+
+/**
+ * Resolve schema from catalog for a given version coverage.
+ *
+ * @param catalog - The schema catalog
+ * @param versionCoverage - The version coverage to use (optional, defaults to latest)
+ * @returns Either with the resolved schema or error
+ */
+export const resolveCatalogSchemaEither = (
+  catalog: Catalog,
+  versionCoverage?: VersionCoverage.VersionCoverage | null,
+): Either.Either<Schema.Schema, VersionNotFoundInCatalogError | EmptyCatalogError> => {
+  if (Unversioned.is(catalog)) {
+    return Either.right(catalog.schema)
+  }
+
+  // If no version coverage specified, use latest
+  if (!versionCoverage) {
+    return Versioned.getLatest(catalog)
+  }
+
+  // Get the latest version from the coverage
+  const version = VersionCoverage.getLatest(versionCoverage)
+
+  const schemaOption = HashMap.get(catalog.entries, version)
+  if (Option.isNone(schemaOption)) {
+    return Either.left(
+      new VersionNotFoundInCatalogError({
+        version: Version.encodeSync(version),
+        reason: `Version ${Version.encodeSync(version)} not found in catalog`,
+      }),
+    )
+  }
+
+  return Either.right(Option.getOrThrow(schemaOption))
+}
+
+/**
+ * Resolve schema from catalog for a given version coverage.
+ *
+ * @param catalog - The schema catalog
+ * @param versionCoverage - The version coverage to use (optional, defaults to latest)
+ * @returns The resolved schema
+ * @throws {Error} If catalog is versioned but version is not found
+ * @deprecated Use resolveCatalogSchemaEither which returns Either
+ */
+export const resolveCatalogSchema = (
+  catalog: Catalog,
+  versionCoverage?: VersionCoverage.VersionCoverage | null,
+): Schema.Schema => {
+  const result = resolveCatalogSchemaEither(catalog, versionCoverage)
+  if (Either.isLeft(result)) {
+    throw new Error(result.left.reason)
+  }
+  return result.right
+}

package/src/lib/catalog/versioned.ts

@@ -1,7 +1,8 @@
 import { S } from '#lib/kit-temp/effect'
-import { Array, HashMap, Iterable, Order, pipe } from 'effect'
+import { Array, Either, HashMap, Iterable, Order, pipe } from 'effect'
 import { Schema } from '../schema/$.js'
 import { Version } from '../version/$.js'
+import { EmptyCatalogError } from './catalog.js'
 
 // ============================================================================
 // Schema
@@ -50,6 +51,25 @@ export const equivalence = S.equivalence(Versioned)
 // Domain Logic
 // ============================================================================
 
+/**
+ * Get the latest schema from a versioned catalog.
+ * The latest version is determined by Version.max comparison.
+ *
+ * @param catalog - The versioned catalog
+ * @returns Either with the latest schema or EmptyCatalogError
+ */
+export const getLatest = (catalog: Versioned): Either.Either<Schema.Versioned.Versioned, EmptyCatalogError> => {
+  const schema = getAll(catalog)[0]
+  if (!schema) {
+    return Either.left(
+      new EmptyCatalogError({
+        reason: 'Versioned catalog has no entries - cannot get latest schema',
+      }),
+    )
+  }
+  return Either.right(schema)
+}
+
 /**
  * Get the latest schema definition from a versioned catalog.
  * The latest version is determined by Version.max comparison.
@@ -57,13 +77,14 @@ export const equivalence = S.equivalence(Versioned)
  * @param catalog - The versioned catalog
  * @returns The GraphQL schema definition of the latest version
  * @throws {Error} If the catalog has no entries
+ * @deprecated Use getLatest which returns Either
  */
 export const getLatestOrThrow = (catalog: Versioned): Schema.Versioned.Versioned => {
-  const schema = getAll(catalog)[0]
-  if (!schema) {
-    throw new Error('Versioned catalog has no entries - cannot get latest schema')
+  const result = getLatest(catalog)
+  if (Either.isLeft(result)) {
+    throw new Error(result.left.reason)
   }
-  return schema
+  return result.right
 }
 
 /**

package/src/lib/document/document.ts

@@ -1,6 +1,30 @@
+import { Catalog } from '#lib/catalog/$'
 import { S } from '#lib/kit-temp/effect'
+import { Schema } from '#lib/schema/$'
+import { VersionCoverage } from '#lib/version-coverage'
+import { Version } from '#lib/version/$'
+import { Data, Either, Option } from 'effect'
 import { DocumentUnversioned } from './unversioned.js'
-import { DocumentVersioned } from './versioned.js'
+import * as DocumentVersioned from './versioned.js'
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * Error thrown when trying to use version coverage with an unversioned catalog
+ */
+export class VersionCoverageMismatchError extends Data.TaggedError('VersionCoverageMismatchError')<{
+  readonly reason: string
+}> {}
+
+/**
+ * Error thrown when a version is not found in the document
+ */
+export class VersionNotFoundInDocumentError extends Data.TaggedError('VersionNotFoundInDocumentError')<{
+  readonly version: string
+  readonly reason: string
+}> {}
 
 // ============================================================================
 // Schema
@@ -13,7 +37,7 @@ import { DocumentVersioned } from './versioned.js'
  */
 export const Document = S.Union(
   DocumentUnversioned,
-  DocumentVersioned,
+  DocumentVersioned.DocumentVersioned,
 )
 
 // ============================================================================
@@ -35,3 +59,112 @@ export const is = S.is(Document)
 export const decode = S.decode(Document)
 export const decodeSync = S.decodeSync(Document)
 export const encode = S.encode(Document)
+
+// ============================================================================
+// Domain Logic - Resolution Functions
+// ============================================================================
+
+/**
+ * Resolve document content for a given version coverage.
+ *
+ * @param document - The document to resolve content from
+ * @param versionCoverage - The version coverage to use (optional, defaults to latest)
+ * @returns The resolved document content
+ * @throws {Error} If version is not found in document
+ */
+export const resolveDocumentContent = (
+  document: Document,
+  versionCoverage?: VersionCoverage.VersionCoverage | null,
+): string => {
+  if (document._tag === 'DocumentUnversioned') {
+    return document.document
+  }
+
+  // If no version coverage specified, use latest
+  if (!versionCoverage) {
+    return DocumentVersioned.getContentForLatestVersionOrThrow(document)
+  }
+
+  // Get the latest version from the coverage
+  const version = VersionCoverage.getLatest(versionCoverage)
+  const contentOption = DocumentVersioned.getContentForVersion(document, version)
+
+  if (Option.isNone(contentOption)) {
+    throw new VersionNotFoundInDocumentError({
+      version: Version.encodeSync(version),
+      reason: `Version ${Version.encodeSync(version)} not covered by document`,
+    })
+  }
+
+  return contentOption.value
+}
+
+/**
+ * Resolve both document content and schema for a given version coverage.
+ * This is the primary resolution function that handles all combinations
+ * of versioned/unversioned documents and catalogs.
+ *
+ * @param document - The document to resolve content from
+ * @param catalog - The schema catalog (optional)
+ * @param versionCoverage - The version coverage to use (optional, defaults to latest)
+ * @returns Either with resolved content and optional schema, or error
+ */
+export const resolveDocumentAndSchema = (
+  document: Document,
+  catalog?: Catalog.Catalog,
+  versionCoverage?: VersionCoverage.VersionCoverage | null,
+): Either.Either<
+  { content: string; schema?: Schema.Schema },
+  | VersionCoverageMismatchError
+  | VersionNotFoundInDocumentError
+  | Catalog.VersionNotFoundInCatalogError
+  | Catalog.EmptyCatalogError
+> => {
+  // Handle unversioned document
+  if (document._tag === 'DocumentUnversioned') {
+    const content = document.document
+
+    if (!catalog) {
+      return Either.right({ content })
+    }
+
+    return Catalog.resolveCatalogSchemaEither(catalog, null).pipe(
+      Either.map(schema => ({ content, schema })),
+    )
+  }
+
+  // Handle versioned document
+  let content: string
+  try {
+    content = resolveDocumentContent(document, versionCoverage)
+  } catch (error) {
+    // resolveDocumentContent throws our tagged error
+    if (error instanceof VersionNotFoundInDocumentError) {
+      return Either.left(error)
+    }
+    // This shouldn't happen but handle gracefully
+    return Either.left(
+      new VersionNotFoundInDocumentError({
+        version: String(versionCoverage),
+        reason: error instanceof Error ? error.message : String(error),
+      }),
+    )
+  }
+
+  if (!catalog) {
+    return Either.right({ content })
+  }
+
+  // Cannot use version coverage with unversioned catalog
+  if (versionCoverage && Catalog.Unversioned.is(catalog)) {
+    return Either.left(
+      new VersionCoverageMismatchError({
+        reason: 'Cannot use a version coverage with an unversioned catalog',
+      }),
+    )
+  }
+
+  return Catalog.resolveCatalogSchemaEither(catalog, versionCoverage).pipe(
+    Either.map(schema => ({ content, schema })),
+  )
+}

package/src/lib/document/versioned.ts

@@ -1,5 +1,5 @@
 import { S } from '#lib/kit-temp/effect'
-import { VersionCoverage } from '#lib/version-selection/$'
+import { VersionCoverage } from '#lib/version-coverage'
 import { Version } from '#lib/version/$'
 import { HashMap, Option } from 'effect'
 
@@ -56,21 +56,21 @@ export const encode = S.encode(DocumentVersioned)
 export const getContentForVersion = (
   doc: DocumentVersioned,
   version: Version.Version,
-): string | null => {
+): Option.Option<string> => {
   // Try exact match first (single version key)
   const exactMatch = HashMap.get(doc.versionDocuments, version)
   if (Option.isSome(exactMatch)) {
-    return exactMatch.value
+    return Option.some(exactMatch.value)
   }
 
   // Check version sets
   for (const [selection, content] of HashMap.entries(doc.versionDocuments)) {
     if (VersionCoverage.isSet(selection) && VersionCoverage.contains(selection, version)) {
-      return content
+      return Option.some(content)
     }
   }
 
-  return null
+  return Option.none()
 }
 
 /**
@@ -98,9 +98,9 @@ export const getContentForLatestVersionOrThrow = (doc: DocumentVersioned): strin
   // Use Version.max with reduce to find the latest version
   const latestVersion = versions.reduce(Version.max)
 
-  const content = getContentForVersion(doc, latestVersion)
-  if (!content) {
+  const contentOption = getContentForVersion(doc, latestVersion)
+  if (Option.isNone(contentOption)) {
     throw new Error('Latest version not found in document')
   }
-  return content
+  return contentOption.value
 }

package/src/lib/lifecycles/lifecycles.ts

@@ -3,7 +3,7 @@ import { Change } from '#lib/change/$'
 import { Revision } from '#lib/revision/$'
 import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
-import { Match } from 'effect'
+import { Match, Option } from 'effect'
 
 // ============================================================================
 // Lifecycles Type - Simple Index
@@ -44,21 +44,21 @@ export type Since =
 /**
  * Extract the type name from a change
  */
-const extractTypeNameFromChange = (change: Change.Change): string | null => {
+const extractTypeNameFromChange = (change: Change.Change): Option.Option<string> => {
   return Match.value(change).pipe(
-    Match.tag('TYPE_ADDED', (c) => c.name),
-    Match.tag('TYPE_REMOVED', (c) => c.name),
-    Match.tag('FIELD_ADDED', (c) => c.typeName),
-    Match.tag('FIELD_REMOVED', (c) => c.typeName),
-    Match.tag('INPUT_FIELD_ADDED', (c) => c.inputName),
-    Match.tag('INPUT_FIELD_REMOVED', (c) => c.inputName),
-    Match.tag('ENUM_VALUE_ADDED', (c) => c.enumName),
-    Match.tag('ENUM_VALUE_REMOVED', (c) => c.enumName),
-    Match.tag('UNION_MEMBER_ADDED', (c) => c.unionName),
-    Match.tag('UNION_MEMBER_REMOVED', (c) => c.unionName),
-    Match.tag('OBJECT_TYPE_INTERFACE_ADDED', (c) => c.objectName),
-    Match.tag('OBJECT_TYPE_INTERFACE_REMOVED', (c) => c.objectName),
-    Match.orElse(() => null),
+    Match.tag('TYPE_ADDED', (c) => Option.some(c.name)),
+    Match.tag('TYPE_REMOVED', (c) => Option.some(c.name)),
+    Match.tag('FIELD_ADDED', (c) => Option.some(c.typeName)),
+    Match.tag('FIELD_REMOVED', (c) => Option.some(c.typeName)),
+    Match.tag('INPUT_FIELD_ADDED', (c) => Option.some(c.inputName)),
+    Match.tag('INPUT_FIELD_REMOVED', (c) => Option.some(c.inputName)),
+    Match.tag('ENUM_VALUE_ADDED', (c) => Option.some(c.enumName)),
+    Match.tag('ENUM_VALUE_REMOVED', (c) => Option.some(c.enumName)),
+    Match.tag('UNION_MEMBER_ADDED', (c) => Option.some(c.unionName)),
+    Match.tag('UNION_MEMBER_REMOVED', (c) => Option.some(c.unionName)),
+    Match.tag('OBJECT_TYPE_INTERFACE_ADDED', (c) => Option.some(c.objectName)),
+    Match.tag('OBJECT_TYPE_INTERFACE_REMOVED', (c) => Option.some(c.objectName)),
+    Match.orElse(() => Option.none()),
   )
 }
 
@@ -72,8 +72,9 @@ export const createFromSchema = (schema: Schema.Schema): Lifecycles => {
   for (const revision of schema.revisions) {
     // Process all changes in this revision
     for (const change of revision.changes) {
-      const typeName = extractTypeNameFromChange(change)
-      if (typeName) {
+      const typeNameOption = extractTypeNameFromChange(change)
+      if (Option.isSome(typeNameOption)) {
+        const typeName = typeNameOption.value
         if (!lifecycles[typeName]) {
           lifecycles[typeName] = []
         }
@@ -100,8 +101,9 @@ export const create = (catalog: Catalog.Catalog): Lifecycles => {
     for (const revision of schema.revisions) {
       // Process all changes in this revision
       for (const change of revision.changes) {
-        const typeName = extractTypeNameFromChange(change)
-        if (typeName) {
+        const typeNameOption = extractTypeNameFromChange(change)
+        if (Option.isSome(typeNameOption)) {
+          const typeName = typeNameOption.value
           if (!lifecycles[typeName]) {
             lifecycles[typeName] = []
           }
@@ -477,9 +479,9 @@ export const getFieldLifecycle = (
   lifecycles: Lifecycles,
   typeName: string,
   fieldName: string,
-): { events: ChangeEntry[] } | undefined => {
+): Option.Option<{ events: ChangeEntry[] }> => {
   const entries = lifecycles[typeName]
-  if (!entries) return undefined
+  if (!entries) return Option.none()
 
   // Filter entries related to this specific field
   const fieldEntries = entries.filter(entry => {
@@ -497,25 +499,28 @@ export const getFieldLifecycle = (
         && entry.change.fieldName === fieldName)
   })
 
-  if (fieldEntries.length === 0) return undefined
+  if (fieldEntries.length === 0) return Option.none()
 
   // Return in a format compatible with existing code that expects an object with events
-  return { events: fieldEntries }
+  return Option.some({ events: fieldEntries })
 }
 
 /**
  * Get type lifecycle info (for compatibility with existing UI code)
  */
-export const getTypeLifecycle = (lifecycles: Lifecycles, typeName: string): { events: ChangeEntry[] } | undefined => {
+export const getTypeLifecycle = (
+  lifecycles: Lifecycles,
+  typeName: string,
+): Option.Option<{ events: ChangeEntry[] }> => {
   const entries = lifecycles[typeName]
-  if (!entries) return undefined
+  if (!entries) return Option.none()
 
   // Filter entries related to type-level changes
   const typeEntries = entries.filter(entry => {
     return entry.change._tag === 'TYPE_ADDED' || entry.change._tag === 'TYPE_REMOVED'
   })
 
-  if (typeEntries.length === 0) return undefined
+  if (typeEntries.length === 0) return Option.none()
 
-  return { events: typeEntries }
+  return Option.some({ events: typeEntries })
 }

package/src/lib/version-coverage/$$.ts

@@ -0,0 +1 @@
+export * from './version-coverage.js'

package/src/lib/{version-selection/version-selection.ts → version-coverage/version-coverage.ts}

@@ -58,7 +58,7 @@ export const encodeSync = S.encodeSync(VersionCoverage)
 export const equivalence = S.equivalence(VersionCoverage)
 
 // ============================================================================
-// Domain Logic
+// Domain Logic - Basic Operations
 // ============================================================================
 
 /**

package/src/template/components/GraphQLDocument.tsx

@@ -1,12 +1,7 @@
 import { Catalog } from '#lib/catalog/$'
 import { Document } from '#lib/document/$'
-import { S } from '#lib/kit-temp/$'
-import type { Schema } from '#lib/schema/$'
-import { VersionCoverage } from '#lib/version-selection/$'
-import { VersionCoverageSet } from '#lib/version-selection/version-selection'
-import { Version } from '#lib/version/$'
-import { Array, HashMap, Match, Option } from 'effect'
-import type { GraphQLSchema } from 'graphql'
+import { VersionCoverage } from '#lib/version-coverage'
+import { Either, Option } from 'effect'
 import * as React from 'react'
 import { useHighlighted } from '../hooks/use-highlighted.js'
 import { GraphQLInteractive } from './GraphQLInteractive/GraphQLInteractive.js'
@@ -47,7 +42,7 @@ export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
   /// ━ VERSION MANAGEMENT
   const isControlled = controlledVersionCoverage !== undefined
   const [internalVersionCoverage, setInternalVersionCoverage] = React.useState<VersionCoverage.VersionCoverage | null>(
-    Catalog.getLatestVersion(schemaCatalog),
+    Option.getOrNull(Catalog.getLatestVersion(schemaCatalog)),
   )
   const selectedVersionCoverage = isControlled ? controlledVersionCoverage : internalVersionCoverage
   const internalOnVersionChange = (version: VersionCoverage.VersionCoverage) => {
@@ -58,11 +53,15 @@ export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
   }
 
   /// ━ DATA RESOLUTION
-  const {
-    schema,
-    content,
-  } = resolveSelectedVerCov(document, selectedVersionCoverage, schemaCatalog)
+  const result = Document.resolveDocumentAndSchema(document, schemaCatalog, selectedVersionCoverage)
 
+  // Handle resolution errors gracefully
+  if (Either.isLeft(result)) {
+    console.error('Failed to resolve document and schema:', result.left.message)
+    return null
+  }
+
+  const { schema, content } = result.right
   const highlightedCode = useHighlighted(content, { interactive: true })
 
   if (!highlightedCode) {
@@ -87,60 +86,3 @@ export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
     />
   )
 }
-
-/**
- * Matches a document with an optional schema catalog, returning the document content,
- * corresponding schema, and available versions for the selected version.
- *
- * @param document - The document to retrieve content from (required)
- * @param selectedVersionCoverage - The version to select (optional, defaults to latest)
- * @param schemaCatalog - The schema catalog to match against (optional)
- * @returns Object with document content, optional schema, and available versions
- * @throws {Error} If versions in catalog don't match versions in document
- */
-type Result = { content: string; schema?: Schema.Schema }
-const resolveSelectedVerCov = (
-  document: Document.Document,
-  selectedVersionCoverage?: VersionCoverage.VersionCoverage | null,
-  schemaCatalog?: Catalog.Catalog,
-): Result => {
-  if (Document.Unversioned.is(document)) {
-    return {
-      content: document.document,
-      schema: Match.value(schemaCatalog).pipe(
-        Match.tagsExhaustive({
-          CatalogUnversioned: (catalog) => catalog.schema,
-          CatalogVersioned: (catalog) => Catalog.Versioned.getLatestOrThrow(catalog),
-        }),
-      ),
-    }
-  }
-
-  return Match.value(selectedVersionCoverage).pipe(
-    Match.whenOr(null, undefined, _ => {
-      const content = Document.Versioned.getContentForLatestVersionOrThrow(document)
-      return { content }
-    }),
-    Match.orElse(_ => {
-      const version = VersionCoverage.getLatest(_)
-
-      const content = Document.Versioned.getContentForVersion(document, version)
-      if (!content) {
-        throw new Error(`Version ${Version.encodeSync(version)} not covered by document`)
-      }
-
-      if (!schemaCatalog) return { version, content }
-
-      if (Catalog.Unversioned.is(schemaCatalog)) {
-        throw new Error('Cannot use a set of versions with an unversioned catalog')
-      }
-      const schemaOption = HashMap.get(schemaCatalog.entries, version)
-      if (Option.isNone(schemaOption)) {
-        throw new Error(`Version ${Version.encodeSync(version)} not found in catalog`)
-      }
-      const schema = Option.getOrThrow(schemaOption)
-
-      return { content, schema: schema }
-    }),
-  )
-}