polen 0.11.0-next.14 → 0.11.0-next.15

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

@@ -0,0 +1,222 @@
+import { InputSource } from '#api/schema/input-source/$'
+import { Catalog } from '#lib/catalog/$'
+import { Change } from '#lib/change/$'
+import { DateOnly } from '#lib/date-only/$'
+import { Grafaid } from '#lib/grafaid'
+import { GraphqlSchemaLoader } from '#lib/graphql-schema-loader'
+import { Revision } from '#lib/revision/$'
+import { Schema } from '#lib/schema/$'
+import { FileSystem } from '@effect/platform/FileSystem'
+import { Fs, Json, Path } from '@wollybeard/kit'
+import { Effect } from 'effect'
+import { createHash } from 'node:crypto'
+
+/**
+ * Configuration for loading schema via GraphQL introspection.
+ *
+ * This source automatically fetches the schema from a GraphQL endpoint
+ * and caches it locally in `.polen/cache/introspection/`.
+ *
+ * The cache can be cleared by deleting the `.polen/cache` directory
+ * or by using the reCreate functionality.
+ *
+ * @example
+ * ```ts
+ * // Basic introspection
+ * introspection: {
+ *   url: 'https://api.example.com/graphql'
+ * }
+ *
+ * // With authentication
+ * introspection: {
+ *   url: 'https://api.example.com/graphql',
+ *   headers: {
+ *     'Authorization': `Bearer ${process.env.API_TOKEN}`
+ *   }
+ * }
+ * ```
+ */
+export interface Options {
+  /**
+   * The GraphQL endpoint URL to introspect.
+   *
+   * Must be a valid GraphQL endpoint that supports introspection queries.
+   *
+   * @example 'https://api.example.com/graphql'
+   */
+  url: string
+  /**
+   * Optional headers to include in the introspection request.
+   *
+   * Use this for authentication, API keys, or any custom headers
+   * required by your GraphQL endpoint.
+   *
+   * @example
+   * ```ts
+   * headers: {
+   *   'Authorization': `Bearer ${process.env.API_TOKEN}`,
+   *   'X-API-Key': process.env.API_KEY
+   * }
+   * ```
+   */
+  headers?: Record<string, string>
+}
+
+interface CacheEntry {
+  url: string
+  fetchedAt: string // ISO timestamp
+  introspectionResult: any // The GraphQL introspection result
+}
+
+const getCacheKey = (url: string): string => {
+  return createHash('sha256').update(url).digest('hex')
+}
+
+const getCachePath = (url: string, projectRoot: string): string => {
+  const cacheKey = getCacheKey(url)
+  return Path.join(projectRoot, '.polen', 'cache', 'introspection', `${cacheKey}.json`)
+}
+
+const readCache = async (cachePath: string): Promise<CacheEntry | null> => {
+  const content = await Fs.read(cachePath)
+  if (!content) return null
+
+  try {
+    const data = Json.codec.decode(content)
+    return data as unknown as CacheEntry
+  } catch {
+    return null
+  }
+}
+
+const writeCache = async (cachePath: string, entry: CacheEntry): Promise<void> => {
+  await Fs.write({
+    path: cachePath,
+    content: Json.codec.encode(entry as any),
+  })
+}
+
+const fetchIntrospection = (options: Options): Effect.Effect<Grafaid.Schema.Schema, Error, FileSystem> =>
+  GraphqlSchemaLoader.load({
+    type: `introspect`,
+    url: options.url,
+    headers: options.headers,
+  })
+
+const createCatalogFromSchema = (
+  schemaData: Grafaid.Schema.Schema,
+): Effect.Effect<Catalog.Unversioned.Unversioned, Error> =>
+  Effect.gen(function*() {
+    const date = new Date()
+    const dateString = date.toISOString().split('T')[0]!
+    const after = schemaData
+    const before = Grafaid.Schema.empty
+    const changes = yield* Change.calcChangeset({
+      before,
+      after,
+    })
+
+    const revision = Revision.make({
+      date: DateOnly.make(dateString),
+      changes,
+    })
+
+    // Create unversioned schema
+    const schema = Schema.Unversioned.make({
+      revisions: [revision],
+      definition: after, // GraphQLSchema object
+    })
+
+    // Return catalog
+    return Catalog.Unversioned.make({
+      schema,
+    })
+  })
+
+export const loader = InputSource.createEffect({
+  name: 'introspection',
+
+  isApplicable: (options: Options) => {
+    // This source is applicable if a URL is provided
+    return Effect.succeed(!!options.url)
+  },
+
+  readIfApplicableOrThrow: (options: Options, config) =>
+    Effect.gen(function*() {
+      if (!options.url) return null
+
+      const cachePath = getCachePath(options.url, config.paths.project.rootDir)
+
+      // Try to read from cache
+      const cacheEntry = yield* Effect.tryPromise({
+        try: () => readCache(cachePath),
+        catch: (error) => InputSource.InputSourceError('introspection', `Failed to read cache: ${error}`, error),
+      })
+
+      let schema: Grafaid.Schema.Schema
+
+      if (cacheEntry && cacheEntry.url === options.url) {
+        // Use cached introspection result
+        schema = Grafaid.Schema.fromIntrospectionQuery(cacheEntry.introspectionResult)
+      } else {
+        // Fetch fresh introspection
+        schema = yield* fetchIntrospection(options).pipe(
+          Effect.mapError((error) =>
+            InputSource.InputSourceError('introspection', `Failed to fetch introspection: ${error}`, error)
+          ),
+        )
+
+        // Save to cache
+        const __schema = Grafaid.Schema.toIntrospectionQuery(schema)
+        const newCacheEntry: CacheEntry = {
+          url: options.url,
+          fetchedAt: new Date().toISOString(),
+          introspectionResult: { data: { __schema } },
+        }
+
+        yield* Effect.tryPromise({
+          try: () => writeCache(cachePath, newCacheEntry),
+          catch: (error) => InputSource.InputSourceError('introspection', `Failed to write cache: ${error}`, error),
+        })
+      }
+
+      return yield* createCatalogFromSchema(schema).pipe(
+        Effect.mapError((error) =>
+          InputSource.InputSourceError('introspection', `Failed to create catalog: ${error}`, error)
+        ),
+      )
+    }),
+
+  reCreate: (options: Options, config) =>
+    Effect.gen(function*() {
+      if (!options.url) return null
+
+      const cachePath = getCachePath(options.url, config.paths.project.rootDir)
+
+      // Force fresh introspection
+      const schema = yield* fetchIntrospection(options).pipe(
+        Effect.mapError((error) =>
+          InputSource.InputSourceError('introspection', `Failed to fetch introspection: ${error}`, error)
+        ),
+      )
+
+      // Update cache
+      const __schema = Grafaid.Schema.toIntrospectionQuery(schema)
+      const newCacheEntry: CacheEntry = {
+        url: options.url,
+        fetchedAt: new Date().toISOString(),
+        introspectionResult: { data: { __schema } },
+      }
+
+      yield* Effect.tryPromise({
+        try: () => writeCache(cachePath, newCacheEntry),
+        catch: (error) => InputSource.InputSourceError('introspection', `Failed to write cache: ${error}`, error),
+      })
+
+      return yield* createCatalogFromSchema(schema).pipe(
+        Effect.mapError((error) =>
+          InputSource.InputSourceError('introspection', `Failed to create catalog: ${error}`, error)
+        ),
+      )
+    }),
+})

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

@@ -0,0 +1,241 @@
+import { InputSource } from '#api/schema/input-source/$'
+import { Catalog } from '#lib/catalog/$'
+import { Change } from '#lib/change/$'
+import { DateOnly } from '#lib/date-only/$'
+import { Grafaid } from '#lib/grafaid'
+import { Revision } from '#lib/revision/$'
+import { Schema } from '#lib/schema/$'
+import { Arr } from '@wollybeard/kit'
+import { Effect } from 'effect'
+import type { GraphQLSchema } from 'graphql'
+
+/**
+ * Configuration for defining schemas programmatically in memory.
+ *
+ * Useful for demos, testing, or when schemas are generated dynamically.
+ */
+export interface Options {
+  /**
+   * Schema revisions defined in various formats.
+   *
+   * Can be:
+   * - A single SDL string (single revision, no changelog)
+   * - Array of SDL strings (uses current date for all)
+   * - Array of objects with date and SDL (full changelog support)
+   * - A GraphQLSchema object (single revision, no changelog)
+   * - Array of GraphQLSchema objects (uses current date for all)
+   * - Array of objects with date and GraphQLSchema (full changelog support)
+   * - A pre-built unversioned Catalog object
+   *
+   * @example
+   * ```ts
+   * // Single SDL schema revision
+   * revisions: `
+   *   type Query {
+   *     hello: String
+   *   }
+   * `
+   *
+   * // Multiple revisions with explicit dates (enables changelog)
+   * revisions: [
+   *   {
+   *     date: new Date('2024-01-15'),
+   *     value: `type Query { users: [User] }`
+   *   },
+   *   {
+   *     date: new Date('2024-03-20'),
+   *     value: `type Query { users: [User], posts: [Post] }`
+   *   }
+   * ]
+   *
+   * // GraphQL schema object
+   * revisions: buildSchema(`type Query { hello: String }`)
+   *
+   * // Pre-built unversioned catalog
+   * revisions: myCatalog
+   * ```
+   */
+  revisions:
+    | string
+    | string[]
+    | { date: Date; value: string }[]
+    | GraphQLSchema
+    | GraphQLSchema[]
+    | { date: Date; value: GraphQLSchema }[]
+    | Catalog.Unversioned.Unversioned
+}
+
+export interface Config {
+  revisions: { date: Date; value: string | GraphQLSchema }[] | Catalog.Unversioned.Unversioned
+}
+
+// Type guard to check if value is a GraphQLSchema
+const isGraphQLSchema = (value: unknown): value is GraphQLSchema => {
+  return value !== null && typeof value === 'object' && '_typeMap' in value
+}
+
+export const normalize = (configInput: Options): Config => {
+  // If it's already a Catalog, return it as-is
+  if (Catalog.is(configInput.revisions)) {
+    return {
+      revisions: configInput.revisions,
+    }
+  }
+
+  // Handle undefined/null revisions
+  if (!configInput.revisions) {
+    return {
+      revisions: [],
+    }
+  }
+
+  // Convert all other formats to normalized array format
+  const revisionsArray = Arr.sure(configInput.revisions)
+
+  const config: Config = {
+    revisions: Arr.map(revisionsArray, (item) => {
+      // Handle string (SDL)
+      if (typeof item === 'string') {
+        return {
+          date: new Date(),
+          value: item,
+        }
+      }
+
+      // Handle GraphQLSchema object
+      if (isGraphQLSchema(item)) {
+        return {
+          date: new Date(),
+          value: item,
+        }
+      }
+
+      // Handle { date, value } where value could be string or GraphQLSchema
+      return item
+    }),
+  }
+
+  return config
+}
+
+const parseSchema = (value: string | GraphQLSchema): Effect.Effect<GraphQLSchema, InputSource.InputSourceError> =>
+  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)),
+      )
+      return yield* Grafaid.Schema.fromAST(ast).pipe(
+        Effect.mapError((error) => InputSource.InputSourceError('memory', `Failed to build schema: ${error}`, error)),
+      )
+    }
+    return value // Already a GraphQLSchema
+  })
+
+export const read = (
+  options: Options,
+): Effect.Effect<
+  null | { schema: Schema.Unversioned.Unversioned; revisions: readonly Revision.Revision[] },
+  InputSource.InputSourceError
+> =>
+  Effect.gen(function*() {
+    const config = normalize(options)
+
+    // If it's already a Catalog, extract schema and revisions
+    if (Catalog.Unversioned.is(config.revisions)) {
+      return {
+        schema: config.revisions.schema,
+        revisions: [...config.revisions.schema.revisions],
+      }
+    }
+
+    if (!Arr.isntEmpty(config.revisions)) {
+      return null
+    }
+
+    const parsedRevisions = yield* Effect.all(
+      Arr.map(config.revisions, (item) =>
+        Effect.gen(function*() {
+          const schema = yield* parseSchema(item.value)
+          return {
+            date: item.date,
+            schema,
+          }
+        })),
+      { concurrency: 'unbounded' },
+    )
+
+    // Sort revisions newest first
+    parsedRevisions.sort((a, b) => b.date.getTime() - a.date.getTime())
+
+    const revisions = yield* Effect.all(
+      Arr.map(parsedRevisions, (revision, index) =>
+        Effect.gen(function*() {
+          const current = revision
+          const previous = parsedRevisions[index - 1]
+
+          // Skip changeset calculation for the newest revision (first in array after sorting)
+          let changes: Change.Change[]
+          if (!previous) {
+            // For the newest revision, we don't have changes - just an empty array
+            changes = []
+          } else {
+            // Fix: Swap before/after to calculate changes correctly
+            // previous is NEWER (lower index), current is OLDER (higher index)
+            const before = current.schema // older
+            const after = previous.schema // newer
+
+            changes = yield* Change.calcChangeset({ before, after }).pipe(
+              Effect.mapError((error) =>
+                InputSource.InputSourceError('memory', `Failed to calculate changeset: ${error}`, error)
+              ),
+            )
+          }
+
+          return Revision.make({
+            date: DateOnly.make(current.date.toISOString().split('T')[0]!),
+            changes,
+          })
+        })),
+      { concurrency: 1 }, // Keep sequential for correct changeset calculation
+    )
+
+    // Get the latest schema (first after sorting newest first)
+    const latestSchemaData = parsedRevisions[0]?.schema
+    if (!latestSchemaData) return null
+
+    const schema = Schema.Unversioned.make({
+      revisions: revisions, // Already sorted newest first
+      definition: latestSchemaData, // GraphQLSchema object
+    })
+
+    return {
+      schema: schema,
+      revisions: schema.revisions,
+    }
+  })
+
+export const loader = InputSource.createEffect({
+  name: 'memory',
+  isApplicable: (options: Options, _context) =>
+    Effect.succeed(options.revisions !== undefined && options.revisions !== null),
+  readIfApplicableOrThrow: (options: Options, _context) =>
+    Effect.gen(function*() {
+      const config = normalize(options)
+
+      // If it's already a Catalog, return it directly
+      if (Catalog.is(config.revisions)) {
+        return config.revisions
+      }
+
+      if (!Arr.isntEmpty(config.revisions)) {
+        return null
+      }
+
+      const result = yield* read(options)
+      if (!result) return null
+
+      return Catalog.Unversioned.make({
+        schema: result.schema,
+      })
+    }),
+})