polen 0.11.0-next.17 → 0.11.0-next.19

package/src/api/schema/input-sources/file.ts

@@ -5,7 +5,6 @@ import { DateOnly } from '#lib/date-only/$'
 import { Grafaid } from '#lib/grafaid'
 import { Revision } from '#lib/revision/$'
 import { Schema } from '#lib/schema/$'
-import { PlatformError } from '@effect/platform/Error'
 import { FileSystem } from '@effect/platform/FileSystem'
 import { Path } from '@wollybeard/kit'
 import { Effect } from 'effect'
@@ -76,18 +75,32 @@ export const loader = InputSource.createEffect({
 
       const ast = yield* Grafaid.Schema.AST.parse(content).pipe(
         Effect.mapError((error) =>
-          InputSource.InputSourceError('file', `Failed to parse schema file: ${error}`, error)
+          new InputSource.InputSourceError({
+            source: 'file',
+            message: `Failed to parse schema file: ${error}`,
+            cause: error,
+          })
         ),
       )
       const after = yield* Grafaid.Schema.fromAST(ast).pipe(
-        Effect.mapError((error) => InputSource.InputSourceError('file', `Failed to build schema: ${error}`, error)),
+        Effect.mapError((error) =>
+          new InputSource.InputSourceError({
+            source: 'file',
+            message: `Failed to build schema: ${error}`,
+            cause: error,
+          })
+        ),
       )
 
       const date = new Date()
       const before = Grafaid.Schema.empty
       const changes = yield* Change.calcChangeset({ before, after }).pipe(
         Effect.mapError((error) =>
-          InputSource.InputSourceError('file', `Failed to calculate changeset: ${error}`, error)
+          new InputSource.InputSourceError({
+            source: 'file',
+            message: `Failed to calculate changeset: ${error}`,
+            cause: error,
+          })
         ),
       )
 

package/src/api/schema/input-sources/introspection-file.ts

@@ -80,7 +80,11 @@ export const read = (
 
     const introspectionFileContent = yield* fs.readFileString(config.path).pipe(
       Effect.mapError((error) =>
-        InputSource.InputSourceError('introspectionFile', `Failed to read file ${config.path}: ${error}`, error)
+        new InputSource.InputSourceError({
+          source: 'introspectionFile',
+          message: `Failed to read file ${config.path}: ${error}`,
+          cause: error,
+        })
       ),
     )
 
@@ -90,16 +94,20 @@ export const read = (
       try: () => Json.codec.decode(introspectionFileContent),
       catch: (error) => {
         if (error instanceof SyntaxError) {
-          return InputSource.InputSourceError(
-            'introspectionFile',
-            `Invalid JSON in ${config.path}: ${error.message}`,
-            error,
+          return new InputSource.InputSourceError(
+            {
+              source: 'introspectionFile',
+              message: `Invalid JSON in ${config.path}: ${error.message}`,
+              cause: error,
+            },
           )
         }
-        return InputSource.InputSourceError(
-          'introspectionFile',
-          `Failed to parse JSON in ${config.path}: ${error}`,
-          error,
+        return new InputSource.InputSourceError(
+          {
+            source: 'introspectionFile',
+            message: `Failed to parse JSON in ${config.path}: ${error}`,
+            cause: error,
+          },
         )
       },
     })
@@ -107,7 +115,10 @@ export const read = (
     // Validate introspection data structure before passing to fromIntrospectionQuery
     if (!introspectionData || typeof introspectionData !== 'object') {
       return yield* Effect.fail(
-        InputSource.InputSourceError('introspectionFile', 'Introspection data must be a valid JSON object'),
+        new InputSource.InputSourceError({
+          source: 'introspectionFile',
+          message: 'Introspection data must be a valid JSON object',
+        }),
       )
     }
 
@@ -115,10 +126,10 @@ export const read = (
     // It will provide more specific GraphQL-related error messages
     if (!('data' in introspectionData)) {
       return yield* Effect.fail(
-        InputSource.InputSourceError(
-          'introspectionFile',
-          'Introspection data missing required "data" property (expected GraphQL introspection result format)',
-        ),
+        new InputSource.InputSourceError({
+          source: 'introspectionFile',
+          message: 'Introspection data missing required "data" property (expected GraphQL introspection result format)',
+        }),
       )
     }
 
@@ -144,7 +155,11 @@ const createCatalogFromSchema = (
       after,
     }).pipe(
       Effect.mapError((error) =>
-        InputSource.InputSourceError('introspectionFile', `Failed to calculate changeset: ${error}`, error)
+        new InputSource.InputSourceError({
+          source: 'introspectionFile',
+          message: `Failed to calculate changeset: ${error}`,
+          cause: error,
+        })
       ),
     )
 

package/src/api/schema/input-sources/introspection.ts

@@ -150,7 +150,12 @@ export const loader = InputSource.createEffect({
       // Try to read from cache
       const cacheEntry = yield* Effect.tryPromise({
         try: () => readCache(cachePath),
-        catch: (error) => InputSource.InputSourceError('introspection', `Failed to read cache: ${error}`, error),
+        catch: (error) =>
+          new InputSource.InputSourceError({
+            source: 'introspection',
+            message: `Failed to read cache: ${error}`,
+            cause: error,
+          }),
       })
 
       let schema: Grafaid.Schema.Schema
@@ -162,7 +167,11 @@ export const loader = InputSource.createEffect({
         // Fetch fresh introspection
         schema = yield* fetchIntrospection(options).pipe(
           Effect.mapError((error) =>
-            InputSource.InputSourceError('introspection', `Failed to fetch introspection: ${error}`, error)
+            new InputSource.InputSourceError({
+              source: 'introspection',
+              message: `Failed to fetch introspection: ${error}`,
+              cause: error,
+            })
           ),
         )
 
@@ -176,13 +185,22 @@ export const loader = InputSource.createEffect({
 
         yield* Effect.tryPromise({
           try: () => writeCache(cachePath, newCacheEntry),
-          catch: (error) => InputSource.InputSourceError('introspection', `Failed to write cache: ${error}`, error),
+          catch: (error) =>
+            new InputSource.InputSourceError({
+              source: 'introspection',
+              message: `Failed to write cache: ${error}`,
+              cause: error,
+            }),
         })
       }
 
       return yield* createCatalogFromSchema(schema).pipe(
         Effect.mapError((error) =>
-          InputSource.InputSourceError('introspection', `Failed to create catalog: ${error}`, error)
+          new InputSource.InputSourceError({
+            source: 'introspection',
+            message: `Failed to create catalog: ${error}`,
+            cause: error,
+          })
         ),
       )
     }),
@@ -196,7 +214,11 @@ export const loader = InputSource.createEffect({
       // Force fresh introspection
       const schema = yield* fetchIntrospection(options).pipe(
         Effect.mapError((error) =>
-          InputSource.InputSourceError('introspection', `Failed to fetch introspection: ${error}`, error)
+          new InputSource.InputSourceError({
+            source: 'introspection',
+            message: `Failed to fetch introspection: ${error}`,
+            cause: error,
+          })
         ),
       )
 
@@ -210,12 +232,21 @@ export const loader = InputSource.createEffect({
 
       yield* Effect.tryPromise({
         try: () => writeCache(cachePath, newCacheEntry),
-        catch: (error) => InputSource.InputSourceError('introspection', `Failed to write cache: ${error}`, error),
+        catch: (error) =>
+          new InputSource.InputSourceError({
+            source: 'introspection',
+            message: `Failed to write cache: ${error}`,
+            cause: error,
+          }),
       })
 
       return yield* createCatalogFromSchema(schema).pipe(
         Effect.mapError((error) =>
-          InputSource.InputSourceError('introspection', `Failed to create catalog: ${error}`, error)
+          new InputSource.InputSourceError({
+            source: 'introspection',
+            message: `Failed to create catalog: ${error}`,
+            cause: error,
+          })
         ),
       )
     }),

package/src/api/schema/input-sources/memory.ts

@@ -122,10 +122,22 @@ const parseSchema = (value: string | GraphQLSchema): Effect.Effect<GraphQLSchema
   Effect.gen(function*() {
     if (typeof value === 'string') {
       const ast = yield* Grafaid.Schema.AST.parse(value).pipe(
-        Effect.mapError((error) => InputSource.InputSourceError('memory', `Failed to parse schema: ${error}`, error)),
+        Effect.mapError((error) =>
+          new InputSource.InputSourceError({
+            source: 'memory',
+            message: `Failed to parse schema: ${error}`,
+            cause: error,
+          })
+        ),
       )
       return yield* Grafaid.Schema.fromAST(ast).pipe(
-        Effect.mapError((error) => InputSource.InputSourceError('memory', `Failed to build schema: ${error}`, error)),
+        Effect.mapError((error) =>
+          new InputSource.InputSourceError({
+            source: 'memory',
+            message: `Failed to build schema: ${error}`,
+            cause: error,
+          })
+        ),
       )
     }
     return value // Already a GraphQLSchema
@@ -186,7 +198,11 @@ export const read = (
 
             changes = yield* Change.calcChangeset({ before, after }).pipe(
               Effect.mapError((error) =>
-                InputSource.InputSourceError('memory', `Failed to calculate changeset: ${error}`, error)
+                new InputSource.InputSourceError({
+                  source: 'memory',
+                  message: `Failed to calculate changeset: ${error}`,
+                  cause: error,
+                })
               ),
             )
           }

package/src/api/schema/input-sources/versioned-directory.ts

@@ -10,7 +10,7 @@ import { debugPolen } from '#singletons/debug'
 import { PlatformError } from '@effect/platform/Error'
 import { FileSystem } from '@effect/platform/FileSystem'
 import { Arr, Path } from '@wollybeard/kit'
-import { Effect, HashMap } from 'effect'
+import { Array, Effect, HashMap } from 'effect'
 import type { GraphQLSchema } from 'graphql'
 
 const debug = debugPolen.sub(`schema:data-source-versioned-schema-directory`)
@@ -203,20 +203,20 @@ export const readOrThrow = (
                 const content = yield* fs.readFileString(filePath)
                 const ast = yield* Grafaid.Schema.AST.parse(content).pipe(
                   Effect.mapError((error) =>
-                    InputSource.InputSourceError(
-                      'versionedDirectory',
-                      `Failed to parse schema from ${filePath}: ${error}`,
-                      error,
-                    )
+                    new InputSource.InputSourceError({
+                      source: 'versionedDirectory',
+                      message: `Failed to parse schema from ${filePath}: ${error}`,
+                      cause: error,
+                    })
                   ),
                 )
                 const schema = yield* Grafaid.Schema.fromAST(ast).pipe(
                   Effect.mapError((error) =>
-                    InputSource.InputSourceError(
-                      'versionedDirectory',
-                      `Failed to build schema from ${filePath}: ${error}`,
-                      error,
-                    )
+                    new InputSource.InputSourceError({
+                      source: 'versionedDirectory',
+                      message: `Failed to build schema from ${filePath}: ${error}`,
+                      cause: error,
+                    })
                   ),
                 )
 
@@ -285,11 +285,11 @@ export const readOrThrow = (
 
                 const changes = yield* Change.calcChangeset({ before, after }).pipe(
                   Effect.mapError((error) =>
-                    InputSource.InputSourceError(
-                      'versionedDirectory',
-                      `Failed to calculate changeset for ${version.name}: ${error}`,
-                      error,
-                    )
+                    new InputSource.InputSourceError({
+                      source: 'versionedDirectory',
+                      message: `Failed to calculate changeset for ${version.name}: ${error}`,
+                      cause: error,
+                    })
                   ),
                 )
 
@@ -330,11 +330,11 @@ export const readOrThrow = (
 
                         const changes = yield* Change.calcChangeset({ before, after }).pipe(
                           Effect.mapError((error) =>
-                            InputSource.InputSourceError(
-                              'versionedDirectory',
-                              `Failed to calculate parent changeset: ${error}`,
-                              error,
-                            )
+                            new InputSource.InputSourceError({
+                              source: 'versionedDirectory',
+                              message: `Failed to calculate parent changeset: ${error}`,
+                              cause: error,
+                            })
                           ),
                         )
 
@@ -452,9 +452,8 @@ export const loader = InputSource.createEffect({
           // Check for revision files or schema.graphql
           const dirFiles = yield* Effect.either(fs.readDirectory(versionPath))
           if (dirFiles._tag === 'Right') {
-            const hasRevisions = dirFiles.right.some(file =>
-              /^\d{4}-\d{2}-\d{2}\.graphql$/.test(file) || file === 'schema.graphql'
-            )
+            const hasRevisions = Array.some(dirFiles.right, file =>
+              /^\d{4}-\d{2}-\d{2}\.graphql$/.test(file) || file === 'schema.graphql')
             if (hasRevisions) {
               return true
             }
@@ -520,9 +519,8 @@ export const loader = InputSource.createEffect({
         // Check for schema files
         const dirFiles = yield* Effect.either(fs.readDirectory(versionPath))
         if (dirFiles._tag === 'Right') {
-          const hasSchemaFiles = dirFiles.right.some(file =>
-            /^\d{4}-\d{2}-\d{2}\.graphql$/.test(file) || file === 'schema.graphql'
-          )
+          const hasSchemaFiles = Array.some(dirFiles.right, file =>
+            /^\d{4}-\d{2}-\d{2}\.graphql$/.test(file) || file === 'schema.graphql')
 
           if (hasSchemaFiles) {
             debug('found valid schema files, proceeding with full read')

package/src/api/schema/load.ts

@@ -1,6 +1,7 @@
 import type { Config } from '#api/config/normalized'
 import { Augmentations } from '#api/schema/augmentations/$'
-import type { EffectInputSource, InputSource, InputSourceError } from '#api/schema/input-source/input-source'
+import type { InputSourceError } from '#api/schema/input-source/errors'
+import type { EffectInputSource, InputSource } from '#api/schema/input-source/input-source'
 import * as InputSourceLoader from '#api/schema/input-source/load'
 import { InputSources } from '#api/schema/input-sources/$'
 import { Catalog } from '#lib/catalog/$'

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
 }
 
 /**