@effect-gql/core 0.1.0 → 1.1.0

package/src/loader.ts

@@ -1,363 +0,0 @@
-import { Effect, Context, Layer } from "effect"
-import DataLoader from "dataloader"
-
-/**
- * Ergonomic DataLoader helpers for Effect-based GraphQL
- *
- * This module provides a type-safe, declarative way to define DataLoaders
- * that integrate seamlessly with Effect's service system.
- *
- * @example
- * ```typescript
- * // Define loaders
- * const loaders = Loader.define({
- *   UserById: Loader.single<string, User>({
- *     batch: (ids) => db.getUsersByIds(ids),
- *     key: (user) => user.id,
- *   }),
- *
- *   PostsByAuthorId: Loader.grouped<string, Post>({
- *     batch: (ids) => db.getPostsForAuthors(ids),
- *     groupBy: (post) => post.authorId,
- *   }),
- * })
- *
- * // Use in resolvers
- * resolve: (parent) => loaders.load("UserById", parent.authorId)
- * ```
- */
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Configuration for a single-value loader (one key -> one value)
- */
-interface SingleLoaderDef<K, V, R> {
-  readonly _tag: "single"
-  readonly batch: (keys: readonly K[]) => Effect.Effect<readonly V[], Error, R>
-  readonly key: (value: V) => K
-}
-
-/**
- * Configuration for a grouped loader (one key -> many values)
- */
-interface GroupedLoaderDef<K, V, R> {
-  readonly _tag: "grouped"
-  readonly batch: (keys: readonly K[]) => Effect.Effect<readonly V[], Error, R>
-  readonly groupBy: (value: V) => K
-}
-
-type LoaderDef<K, V, R> = SingleLoaderDef<K, V, R> | GroupedLoaderDef<K, V, R>
-
-/**
- * Runtime DataLoader instances
- */
-type LoaderInstances<Defs extends Record<string, LoaderDef<any, any, any>>> = {
-  [Name in keyof Defs]: Defs[Name] extends SingleLoaderDef<infer K, infer V, any>
-    ? DataLoader<K, V>
-    : Defs[Name] extends GroupedLoaderDef<infer K, infer V, any>
-      ? DataLoader<K, V[]>
-      : never
-}
-
-/**
- * Extract the value type for a loader (accounting for grouped loaders)
- */
-type LoaderValue<Def> =
-  Def extends SingleLoaderDef<any, infer V, any>
-    ? V
-    : Def extends GroupedLoaderDef<any, infer V, any>
-      ? V[]
-      : never
-
-/**
- * Extract the key type for a loader
- */
-type LoaderKey<Def> = Def extends LoaderDef<infer K, any, any> ? K : never
-
-/**
- * Extract combined requirements from all loaders
- */
-type LoaderRequirements<Defs extends Record<string, LoaderDef<any, any, any>>> = {
-  [K in keyof Defs]: Defs[K] extends LoaderDef<any, any, infer R> ? R : never
-}[keyof Defs]
-
-// ============================================================================
-// Loader Builders
-// ============================================================================
-
-/**
- * Create a single-value loader definition.
- * One key maps to one value.
- *
- * @example
- * ```typescript
- * Loader.single<string, User>({
- *   batch: (ids) => db.getUsersByIds(ids),
- *   key: (user) => user.id,
- * })
- * ```
- */
-function single<K, V, R = never>(config: {
-  batch: (keys: readonly K[]) => Effect.Effect<readonly V[], Error, R>
-  key: (value: V) => K
-}): SingleLoaderDef<K, V, R> {
-  return {
-    _tag: "single",
-    batch: config.batch,
-    key: config.key,
-  }
-}
-
-/**
- * Create a grouped loader definition.
- * One key maps to many values.
- *
- * @example
- * ```typescript
- * Loader.grouped<string, Post>({
- *   batch: (authorIds) => db.getPostsForAuthors(authorIds),
- *   groupBy: (post) => post.authorId,
- * })
- * ```
- */
-function grouped<K, V, R = never>(config: {
-  batch: (keys: readonly K[]) => Effect.Effect<readonly V[], Error, R>
-  groupBy: (value: V) => K
-}): GroupedLoaderDef<K, V, R> {
-  return {
-    _tag: "grouped",
-    batch: config.batch,
-    groupBy: config.groupBy,
-  }
-}
-
-// ============================================================================
-// Loader Registry
-// ============================================================================
-
-/**
- * A registry of loader definitions with methods to create instances and layers
- */
-class LoaderRegistry<Defs extends Record<string, LoaderDef<any, any, any>>> {
-  readonly _tag = "LoaderRegistry"
-
-  /**
-   * The Effect service tag for this loader registry
-   */
-  readonly Service: Context.Tag<LoaderInstances<Defs>, LoaderInstances<Defs>>
-
-  constructor(readonly definitions: Defs) {
-    this.Service = Context.GenericTag<LoaderInstances<Defs>>(
-      `DataLoaders(${Object.keys(definitions).join(", ")})`
-    )
-  }
-
-  /**
-   * Create a Layer that provides fresh DataLoader instances.
-   * Call this once per request to get request-scoped loaders.
-   */
-  toLayer(): Layer.Layer<LoaderInstances<Defs>, never, LoaderRequirements<Defs>> {
-    const self = this
-    return Layer.effect(
-      this.Service,
-      Effect.gen(function* () {
-        const instances: Record<string, DataLoader<any, any>> = {}
-
-        for (const [name, def] of Object.entries(self.definitions)) {
-          instances[name] = yield* createDataLoader(def)
-        }
-
-        return instances as LoaderInstances<Defs>
-      })
-    ) as Layer.Layer<LoaderInstances<Defs>, never, LoaderRequirements<Defs>>
-  }
-
-  /**
-   * Helper to use loaders in a resolver with a callback.
-   */
-  use<A>(
-    fn: (loaders: LoaderInstances<Defs>) => Promise<A>
-  ): Effect.Effect<A, Error, LoaderInstances<Defs>> {
-    const self = this
-    return Effect.gen(function* () {
-      const loaders = yield* self.Service
-      return yield* Effect.promise(() => fn(loaders))
-    })
-  }
-
-  /**
-   * Load a single value by key.
-   * This is the most common operation in resolvers.
-   */
-  load<Name extends keyof Defs & string>(
-    name: Name,
-    key: LoaderKey<Defs[Name]>
-  ): Effect.Effect<LoaderValue<Defs[Name]>, Error, LoaderInstances<Defs>> {
-    const self = this
-    return Effect.gen(function* () {
-      const loaders = yield* self.Service
-      const loader = loaders[name] as DataLoader<any, any>
-      return yield* Effect.promise(() => loader.load(key))
-    })
-  }
-
-  /**
-   * Load multiple values by keys.
-   * All keys are batched into a single request.
-   */
-  loadMany<Name extends keyof Defs & string>(
-    name: Name,
-    keys: readonly LoaderKey<Defs[Name]>[]
-  ): Effect.Effect<readonly LoaderValue<Defs[Name]>[], Error, LoaderInstances<Defs>> {
-    const self = this
-    return Effect.gen(function* () {
-      const loaders = yield* self.Service
-      const loader = loaders[name] as DataLoader<any, any>
-      const results = yield* Effect.promise(() => loader.loadMany(keys))
-      // Convert any errors to a failure
-      for (const result of results) {
-        if (result instanceof Error) {
-          return yield* Effect.fail(result)
-        }
-      }
-      return results as readonly LoaderValue<Defs[Name]>[]
-    })
-  }
-}
-
-/**
- * Create a DataLoader from a loader definition
- */
-function createDataLoader<K, V, R>(
-  def: LoaderDef<K, V, R>
-): Effect.Effect<DataLoader<K, any>, never, R> {
-  return Effect.gen(function* () {
-    // Capture context for use in batch function
-    const context = yield* Effect.context<R>()
-
-    if (def._tag === "single") {
-      const loader = new DataLoader<K, V>(async (keys) => {
-        const items = await Effect.runPromise(def.batch(keys).pipe(Effect.provide(context)))
-        // Map items back to keys in order
-        return keys.map((key) => {
-          const item = items.find((i) => def.key(i) === key)
-          if (!item) return new Error(`Not found: ${key}`) as any
-          return item
-        })
-      })
-      return loader
-    } else {
-      // Grouped loader
-      const loader = new DataLoader<K, V[]>(async (keys) => {
-        const items = await Effect.runPromise(def.batch(keys).pipe(Effect.provide(context)))
-        // Group items by key with lazy array initialization
-        // Only create arrays for keys that have matching items
-        const map = new Map<K, V[]>()
-        for (const item of items) {
-          const key = def.groupBy(item)
-          let arr = map.get(key)
-          if (!arr) {
-            arr = []
-            map.set(key, arr)
-          }
-          arr.push(item)
-        }
-        // Return results in key order, defaulting to empty array for missing keys
-        return keys.map((key) => map.get(key) ?? [])
-      })
-      return loader
-    }
-  })
-}
-
-// ============================================================================
-// Public API
-// ============================================================================
-
-/**
- * Define a set of loaders.
- *
- * @example
- * ```typescript
- * const loaders = Loader.define({
- *   UserById: Loader.single<string, User>({
- *     batch: (ids) => db.getUsersByIds(ids),
- *     key: (user) => user.id,
- *   }),
- *   PostsByAuthorId: Loader.grouped<string, Post>({
- *     batch: (ids) => db.getPostsForAuthors(ids),
- *     groupBy: (post) => post.authorId,
- *   }),
- * })
- *
- * // In resolvers:
- * loaders.load("UserById", "123")
- * loaders.loadMany("UserById", ["1", "2", "3"])
- * ```
- */
-function define<Defs extends Record<string, LoaderDef<any, any, any>>>(
-  definitions: Defs
-): LoaderRegistry<Defs> {
-  return new LoaderRegistry(definitions)
-}
-
-// ============================================================================
-// Utility Functions
-// ============================================================================
-
-/**
- * Map an array of items to match requested keys.
- * Returns items in the same order as keys, with errors for missing items.
- */
-function mapByKey<K, V>(
-  keys: readonly K[],
-  items: readonly V[],
-  keyFn: (item: V) => K
-): (V | Error)[] {
-  const map = new Map<K, V>()
-  for (const item of items) {
-    map.set(keyFn(item), item)
-  }
-  return keys.map((key) => map.get(key) ?? new Error(`Not found: ${key}`))
-}
-
-/**
- * Group an array of items by a key function.
- * Returns a Map from key to array of matching items.
- * Guarantees an entry (possibly empty) for each requested key.
- */
-function groupByKey<K, V>(
-  keys: readonly K[],
-  items: readonly V[],
-  keyFn: (item: V) => K
-): Map<K, V[]> {
-  const map = new Map<K, V[]>()
-  // Initialize empty arrays for all requested keys
-  for (const key of keys) {
-    map.set(key, [])
-  }
-  // Fill in items
-  for (const item of items) {
-    const key = keyFn(item)
-    const arr = map.get(key)
-    if (arr) arr.push(item)
-  }
-  return map
-}
-
-// ============================================================================
-// Export
-// ============================================================================
-
-export const Loader = {
-  define,
-  single,
-  grouped,
-  mapByKey,
-  groupByKey,
-} as const
-
-export type { LoaderRegistry, LoaderDef, LoaderInstances }

package/src/resolver-context.ts

@@ -1,253 +0,0 @@
-import { Effect, Context, Layer, Ref, Option, HashMap } from "effect"
-
-/**
- * A type-safe context system for passing values through the resolver hierarchy.
- *
- * Unlike simple property bags, this provides:
- * - Type-safe slots that know their value type
- * - Clear errors when required context is missing
- * - Request-scoped storage that works across nested resolvers
- *
- * @example
- * ```typescript
- * // Define a context slot
- * const AuthPrincipal = ResolverContext.make<User>("AuthPrincipal")
- *
- * // Provide in a directive
- * .directive({
- *   name: "auth",
- *   apply: () => (effect) => Effect.gen(function*() {
- *     const user = yield* validateJwt()
- *     yield* ResolverContext.set(AuthPrincipal, user)
- *     return yield* effect
- *   }),
- * })
- *
- * // Access in any nested resolver
- * .field("User", "posts", {
- *   resolve: (parent) => Effect.gen(function*() {
- *     const user = yield* ResolverContext.get(AuthPrincipal)
- *     // ...
- *   }),
- * })
- * ```
- */
-
-/**
- * Error thrown when trying to access a context value that hasn't been set
- */
-export class MissingResolverContextError extends Error {
-  readonly _tag = "MissingResolverContextError"
-
-  constructor(readonly contextName: string) {
-    super(
-      `Resolver context "${contextName}" was not provided. Ensure a parent resolver or directive provides this context.`
-    )
-    this.name = "MissingResolverContextError"
-  }
-}
-
-/**
- * A typed context slot that can hold a value of type A
- */
-export interface ResolverContextSlot<A> {
-  readonly _tag: "ResolverContextSlot"
-  readonly name: string
-  readonly _A: A // Phantom type for type inference
-}
-
-/**
- * Internal storage for resolver context values.
- * This is a request-scoped service that holds all context values.
- */
-export interface ResolverContextStore {
-  readonly ref: Ref.Ref<HashMap.HashMap<string, unknown>>
-}
-
-export const ResolverContextStore = Context.GenericTag<ResolverContextStore>(
-  "effect-gql/ResolverContextStore"
-)
-
-/**
- * Create a Layer that provides the ResolverContextStore.
- * This should be included in the request layer.
- */
-export const makeStoreLayer = (): Effect.Effect<Layer.Layer<ResolverContextStore>> =>
-  Effect.map(Ref.make(HashMap.empty<string, unknown>()), (ref) =>
-    Layer.succeed(ResolverContextStore, { ref })
-  )
-
-/**
- * Create a Layer that provides an empty ResolverContextStore.
- * Convenience function for creating a fresh store layer.
- */
-export const storeLayer: Layer.Layer<ResolverContextStore> = Layer.effect(
-  ResolverContextStore,
-  Effect.map(Ref.make(HashMap.empty<string, unknown>()), (ref) => ({ ref }))
-)
-
-/**
- * Create a new resolver context slot.
- *
- * The name is used for error messages when the context is accessed but not set.
- *
- * @example
- * ```typescript
- * const AuthPrincipal = ResolverContext.make<User>("AuthPrincipal")
- * const TenantId = ResolverContext.make<string>("TenantId")
- * ```
- */
-export const make = <A>(name: string): ResolverContextSlot<A> => ({
-  _tag: "ResolverContextSlot",
-  name,
-  _A: undefined as unknown as A,
-})
-
-/**
- * Get a value from the resolver context.
- *
- * Fails with MissingResolverContextError if the context was not set
- * by a parent resolver or directive.
- *
- * @example
- * ```typescript
- * const effect = Effect.gen(function*() {
- *   const user = yield* ResolverContext.get(AuthPrincipal)
- *   // user is typed as User
- * })
- * ```
- */
-export const get = <A>(
-  slot: ResolverContextSlot<A>
-): Effect.Effect<A, MissingResolverContextError, ResolverContextStore> =>
-  Effect.flatMap(ResolverContextStore, (store) =>
-    Effect.flatMap(Ref.get(store.ref), (map) => {
-      const value = HashMap.get(map, slot.name)
-      return Option.match(value, {
-        onNone: () => Effect.fail(new MissingResolverContextError(slot.name)),
-        onSome: (v) => Effect.succeed(v as A),
-      })
-    })
-  )
-
-/**
- * Get a value from the resolver context as an Option.
- *
- * Returns None if the context was not set, instead of failing.
- * Useful when context is optional.
- */
-export const getOption = <A>(
-  slot: ResolverContextSlot<A>
-): Effect.Effect<Option.Option<A>, never, ResolverContextStore> =>
-  Effect.flatMap(ResolverContextStore, (store) =>
-    Effect.map(Ref.get(store.ref), (map) => HashMap.get(map, slot.name) as Option.Option<A>)
-  )
-
-/**
- * Set a value in the resolver context.
- *
- * The value will be available to all subsequent resolver calls in this request.
- * This mutates the request-scoped store, so nested resolvers will see the value.
- *
- * @example
- * ```typescript
- * // In a directive
- * const withAuth = (effect) => Effect.gen(function*() {
- *   const user = yield* validateJwt()
- *   yield* ResolverContext.set(AuthPrincipal, user)
- *   return yield* effect
- * })
- * ```
- */
-export const set = <A>(
-  slot: ResolverContextSlot<A>,
-  value: A
-): Effect.Effect<void, never, ResolverContextStore> =>
-  Effect.flatMap(ResolverContextStore, (store) =>
-    Ref.update(store.ref, (map) => HashMap.set(map, slot.name, value))
-  )
-
-/**
- * Set multiple context values at once.
- */
-export const setMany = (
-  values: ReadonlyArray<readonly [ResolverContextSlot<any>, any]>
-): Effect.Effect<void, never, ResolverContextStore> =>
-  Effect.flatMap(ResolverContextStore, (store) =>
-    Ref.update(store.ref, (map) => {
-      let result = map
-      for (const [slot, value] of values) {
-        result = HashMap.set(result, slot.name, value)
-      }
-      return result
-    })
-  )
-
-/**
- * Check if a context slot has a value set.
- */
-export const has = <A>(
-  slot: ResolverContextSlot<A>
-): Effect.Effect<boolean, never, ResolverContextStore> =>
-  Effect.flatMap(ResolverContextStore, (store) =>
-    Effect.map(Ref.get(store.ref), (map) => HashMap.has(map, slot.name))
-  )
-
-/**
- * Get a value or return a default if not set.
- */
-export const getOrElse = <A>(
-  slot: ResolverContextSlot<A>,
-  orElse: () => A
-): Effect.Effect<A, never, ResolverContextStore> =>
-  Effect.flatMap(ResolverContextStore, (store) =>
-    Effect.map(Ref.get(store.ref), (map) =>
-      Option.getOrElse(HashMap.get(map, slot.name) as Option.Option<A>, orElse)
-    )
-  )
-
-/**
- * Run an effect with a temporary context value.
- * The value is set before the effect runs and removed after.
- * Useful for scoped context that shouldn't persist.
- */
-export const scoped =
-  <A>(slot: ResolverContextSlot<A>, value: A) =>
-  <B, E, R>(effect: Effect.Effect<B, E, R>): Effect.Effect<B, E, R | ResolverContextStore> =>
-    Effect.flatMap(ResolverContextStore, (store) =>
-      Effect.acquireUseRelease(
-        // Acquire: save current value and set new one
-        Effect.flatMap(Ref.get(store.ref), (map) => {
-          const previous = HashMap.get(map, slot.name)
-          return Effect.as(Ref.set(store.ref, HashMap.set(map, slot.name, value)), previous)
-        }),
-        // Use: run the effect
-        () => effect,
-        // Release: restore previous value
-        (previous) =>
-          Ref.update(store.ref, (map) =>
-            Option.match(previous, {
-              onNone: () => HashMap.remove(map, slot.name),
-              onSome: (v) => HashMap.set(map, slot.name, v),
-            })
-          )
-      )
-    )
-
-/**
- * Namespace for ResolverContext functions
- */
-export const ResolverContext = {
-  make,
-  get,
-  getOption,
-  set,
-  setMany,
-  has,
-  getOrElse,
-  scoped,
-  storeLayer,
-  makeStoreLayer,
-  Store: ResolverContextStore,
-  MissingResolverContextError,
-} as const